Skip to main content
Checkout links prepare the existing guest-checkout ledger. They do not create a Stripe Payment Link or Checkout Session; the web /pay/{token} experience is the only Checkout Session owner. Creation persists the credential-selected checkout lane (sandbox or production) on the link. Use an explicit studio path and an account-owned API key with the checkout-link and print-order scopes. Creating, preparing, or recovering a checkout link also requires offers:apply, because checkout resolves an explicit or automatic offer. The key must be authorized for the named studio. Individual keys additionally need the matching studio grant. Anonymous sessions cannot use these endpoints.
The request names an event, a recipient context, and one sellable item or package. It can optionally be customizable and set expires_at. The server rejects price, tax, payment, provider, token, and unknown fields; it resolves the current published retail amount itself. A requested expiration must be in the future and no more than seven days away. Omitting it defaults to seven days. The optional promotion field selects one code, offer_id, or automatic: true. If omitted, the API selects the active automatic storewide offer. The handler therefore requires offers:apply even when the request does not include a promotion selector. The selected offer is checked against the event, recipient, sellable, date window, and usage limits by the checkout service. For example, a code selector is "promotion": {"code": "FALL2026"}. An offer ID or automatic selection use "promotion": {"offer_id": "off_example"} or "promotion": {"automatic": true}. Supply exactly one selector; prices and discount amounts remain server-owned.
For a new Live Mode link, Batch Relay first requires the studio’s payment readiness. If that check cannot pass, creation fails closed and no link or bearer URL is issued. A successful 201 returns share_url exactly once. It is a bearer capability: deliver it only through the intended private channel and do not store it in logs. The idempotency key is bound to a stable request fingerprint, including the recipient context, sellable, quantity, expiry, customization choice, and prepared-asset or digital configuration inputs. Replaying the same request returns the same lifecycle record without another share_url or token. Reuse of the same key with a different request returns 409 checkout_link_conflict.

​
Test Mode behavior

A br_test_ key selects an isolated Test Mode management lane. Creation returns preview_status: "non_payable" and no URL. The persisted sandbox link is an authenticated management record, not a payment capability, and has no live payment or provider effect. Test Mode does not promote a link, quote, recipient context, or token into Live Mode. Create a separate Live Mode link when that work is approved. A sandbox promotion does not include checkout links. After promoting a storefront or catalog configuration, create new Live Mode links for the approved recipients. Test links remain non-payable.

​
Read and revoke

Both return safe lifecycle metadata: id, expires_at, status, revocable, and a subtotal when present. Reads never expose the token, recipient identity, payment-provider details, or retail line data. Revocation is a lifecycle transition, not deletion; an already non-revocable link returns 409 checkout_link_conflict and no replacement token is minted. Guest payment respects the persisted lane: an explicitly sandboxed link is non-payable, while an explicitly production link is payable, subject to normal guest-checkout lifecycle and storefront-policy checks. For historical rows that predate lane persistence, compatibility is deliberately narrow: staff or guardian links with no machine API-key provenance remain payable; missing-lane machine links fail closed. The service never infers production from current studio policy.

​
Stable errors

Creation can return 400 idempotency_key_required, 409 checkout_link_conflict, 422 invalid_checkout_link, or 503 checkout_link_unavailable. Read and revoke can also return 403 checkout_link_forbidden and 404 checkout_link_not_found. See Idempotency for retry guidance and Sandbox Testing for the Test Mode boundary.