Error

A valid request URL is required to generate request examples

{
  "id": "<string>",
  "object": "checkout_session",
  "merchant_id": "<string>",
  "livemode": true,
  "mode": "payment",
  "ui_mode": "hosted",
  "submit_type": "auto",
  "status": "open",
  "payment_status": "paid",
  "success_url": "<string>",
  "cancel_url": "<string>",
  "locale": "<string>",
  "customer": "<string>",
  "customer_email": "<string>",
  "client_reference_id": "<string>",
  "line_items": [
    {
      "id": "<string>",
      "name": "<string>",
      "amount": 123,
      "currency": "<string>",
      "quantity": 123,
      "fulfillment_type": "digital",
      "tip_eligible": true,
      "metadata": {},
      "price_id": "<string>",
      "product_id": "<string>",
      "recurring": {
        "interval": "<string>",
        "interval_count": 123
      },
      "adjustable_quantity": {
        "enabled": true,
        "minimum": 123,
        "maximum": 123
      },
      "image_url": "<string>"
    }
  ],
  "collect_config": {
    "email": "required",
    "name": "required",
    "phone": "required",
    "address": "required",
    "require_full_billing_address": true,
    "require_shipping_address": true,
    "require_phone": true,
    "wallet_billing_mode": "min"
  },
  "amount_subtotal": 123,
  "amount_total": 123,
  "currency": "<string>",
  "payment_intent_id": "<string>",
  "expires_at": 123,
  "metadata": {},
  "created_at": 123,
  "updated_at": 123,
  "merchant": {
    "name": "<string>"
  },
  "client_secret": "<string>",
  "optional_items": [
    {
      "id": "<string>",
      "name": "<string>",
      "amount": 123,
      "currency": "<string>",
      "quantity": 123,
      "fulfillment_type": "digital",
      "tip_eligible": true,
      "metadata": {},
      "price_id": "<string>",
      "product_id": "<string>",
      "recurring": {
        "interval": "<string>",
        "interval_count": 123
      },
      "adjustable_quantity": {
        "enabled": true,
        "minimum": 123,
        "maximum": 123
      },
      "image_url": "<string>"
    }
  ],
  "selected_optional_item_ids": [
    "<string>"
  ],
  "payment_intent_status": "<string>",
  "payment_retry_allowed": true,
  "payment_intent_client_secret": "<string>",
  "setup_future_usage": "on_session",
  "payment_error": {
    "code": "<string>",
    "message": "<string>",
    "type": "card_error",
    "decline_code": "<string>",
    "decline_type": "authorization",
    "retryable": true,
    "doc_url": "<string>"
  },
  "payment_link_id": "<string>",
  "tokenization": {
    "provider": "<string>",
    "tokenization_key": "<string>"
  },
  "provider": {
    "name": "<string>",
    "public_key": "<string>",
    "config": {}
  },
  "url": "<string>",
  "embed_url": "<string>"
}

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "line_items must not be empty"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

Checkout sessions

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.

POST

checkout

sessions

Error

A valid request URL is required to generate request examples

{
  "id": "<string>",
  "object": "checkout_session",
  "merchant_id": "<string>",
  "livemode": true,
  "mode": "payment",
  "ui_mode": "hosted",
  "submit_type": "auto",
  "status": "open",
  "payment_status": "paid",
  "success_url": "<string>",
  "cancel_url": "<string>",
  "locale": "<string>",
  "customer": "<string>",
  "customer_email": "<string>",
  "client_reference_id": "<string>",
  "line_items": [
    {
      "id": "<string>",
      "name": "<string>",
      "amount": 123,
      "currency": "<string>",
      "quantity": 123,
      "fulfillment_type": "digital",
      "tip_eligible": true,
      "metadata": {},
      "price_id": "<string>",
      "product_id": "<string>",
      "recurring": {
        "interval": "<string>",
        "interval_count": 123
      },
      "adjustable_quantity": {
        "enabled": true,
        "minimum": 123,
        "maximum": 123
      },
      "image_url": "<string>"
    }
  ],
  "collect_config": {
    "email": "required",
    "name": "required",
    "phone": "required",
    "address": "required",
    "require_full_billing_address": true,
    "require_shipping_address": true,
    "require_phone": true,
    "wallet_billing_mode": "min"
  },
  "amount_subtotal": 123,
  "amount_total": 123,
  "currency": "<string>",
  "payment_intent_id": "<string>",
  "expires_at": 123,
  "metadata": {},
  "created_at": 123,
  "updated_at": 123,
  "merchant": {
    "name": "<string>"
  },
  "client_secret": "<string>",
  "optional_items": [
    {
      "id": "<string>",
      "name": "<string>",
      "amount": 123,
      "currency": "<string>",
      "quantity": 123,
      "fulfillment_type": "digital",
      "tip_eligible": true,
      "metadata": {},
      "price_id": "<string>",
      "product_id": "<string>",
      "recurring": {
        "interval": "<string>",
        "interval_count": 123
      },
      "adjustable_quantity": {
        "enabled": true,
        "minimum": 123,
        "maximum": 123
      },
      "image_url": "<string>"
    }
  ],
  "selected_optional_item_ids": [
    "<string>"
  ],
  "payment_intent_status": "<string>",
  "payment_retry_allowed": true,
  "payment_intent_client_secret": "<string>",
  "setup_future_usage": "on_session",
  "payment_error": {
    "code": "<string>",
    "message": "<string>",
    "type": "card_error",
    "decline_code": "<string>",
    "decline_type": "authorization",
    "retryable": true,
    "doc_url": "<string>"
  },
  "payment_link_id": "<string>",
  "tokenization": {
    "provider": "<string>",
    "tokenization_key": "<string>"
  },
  "provider": {
    "name": "<string>",
    "public_key": "<string>",
    "config": {}
  },
  "url": "<string>",
  "embed_url": "<string>"
}

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "line_items must not be empty"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

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}$

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.

Option 1
Option 2

Show child attributes

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.

Show child attributes

optional_items

object[]

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

Maximum array length: 10

Option 1
Option 2

Show child attributes

payment_intent_data

object

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

Show child attributes

metadata

object

Custom key-value pairs for your use.

Show child attributes

Response

The created checkout session.

A checkout session.

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.

Show child attributes

collect_config

object

required

Field-collection requirements for this session.

Show child attributes

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.

Show child attributes

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.

Show child attributes

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.

Show child attributes

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.

Show child attributes

payment_link_id

string | null

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.

Show child attributes

provider

object | null

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

Show child attributes

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

Fundamentals

Payments

Checkout

In-person payments

Customers and catalog

Connect

Billing

Webhooks

Create a checkout session

Authorizations

Headers

Body

Response