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 both checkout link and print-order scope: 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.
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.