Invoices

Customer invoice with independent lifecycle, settlement state, and disputes.

Business object

Vue d’ensemble

Invoice endpoints cover creation, invoice transitions, attached documents, and relationships with orders, lines, and disputes.

See also the business-model page invoice for semantics, relationships, and functional lifecycle.

Contrat JSON

Responses use the prefixed identifier inv_ and the field object to make the type explicit.

buyer_idstring

Identifier of the buyer company, when applicable.

statusenum

Document lifecycle: `draft`, `issued`, `sent`, `received`, `cancelled`, or `written_off`.

settlement_statusenum

Settlement state: `unpaid`, `partially_paid`, or `paid`.

amount_excluding_tax / amount_tax / amount_including_taxnumber

Invoice amounts. `amount_including_tax` must equal `amount_excluding_tax + amount_tax`.

currencystring

ISO currency of the amount.

due_datedate

Due date.

documentobject

Invoice document attached through document endpoints.

REST

Method	Endpoint	Usage
POST	`/v1/invoices`	Create an invoice.
GET	`/v1/invoices`	List invoices, with filters for `merchant_id`, `buyer_id`, `source_reference`, `type`, `status`, or `settlement_status`.
GET	`/v1/invoices/eligible-allocation`	List invoices eligible for a payment allocation.
GET	`/v1/invoices/{id}`	Retrieve an invoice.
POST	`/v1/invoices/{id}`	Update an invoice.
POST	`/v1/invoices/{id}/issue`	Issue an invoice.
POST	`/v1/invoices/{id}/send`	Mark an invoice as sent.
POST	`/v1/invoices/{id}/received`	Mark an invoice as received.
POST	`/v1/invoices/{id}/cancel`	Cancel an invoice.
POST	`/v1/invoices/{id}/document`	Attach or replace the document.
GET	`/v1/invoices/{id}/document`	Download or view the document.
GET	`/v1/invoices/{id}/orders`	List linked orders.
GET	`/v1/invoices/{id}/line-items`	List invoice lines.
GET	`/v1/invoices/{id}/disputes`	List attached disputes.

Events

These events can be consumed through platform webhooks when the account is configured to receive them.

invoice.issuedinvoice.sentinvoice.receivedinvoice.partially_paidinvoice.paidinvoice.disputedinvoice.cancelled

Behavior

The `issue`, `send`, `received`, and `cancel` actions advance the lifecycle; allocations advance `settlement_status` without changing `status`.
Documents are exposed through dedicated endpoints to keep the invoice JSON contract stable.