Skip to main content
POST
Error

Authorizations

Authorization
string
header
required

A merchant secret key (sk_…) sent as Authorization: Bearer <key>.

Headers

Idempotency-Key
string

A unique key that makes retries safe: the same key with the same request body returns the original response instead of repeating the operation.

Maximum string length: 255
Ionic-Account
string

Merchant ID when an authorized Platform acts for a connected Merchant. Omit when authenticating directly as that Merchant.

Pattern: ^mer_[0-9A-Za-z]{14}$

Path Parameters

id
string
required

The checkout session id (cs_…).

line_item_id
string
required

The line item id.

Response

The updated checkout session.

A checkout session.

id
string
required

Checkout session id (cs_…).

object
enum<string>
required
Available options:
checkout_session
merchant_id
string
required

Merchant id that owns this session (mer_…).

livemode
boolean
required

True for live-mode sessions; false for test-mode.

mode
enum<string>
required

Checkout mode.

Available options:
payment,
subscription,
setup
ui_mode
enum<string>
required

Presentation mode.

Available options:
hosted,
embedded
submit_type
enum<string>
required

Checkout button label mode.

Available options:
auto,
pay,
book,
donate
status
enum<string>
required

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.

Available options:
open,
complete,
expired
payment_status
enum<string>
required

Payment outcome.

Available options:
paid,
unpaid,
no_payment_required
success_url
string | null
required

URL to redirect the buyer after successful payment.

cancel_url
string | null
required

URL to redirect the buyer if they cancel.

locale
string | null
required

Checkout page locale.

customer
string | null
required

Linked customer id (cus_…).

customer_email
string | null
required

Pre-filled email address.

client_reference_id
string | null
required

Merchant-supplied reference id.

line_items
object[]
required

Required line items.

collect_config
object
required

Field-collection requirements for this session.

amount_subtotal
integer<int64>
required

Sum of required line item amounts in minor units.

amount_total
integer<int64>
required

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

currency
string
required

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

payment_intent_id
string | null
required

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

expires_at
integer<int64>
required

Unix epoch seconds when this session expires.

metadata
object
required

Custom key-value pairs attached to this session.

created_at
integer<int64>
required

Unix epoch seconds.

updated_at
integer<int64>
required

Unix epoch seconds when the session was last updated.

merchant
object | null

Merchant display details. Present when the session was retrieved from the hosted checkout page context.

client_secret
string

SDK initialization token for embedded mode. Present only on the create response when ui_mode is embedded; absent on all other responses.

optional_items
object[]

Optional upsell items offered on the checkout form. Absent when none were configured.

selected_optional_item_ids
string[]

Ids of optional items the buyer selected. Absent when none are selected.

payment_intent_status
string

Current status of the attached PaymentIntent. Returned by authorized hosted and embedded checkout session reads once a payment exists. An open session may still have a processing payment.

payment_retry_allowed
boolean

Whether payment collection is currently eligible on this session, considering expiration and all prior attempts. Returned in hosted and embedded checkout responses. False while any relevant attempt is unresolved or the payment is approved. Confirmation rechecks eligibility; this field does not guarantee payment approval.

payment_intent_client_secret
string | null

Payment intent client secret. Present only on the confirm response so the frontend can initialize the card form.

setup_future_usage
enum<string> | null

Set when the merchant enabled saving the payment method. The hosted form shows a save-card checkbox to the buyer.

Available options:
on_session,
off_session
payment_error
object | null

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.

tokenization
object | null

Card-fields configuration used by Ionic Checkout. Present when the session includes browser tokenization access.

provider
object | null

Card-fields configuration used by Ionic Checkout. No integration action is required.

url
string

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

embed_url
string

Embedded checkout iframe URL (ui_mode: embedded only).