# Invoices

> Create, send, update and void invoices from your own code, with lines, discount, tax, a due date, part payments and tips. The same invoices as the dashboard's, emailed in your business's name with their PDF.

Source: https://railbed.com/docs/api/invoices/ · Updated: 2026-11-18 · Railbed developer docs

For AI assistants: the index of every docs page, with the rules for an integration, is https://railbed.com/docs/llms.txt

## The invoice object

An invoice asks a customer for what they owe: lines with a quantity and a price, an optional discount and tax, a due date and your terms. It's the same invoice you build under [Invoices](https://app.railbed.io/invoices) in the dashboard, and it shows up there. The customer opens its `url`, sees the invoice, and pays it by card, in full or (if you allow it) in parts, with a tip if you allow one. Railbed can email it to them in your business's name with its PDF, remind them around the due date, and send a receipt for each payment.

Each payment toward an invoice is an ordinary [payment](https://railbed.com/docs/api/payments.md) with its `invoice_id` set, settled like any other: list them with `GET /v1/payments?invoice_id=in_…`. The invoice's own figures (`amount_paid`, `amount_due`, `status`) follow from its payments as they settle. Every [payment link](https://railbed.com/docs/api/payment-links.md) is listed here too, as `kind: "link"`, so one list holds everything your customers owe; change a link through the payment links endpoints.

| Field | Type | Description |
|---|---|---|
| `id` | string | The invoice's id, `in_…` |
| `object` | string | `"invoice"` |
| `kind` | string | `invoice` for one built as an invoice, `link` for a payment link |
| `number` | string | `INV-0042`, counted per account and mode, payment links included |
| `status` | string | `draft`, `sent`, `viewed`, `partially_paid`, `overdue`, `paid`, `void` or `expired`. See [Statuses](#statuses) |
| `livemode` | boolean | `false` for Test mode, `true` for Live mode |
| `url` | string or null | The customer's page, where they pay. Send them this. `null` for a draft |
| `pdf_url` | string or null | The PDF the customer can download from their page. `null` for a draft. [Download an invoice PDF](#download-an-invoice-pdf) works for drafts too |
| `currency` | string | `USD`, `EUR`, `GBP`, `CAD`, `AUD`, `INR` or `SEK` |
| `lines` | array | Each line's `description`, `quantity` (`"12.5"`), `unit_amount` and `amount` (`quantity` × `unit_amount`, rounded half up to the cent) |
| `subtotal` | string | The lines added up |
| `discount` | string | Taken off the subtotal, `"0.00"` for none |
| `discount_percent` | string or null | Set when the discount is a percentage (`"10"`) |
| `tax` | string | Tax on the subtotal less the discount, `"0.00"` for none |
| `tax_percent`, `tax_label` | string or null | The tax's rate (`"8.25"`) and name (`"Sales tax"`) |
| `total` | string | What the invoice asks for |
| `amount_paid` | string | Paid toward the total so far. Tips never count |
| `amount_due` | string | What's left to pay |
| `tips` | string | Tips customers added on top, `"0.00"` for none |
| `customer` | object | `id` (`cus_…`, the saved [customer](https://railbed.com/docs/api/customers.md), once there is one), `name`, `email`, `company`, `phone` and `billing_address` |
| `memo` | string or null | Your note to the customer |
| `terms` | string or null | Your payment terms |
| `reference` | string or null | Your own id, such as a purchase order number |
| `due_date` | string or null | `YYYY-MM-DD`. The invoice is due until the end of that day anywhere on Earth, so no customer is late on the day it's due |
| `allow_partial` | boolean | Whether the customer may pay in parts |
| `min_payment` | string or null | With `allow_partial`: the least first payment, a deposit |
| `allow_tip` | boolean | Whether the customer may add a tip |
| `reminders` | array or null | Days around the due date when Railbed emails a reminder (negative: before it), such as `[-3, 0, 3]` |
| `email_receipts` | boolean | Whether the customer gets a receipt for each payment |
| `routing` | object | Which card providers the customer's payments offer. See [The routing field](https://railbed.com/docs/api/payment-links.md#the-routing-field) |
| `collect` | object or null | What the customer's payment page asks besides their email. See [The collect field](https://railbed.com/docs/api/checkout-sessions.md#the-collect-field) |
| `success_url` | string or null | Where the customer lands once paid |
| `payout_wallet_id` | string or null | The saved wallet the invoice pays, `pw_…`, or `null` for the account's payout wallet |
| `payment_link_id` | string or null | A link invoice's payment link, `pay_…`. `null` for an invoice |
| `owner` | object or null | The person on your team it belongs to: `id` (`usr_…`), `name` and `email`. Invoices made with a key have none unless you name one |
| `created_via` | string | Where it was made: `dashboard`, `api`, `mcp`, `telegram` or `slack` |
| `send_count` | integer | How many times Railbed emailed it, reminders included |
| `view_count` | integer | How many times its customer opened it |
| `version` | integer | Goes up with every change. Send it back as `expected_version` when you [update it](#update-an-invoice) |
| `created`, `updated` | integer | When it was made and last changed, in Unix seconds |
| `issued_at`, `last_sent_at`, `viewed_at`, `paid_at`, `voided_at` | integer or null | When it was issued, last emailed, first opened by its customer, paid in full and voided |
| `void_reason` | string or null | Your reason for voiding it. Never shown to the customer |
| `expires_at` | integer or null | Payment links only: when it stops being payable |
| `next_reminder_at` | integer or null | When the next reminder goes, in Unix seconds |
| `warnings` | array | On create and update only, and only when there is something to say: what the card providers' minimums mean for this total. See [Provider minimums](https://railbed.com/docs/api/checkout-sessions.md#provider-minimums) |
| `email` | object | On [Send an invoice](#send-an-invoice), and create with `send`: the email just queued. See [The email object](#the-email-object) |
| `email_error` | object | On create with `send` only: the invoice was made and issued, but the email couldn't be queued. `code` and `message` are the error [Send an invoice](#send-an-invoice) would answer |

Example: An invoice · response 200 OK

```json
{
  "id": "in_Vn3qT8kR5xWm2LcZp7Hb",
  "object": "invoice",
  "kind": "invoice",
  "number": "INV-0042",
  "status": "sent",
  "livemode": false,
  "url": "https://pay.railbed.io/i/4c9e1f7a2b6d48e3a5f0c8b1d7e2a9f3",
  "pdf_url": "https://pay.railbed.io/i/4c9e1f7a2b6d48e3a5f0c8b1d7e2a9f3/pdf",
  "currency": "USD",
  "lines": [
    {
      "description": "Brand strategy workshop",
      "quantity": "1",
      "unit_amount": "3200.00",
      "amount": "3200.00"
    },
    {
      "description": "Design hours",
      "quantity": "12.5",
      "unit_amount": "150.00",
      "amount": "1875.00"
    }
  ],
  "subtotal": "5075.00",
  "discount": "0.00",
  "discount_percent": null,
  "tax": "418.69",
  "tax_percent": "8.25",
  "tax_label": "Sales tax",
  "total": "5493.69",
  "amount_paid": "0.00",
  "amount_due": "5493.69",
  "tips": "0.00",
  "customer": {
    "id": "cus_Rk8mW3pZ6tQv1NxLc4Ys",
    "name": "Ada Lovelace",
    "email": "ada@example.com",
    "company": "Analytical Engines Ltd",
    "phone": null,
    "billing_address": null
  },
  "memo": "Thanks for your business.",
  "terms": "Due within 30 days. Bank details on request.",
  "reference": "PO-1042",
  "due_date": "2026-10-26",
  "allow_partial": true,
  "min_payment": "1000.00",
  "allow_tip": false,
  "reminders": [
    -3,
    0,
    3
  ],
  "email_receipts": true,
  "routing": {
    "choice": "buyer",
    "provider": null,
    "fallback": true,
    "providers": null
  },
  "collect": null,
  "success_url": null,
  "payout_wallet_id": null,
  "payment_link_id": null,
  "owner": null,
  "created_via": "api",
  "send_count": 0,
  "view_count": 0,
  "version": 0,
  "created": 1790380525,
  "updated": 1790380525,
  "issued_at": 1790380525,
  "last_sent_at": null,
  "viewed_at": null,
  "paid_at": null,
  "voided_at": null,
  "void_reason": null,
  "expires_at": null,
  "next_reminder_at": 1792746000
}
```

### Statuses

| Status | Meaning |
|---|---|
| `draft` | Not issued. It has no page, can change freely, and can be deleted |
| `sent` | Issued: its `url` can be paid. It reads `sent` whether Railbed emailed it or you shared the link yourself; `send_count` says how many emails went |
| `viewed` | Its customer opened it |
| `partially_paid` | Part of it is paid and the rest is due |
| `overdue` | Past its due date with something still to pay |
| `paid` | Paid in full. It can't change or be voided |
| `void` | Voided: it can't be paid any more |
| `expired` | A payment link that can no longer be paid |

Once a customer has started a payment toward an issued invoice, its lines, discount, tax, currency, customer and payment options lock, so what they're paying doesn't move under them. Its due date, reminders, memo, terms, receipts and owner can still change.

## Create an invoice

`POST /v1/invoices`

Makes an invoice in the credential's mode. By default it's a draft: change it, then [issue](#issue-an-invoice) or [send](#send-an-invoice) it. Send `issue: true` to issue it at once, so its `url` can be shared and paid, or `send: true` to issue it and email it to the customer. An invoice shared by its `url` needs no customer: one who isn't named gives their email as they pay. Emailing it needs the customer's name and email.

| Parameter | Type | Description |
|---|---|---|
| `currency` | string · required | `USD`, `EUR`, `GBP`, `CAD`, `AUD`, `INR` or `SEK`, in any letter case |
| `lines` | array · required | 1–50 lines, each `description` (up to 200 characters), `quantity` (from `"0.01"` to `"99999"`, up to two decimals; default 1) and `unit_amount` (a decimal string such as `"150.00"`). The total must be from 1.00 to 100,000.00 and at least the smallest card payment |
| `customer` | object | Who it's for: `name` (up to 80 characters), `email`, `company` (up to 120), `phone` (up to 40) and `billing_address` (`line1`, `line2`, `city`, `region`, `postal_code`, `country`). Pass `id` (`cus_…`) for a saved customer, and their details fill in what you leave out |
| `discount` | object | `{ "amount": "25.00" }` or `{ "percent": "10" }`, taken off the subtotal |
| `tax` | object | `{ "percent": "8.25", "label": "Sales tax" }`, on the subtotal less the discount |
| `due_date` | string | `YYYY-MM-DD`, from today to two years ahead |
| `memo` | string | A note to the customer, up to 1,000 characters |
| `terms` | string | Your payment terms, up to 2,000 characters |
| `reference` | string | Your own id, up to 64 characters |
| `allow_partial` | boolean | Let the customer pay in parts. Default `false` |
| `min_payment` | string | With `allow_partial`: the least first payment, such as a deposit of `"1000.00"`. Under the total |
| `allow_tip` | boolean | Let the customer add a tip. Default `false` |
| `reminders` | array | Days around the due date to email a reminder: from `-7`, `-3`, `-1`, `0`, `1`, `3`, `7`, `14` and `30`. Default none: Railbed only emails your customer when you ask it to |
| `email_receipts` | boolean | Email the customer a receipt for each payment. Default `true` |
| `owner_id`, `owner_email` | string | Who on your team it belongs to: an owner, manager or salesperson, by user id or by the email they sign in with. Not both |
| `routing` | object | Which card providers the customer's payments offer, as on a [payment link](https://railbed.com/docs/api/payment-links.md#the-routing-field) |
| `collect` | object | What the payment page asks besides the email, as on a [checkout session](https://railbed.com/docs/api/checkout-sessions.md#the-collect-field) |
| `success_url` | string | Where the customer lands once paid. Live mode needs a public `https://` page on your own site |
| `payout_wallet_id` | string | Pay one of the account's other saved wallets, `pw_…`, instead of its payout wallet (card only). See [payment links](https://railbed.com/docs/api/payment-links.md#create-a-payment-link) |
| `issue` | boolean | Issue it at once. Default `false` |
| `send` | boolean | Issue it and email it to the customer |
| `message` | string | With `send`: a few words shown above the invoice in the email, up to 1,000 characters |

Money is always a decimal string, never a JSON number. A field invoices don't have is refused with `400 unknown_field`, and the message names the one you probably meant, so `unitAmount` or `dueDate` can't be dropped without a word.

Example: cURL

```bash
curl https://pay.railbed.io/v1/invoices \
  -H "Authorization: Bearer $RAILBED_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: invoice-PO-1042" \
  -d '{
    "currency": "USD",
    "customer": { "name": "Ada Lovelace", "email": "ada@example.com", "company": "Analytical Engines Ltd" },
    "lines": [
      { "description": "Brand strategy workshop", "unit_amount": "3200.00" },
      { "description": "Design hours", "quantity": "12.5", "unit_amount": "150.00" }
    ],
    "tax": { "percent": "8.25", "label": "Sales tax" },
    "due_date": "2026-10-26",
    "terms": "Due within 30 days. Bank details on request.",
    "reference": "PO-1042",
    "allow_partial": true,
    "min_payment": "1000.00",
    "reminders": [-3, 0, 3],
    "send": true
  }'
```

Example: Node\.js

```js
const invoice = await fetch('https://pay.railbed.io/v1/invoices', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.RAILBED_SECRET_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': `invoice-${order.id}`,
  },
  body: JSON.stringify({
    currency: 'USD',
    customer: { name: 'Ada Lovelace', email: 'ada@example.com', company: 'Analytical Engines Ltd' },
    lines: [
      { description: 'Brand strategy workshop', unit_amount: '3200.00' },
      { description: 'Design hours', quantity: '12.5', unit_amount: '150.00' },
    ],
    tax: { percent: '8.25', label: 'Sales tax' },
    due_date: '2026-10-26',
    reference: 'PO-1042',
    send: true,
  }),
}).then((r) => r.json());
// invoice.url is the customer's page; invoice.email is the email just queued.
```

Example: Python

```python
invoice = requests.post(
    "https://pay.railbed.io/v1/invoices",
    headers={
        "Authorization": f"Bearer {os.environ['RAILBED_SECRET_KEY']}",
        "Idempotency-Key": f"invoice-{order_id}",
    },
    json={
        "currency": "USD",
        "customer": {"name": "Ada Lovelace", "email": "ada@example.com", "company": "Analytical Engines Ltd"},
        "lines": [
            {"description": "Brand strategy workshop", "unit_amount": "3200.00"},
            {"description": "Design hours", "quantity": "12.5", "unit_amount": "150.00"},
        ],
        "tax": {"percent": "8.25", "label": "Sales tax"},
        "due_date": "2026-10-26",
        "reference": "PO-1042",
        "send": True,
    },
    timeout=15,
).json()
```

Example: Response · response 201 Created

```json
{
  "id": "in_Vn3qT8kR5xWm2LcZp7Hb",
  "object": "invoice",
  "kind": "invoice",
  "number": "INV-0042",
  "status": "sent",
  "livemode": false,
  "url": "https://pay.railbed.io/i/4c9e1f7a2b6d48e3a5f0c8b1d7e2a9f3",
  "pdf_url": "https://pay.railbed.io/i/4c9e1f7a2b6d48e3a5f0c8b1d7e2a9f3/pdf",
  "currency": "USD",
  "lines": [
    {
      "description": "Brand strategy workshop",
      "quantity": "1",
      "unit_amount": "3200.00",
      "amount": "3200.00"
    },
    {
      "description": "Design hours",
      "quantity": "12.5",
      "unit_amount": "150.00",
      "amount": "1875.00"
    }
  ],
  "subtotal": "5075.00",
  "discount": "0.00",
  "discount_percent": null,
  "tax": "418.69",
  "tax_percent": "8.25",
  "tax_label": "Sales tax",
  "total": "5493.69",
  "amount_paid": "0.00",
  "amount_due": "5493.69",
  "tips": "0.00",
  "customer": {
    "id": "cus_Rk8mW3pZ6tQv1NxLc4Ys",
    "name": "Ada Lovelace",
    "email": "ada@example.com",
    "company": "Analytical Engines Ltd",
    "phone": null,
    "billing_address": null
  },
  "memo": "Thanks for your business.",
  "terms": "Due within 30 days. Bank details on request.",
  "reference": "PO-1042",
  "due_date": "2026-10-26",
  "allow_partial": true,
  "min_payment": "1000.00",
  "allow_tip": false,
  "reminders": [
    -3,
    0,
    3
  ],
  "email_receipts": true,
  "routing": {
    "choice": "buyer",
    "provider": null,
    "fallback": true,
    "providers": null
  },
  "collect": null,
  "success_url": null,
  "payout_wallet_id": null,
  "payment_link_id": null,
  "owner": null,
  "created_via": "api",
  "send_count": 1,
  "view_count": 0,
  "version": 0,
  "created": 1790380525,
  "updated": 1790380525,
  "issued_at": 1790380525,
  "last_sent_at": 1790380645,
  "viewed_at": null,
  "paid_at": null,
  "voided_at": null,
  "void_reason": null,
  "expires_at": null,
  "next_reminder_at": 1792746000,
  "email": {
    "id": "iem_Hc6tN1vQ9rXk4WmZb2Lp",
    "object": "invoice_email",
    "kind": "invoice",
    "to": "you@example.com",
    "test_copy": true,
    "status": "sent",
    "delivery": null,
    "error": null,
    "created": 1790380645,
    "sent_at": 1790380645
  }
}
```

**Retries.** Send an `Idempotency-Key` (1–120 printable ASCII characters) and a request that timed out can be sent again safely: the same key with the same body (compared as sent, in any field order) answers the invoice it made, with `200`, for 24 hours; the same key with a different body is `409 idempotency_conflict`. A draft deleted since frees its key.

**Sending with create.** With `send`, the invoice is made and issued first. If the email can't be queued (the customer's address bounced before, say), the invoice still comes back `201` with `email_error`, and its `url` works: fix the cause and [send it](#send-an-invoice), or share the link yourself.

**Test mode.** A Test invoice never emails its customer. Its email goes to the person behind the credential instead, marked as a Test copy: the person who created the key, or who connected the agent. Test invoices get no reminders or receipts, and only your team can pay them, as with every Test page.

| Error | Cause |
|---|---|
| `400 unknown_field` | A field invoices don't have. The message names the nearest one, and `field` the one you sent |
| `400 invalid_amount` | A `unit_amount`, `discount.amount` or `min_payment` isn't a decimal string, or the total is under 1.00, over 100,000.00, or under the smallest card payment the invoice's providers take |
| `400 invalid_lines`, `400 missing_description`, `400 invalid_quantity` | `lines` is empty or has more than 50, or a line has no description or a quantity out of range. `field` names it, such as `lines.1.quantity` |
| `400 invalid_customer`, `400 invalid_email`, `400 invalid_address` | `customer.id` isn't one of your customers in this mode, a customer field isn't text, the email isn't an address, or the billing address lacks a part its country needs |
| `400 invalid_discount`, `400 invalid_tax` | Not an amount or a percentage from 0.01 to 100, or a tax rate from 0 to 100 |
| `400 invalid_due_date` | Not a `YYYY-MM-DD` date from today to two years ahead |
| `400 invalid_min_payment` | Under 1.00, or not less than the total |
| `400 invalid_reminders` | A day that isn't one of `-7`, `-3`, `-1`, `0`, `1`, `3`, `7`, `14` or `30` |
| `400 invalid_owner` | `owner_id` or `owner_email` isn't an owner, manager or salesperson of the business, or both were sent |
| `400 customer_required` | `send` without the customer's name and email |
| `400 invalid_issue`, `400 invalid_send`, `400 invalid_message` | Not `true` or `false`; or `message` isn't text, is too long, or was sent without `send` |
| `400 invalid_routing`, `400 invalid_collect`, `400 invalid_url`, `400 invalid_payout_wallet` | As on [Create a payment link](https://railbed.com/docs/api/payment-links.md#create-a-payment-link) |
| `409 idempotency_conflict`, `409 idempotency_in_progress` | The key was used with a different body, or its first request hasn't finished: retry after `Retry-After` |
| `409 no_payout_wallet`, `409 account_review`, `409 payout_wallet_unusable` | Issuing or sending in Live mode, and the account can't take Live payments yet. A draft can still be made |
| `409 commerce_paused`, `403 integration_disabled` | The account has paused payments, or payment links or the API are turned off for it |

## Retrieve an invoice

`GET /v1/invoices/:id`

Returns one of your invoices in the credential's mode, as it is now. One in the other mode is `404 not_found`, and the message says which mode it's in.

Example: cURL

```bash
curl https://pay.railbed.io/v1/invoices/in_Vn3qT8kR5xWm2LcZp7Hb \
  -H "Authorization: Bearer $RAILBED_SECRET_KEY"
```

To see its payments, list them: `GET /v1/payments?invoice_id=in_Vn3qT8kR5xWm2LcZp7Hb`. A tip rides on its payment as `tip`, part of that payment's `amount`.

## Update an invoice

`PATCH /v1/invoices/:id`

Changes the fields you send and leaves the rest, with the parameters of [Create an invoice](#create-an-invoice) (not `issue`, `send` or `message`). Send `null` to clear a field, such as `"discount": null`. A draft takes any change. Once a customer has started paying an issued invoice, only `due_date`, `reminders`, `memo`, `terms`, `email_receipts` and the owner can change; a paid or void invoice changes only its owner. `payout_wallet_id` is chosen before it's issued.

| Parameter | Type | Description |
|---|---|---|
| `expected_version` | integer | The `version` you read. If anyone changed the invoice since, it answers `409 invoice_changed` instead of overwriting their change |

Example: cURL

```bash
curl -X PATCH https://pay.railbed.io/v1/invoices/in_Vn3qT8kR5xWm2LcZp7Hb \
  -H "Authorization: Bearer $RAILBED_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "due_date": "2026-11-09", "expected_version": 0 }'
```

Changing what an issued invoice asks for (its amounts, customer or payment options) closes any payment toward it that nobody has started, so the customer pays what it says now. A payment link's invoice is changed through [Payment links](https://railbed.com/docs/api/payment-links.md): here it's `409 payment_link`.

| Error | Cause |
|---|---|
| `409 invoice_changed` | Someone changed it since `expected_version`. Read it again, then make your change |
| `409 invoice_not_editable` | Payment has started, or it's paid or void. `field` names the first field refused |
| `400 not_editable` | `payout_wallet_id` on an issued invoice |
| `400 invalid_expected_version` | Not a whole number |

## List invoices

`GET /v1/invoices`

Returns your invoices in the credential's mode, newest first, payment links among them.

| Parameter | Type | Description |
|---|---|---|
| `limit` | integer | 1–100. Default 20 |
| `starting_after` | string | An invoice id from the previous page's `next_cursor` |
| `status` | string | One [status](#statuses), or `unpaid` for every issued invoice that can still be paid (sent, viewed, partly paid or overdue) |
| `kind` | string | `invoice` or `link` |
| `customer` | string | Only this customer's, `cus_…` |
| `owner` | string | Only those this person owns, `usr_…`, or `none` for those nobody owns |
| `reference` | string | Only invoices with exactly this reference |

Example: cURL

```bash
curl "https://pay.railbed.io/v1/invoices?status=overdue&kind=invoice" \
  -H "Authorization: Bearer $RAILBED_SECRET_KEY"
```

Example: Response · response 200 OK

```json
{
  "data": [
    {
      "id": "in_Vn3qT8kR5xWm2LcZp7Hb",
      "object": "invoice",
      "kind": "invoice",
      "number": "INV-0042",
      "status": "sent",
      "livemode": false,
      "url": "https://pay.railbed.io/i/4c9e1f7a2b6d48e3a5f0c8b1d7e2a9f3",
      "pdf_url": "https://pay.railbed.io/i/4c9e1f7a2b6d48e3a5f0c8b1d7e2a9f3/pdf",
      "currency": "USD",
      "lines": [
        {
          "description": "Brand strategy workshop",
          "quantity": "1",
          "unit_amount": "3200.00",
          "amount": "3200.00"
        },
        {
          "description": "Design hours",
          "quantity": "12.5",
          "unit_amount": "150.00",
          "amount": "1875.00"
        }
      ],
      "subtotal": "5075.00",
      "discount": "0.00",
      "discount_percent": null,
      "tax": "418.69",
      "tax_percent": "8.25",
      "tax_label": "Sales tax",
      "total": "5493.69",
      "amount_paid": "0.00",
      "amount_due": "5493.69",
      "tips": "0.00",
      "customer": {
        "id": "cus_Rk8mW3pZ6tQv1NxLc4Ys",
        "name": "Ada Lovelace",
        "email": "ada@example.com",
        "company": "Analytical Engines Ltd",
        "phone": null,
        "billing_address": null
      },
      "memo": "Thanks for your business.",
      "terms": "Due within 30 days. Bank details on request.",
      "reference": "PO-1042",
      "due_date": "2026-10-26",
      "allow_partial": true,
      "min_payment": "1000.00",
      "allow_tip": false,
      "reminders": [
        -3,
        0,
        3
      ],
      "email_receipts": true,
      "routing": {
        "choice": "buyer",
        "provider": null,
        "fallback": true,
        "providers": null
      },
      "collect": null,
      "success_url": null,
      "payout_wallet_id": null,
      "payment_link_id": null,
      "owner": null,
      "created_via": "api",
      "send_count": 0,
      "view_count": 0,
      "version": 0,
      "created": 1790380525,
      "updated": 1790380525,
      "issued_at": 1790380525,
      "last_sent_at": null,
      "viewed_at": null,
      "paid_at": null,
      "voided_at": null,
      "void_reason": null,
      "expires_at": null,
      "next_reminder_at": 1792746000
    }
  ],
  "has_more": false,
  "next_cursor": null
}
```

## Issue an invoice

`POST /v1/invoices/:id/issue`

Issues a draft without emailing it: from now on its `url` can be shared and paid, and its number and history stay. Use it when you send the link yourself, by text or chat; it needs no customer. No body is needed. An invoice already issued is `409 already_issued`, and a draft whose saved wallet was removed since is `400 invalid_payout_wallet`.

Example: cURL

```bash
curl -X POST https://pay.railbed.io/v1/invoices/in_Vn3qT8kR5xWm2LcZp7Hb/issue \
  -H "Authorization: Bearer $RAILBED_SECRET_KEY"
```

## Send an invoice

`POST /v1/invoices/:id/send`

Emails the invoice to its customer, issuing a draft first. The email comes from your business's name through Railbed's mail service, with replies going to the invoice's owner (or your business's support address), and carries the amount due, the due date, the lines, your message, a button to the invoice's page and its PDF. Sent again, it reads as a reminder. A Test invoice's copy goes to the person behind the credential instead of the customer.

| Parameter | Type | Description |
|---|---|---|
| `message` | string | A few words shown above the invoice, up to 1,000 characters |

Example: cURL

```bash
curl -X POST https://pay.railbed.io/v1/invoices/in_Vn3qT8kR5xWm2LcZp7Hb/send \
  -H "Authorization: Bearer $RAILBED_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "message": "Thanks again for last week. Here is the invoice for the workshop." }'
```

Example: Response · response 200 OK

```json
{
  "id": "in_Vn3qT8kR5xWm2LcZp7Hb",
  "object": "invoice",
  "kind": "invoice",
  "number": "INV-0042",
  "status": "sent",
  "livemode": false,
  "url": "https://pay.railbed.io/i/4c9e1f7a2b6d48e3a5f0c8b1d7e2a9f3",
  "pdf_url": "https://pay.railbed.io/i/4c9e1f7a2b6d48e3a5f0c8b1d7e2a9f3/pdf",
  "currency": "USD",
  "lines": [
    {
      "description": "Brand strategy workshop",
      "quantity": "1",
      "unit_amount": "3200.00",
      "amount": "3200.00"
    },
    {
      "description": "Design hours",
      "quantity": "12.5",
      "unit_amount": "150.00",
      "amount": "1875.00"
    }
  ],
  "subtotal": "5075.00",
  "discount": "0.00",
  "discount_percent": null,
  "tax": "418.69",
  "tax_percent": "8.25",
  "tax_label": "Sales tax",
  "total": "5493.69",
  "amount_paid": "0.00",
  "amount_due": "5493.69",
  "tips": "0.00",
  "customer": {
    "id": "cus_Rk8mW3pZ6tQv1NxLc4Ys",
    "name": "Ada Lovelace",
    "email": "ada@example.com",
    "company": "Analytical Engines Ltd",
    "phone": null,
    "billing_address": null
  },
  "memo": "Thanks for your business.",
  "terms": "Due within 30 days. Bank details on request.",
  "reference": "PO-1042",
  "due_date": "2026-10-26",
  "allow_partial": true,
  "min_payment": "1000.00",
  "allow_tip": false,
  "reminders": [
    -3,
    0,
    3
  ],
  "email_receipts": true,
  "routing": {
    "choice": "buyer",
    "provider": null,
    "fallback": true,
    "providers": null
  },
  "collect": null,
  "success_url": null,
  "payout_wallet_id": null,
  "payment_link_id": null,
  "owner": null,
  "created_via": "api",
  "send_count": 1,
  "view_count": 0,
  "version": 0,
  "created": 1790380525,
  "updated": 1790380525,
  "issued_at": 1790380525,
  "last_sent_at": 1790380645,
  "viewed_at": null,
  "paid_at": null,
  "voided_at": null,
  "void_reason": null,
  "expires_at": null,
  "next_reminder_at": 1792746000,
  "email": {
    "id": "iem_Hc6tN1vQ9rXk4WmZb2Lp",
    "object": "invoice_email",
    "kind": "invoice",
    "to": "you@example.com",
    "test_copy": true,
    "status": "sent",
    "delivery": null,
    "error": null,
    "created": 1790380645,
    "sent_at": 1790380645
  }
}
```

The email is queued and tried at once; `email.status` is `sent` once the mail service took it, and `email.delivery` later says what the inbox did with it (`delivered`, `bounced` and so on), on the invoice's page in the dashboard too. An invoice can be emailed once a minute and 10 times a day, and a business can send 200 invoice emails a day.

| Error | Cause |
|---|---|
| `409 invoice_not_payable` | It's paid, void or expired |
| `409 email_suppressed` | The customer's address bounced or reported an earlier email as spam. Fix it with [Update an invoice](#update-an-invoice) before payment starts, or share the `url` another way |
| `409 email_blocked` | Email can't go for this business right now, such as while it's paused. Share the `url` |
| `400 customer_required` | The invoice has no customer name or email yet |
| `429 email_too_soon`, `429 email_limit` | Emailed in the last minute, or over a daily limit |
| `503 email_unavailable` | Email can't be sent right now. Share the `url` |

### The email object

| Field | Type | Description |
|---|---|---|
| `id` | string | `iem_…` |
| `object` | string | `"invoice_email"` |
| `kind` | string | `invoice`, `reminder` (any send after the first, and scheduled reminders) or `receipt` |
| `to` | string | Where it went |
| `test_copy` | boolean | A Test invoice's copy to your team |
| `status` | string | `pending` (queued or being retried), `sent` (the mail service took it) or `failed` (it won't be sent, and `error` says why) |
| `delivery` | string or null | What the inbox said: `delivered`, `delayed`, `bounced`, `complained`, `suppressed` or `failed` |
| `error` | string or null | Why it failed |
| `created`, `sent_at` | integer | When it was queued and handed to the mail service |

## Void an invoice

`POST /v1/invoices/:id/void`

Voids an issued invoice: its page says so and it can't be paid any more. Payments toward it that nobody has started are closed. One a customer has already taken to a card provider stays open, because their money may be on its way, and money that arrives still settles and counts. Voiding again returns the same invoice. A draft is deleted instead, and a paid invoice can't be voided.

| Parameter | Type | Description |
|---|---|---|
| `reason` | string | Why, for your records and the invoice's history, up to 200 characters. Never shown to the customer |

Example: cURL

```bash
curl -X POST https://pay.railbed.io/v1/invoices/in_Vn3qT8kR5xWm2LcZp7Hb/void \
  -H "Authorization: Bearer $RAILBED_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Replaced by INV-0043" }'
```

Example: Response · response 200 OK

```json
{
  "id": "in_Vn3qT8kR5xWm2LcZp7Hb",
  "object": "invoice",
  "kind": "invoice",
  "number": "INV-0042",
  "status": "void",
  "livemode": false,
  "url": "https://pay.railbed.io/i/4c9e1f7a2b6d48e3a5f0c8b1d7e2a9f3",
  "pdf_url": "https://pay.railbed.io/i/4c9e1f7a2b6d48e3a5f0c8b1d7e2a9f3/pdf",
  "currency": "USD",
  "lines": [
    {
      "description": "Brand strategy workshop",
      "quantity": "1",
      "unit_amount": "3200.00",
      "amount": "3200.00"
    },
    {
      "description": "Design hours",
      "quantity": "12.5",
      "unit_amount": "150.00",
      "amount": "1875.00"
    }
  ],
  "subtotal": "5075.00",
  "discount": "0.00",
  "discount_percent": null,
  "tax": "418.69",
  "tax_percent": "8.25",
  "tax_label": "Sales tax",
  "total": "5493.69",
  "amount_paid": "0.00",
  "amount_due": "5493.69",
  "tips": "0.00",
  "customer": {
    "id": "cus_Rk8mW3pZ6tQv1NxLc4Ys",
    "name": "Ada Lovelace",
    "email": "ada@example.com",
    "company": "Analytical Engines Ltd",
    "phone": null,
    "billing_address": null
  },
  "memo": "Thanks for your business.",
  "terms": "Due within 30 days. Bank details on request.",
  "reference": "PO-1042",
  "due_date": "2026-10-26",
  "allow_partial": true,
  "min_payment": "1000.00",
  "allow_tip": false,
  "reminders": [
    -3,
    0,
    3
  ],
  "email_receipts": true,
  "routing": {
    "choice": "buyer",
    "provider": null,
    "fallback": true,
    "providers": null
  },
  "collect": null,
  "success_url": null,
  "payout_wallet_id": null,
  "payment_link_id": null,
  "owner": null,
  "created_via": "api",
  "send_count": 0,
  "view_count": 0,
  "version": 1,
  "created": 1790380525,
  "updated": 1790384125,
  "issued_at": 1790380525,
  "last_sent_at": null,
  "viewed_at": null,
  "paid_at": null,
  "voided_at": 1790384125,
  "void_reason": "Replaced by INV-0043",
  "expires_at": null,
  "next_reminder_at": null
}
```

## Delete a draft invoice

`DELETE /v1/invoices/:id`

Deletes a draft. An issued invoice is never deleted: [void it](#void-an-invoice), so its number and history stay (`409 not_draft`).

Example: cURL

```bash
curl -X DELETE https://pay.railbed.io/v1/invoices/in_Vn3qT8kR5xWm2LcZp7Hb \
  -H "Authorization: Bearer $RAILBED_SECRET_KEY"
```

Example: Response · response 200 OK

```json
{
  "id": "in_Vn3qT8kR5xWm2LcZp7Hb",
  "object": "invoice",
  "deleted": true
}
```

## Download an invoice PDF

`GET /v1/invoices/:id/pdf`

Answers the invoice as a PDF (`application/pdf`), as its customer gets it: your logo, the lines and totals, the payments received, and the due date. A draft is marked Draft, and a paid invoice reads as a receipt. The file is named after the invoice's number.

Example: cURL

```bash
curl https://pay.railbed.io/v1/invoices/in_Vn3qT8kR5xWm2LcZp7Hb/pdf \
  -H "Authorization: Bearer $RAILBED_SECRET_KEY" \
  -o INV-0042.pdf
```

## Webhooks

Choose the invoice events for an endpoint, in [Developers](https://app.railbed.io/developers) or with `events` on [Create a webhook endpoint](https://railbed.com/docs/api/webhook-endpoints.md#create-a-webhook-endpoint): `invoice.issued`, `invoice.sent`, `invoice.viewed`, `invoice.partially_paid`, `invoice.paid` and `invoice.voided`. An endpoint made without a list gets the payment events only, so nothing new arrives at a receiver that didn't ask. Each payment toward an invoice also sends its own `payment.*` events, with `invoiceId` and `tip`. See [Event types](https://railbed.com/docs/webhooks/events.md#invoice-events).

## Access

Retrieving, listing and downloading need the `payments:read` [scope](https://railbed.com/docs/api.md#scopes), which **Read only** keys have. Creating, changing, issuing, sending, voiding and deleting need `checkouts:write`, which **Full access** keys and agents with full access have. A change made with a key is recorded on the invoice's history as the key's, under its name, never as a person's.
