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.

On this page

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 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 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 is listed here too, as kind: "link", so one list holds everything your customers owe; change a link through the payment links endpoints.

FieldTypeDescription
idstringThe invoice's id, in_…
objectstring"invoice"
kindstringinvoice for one built as an invoice, link for a payment link
numberstringINV-0042, counted per account and mode, payment links included
statusstringdraft, sent, viewed, partially_paid, overdue, paid, void or expired. See Statuses
livemodebooleanfalse for Test mode, true for Live mode
urlstring or nullThe customer's page, where they pay. Send them this. null for a draft
pdf_urlstring or nullThe PDF the customer can download from their page. null for a draft. Download an invoice PDF works for drafts too
currencystringUSD, EUR, GBP, CAD, AUD, INR or SEK
linesarrayEach line's description, quantity ("12.5"), unit_amount and amount (quantity × unit_amount, rounded half up to the cent)
subtotalstringThe lines added up
discountstringTaken off the subtotal, "0.00" for none
discount_percentstring or nullSet when the discount is a percentage ("10")
taxstringTax on the subtotal less the discount, "0.00" for none
tax_percent, tax_labelstring or nullThe tax's rate ("8.25") and name ("Sales tax")
totalstringWhat the invoice asks for
amount_paidstringPaid toward the total so far. Tips never count
amount_duestringWhat's left to pay
tipsstringTips customers added on top, "0.00" for none
customerobjectid (cus_…, the saved customer, once there is one), name, email, company, phone and billing_address
memostring or nullYour note to the customer
termsstring or nullYour payment terms
referencestring or nullYour own id, such as a purchase order number
due_datestring or nullYYYY-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_partialbooleanWhether the customer may pay in parts
min_paymentstring or nullWith allow_partial: the least first payment, a deposit
allow_tipbooleanWhether the customer may add a tip
remindersarray or nullDays around the due date when Railbed emails a reminder (negative: before it), such as [-3, 0, 3]
email_receiptsbooleanWhether the customer gets a receipt for each payment
routingobjectWhich card providers the customer's payments offer. See The routing field
collectobject or nullWhat the customer's payment page asks besides their email. See The collect field
success_urlstring or nullWhere the customer lands once paid
payout_wallet_idstring or nullThe saved wallet the invoice pays, pw_…, or null for the account's payout wallet
payment_link_idstring or nullA link invoice's payment link, pay_…. null for an invoice
ownerobject or nullThe person on your team it belongs to: id (usr_…), name and email. Invoices made with a key have none unless you name one
created_viastringWhere it was made: dashboard, api, mcp, telegram or slack
send_countintegerHow many times Railbed emailed it, reminders included
view_countintegerHow many times its customer opened it
versionintegerGoes up with every change. Send it back as expected_version when you update it
created, updatedintegerWhen it was made and last changed, in Unix seconds
issued_at, last_sent_at, viewed_at, paid_at, voided_atinteger or nullWhen it was issued, last emailed, first opened by its customer, paid in full and voided
void_reasonstring or nullYour reason for voiding it. Never shown to the customer
expires_atinteger or nullPayment links only: when it stops being payable
next_reminder_atinteger or nullWhen the next reminder goes, in Unix seconds
warningsarrayOn create and update only, and only when there is something to say: what the card providers' minimums mean for this total. See Provider minimums
emailobjectOn Send an invoice, and create with send: the email just queued. See The email object
email_errorobjectOn 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 would answer
An invoice
{
  "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
}
200 OK

Statuses

StatusMeaning
draftNot issued. It has no page, can change freely, and can be deleted
sentIssued: 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
viewedIts customer opened it
partially_paidPart of it is paid and the rest is due
overduePast its due date with something still to pay
paidPaid in full. It can't change or be voided
voidVoided: it can't be paid any more
expiredA 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 or send 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.

ParameterTypeDescription
currencystring RequiredUSD, EUR, GBP, CAD, AUD, INR or SEK, in any letter case
linesarray Required1–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
customerobjectWho 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
discountobject{ "amount": "25.00" } or { "percent": "10" }, taken off the subtotal
taxobject{ "percent": "8.25", "label": "Sales tax" }, on the subtotal less the discount
due_datestringYYYY-MM-DD, from today to two years ahead
memostringA note to the customer, up to 1,000 characters
termsstringYour payment terms, up to 2,000 characters
referencestringYour own id, up to 64 characters
allow_partialbooleanLet the customer pay in parts. Default false
min_paymentstringWith allow_partial: the least first payment, such as a deposit of "1000.00". Under the total
allow_tipbooleanLet the customer add a tip. Default false
remindersarrayDays 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_receiptsbooleanEmail the customer a receipt for each payment. Default true
owner_id, owner_emailstringWho on your team it belongs to: an owner, manager or salesperson, by user id or by the email they sign in with. Not both
routingobjectWhich card providers the customer's payments offer, as on a payment link
collectobjectWhat the payment page asks besides the email, as on a checkout session
success_urlstringWhere the customer lands once paid. Live mode needs a public https:// page on your own site
payout_wallet_idstringPay one of the account's other saved wallets, pw_…, instead of its payout wallet (card only). See payment links
issuebooleanIssue it at once. Default false
sendbooleanIssue it and email it to the customer
messagestringWith 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.

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
  }'
Response
{
  "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
  }
}
201 Created

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, 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.

ErrorCause
400 unknown_fieldA field invoices don't have. The message names the nearest one, and field the one you sent
400 invalid_amountA 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_quantitylines 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_addresscustomer.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_taxNot an amount or a percentage from 0.01 to 100, or a tax rate from 0 to 100
400 invalid_due_dateNot a YYYY-MM-DD date from today to two years ahead
400 invalid_min_paymentUnder 1.00, or not less than the total
400 invalid_remindersA day that isn't one of -7, -3, -1, 0, 1, 3, 7, 14 or 30
400 invalid_ownerowner_id or owner_email isn't an owner, manager or salesperson of the business, or both were sent
400 customer_requiredsend without the customer's name and email
400 invalid_issue, 400 invalid_send, 400 invalid_messageNot 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_walletAs on Create a payment link
409 idempotency_conflict, 409 idempotency_in_progressThe 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_unusableIssuing 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_disabledThe 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.

cURL
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 (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.

ParameterTypeDescription
expected_versionintegerThe version you read. If anyone changed the invoice since, it answers 409 invoice_changed instead of overwriting their change
cURL
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: here it's 409 payment_link.

ErrorCause
409 invoice_changedSomeone changed it since expected_version. Read it again, then make your change
409 invoice_not_editablePayment has started, or it's paid or void. field names the first field refused
400 not_editablepayout_wallet_id on an issued invoice
400 invalid_expected_versionNot a whole number

List invoices

GET /v1/invoices

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

ParameterTypeDescription
limitinteger1–100. Default 20
starting_afterstringAn invoice id from the previous page's next_cursor
statusstringOne status, or unpaid for every issued invoice that can still be paid (sent, viewed, partly paid or overdue)
kindstringinvoice or link
customerstringOnly this customer's, cus_…
ownerstringOnly those this person owns, usr_…, or none for those nobody owns
referencestringOnly invoices with exactly this reference
cURL
curl "https://pay.railbed.io/v1/invoices?status=overdue&kind=invoice" \
  -H "Authorization: Bearer $RAILBED_SECRET_KEY"
Response
{
  "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
}
200 OK

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.

cURL
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.

ParameterTypeDescription
messagestringA few words shown above the invoice, up to 1,000 characters
cURL
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." }'
Response
{
  "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
  }
}
200 OK

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.

ErrorCause
409 invoice_not_payableIt's paid, void or expired
409 email_suppressedThe customer's address bounced or reported an earlier email as spam. Fix it with Update an invoice before payment starts, or share the url another way
409 email_blockedEmail can't go for this business right now, such as while it's paused. Share the url
400 customer_requiredThe invoice has no customer name or email yet
429 email_too_soon, 429 email_limitEmailed in the last minute, or over a daily limit
503 email_unavailableEmail can't be sent right now. Share the url

The email object

FieldTypeDescription
idstringiem_…
objectstring"invoice_email"
kindstringinvoice, reminder (any send after the first, and scheduled reminders) or receipt
tostringWhere it went
test_copybooleanA Test invoice's copy to your team
statusstringpending (queued or being retried), sent (the mail service took it) or failed (it won't be sent, and error says why)
deliverystring or nullWhat the inbox said: delivered, delayed, bounced, complained, suppressed or failed
errorstring or nullWhy it failed
created, sent_atintegerWhen 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.

ParameterTypeDescription
reasonstringWhy, for your records and the invoice's history, up to 200 characters. Never shown to the customer
cURL
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" }'
Response
{
  "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
}
200 OK

Delete a draft invoice

DELETE /v1/invoices/:id

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

cURL
curl -X DELETE https://pay.railbed.io/v1/invoices/in_Vn3qT8kR5xWm2LcZp7Hb \
  -H "Authorization: Bearer $RAILBED_SECRET_KEY"
Response
{
  "id": "in_Vn3qT8kR5xWm2LcZp7Hb",
  "object": "invoice",
  "deleted": true
}
200 OK

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.

cURL
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 or with events on 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.

Access

Retrieving, listing and downloading need the payments:read scope, 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.

Updated · This page as Markdown