Select an optional item

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_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": "CHECKOUT_SESSION_NOT_FOUND",
    "message": "checkout session not found"
  }
}

{
  "error": {
    "code": "INVALID_SESSION_STATE",
    "message": "invalid session state for this operation"
  }
}

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

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

POST

checkout

sessions

{id}

optional_items

{line_item_id}

select

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_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": "CHECKOUT_SESSION_NOT_FOUND",
    "message": "checkout session not found"
  }
}

{
  "error": {
    "code": "INVALID_SESSION_STATE",
    "message": "invalid session state for this operation"
  }
}

{
  "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

Path Parameters

string

required

The checkout session id (cs_…).

line_item_id

string

required

The line item id.

Response

The updated 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

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

Start here

Checkout

Commerce

Checkout endpoints

Payment link endpoints

Catalog endpoints

Payments

Terminal locations

Terminal management

Terminal testing

Terminal payments

Invoices

Subscriptions

Setup intents

Credit notes

Webhook endpoints

Customer endpoints

API key endpoints

Payment method endpoints

Select an optional item

Authorizations

Headers

Path Parameters

Response