DocsCheckout

Checkout with the API

Create once. Read the returned checkout until it needs input or reaches a final state.

Create
Use an operational user key from your secure server environment. Set CHECKOUT_REQUEST_KEY to a unique value for this checkout. Keep it unchanged if you retry the same request.
HTTP · POST /v1/checkout
```
curl https://api.shopstack.ai/v1/checkout \
  -H "Authorization: Bearer $SHOPSTACK_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $CHECKOUT_REQUEST_KEY" \
  --data-binary @checkout.json
```
Use the checkout request body. A 202 response means accepted. Save its id as CHECKOUT_ID; it is not an order confirmation.
Read current state
HTTP · GET /v1/checkout/{id}
```
curl "https://api.shopstack.ai/v1/checkout/$CHECKOUT_ID" \
  -H "Authorization: Bearer $SHOPSTACK_API_KEY"
```
Display status and activity. Read required_input, approval, result, and failure when present.
Handle the next action
help_required
For an ordinary question, read messages and send {"content":"Choose size M."} to the messages route.
required_input.type = payment_card
Use your protected card input interface and the payment-details route. Do not send card data as a message.
approval_required
Show the current amount breakdown and expiry. After the user decides, send the returned approval ID and their decision through your trusted payment interface.
POST /v1/checkout/{id}/payment-approval · body shape
```
{
  "approval_id": "<current approval.id>",
  "approved": true
}
```
Card input and approval require checkout:approve. Use an Idempotency-Key for each mutation; reuse it only for retries of that same operation.
Stop at a final state
Stop monitoring at complete, failed, or cancelled. Read the result or failure fields. Do not treat submitting as success.

Progress updates & live view

In the current API source, POST /checkout/{id}/updates returns a one-time WebSocket subscription. Use the returned socket_url, protocol shopstack.v1, and token as subprotocols. Each notification tells you when to read the checkout again.

The HTTP fallback is GET /checkout/{id}/updates?after=PRESENTATION_REVISION&wait=25. It returns current state with 200, or 204 when there is no change.

presentation_revision tracks display changes. revision tracks lifecycle changes. They are separate.

The accepted checkout includes an owner-only live_view_url. Use it exactly as returned. A replacement link invalidates the previous viewer. The live page can stop checkout or accept a requested card; it cannot approve payment.

Endpoint reference

All paths below use https://api.shopstack.ai/v1.

GET/checkout/{id}: Read current state and result.
GET / POST/checkout/{id}/messages: Read questions or send ordinary information.
POST/checkout/{id}/payment-details: Supply protected card input when requested.
POST/checkout/{id}/payment-approval: Approve or decline the exact current payment.
POST/checkout/{id}/cancel: Cancel before submission.
POST/checkout/{id}/live-view: Issue a replacement one-time live-view link.
GET/checkout/{id}/events: Read ordered lifecycle events.

Errors & retries

Errors contain error.code, error.message, and error.request_id. Keep the request ID for support.

Check permissions for 403. For 409, read the current checkout before you act again. For 422, correct the request fields. An uncertain create response must be retried with the original idempotency key.

Checkout with the API

Create

Read current state

Handle the next action

Stop at a final state