Checkout session ( checkout_session )

Role

The checkout session is the entry point of the purchase flow. It carries two independent dimensions: the session lifecycle (is it still active?) and the financial outcome (what was decided for payment?). Separating them lets the process close the session ( status: completed) regardless of the outcome — immediate payment, granted credit, or failure — without ambiguity.

At creation, an orchestration process is started automatically. That process drives the User Journey, communicates with payment providers, and updates session statuses through dedicated nodes.

Identifier and structure

Each session has a stable identifier prefixed with cs_. The object field is "checkout_session".

{
"object": "checkout_session",
"id": "cs_5e2d8f1a9b3c4d7e",
"status": "open",
"payment_status": "unpaid",
"buyer_id": "cmp_3a8f1d9c2b4e7f6a",
"buyer_contact_id": "ctc_d12e3f4a5b6c7d8e",
"process_definition_id": "prd_1a2b3c4d5e6f7a8b",
"process_instance_id": "pci_9a8b7c6d5e4f3a2b",
"process_status": "running",
"currency": "eur",
"amount_excluding_tax": 100000,
"amount_tax": 20000,
"amount_including_tax": 120000,
"billing_details": null,
"shipping_details": null,
"locale": "fr",
"url": "https://checkout.example.com/c/cs_5e2d8f…",
"return_url": "https://example.com/checkout/return",
"expires_at": "2026-06-18T10:00:00.000Z",
"closed_at": null,
"source_reference": "ORDER-2026-00842",
"metadata": {},
"created_at": "2026-06-17T10:00:00.000Z"
}

Fields

Lifecycle (status)

The field status follows the session lifecycle. A session always starts at open and transitions to one of three final states.

A final status cannot be changed. Only an open session may be expired through POST /v1/checkout/sessions/:id/expire.

Financial outcome (payment_status)

The field payment_status records the financial outcome of the session independently from its lifecycle. It is updated by the checkout process through the update_checkout_session_payment_status or finalize_checkout_session.

Associated process

A session created with a checkout process exposes two pieces of execution information: process_instance_id, the instance currently driving the session, and process_status, its current state. process_status is computed from the associated instance; it is not a third business status of the checkout session.

A manual retry, retry_step / skip_step fork, or resume of a user step may create a new instance to continue the same session. In that case, process_instance_id is transferred to the new instance and process_status immediately reflects its state. The old instance remains visible in orchestration history but is no longer the canonical execution of the session.

See Errors and idempotency for detailed retry, fork, and associated-instance transfer rules.

Amounts

The three amount fields are expressed in cents (non-negative integers) in the currency indicated by currency (lowercase ISO 4217 code). The following constraint is checked at creation:

amount_excluding_tax + amount_tax = amount_including_tax

Example for an order of EUR 1,000 excluding tax with 20% VAT:

{
"currency": "eur",
"amount_excluding_tax": 100000,
"amount_tax": 20000,
"amount_including_tax": 120000
}

Currency is normalized to lowercase on persistence. Attached line items (line_items) must use the same currency.

URL and expiration

The field url contains the User Journey address to provide to the buyer (redirect, email link, iframe). This URL is returned directly in the creation response — no additional call is required.

The session automatically expires at expires_at. When this field is not supplied at creation, the platform sets expiration to 24 hours after creation. Once expired, the URL is no longer accessible and the session moves to status: expired.

You can also expire an open session manually before its deadline:

POST /v1/checkout/sessions/cs_5e2d/expire

{
"status": "expired",
"closed_at": "2026-06-17T11:30:00.000Z"
}

Lignes d'article

Line items can be attached at session creation through the line_itemsfield. They are then accessible through GET /v1/checkout/sessions/:id/line-items. Lines cannot be modified after creation.

Once attached, lines are available to any logic that needs them: showing order details to the buyer in the User Journey, sending them to a fraud-prevention partner analyzing item nature or value, or using them in your own business rules.

In processes

The checkout_session is the central object for checkout processes. It is automatically injected as a process input at startup and flows between nodes as a typed platform.checkout_session.

The node finalize_checkout_session is the recommended pattern for closing a session at process end — it guarantees that both dimensions are updated atomically.

If the session was created without process_definition_id, the platform automatically selects the process launcher of type checkout configured for your merchant account. The process must accept an input of type platform.checkout_session named checkout_session.

Events

Changing to cancelled does not trigger a dedicated event. Only completed and expired produce a transition event. Each event includes the complete checkout_session object in its payload.