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

Body

application/json

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.

line_items
object[]
required

Required line items to charge for.

Required array length: 1 - 20 elements

A 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.

mode
enum<string>
default:payment

Checkout mode. Use payment for a one-time purchase or subscription with recurring catalog prices for recurring billing.

Available options:
payment,
subscription
success_url
string

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.

Maximum string length: 2048
cancel_url
string

URL to redirect the buyer if they cancel. Ignored for embedded sessions.

Maximum string length: 2048
locale
string

Advanced. Checkout page locale (e.g., en_US, fr_FR).

Maximum string length: 16
ui_mode
enum<string>
default:hosted

Presentation 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).

Available options:
hosted,
embedded
submit_type
enum<string>

Advanced. Controls the checkout submit button label. auto infers the label from line items.

Available options:
auto,
pay,
book,
donate
customer
string

Customer id (cus_…) to link to this session. Recommended for subscription checkout when the buyer already has an Ionic customer.

customer_email
string

Email address to pre-fill in the checkout form.

client_reference_id
string

Your order number or other reference.

Maximum string length: 256
expires_at
integer<int64>

Advanced. Unix epoch seconds when the session expires. Must be between 30 minutes and 24 hours from now. Defaults to 24 hours from creation.

collect_config
object

Advanced. Overrides the default field-collection policy for the checkout form. Subscription mode always requires email, name, and billing address and hides phone.

optional_items
object[]

Advanced. Upsell items the buyer can optionally add. Same structure as line_items.

Maximum array length: 10

A 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.

payment_intent_data
object

Advanced. Payment intent configuration applied when the session is confirmed.

metadata
object

Custom key-value pairs for your use.

Response

The created 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
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_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).