Invoice ( invoice )

Role

The invoice is the central accounting object of the invoicing lifecycle. It may be created independently or directly from an order. Issuing an invoice records an accounting fact; it neither reserves nor automatically validates credit capacity. Exposure movements are explicitly orchestrated in processes.

The invoice has a counterpart: the credit note (credit_note), which follows the same rules but reduces the committed amount rather than increasing it and references the original invoice.

Identifier and structure

Every invoice has a stable identifier prefixed with inv_.

{
"object": "invoice",
"id": "inv_4a7b2e9f1c3d8a5e",
"merchant_id": "mer_1a2b3c4d5e6f7a8b",
"buyer_id": "cmp_3a8f1d9c2b4e7f6a",
"type": "invoice",
"source_invoice_id": null,
"source_reference": "FAC-2026-00042",
"metadata": {},
"status": "sent",
"settlement_status": "unpaid",
"amount_excluding_tax": 100000,
"amount_tax": 20000,
"amount_including_tax": 120000,
"currency": "eur",
"reference": "FAC-2026-00042",
"issue_date": "2026-06-17",
"due_date": "2026-07-17",
"document_url": null,
"created_at": "2026-06-17T10:00:00.000Z"
}

Type

The field type distinguishes two variants of the same object.

Fields

The excluding tax + tax = including tax constraint is enforced at creation and every update. Amounts are positive integers in cents.

Lifecycle

The field status describes only the document lifecycle: drafting, issuance, sending, receipt, then optional cancellation or write-off. Settlement never overwrites this status.

The transitions draft → issued → sent → received are driven by invoice business actions. Payment allocations do not affect this axis.

Settlement

The field settlement_status independently tracks how much of the invoice has been settled. It is calculated from payment applications and never changes the document lifecycle.

partially_paid and paid are updated automatically by payment allocations. The PDF document cannot be deleted or replaced when settlement_status is paid.

Outstanding balance

Ormuz exposes an invoice_balance projection representing the invoice's current outstanding amount. This projection accounts for already-applied payments and credit notes reducing the receivable; it must therefore not be recalculated from amount_including_tax.

alone. The balance is calculated on demand from current financial state and can be used in processes through fetch_invoice_balance. It also serves as a snapshot in due-date events, notably invoice.overdue and invoice.due_date_stage_reached, so a reminder directly uses the amount still due when the event is emitted.

An invoice whose balance is zero is not considered unpaid even if its face amount remains unchanged. Conversely, a new allocation or credit note immediately changes the projection used by future events.

Disputes

A dispute is not an invoice status value. It is carried by an independent dispute , allowing a case to open or close without losing either status or settlement_status courants.

The disputed boolean is a projection: it is true as long as at least one open dispute open covers the invoice itself or a line contextualized by that invoice. Several open disputes on the same invoice do not create double counting in the receivable.

Issuance

Issuing an invoice (status : draft → issued) is done either through the dedicated endpoint or atomically at creation.

Create and issue in one operation

POST /v1/invoices

{
"merchant_id": "mer_1a2b3c",
"buyer_id": "cmp_3a8f1d",
"type": "invoice",
"amount_excluding_tax": 100000,
"amount_tax": 20000,
"amount_including_tax": 120000,
"currency": "eur",
"reference": "FAC-2026-00042",
"issue_date": "2026-06-17",
"due_date": "2026-07-17",
"issue": true
}

Issue an existing invoice

POST /v1/invoices/inv_4a7b/issue

Issuance is not blocked by credit capacity and produces no implicit credit movement. If the merchant wants the invoice reflected in exposure, a process can explicitly execute the credit-consumption node.

Document PDF

An invoice file may be attached at any time. Accepted formats are PDF, JPEG, and PNG, up to 10 MB. The URL is stored in document_url after upload.

POST /v1/invoices/inv_4a7b/document
GET /v1/invoices/inv_4a7b/document
DELETE /v1/invoices/inv_4a7b/document

Deleting or replacing the document is blocked when the settlement_status is paid.

Avoirs

A asee (type: "credit_note") is an invoice in the opposite direction: it reduces the receivable owed by the buyer. It follows the same axes as an invoice (status, settlement_status, issuance, document, lines). For receivable balances, a credit note linked to a source invoice follows the analytical scope of that invoice, including its due bucket and any dispute.

POST /v1/invoices

{
"merchant_id": "mer_1a2b3c",
"buyer_id": "cmp_3a8f1d",
"type": "credit_note",
"source_invoice_id": "inv_4a7b2e",
"amount_excluding_tax": 20000,
"amount_tax": 4000,
"amount_including_tax": 24000,
"currency": "eur",
"reference": "AV-2026-00007",
"issue": true
}

The field source_invoice_id points to the original invoice for documentary purposes — there is no automatic status coupling between invoice and credit note. Any reversal of credit consumption remains an explicit process action from the relevant consumption movement.

Orders and line items

Linking with orders

An invoice may be linked to one or more orders.

Lignes d'article

Invoice line items are available through GET /v1/invoices/:id/line-items. Their structure is identical to order-line items (fields product_name, quantity, amount_including_tax, etc.).

Allocation

L'endpoint GET /v1/invoices/eligible-allocation returns open invoices and floating credit notes eligible for payment allocation for a given buyer and merchant.

GET /v1/invoices/eligible-allocation?buyer_id=cmp_3a8f&merchant_id=mer_1a2b

{
"invoices": [
  {
    "id": "inv_4a7b",
    "net_due": 120000,
    "currency": "eur"
  }
],
"credit_notes": [
  {
    "id": "inv_9c2e",
    "net_due": 24000,
    "currency": "eur"
  }
]
}

In processes

There is no dedicated node for invoice creation or transitions. The object is driven through direct API calls or HTTP actions in an orchestration process.

Three generic helpers are available for handling an invoice in a process: fetch_invoice retrieves an invoice by identifier, refresh_invoice reloads its current state from the platform, and fetch_invoice_balance returns its current outstanding balance.

Events

Settlement changes emit invoice.partially_paid or invoice.paid. Disputes remain independent from settlement and generate their own events through the linked dispute object.