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

200Checkout 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

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

Request

curl -X POST "https://api.onbolder.com/v2/orders/string/checkout_session" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -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",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
  "return_url": "https://mystore.com/order/confirmation"
})
});

import requests

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

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