API reference

Invoices

An invoice is a numbered bill to a named customer with a due date.

The states, in the order an object moves through them. Where a step lists several, the object takes one of them.

draftEditable, no order
openFinalized: the number is assigned, the order exists, the page https://pay.orrerie.com/i/<inv_id> works
paid or void

overdue is a flag on an open invoice past its due date. Finalizing creates exactly one order, which expires 30 days after the due date; paying the order pays the invoice. Numbers are INV- plus a per-merchant counter padded to four digits, never reused.

tax_amount is a figure you type. Orrerie calculates no tax and gives no tax advice.

The `invoice` object

JSON

{
  "id": "inv_sxr44t9zk7krg104gmhsqx2p",
  "object": "invoice",
  "livemode": true,
  "created": "2026-10-08T09:00:00.000Z",
  "updated": "2026-10-08T09:02:00.000Z",
  "number": "INV-0042",
  "status": "open",
  "overdue": false,
  "customer": "cus_8ea07c40qsvv19f7rgmeb8ha",
  "order": "ord_18ayqdcy8s50t2dp5r257ep3",
  "currency": "USD",
  "line_items": [
    {
      "name": "Wholesale beans, 20 kg",
      "quantity": 20,
      "unit_amount": "17.50",
      "amount": "350.00",
      "price": null
    }
  ],
  "subtotal": "350.00",
  "discount_amount": "0.00",
  "tax_amount": "0.00",
  "total": "350.00",
  "amount_paid": "0.00",
  "amount_due": "350.00",
  "due_date": "2026-10-22",
  "memo": "Thank you for your order.",
  "footer": "Acme Coffee Roasters LLC",
  "url": "https://pay.orrerie.com/i/inv_sxr44t9zk7krg104gmhsqx2p",
  "pdf": "file_jgxe7twfcheqtdha9pafpnc3",
  "reminders": {
    "days_before_due": [
      3
    ],
    "days_after_due": [
      1,
      7
    ]
  },
  "finalized_at": "2026-10-08T09:02:00.000Z",
  "sent_at": "2026-10-08T09:02:05.000Z",
  "paid_at": null,
  "voided_at": null,
  "metadata": {}
}

Table: The invoice object
Field	Meaning
`status`	One of `draft`, `open`, `paid`, `void`.

Every field

Fields of the `invoice` object

Fields of the invoice object
Field	Type	Meaning
`id`	string	Unique identifier: the object prefix, an underscore, 24 lower-case Crockford base32 characters.
`object`	string	The type of this object.
`livemode`	boolean	`true` for live mode (real money); `false` for test mode (simulated payments).
`created`	string (date-time)	When the object was created. RFC 3339, UTC, milliseconds.
`updated`	string (date-time)	When the object last changed.
`number`	string or null	The invoice number, `INV-` and a counter; `null` while the invoice is a draft.
`status`	string	One of `draft`, `open`, `paid`, `void`.
`overdue`	boolean	`true` when the invoice is open and past its due date.
`customer`	object	The `cus_` id billed, or the customer object when expanded.
`order`	object	The `ord_` id the invoice is paid through, or the order object when expanded; `null` while a draft.
`currency`	string	The currency the invoice is in.
`line_items`	array of objects	What the invoice bills, line by line.
`line_items[].name`	string	The item's name, as shown to the payer.
`line_items[].quantity`	integer	How many of the item.
`line_items[].unit_amount`	string	The price of one, a decimal string in the invoice's currency.
`line_items[].amount`	string	The line's total: quantity times the unit amount.
`line_items[].price`	string or null	The `price_` id the line was made from; `null` for a line given by name and amount.
`subtotal`	string	The sum of the lines.
`discount_amount`	string	The discount taken off the subtotal.
`tax_amount`	string	The tax added, as the merchant typed it. Orrerie calculates no tax.
`total`	string	What the invoice asks for: subtotal minus discount plus tax.
`amount_paid`	string	What has been paid.
`amount_due`	string	What is still to pay.
`due_date`	string	The day payment is due, `YYYY-MM-DD`.
`memo`	string or null	A note printed on the invoice; `null` for none.
`footer`	string or null	Text printed at the bottom of the invoice; `null` for none.
`url`	string or null	The invoice's page on the payer site; `null` while a draft.
`pdf`	string or null	The `file_` id of the invoice's PDF; `null` until it is made.
`reminders`	object	When the customer is reminded to pay.
`reminders.days_before_due`	array of integers	Days before the due date a reminder is sent.
`reminders.days_after_due`	array of integers	Days after the due date a reminder is sent.
`finalized_at`	string (date-time) or null	When the invoice was finalized; `null` while a draft.
`sent_at`	string (date-time) or null	When the invoice was emailed; `null` until then.
`paid_at`	string or null	When the invoice was paid; `null` until then.
`voided_at`	string or null	When the invoice was voided; `null` unless it was.
`metadata`	object	Up to 50 keys of your own data. Key up to 40 characters, value a string up to 500 characters. Never used by Orrerie; never put secrets or personal data here.

Endpoints

Events

Webhook events whose data.object is an object of this page.