The Invoices object

The Invoice object represents a sales or purchase invoice linked to a contact. It contains header fields (dates, reference, terms), computed totals (subtotal, vatAmount, total), and an array of line items.

The invoiceNumber is assigned automatically on creation (e.g. INV-0043) and is sequential per organisation. Computed fields (subtotal, vatAmount, total, amountPaid) are read-only and updated by the API when line items change or payments are recorded. The status field is managed via the status update and payment endpoints — it cannot be set directly on create or update except for the initial draft / sent choice.

Attributes

id string
Prefixed string identifier. Always starts with inv_ (e.g. inv_42).
invoiceNumber string
Sequential number assigned on creation (e.g. INV-0042). Unique per organisation. Read-only.
invoiceType string
Either sales (issued to a customer) or purchase (received from a supplier). Immutable after creation.
status string
Current lifecycle state. Transitions are enforced by the API — see the Update Status endpoint for valid transitions.
subtotal string
Sum of all line item net amounts, in pence. Computed by the API. Read-only.
vatAmount string
Sum of all line item VAT amounts, in pence. Computed by the API. Read-only.
total string
Invoice total including VAT, in pence (subtotal + vatAmount). Computed by the API. Read-only.
amountPaid string
Cumulative total of all payments recorded against this invoice, in pence. Increases with each payment. Read-only.
sentAt string
ISO 8601 timestamp when the invoice was first transitioned to sent status, or null if still in draft.
reference string
Optional external reference such as a purchase order number. Max 100 characters.
metadata string
Custom key-value pairs (Stripe-style). Max 50 keys, values must be strings. Keys prefixed _sb_ are reserved.
lines string
Array of line items in sort order. Each references an account from your chart of accounts via accountId.