Order ( order )

Role

The order models the commercial lifecycle of a purchase from initial creation through fulfillment and closure. It may be created directly through the API or automatically produced by an orchestration process after a checkout session.

checkout session. The order is also the natural anchor for invoicing: invoices and credit notes may be created directly from an order or linked to an existing order later.

Identifier and structure

Every order has a stable identifier prefixed with ord_.

{
"object": "order",
"id": "ord_7e3b9f2a1c4d8e5f",
"buyer_id": "cmp_3a8f1d9c2b4e7f6a",
"buyer_contact_id": "ctc_d12e3f4a5b6c7d8e",
"checkout_session_id": "cs_5e2d8f1a9b3c4d7e",
"source_reference": "ORDER-2026-00842",
"status": "confirmed",
"currency": "eur",
"amount_excluding_tax": 100000,
"amount_tax": 20000,
"amount_including_tax": 120000,
"metadata": {},
"confirmed_at": "2026-06-17T10:05:00.000Z",
"fulfilled_at": null,
"closed_at": null,
"created_at": "2026-06-17T10:00:00.000Z",
"updated_at": "2026-06-17T10:05:00.000Z"
}

Fields

Lifecycle

. The order follows a linear lifecycle with two final states. The initial status (draft or created) is selected at creation — later statuses are reachable only through dedicated transition endpoints.

Statuses

Transitions

Progress timestamps are cumulative: moving directly to fulfilled without explicitly going through confirmed also populates confirmed_at. Likewise, complete populates fulfilled_at if it was still null.

Lignes d'article

Line items describe the products or services in the order. They may be supplied at creation and atomically replaced during an update while the order is in draft or createdstatus. They are then available through GET /v1/orders/:id/line-items.

{
"object": "line_item",
"id": "li_a1b2c3d4e5f6",
"product_name": "Pro Subscription",
"description": "12-month access",
"line_type": "service",
"product_reference": "PROD-PRO-12M",
"quantity": 1,
"unit_amount_excluding_tax": 100000,
"unit_amount_including_tax": 120000,
"amount_excluding_tax": 100000,
"amount_tax": 20000,
"amount_including_tax": 120000,
"currency": "eur",
"tax": { "type": "percent", "rate": 0.20, "code": "VAT20" }
}

. The equality constraint HT + taxe = TTC applies to every line individually. Line amounts (amount_*) are calculated automatically when absent (unit_amount × quantity).

Invoicing

An order may be associated with one or more invoices or credit notes. Two modes are available: create an invoice directly from the order or link existing invoices.

Create an invoice from the order

POST /v1/orders/:id/invoices creates an invoice automatically inheriting the merchant_id, du buyer_id and currency from the order — these fields cannot be overridden. The order must have a buyer_id for an invoice to be issued.

POST /v1/orders/ord_7e3b/invoices

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

Setting "issue": true immediately issues the invoice (transition to status: "issued") and triggers the invoice.issued event in addition to invoice.created. For credit notes, use "type": "credit_note" and reference the original invoice through source_invoice_id.

Link existing invoices

Existing invoices created independently may be attached to the order.

Linked invoices must belong to the same merchant and buyer as the order. The link is purely relational — it does not affect invoice status.

In processes

There is no dedicated node for order creation or transitions. The object is managed through direct API calls from your systems or HTTP actions in an orchestration process.

The order may be passed as a parameter to some payment nodes — for example create_psp_payment accepts a order optional field to attach the payment to the corresponding order. Once persisted, it can be retrieved in a process through the generic helper fetch_order.

Events

Transition events (confirmed, fulfilled, completed, cancelled) include a diff with the final status in after. The order.updated event includes a diff with the previous status in before and changed fields in after.