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.
| 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 |
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 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, 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 |
collect | object or null | What the customer's payment page asks besides their email. See 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 |
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 |
email | object | On Send an invoice, and create with send: the email just queued. See 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 would answer |
{
"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 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.
| 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 |
collect | object | What the payment page asks besides the email, as on a checkout session |
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 |
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.
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
}'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.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(){
"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, 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 |
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.
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.
| 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 |
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.
| 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, 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 |
curl "https://pay.railbed.io/v1/invoices?status=overdue&kind=invoice" \
-H "Authorization: Bearer $RAILBED_SECRET_KEY"{
"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.
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 |
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." }'{
"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 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 |
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" }'{
"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, so its number and history stay (409 not_draft).
curl -X DELETE https://pay.railbed.io/v1/invoices/in_Vn3qT8kR5xWm2LcZp7Hb \
-H "Authorization: Bearer $RAILBED_SECRET_KEY"{
"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.
curl https://pay.railbed.io/v1/invoices/in_Vn3qT8kR5xWm2LcZp7Hb/pdf \
-H "Authorization: Bearer $RAILBED_SECRET_KEY" \
-o INV-0042.pdfWebhooks
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.