The checkout session object

{
  "id": "cs_01JEXAMPLE2K8V4N9C6M1Q7R",
  "object": "checkout_session",
  "mode": "payment",
  "ui_mode": "hosted",
  "status": "open",
  "payment_status": "paid",
  "url": "https://…",
  "amount_total": 2500,
  "currency": "usd",
  "payment_intent_id": null,
  "client_reference_id": null,
  "expires_at": 1767225600,
  "metadata": {},
  "livemode": false
}

Checkout sessions are one buyer attempt to pay or start a subscription through Ionic checkout. Create them from your backend, send the buyer to hosted checkout or continue an embedded checkout flow, then retrieve the session to check the result. The exact request and response payloads live on the generated endpoint pages.

Attributes

string

Checkout session id (cs_…).

string

Checkout mode.

string

Presentation mode.

string

open: active, buyer can continue. complete: the hosted payment or subscription activation finished; inspect payment_status and process webhooks. expired: timed out, buyer must start a new session.

string

Payment outcome.

string

Hosted checkout URL (ui_mode: hosted only). Redirect the buyer here to begin payment.

integer

Subtotal plus the amounts of selected optional items in minor units.

string

Uppercase three-letter ISO currency code, derived from the first line item.

string | null

The payment intent created to collect this session (pi_…). Null until the session is confirmed.

string | null

Merchant-supplied reference id.

integer

Unix epoch seconds when this session expires.

object

Custom key-value pairs attached to this session.

See every field in the response of Retrieve a checkout session.

Endpoints

Endpoint	Use it for
Create checkout session	Create a hosted checkout session from inline or catalog line items.
List checkout sessions	Review checkout history or build reporting.
Get checkout session	Retrieve one session by `cs_` ID.
Confirm checkout session	Lazily create the payment intent for an open session.
Adjust line item quantity	Change adjustable quantities before payment confirmation.
Select optional item	Add an optional item to an open session.
Deselect optional item	Remove a selected optional item from an open session.

Notes

line_items is required when creating a session.
mode: payment accepts either catalog-backed items with price_id or inline items with name, amount, and currency.
mode: subscription requires recurring catalog prices. Recurring items must share one currency and billing cadence.
Hosted checkout confirms payment or activates the subscription for you. Do not call the merchant confirm endpoint from a hosted integration.
POST /v1/checkout/sessions/{id}/confirm takes no JSON body and does not support subscription-mode sessions.
Quantity and optional-item mutations only apply while a session is open and before the payment intent is attached.
Hosted checkout URLs are buyer-facing capability URLs. Merchant API keys should stay on your server.
Treat redirects as user-experience signals. Verify server-side state before fulfillment.

Fundamentals

Payments

Checkout

In-person payments

Customers and catalog

Connect

Billing

Webhooks

The checkout session object

Attributes

Endpoints

Notes

​Attributes

​Endpoints

​Notes

Attributes

Endpoints

Notes