Create a checkout session
Creates a new checkout session. Payment-mode sessions accept either the catalog
path (price_id + quantity) or the inline path (name, amount, currency,
quantity). Subscription-mode sessions require recurring catalog prices. All
items must share the same currency. The session starts open and expires after
24 hours by default.
For hosted mode (ui_mode: hosted), redirect the buyer to the url in the
response. For embedded mode (ui_mode: embedded), pass the client_secret to
the @ionicfi/js SDK on your frontend.
Send an Idempotency-Key header to safely retry — the same key with the same
body returns the original session without creating a duplicate.
Authorizations
A merchant secret key (sk_…) sent as Authorization: Bearer <key>.
Headers
A unique key that makes retries safe: the same key with the same request body returns the original response instead of repeating the operation.
255Body
Request body for creating a checkout session. Payment-mode sessions accept either
the catalog path (price_id + quantity) or the inline path (name, amount,
currency, quantity). Mixing paths within a single line item is an error.
Subscription-mode sessions require recurring catalog prices. All items must use
the same currency; recurring items must use the same billing cadence.
Required line items to charge for.
1 - 20 elementsA single line item. Use the catalog shape (price_id + quantity) or the inline
shape (name + amount + currency + quantity). Providing price_id alongside
name, amount, or currency is an error.
- Option 1
- Option 2
Checkout mode. Use payment for a one-time purchase or subscription with recurring catalog prices for recurring billing.
payment, subscription URL to redirect the buyer after successful payment (hosted mode). Supports the placeholder {CHECKOUT_SESSION_ID}, which is replaced with the session id on redirect. Ignored for embedded sessions — embedded completion is reported through the SDK's onComplete callback.
2048URL to redirect the buyer if they cancel. Ignored for embedded sessions.
2048Advanced. Checkout page locale (e.g., en_US, fr_FR).
16Presentation mode. hosted redirects to Ionic's domain (generally available). embedded mounts an iframe on your domain via the @ionicfi/js SDK (preview, requires domain allowlisting).
hosted, embedded Advanced. Controls the checkout submit button label. auto infers the label from line items.
auto, pay, book, donate Customer id (cus_…) to link to this session. Recommended for subscription checkout when the buyer already has an Ionic customer.
Email address to pre-fill in the checkout form.
Your order number or other reference.
256Advanced. Unix epoch seconds when the session expires. Must be between 30 minutes and 24 hours from now. Defaults to 24 hours from creation.
Advanced. Overrides the default field-collection policy for the checkout form. Subscription mode always requires email, name, and billing address and hides phone.
Advanced. Upsell items the buyer can optionally add. Same structure as line_items.
10A single line item. Use the catalog shape (price_id + quantity) or the inline
shape (name + amount + currency + quantity). Providing price_id alongside
name, amount, or currency is an error.
- Option 1
- Option 2
Advanced. Payment intent configuration applied when the session is confirmed.
Custom key-value pairs for your use.
Response
The created checkout session.
A checkout session.
Checkout session id (cs_…).
checkout_session Merchant id that owns this session (mer_…).
True for live-mode sessions; false for test-mode.
Checkout mode.
payment, subscription, setup Presentation mode.
hosted, embedded Checkout button label mode.
auto, pay, book, donate 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.
open, complete, expired Payment outcome.
paid, unpaid, no_payment_required URL to redirect the buyer after successful payment.
URL to redirect the buyer if they cancel.
Checkout page locale.
Linked customer id (cus_…).
Pre-filled email address.
Merchant-supplied reference id.
Required line items.
Field-collection requirements for this session.
Sum of required line item amounts in minor units.
Subtotal plus the amounts of selected optional items in minor units.
Uppercase three-letter ISO currency code, derived from the first line item.
The payment intent created to collect this session (pi_…). Null until the session is confirmed.
Unix epoch seconds when this session expires.
Custom key-value pairs attached to this session.
Unix epoch seconds.
Merchant display details. Present when the session was retrieved from the hosted checkout page context.
SDK initialization token for embedded mode. Present only on the create response when ui_mode is embedded; absent on all other responses.
Optional upsell items offered on the checkout form. Absent when none were configured.
Ids of optional items the buyer selected. Absent when none are selected.
Payment intent client secret. Present only on the confirm response so the frontend can initialize the card form.
Set when the merchant enabled saving the payment method. The hosted form shows a save-card checkbox to the buyer.
on_session, off_session Error returned to the buyer surface after a declined charge attempt. Absent when no decline occurred.
Back-reference to the payment link that spawned this session (pl_…). Absent for API-created sessions.
Card-fields configuration used by Ionic Checkout. Present when the session includes browser tokenization access.
Card-fields configuration used by Ionic Checkout. No integration action is required.
Hosted checkout URL (ui_mode: hosted only). Redirect the buyer here to begin payment.
Embedded checkout iframe URL (ui_mode: embedded only).

