invoices
Finance module · 7 operations
List invoice rows
GET/invoices
An invoice issued or received. A closed production refuses new invoices. Returns a cursor page of invoice rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.
Create an invoice
POST/invoices
An invoice issued or received. A closed production refuses new invoices. Creates an invoice. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.
Get an invoice
GET/invoices/{id}
An invoice issued or received. A closed production refuses new invoices. Returns one invoice with its `ETag`. A invoice the caller may not see returns 404.
Update an invoice
PATCH/invoices/{id}
An invoice issued or received. A closed production refuses new invoices. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.
Transition the invoice state
POST/invoices/{id}/transitions
Moves the invoice lifecycle to another state through its transition RPC, which writes the transition ledger. Uses compare-and-set on `expected_state`; a disallowed transition returns a 422 refusal. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.
Approve a invoice
POST/invoices/{id}/approve
Records an approval decision on the invoice. Three-way match must pass, and a person who created the vendor or edited its bank details cannot approve payment to it. Spend authority and separation of duties are enforced in the approval RPC; a refusal returns 422 and names the rule. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.
Record a payment
POST/invoices/{id}/record-payment
Records that an approved payable (or issued receivable) was paid: a Proposed payment of the invoice's payee, its counterparty or the person engaged as an individual, applied to the invoice for the whole balance unless `amount_minor` says otherwise. Money moves on the org's own rails; XOS never holds funds. Another eligible person approves the payment. Refuses a Proposed, Disputed or Canceled invoice and an invoice with nothing left to pay (422). Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.