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.

Computed fields (subtotal, vatAmount, total, amountPaid) are read-only and maintained by the API as line items change or payments are recorded. The status field is managed via the status, payment, and email endpoints; on create the only choice is the initial draft or sent.

List rows carry a compact shape including contactName and contactEmail; single-invoice reads include the full contact object and lines instead.

Attributes

idstring
Prefixed string identifier. Always starts with inv_ (e.g. inv_42).
invoiceNumberstring
Sequential number assigned on creation (e.g. INV-0042). Unique per organisation. Read-only.
invoiceTypestring
Either sales (issued to a customer) or purchase (received from a supplier). Immutable after creation.
contactIdstring
Prefixed ID of the linked contact (e.g. cont_3).
statusstring
Current lifecycle state, one of the seven stored values. Transitions follow the enforced table in the resource description; partial/paid are payment-derived and credited is reserved.
issueDatestring
Invoice issue date, the tax point. YYYY-MM-DD.
dueDatestring
Payment due date. YYYY-MM-DD.
subtotalstring
Sum of all line item net amounts, in pence. Computed by the API. Read-only.
vatAmountstring
Sum of all line item VAT amounts, in pence. Computed by the API. Read-only.
totalstring
Invoice total including VAT, in pence (subtotal + vatAmount). Computed by the API. Read-only.
amountPaidstring
Cumulative total of all payments recorded against this invoice, in pence. Increases with each payment. Read-only.
sentAtstring
ISO 8601 timestamp of the FIRST issue of the invoice, stamped once and never restamped by re-sends or subsequent transitions. null until first issued.
createdBystring
Integer id of the user who created the invoice, or null when it was created with an API key.
referencestring
Optional external reference such as a purchase order number. Max 100 characters. Empty string when unset.
notesstring
Optional freeform notes on the invoice. Max 2000 characters. Null when never set, empty string when set to empty.
termsstring
Optional payment terms text shown on the invoice. Max 2000 characters. Empty string when unset.
metadatastring
Custom string key-value pairs. Max 50 keys; keys prefixed _sb_ are reserved.
createdAtstring
ISO 8601 creation timestamp.
updatedAtstring
ISO 8601 last-updated timestamp.
contactstring
On single-invoice reads, the embedded contact object (name, email, phone, VAT number, address parts). List rows instead carry the compact contactName and contactEmail.
linesstring
Array of line items in sort order. Each line carries quantity (units), unitPrice (pence on read), vatRate (integer percent), computed vatAmount and lineTotal (pence), and the account mapping (accountId, accountCode, accountName).