/v1/checkout_sessions

POST/v1/checkout_sessions

[checkout_api] create checkout session + line_items

Security: gated; the registry declares no role list for this surface.

Header Parameters

Idempotency-Key*string

Client-supplied idempotency key. Required on every registry-idempotent door.

Length1 <= length

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

mode?string

Optional; must match API key mode when present

Value in

"test"
"live"

ui_mode?string

Optional; defaults from merchant_defaults

Value in

"hosted"
"embedded"

currency*string

ISO-4217 currency code

amount*integer

Session amount minor units (bare integer); must equal amount_total

amount_subtotal*integer

Subtotal minor units (bare integer)

amount_discount?integer

Optional discount minor units; default 0

amount_shipping?integer

Optional shipping minor units; default 0

amount_tax?integer

Optional tax minor units; default 0

amount_total*integer

Total minor units (bare integer)

line_items*array<>

Items1 <= items

description?string

Lengthlength <= 500

merchant_reference?string

Lengthlength <= 200

customer_email?string

Formatemail

Lengthlength <= 320

locale?string

Lengthlength <= 20

metadata?

quote_id?string

Optional FX quote UUID

Formatuuid

expires_at?integer

Optional absolute expiry as unix seconds

success_url?string

Formaturi

cancel_url?string

Formaturi

return_url?string

Formaturi

notify_url?string

Formaturi

Response Body

`application/json`

curl -X POST "https://example.com/v1/checkout_sessions" \  -H "Idempotency-Key: string" \  -H "Content-Type: application/json" \  -d '{    "currency": "string",    "amount": 0,    "amount_subtotal": 0,    "amount_total": 0,    "line_items": [      {        "quantity": 1,        "amount_subtotal": 0,        "price_data": {          "currency": "string",          "unit_amount": 0,          "product_data": {            "name": "string"          }        }      }    ]  }'

{  "id": "string",  "object": "checkout.session",  "mode": "test",  "ui_mode": "hosted",  "status": "string",  "payment_status": "string",  "currency": "string",  "amount": 0,  "amount_subtotal": 0,  "amount_discount": 0,  "amount_shipping": 0,  "amount_tax": 0,  "amount_total": 0,  "success_url": "string",  "cancel_url": "string",  "return_url": "string",  "notify_url": "string",  "description": "string",  "customer_email": "string",  "locale": "string",  "metadata": {    "property1": "string",    "property2": "string"  },  "expires_at": 0,  "created_at": 0,  "line_items": {    "object": "list",    "data": [      {        "product_name": "string",        "description": "string",        "images": [          "string"        ],        "tax_behavior": "inclusive",        "quantity": 0,        "unit_price": 0,        "currency": "string",        "amount_subtotal": 0,        "amount_discount": 0,        "amount_tax": 0,        "amount_total": 0      }    ]  }}

{  "request_id": "string",  "error": {    "type": "invalid_request",    "message": "string",    "param": "string",    "errors": [      {        "param": "string",        "code": "string",        "message": "string",        "allowed": [          "string"        ]      }    ],    "next_step": {      "type": "string",      "path": "string",      "method": "string"    },    "code": "invalid_param"  }}

{  "request_id": "string",  "error": {    "type": "invalid_request",    "message": "string",    "param": "string",    "errors": [      {        "param": "string",        "code": "string",        "message": "string",        "allowed": [          "string"        ]      }    ],    "next_step": {      "type": "string",      "path": "string",      "method": "string"    },    "code": "invalid_api_key"  }}

{  "request_id": "string",  "error": {    "type": "invalid_request",    "message": "string",    "param": "string",    "errors": [      {        "param": "string",        "code": "string",        "message": "string",        "allowed": [          "string"        ]      }    ],    "next_step": {      "type": "string",      "path": "string",      "method": "string"    },    "code": "invalid_amount"  }}

{  "request_id": "string",  "error": {    "type": "invalid_request",    "message": "string",    "param": "string",    "errors": [      {        "param": "string",        "code": "string",        "message": "string",        "allowed": [          "string"        ]      }    ],    "next_step": {      "type": "string",      "path": "string",      "method": "string"    },    "code": "origin_not_allowed"  }}

{  "request_id": "string",  "error": {    "type": "invalid_request",    "message": "string",    "param": "string",    "errors": [      {        "param": "string",        "code": "string",        "message": "string",        "allowed": [          "string"        ]      }    ],    "next_step": {      "type": "string",      "path": "string",      "method": "string"    },    "code": "idempotency_conflict"  }}

Header Parameters

Request Body

Response Body

200application/json

400application/json

401application/json

402application/json

403application/json

409application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`