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": "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>"
}
}Deselect an optional item
Removes a previously selected optional item from the session. The session must be
open. After deselection, amount_total decreases by the item’s amount. Secrets
are stripped from the response.
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": "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
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.
255Merchant ID when an authorized Platform acts for a connected Merchant. Omit when authenticating directly as that Merchant.
^mer_[0-9A-Za-z]{14}$Path Parameters
The checkout session id (cs_…).
The line item id.
Response
The updated 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.
Show child attributes
Show child attributes
Field-collection requirements for this session.
Show child attributes
Show child attributes
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.
Show child attributes
Show child attributes
Unix epoch seconds.
Unix epoch seconds when the session was last updated.
Merchant display details. Present when the session was retrieved from the hosted checkout page context.
Show child attributes
Show child attributes
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.
Show child attributes
Show child attributes
Ids of optional items the buyer selected. Absent when none are selected.
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.
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. 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.
Show child attributes
Show child attributes
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.
Show child attributes
Show child attributes
Card-fields configuration used by Ionic Checkout. No integration action is required.
Show child attributes
Show child attributes
Hosted checkout URL (ui_mode: hosted only). Redirect the buyer here to begin payment.
Embedded checkout iframe URL (ui_mode: embedded only).

