Create checkout session

Creates a checkout session with a 6-hour TTL. Returns a checkout_url that you can redirect customers to, or use the session ID to build a custom checkout experience. Supports both catalog products (by product_id) and dynamic line items (by name + amount).

Path Parameters

storeId*string

Store ID (shp_ prefix)

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

items*array<|>

Line items — use product_id for catalog products or name + amount for dynamic items

Items1 <= items <= 10

title?string

Custom title for the checkout page. Defaults to the store name.

Length1 <= length <= 128

description?string

Custom description shown on the checkout page. Not included unless explicitly set.

Length1 <= length <= 500

amount?integer

Expected total in cents. If provided, must match the computed item total (validation safeguard).

Range100 <= value <= 1000000

customer?

coupon_code?string

Coupon code to apply

Lengthlength <= 64

tax_id?string

Tax ID (VAT number)

Lengthlength <= 32

display?

Checkout UI configuration

metadata?

Key-value pairs attached to the session. Flows through to the order and webhook payloads. Max 20 keys, key max 40 chars, value max 500 chars.

return_url?string

URL to redirect after successful payment. Must use HTTPS.

Formaturi

cancel_url?string

URL to redirect if the customer cancels. Must use HTTPS.

Formaturi

Response Body

`application/json`

curl -X POST "https://example.com/stores/string/checkouts" \  -H "Content-Type: application/json" \  -d '{    "items": [      {        "product_id": "string",        "quantity": 1      }    ]  }'

{  "ok": true,  "data": {    "id": "string",    "title": "string",    "description": "string",    "checkout_url": "http://example.com",    "pay_redirect_url": "http://example.com",    "merchant": {      "id": "string",      "name": "string",      "handle": "string",      "slug": "string",      "logo": "string",      "favicon": "string",      "accentColor": "string",      "primaryColor": "string",      "statementDescriptor": "string",      "supportEmail": "string"    },    "amount": 0,    "discount_amount": 0,    "tax_amount": 0,    "total_amount": 0,    "coupon": {      "code": "string",      "discount_amount": 0    },    "items": [      {        "name": "string",        "amount": 0,        "quantity": 0,        "image": "string"      }    ],    "display": {},    "metadata": {      "property1": "string",      "property2": "string"    },    "return_url": "string",    "cancel_url": "string",    "expires_at": 0  }}

Create checkout session

Path ParametersCopy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

201application/json

400application/json

404application/json

Path Parameters

Request Body

Response Body

`application/json`

`application/json`

`application/json`