Invoices

Invoices represent amounts owed to or by your organisation. Sales invoices are issued to contacts (customers); purchase invoices are bills received from suppliers.

Invoices follow a lifecycle: draft → sent → paid (or partial → overdue → cancelled / written_off). Status transitions are enforced by the API — you cannot set status directly except via the status update endpoint. Valid transitions are:

• draft → sent, cancelled
• sent → paid, partial, overdue, cancelled, written_off
• partial → paid, overdue, cancelled, written_off
• overdue → paid, partial, cancelled, written_off

All monetary values are in pence (minor units). An invoice with total: 180000 represents £1,800.00. Line items reference accounts from your chart of accounts via accountId. VAT is calculated per line item based on the specified vatRate.

When an invoice is finalised (status moves from draft to sent), SpeyBooks creates the corresponding double-entry journal transaction: debit Trade Debtors, credit the revenue accounts specified in the line items. This transaction is immutable — to correct a finalised invoice, cancel it and create a new one.

Invoices support custom metadata (Stripe-style key-value pairs) and can be filtered by type, status, contact, and date range. Payments are recorded via a dedicated endpoint which automatically transitions the status to paid or partial based on the cumulative amount paid.