API reference Checkout sessions Start a checkout for a buyer on your site

Start a checkout for a buyer on your site

POST methodhttps://api.anyshop.io/v1/checkout_sessions

Holds the keys for the buyer: send the buyer to the answer's url, where the buyer's browser starts the payment once anyshop has checked the buyer's own request (a GET of the url alone changes nothing). The amount comes from your prices, the quantity and the coupon; the API takes no price. success_url and cancel_url must be on your store's allowed sites. A test key starts test checkouts. Send an Idempotency-Key: a retry with it answers the same session, as it is now.

Scope checkouts:write
Idempotent with Idempotency-Key
403 store_suspended while suspended

Body

application/json3 required, 6 optional

variantstring The product option to sell (a variant ID); the product's own when it has oneUp to 80 characters
productstring A product with a single optionUp to 80 characters
quantityinteger Default 11 to 1,000
buyer_emailstring requiredWhere anyshop delivers the orderUp to 254 characters
couponstring A coupon code of the storeUp to 64 characters
payment_methodenum paypal, btc, ltc, nowpayments (live mode only) or stripe (cards; some product types may not be available on cards), as your store offers them, or simulated in test mode: it starts when the buyer opens the url. Without it the buyer chooses on the session's pagepaypalbtcltcnowpaymentsstripesimulatedUp to 20 characters
success_urlstring requiredWhere the buyer goes once paid, with ?checkout={id} added: https, on one of your store's allowed sites (or your store's own anyshop address)Up to 2,000 characters
cancel_urlstring requiredWhere the buyer goes if they cancel: https, on one of your allowed sitesUp to 2,000 characters
metadataobject Up to 20 keys (letters, digits, _ . or -, not starting with __), string values; echoed in the order's webhook events as checkout_session.metadata

Headers

Idempotency-Keystring Up to 255 characters. A retry with the same key and request gets the first answer, without running twice (24 hours).

Example

as_live_ or as_test_

curl -X POST https://api.anyshop.io/v1/checkout_sessions \
  -H "Authorization: Bearer $ANYSHOP_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "buyer_email": "",
    "success_url": "",
    "cancel_url": ""
  }'

{
  "object": "checkout_session",
  "id": "",
  "livemode": false,
  "status": "open",
  "url": "",
  "expires_at": "2026-10-02T14:21:07.000Z",
  "amount": 0,
  "currency": "",
  "payment_method": null,
  "order": null,
  "success_url": "",
  "cancel_url": "",
  "metadata": {},
  "created_at": "2026-10-02T14:21:07.000Z"
}

The IDs and keys in these examples are made up. Every schema is in the OpenAPI document, served at https://api.anyshop.io/v1/openapi.json.

Returns

The checkout_session object.

Errors

Status and error.type

400invalid_requestThe request is not valid; error.param names the field
401authenticationNo API key, or it is not valid
403permissionThe key does not have the scope this needs, it is a test key where only a live key may act (the catalog), or the store is suspended (store_suspended)
404not_foundNot found in the key's store and mode
409conflictConflicts with the object's state (type conflict), or an Idempotency-Key reused for another request (type idempotency, code idempotency_key_reused)
429rate_limitedToo many requests; see Retry-After