> ## Documentation Index
> Fetch the complete documentation index at: https://docs.batchrelay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Checkout Links

> Prepare and revoke studio-scoped guest checkout links safely.

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:

| Operation        | Required scopes                              |
| ---------------- | -------------------------------------------- |
| Create or revoke | `checkout_links:write`, `print_orders:write` |
| Read             | `checkout_links:read`, `print_orders:read`   |

The key must be authorized for the named studio. Individual keys additionally
need the matching studio grant. Anonymous sessions cannot use these endpoints.

## Create a link

```http theme={null}
POST /v1/studios/{studio_id}/checkout-links
Idempotency-Key: your-stable-workflow-id
```

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.

```json theme={null}
{
  "event_id": "evt_example",
  "recipient": {
    "guardian_id": "guardian_example",
    "athlete_event_entry_id": "entry_example"
  },
  "sellable": {
    "type": "item",
    "id": "catalog_item_example",
    "quantity": 1
  }
}
```

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

```http theme={null}
GET /v1/studios/{studio_id}/checkout-links/{link_id}
POST /v1/studios/{studio_id}/checkout-links/{link_id}/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](/idempotency) for retry guidance and
[Sandbox Testing](/sandbox-testing) for the Test Mode boundary.