Start (or resume) checkout for an order

Starts, or returns the existing active, checkout session for an order. Idempotent while a session is still active — calling this repeatedly before expiry returns the same token.

POST/orders/{order_id}/checkout_session

Authorization

AuthorizationBearer token (JWT) · headerrequired

Path parameters

order_idstringrequired

Request body

application/json

return_urlstring

Where to redirect the buyer after a hosted-redirect-mode gateway round-trip. Its host must match the shop's own domain or one of its configured allowed embed origins — any other host is rejected with 422, to prevent open redirects. Only applied if the session doesn't already have a return_url (first caller wins); ignored on later idempotent calls.

Responses

200

Checkout session

tokenstring

statusstring

order_idinteger

return_urlstring | null

Where the buyer is redirected after a hosted-redirect-mode gateway round-trip (see storefronts headless-reference.md). Set at most once per session lineage — the first non-blank return_url given to POST /orders/{order_id}/checkout_session wins; later calls while the same session is still active are ignored. Carried forward automatically if the session is later forked due to a stale cart total.

expires_atstring<date-time>

last_viewed_atstring<date-time> | null

view_countinteger

checkout_urlstring

422

Either this shop is not on the session-based checkout, or return_url was given but its host isn't allowed for this shop

Try it

Server

Base URLCustom base URLOverrides the selected server when set.

Authorization

Bearer token (JWT)Remember on this deviceInclude my values in samples

Parameters

order_idpath*

Bodyapplication/json

return_urlstringWhere to redirect the buyer after a hosted-redirect-mode gateway round-trip. Its host must match the shop's own domain or one of its configured allowed embed origins — any other host is rejected with 422, to prevent open redirects. Only applied if the session doesn't already have a `return_url` (first caller wins); ignored on later idempotent calls.

Request

curl -X POST 'https://api.onbolder.com/v2/orders/string/checkout_session' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "return_url": "https://mystore.com/order/confirmation"
}'

const response = await fetch("https://api.onbolder.com/v2/orders/string/checkout_session", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Accept": "application/json",
    "Content-Type": "application/json"
  },
  body: "{\n  \"return_url\": \"https://mystore.com/order/confirmation\"\n}"
});

import requests

response = requests.post(
    "https://api.onbolder.com/v2/orders/string/checkout_session",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Accept": "application/json",
        "Content-Type": "application/json"
    },
    data="{\n  \"return_url\": \"https://mystore.com/order/confirmation\"\n}",
)

Response

{
  "token": "string",
  "status": "string",
  "order_id": 0,
  "return_url": "string",
  "expires_at": "2019-08-24T14:15:22Z",
  "last_viewed_at": "2019-08-24T14:15:22Z",
  "view_count": 0,
  "checkout_url": "string"
}