SalesInvoice
A sales invoice header: what a customer is billed, when it is due, and how far it has got through the accounting sync.
- Summary view
- SalesInvoiceList, 28 fields. What a list returns by default.
- Detail view
- SalesInvoice, 30 fields. The default for a single read and for every write.
- Read with
- api:
read: andsales_invoices::sales_invoices read - Write with
- api:
write: andsales_invoices::sales_invoices create
The money on it is the sum of its rows, which are reached through sales-invoices/{sales_invoice}/rows; the API never writes rows inline. Invoices that predate the current invoicing flow are marked is_legacy and are read-only.
Used by
Fields
- Detail only
- Only in the detail view.
- Only with include
- Only when you ask for it with include.
- Server-assigned
- Set by plnnrly, never by a request.
The customer this invoice is billed to. Expanding it with ?include=customer additionally requires the customers::read permission and a token scope covering the customers prefix.
Customer subscription this invoice was generated from, when it was generated from a renewal.
Invoice number, allocated by the server from the organisation's yearly sequence: B-26-00001 for an invoice raised in this flow, L-1234 for one converted from a legacy invoice. It also works in the path: GET sales-invoices/B-26-00001 works. This is the field ?q= searches.
The customer's own reference, typically a purchase-order number, reproduced on the invoice.
Invoice date, a zone-free calendar date. Newest first is the default sort.
Date payment is due, a zone-free calendar date. Null when no term was applied.
Lifecycle status. Resolved by the server on create and never writable: a caller without sales_invoices::finalize creates a pending_approval invoice, and any update by such a caller returns the invoice to pending_approval.
draftpending_approvalsentpaidoverduecancelled
New values may be added.
Whether the invoice is emailed to the customer when it syncs. The email is sent through the accounting integration, so it is forced to false in an organisation with no integration configured. Writing it requires sales_invoices::finalize.
Sum of the row line totals excluding VAT, as a decimal string. Recomputed from the rows; never written directly.
2 decimal places, may be negative
Sum of the row VAT amounts, as a decimal string. Recomputed from the rows; never written directly.
2 decimal places, may be negative
Subtotal plus VAT, as a decimal string. Recomputed from the rows; never written directly.
2 decimal places, may be negative
The accounting system's own identifier for this invoice, written by the sync. Not a local id.
Sales journal the invoice is booked in, resolved from the organisation's accounting settings on create. Null in an organisation with no integration configured.
How far the invoice has got through the accounting sync. Set on create: local in an organisation with no integration configured, pending otherwise.
pendingsyncedfailedlocal
New values may be added.
Why the last sync attempt failed, verbatim from the accounting system. Null while nothing has failed.
When the invoice last synced successfully.
When the invoice was last handed to the sync, successfully or not.
When the invoice was settled. Set on create for a local invoice that is immediately definitive; otherwise written when payment is registered.
Whether this invoice was converted from a legacy invoice. Such an invoice is read-only: PATCH and DELETE answer 409 state-conflict with reason locked_by_legacy.
The id of the legacy invoice this invoice was converted from, so it can be matched with GET /api/v2/invoices. The legacy invoice may since have been removed.
Notes for colleagues. Never rendered on the invoice the customer receives.
Last-write timestamp; use for incremental sync. It also feeds the ETag revision, because a sales invoice has no version field.
Variants
SalesInvoiceList 28 fields
What a collection returns, and what ?view=summary returns on a single record.
Leaves out: sync_error, internal_notes
SalesInvoiceSummary 3 fields
The embedded form: what you get when another resource carries this one and you did not include it.
Leaves out: customer_id, customer, project_id, customer_subscription_id, reference, description, due_date, status, should_email, subtotal, vat_total, total, exact_invoice_id, exact_journal, sync_status, sync_error, synced_at, sync_attempted_at, paid_at, is_legacy, legacy_invoice_id, internal_notes, rows_count, created_at, updated_at, deleted_at, links
SalesInvoiceLinks 2 fields
The links object on this resource.
Keys: self, rows
Something wrong or missing on this page? Tell us