Supplier invoice ( supplier_invoice )
A supplier_invoice represents an invoice received from a supplier. Its model separates receipt/approval lifecycle, settlement progress, and dispute existence so all three dimensions can evolve without overwriting one another.
Role
The supplier invoice is the central document of the Accounts Payable flow. It may be matched to one or more purchase orders, submitted for approval, scheduled for payment, then allocated to a supplier payment.
The field type distinguishes an invoice (invoice) from a supplier credit note (credit_note). A credit note may reference its original invoice through source_invoice_id.
Identifier and structure
Every supplier invoice has an identifier prefixed with sinv_.
{
"object": "supplier_invoice",
"id": "sinv_4a7b2e9f1c3d8a5e",
"merchant_id": "mer_1a2b3c4d5e6f7a8b",
"supplier_id": "cmp_3a8f1d9c2b4e7f6a",
"supplier_contact_id": null,
"type": "invoice",
"source_invoice_id": null,
"status": "approved",
"settlement_status": "scheduled",
"disputed": false,
"amount_excluding_tax": 100000,
"amount_tax": 20000,
"amount_including_tax": 120000,
"currency": "eur",
"reference": "SUP-2026-0042",
"source_reference": "ERP-AP-7842",
"issue_date": "2026-06-17",
"received_at": "2026-06-18T09:00:00.000Z",
"due_date": "2026-07-17",
"scheduled_payment_date": "2026-07-15",
"paid_at": null
}Fields
| Field | Type | Description |
|---|---|---|
id | string | Supplier-invoice identifier (prefix `sinv_`). |
object | string | Always "supplier_invoice". |
merchant_id | string | Merchant receiving the invoice. |
supplier_id | string | Supplier (`cmp_…`). |
supplier_contact_id | string | null | Associated supplier contact, when known. |
type | enum | `invoice` or `credit_note`. |
source_invoice_id | string | null | Original supplier invoice for a credit note. |
status | enum | Lifecycle: `received`, `pending_approval`, `approved`, `cancelled`. |
settlement_status | enum | Settlement: `unpaid`, `scheduled`, `partially_paid`, `paid`. |
disputed | boolean | Whether the invoice is currently disputed. |
amount_excluding_tax | integer | Amount excluding tax in cents. |
amount_tax | integer | Tax amount in cents. |
amount_including_tax | integer | Amount including tax in cents. |
currency | string | Lowercase ISO 4217 currency. |
reference | string | null | Invoice number assigned by the supplier. |
source_reference | string | null | Reference in your source system. |
issue_date | date | null | Issue date indicated by the supplier. |
received_at | datetime | null | Invoice receipt date. |
due_date | date | null | Due date. |
approved_at | datetime | null | Approval date. |
scheduled_payment_date | date | null | Scheduled payment date, when applicable. |
paid_at | datetime | null | Full settlement date, when known. |
document_file | file | null | Attached invoice document. |
metadata | object | Flat map of `string | number | boolean` scalars, following the API metadata convention. |
created_at | datetime | Creation date. |
updated_at | datetime | Last update date. |
Lifecycle
status answers only “where is the document in processing?”. Scheduling or executing a payment does not change this axis.
| status | Description |
|---|---|
received | Invoice received and recorded. Initial status. |
pending_approval | Submitted to the approval workflow. |
approved | Approved for processing and payment. |
cancelled | Canceled. End of document lifecycle. |
Settlement
settlement_status separately tracks payment progress. The value
scheduled belongs to this axis: it indicates that a disbursement is planned without making scheduling a stage of invoice lifecycle.
| settlement_status | Description |
|---|---|
unpaid | No settlement has yet been initiated on the invoice. |
scheduled | A supplier payment has been scheduled for this invoice. |
partially_paid | Part of the amount has been settled. |
paid | The full amount has been settled. |
When a supplier payment is applied to the document, settlement progresses toward
partially_paid or paid according to the amount actually allocated.
Disputes
The disputed forms a third independent axis. Opening a dispute replaces neither status nor settlement_status ; for example an invoice can remain approved while disputed.
POST /v1/supplier-invoices/sinv_4a7b/dispute
{}POST /v1/supplier-invoices/:id/resolve-dispute closes the dispute and resets
disputed to false. The request specifies whether lifecycle resumes in
received or approved.
Purchase orders
A supplier invoice may be linked to one or more purchase orders. Relationships are available through GET /v1/supplier-invoices/:id/purchase-orders
and editable through POST /v1/supplier-invoices/:id/purchase-order-links.
Line items may also reference a purchase-order line using
purchase_order_line_item_id to preserve line-by-line matching.
Business actions
| Endpoint | Effect on the axes |
|---|---|
POST /v1/supplier-invoices/:id/submit-for-approval | status : received → pending_approval |
POST /v1/supplier-invoices/:id/approve | status : received/pending_approval → approved |
POST /v1/supplier-invoices/:id/schedule | settlement_status → scheduled; status remains approved |
POST /v1/supplier-invoices/:id/dispute | `disputed` → true; `status` and `settlement_status` remain independent |
POST /v1/supplier-invoices/:id/resolve-dispute | `disputed` → false; lifecycle resumes in `received` or `approved` |
POST /v1/supplier-invoices/:id/cancel | status → cancelled |
Events
| Event | Trigger |
|---|---|
supplier_invoice.received | A supplier invoice was just recorded. |
supplier_invoice.updated | The invoice or its business lifecycle was updated. |
supplier_invoice.approved | The invoice was just approved. |
supplier_invoice.partially_paid | Settlement became partial. |
supplier_invoice.paid | The invoice is fully settled. |
supplier_invoice.overdue | The invoice is overdue and remains open. |
supplier_invoice.disputed | A dispute was opened on the invoice. |
supplier_invoice.cancelled | The invoice was canceled. |