# Checkout

This page is the full checkout knowledge transfer: every listing, the
orchestrated Buy-click sequence, the amount-sync matrix, dead-PI recovery,
and the completion contract. Amounts are EUR decimal major units and the
**server totals engine is the only amount authority** — the client never
supplies an amount anywhere in this flow.

**Auth for every endpoint on this page:** anon `x-client-id` (checkout is
guest-capable; the one exception is the store setting
`accounts_mode='required'` — see [complete](#post-apistorecartsidcomplete--place-the-order)).

SDK module: `@cartbase/storefront/api/checkout` (+ `carts.completeCart` from
`@cartbase/storefront/api/carts`).

## The two checkout paths

**Orchestrated (recommended — what production storefronts
run):**

```
listShippingOptions(cart_id) ─┐  (render pickers)
listPaymentProviders(cart_id) ┘
        │  Buy click
        ▼
prepareCheckout(cart, {address, shipping_method_id, carrier_metadata,
                       payment_provider XOR payment_method_id})
        │                         ONE atomic call, compensated on failure
        ├─ pp_stripe → stripe.confirmPayment(client_secret) ─┐
        └─ a payment method (Bank transfer, COD…) ───────────┤
                                                             ▼
                                            completeCart(cart) → {type:"order", order}
```

While checkout stays mounted: `syncPaymentAmount()` after anything that
changes the total; `refreshPaymentIfTerminal()` from Stripe Elements
`loaderror` (never proactively).

**Manual (step-by-step, for custom flows):** `updateCart` (address+email) →
`addShippingMethod` → `createPaymentCollection` → `initiatePaymentSession`
→ `completeCart`. Both paths are executed against the live server below.

---

## GET /api/store/shipping-options — list (rule-filtered)

- **Purpose** — render the shipping picker. Pass `cart_id` — it prices the
  options in the cart currency AND gives the checkout-rules engine its
  evaluation context.
- **Auth** — anon `x-client-id`.
- **Request** — `GET ?cart_id=cart_…` (optional; without it `amount` is
  null and cart-dependent hide rules cannot match).
- **Response** — list envelope; `count`/`limit` = the full filtered list
  (no pagination):

```jsonc
{
  "shipping_options": [{
    "id": "so_…", "name": "Standard",
    "provider_id": null,          // the carrier, when the merchant bound one
    "service_zone_id": "sz_…", "shipping_profile_id": "sp_…",
    "data": null,
    "type": { "label": "Express" }, // the option's display label, or null
    "amount": 5,                 // the price the cart pays; null without cart_id
    "price_type": "flat"         // calculated-rate carriers not wired yet
  }],
  "count": 1, "offset": 0, "limit": 1
}
```

- **Eligibility** — four gates run server-side before an option lists:
  the option's shipping profile must be among the cart products' profiles;
  its zone must cover the shipping address; its visibility rules must
  pass; and a price must exist for the cart. Conditional rates (tiers by
  order amount, cart weight, or cart volume) resolve here — `amount` is
  always the tier the cart actually satisfies.
- **Errors** — 404 `cart_not_found` (bad `cart_id`).
- **SDK** — `checkout.listShippingOptions(client, {cart_id})`.
- **Components** — shipping picker, carrier/locker pickers (carrier
  metadata is collected client-side and handed to `prepareCheckout`).
- **Settings** — checkout rules (`target_type=shipping_option`) hide
  options server-side; `checkout_method_order` orders them; fail-open (a
  broken rule never bricks the listing). Hidden-method enforcement is at
  complete (`checkout_method_hidden`), not only here.

```bash
# Payable cart for the whole page (seeded Linen Shirt M + address + email).
CART_JSON=$(curl -sf -X POST "$BASE/api/store/carts" \
  -H "x-client-id: $CLIENT_ID" -H "content-type: application/json" \
  -d '{"email":"checkout-doc-'"$RUN"'@example.test","currency_code":"eur",
       "items":[{"variant_id":"variant_01tst000000000000000002","quantity":1}]}')
CART_ID=$(echo "$CART_JSON" | grep -o '"id":"cart_[^"]*"' | head -1 | cut -d'"' -f4)
REGION_ID=$(echo "$CART_JSON" | grep -o '"region_id":"[^"]*"' | head -1 | cut -d'"' -f4)
test -n "$CART_ID" && test -n "$REGION_ID"

OPTS_JSON=$(curl -sf "$BASE/api/store/shipping-options?cart_id=$CART_ID" \
  -H "x-client-id: $CLIENT_ID")
echo "$OPTS_JSON" | grep -q '"price_type":"flat"'
# Pick a PRICED option — an option without a price row for the cart currency
# lists amount: null and cannot be calculated or prepared. (The listing is
# shared dev-tenant state; never grab blindly the first row.)
SO_ID=$(echo "$OPTS_JSON" | grep -o '"id":"so_[^"]*","name":"Flat Rate (Bulgaria)"' \
  | head -1 | cut -d'"' -f4)
test -n "$SO_ID"
```

---

## POST /api/store/shipping-options/:id/calculate — price one option

- **Purpose** — price a single option for a cart (kept for API parity /
  future calculated-rate carriers; the listing already returns `amount`).
- **Auth** — anon `x-client-id`.
- **Request** — `{cart_id, data?}` — `data` is provider-specific input,
  accepted and currently **ignored** (flat prices only).
- **Response** — `200 {shipping_option}` with `amount` in the cart
  currency.
- **Errors** — 404 `cart_not_found` | `shipping_option_not_found`; 400
  `shipping_price_missing` (no price row in the cart currency) |
  `validation_failed`.
- **SDK** — `checkout.calculateShippingOption(client, id, {cart_id})`.

```bash
curl -sf -X POST "$BASE/api/store/shipping-options/$SO_ID/calculate" \
  -H "x-client-id: $CLIENT_ID" -H "content-type: application/json" \
  -d '{"cart_id":"'"$CART_ID"'"}' | grep -q '"amount"'
```

---

## GET /api/store/payment-providers — list (rule-filtered)

- **Purpose** — render the payment-method picker.
- **Auth** — anon `x-client-id`.
- **Request** — `GET ?region_id=…&cart_id=…`, both optional. Without
  `region_id`: the tenant's enabled providers (global catalog ∩ tenant
  enablement). With it: providers linked to that region. `cart_id` feeds
  the rules engine — storefronts SHOULD pass it during checkout.
- **Response** — list envelope, full filtered list. Two entry shapes share
  the array: connected PROCESSORS (`{id}` — pp_stripe) and merchant
  payment METHODS (`{payment_method_id, name, kind, instructions,
  fee_amount, fee_label}` — "Bank transfer", the COD method). Methods
  carry no provider id anywhere; a fresh store with nothing configured
  gets an honestly empty list. With `region_id`, BOTH families filter by
  the region's claims (`region_payment_provider` /
  `region_payment_method` — availability is a per-region merchant
  choice):

```jsonc
{
  "payment_providers": [
    { "id": "pp_stripe", "is_enabled": true, "created_at": "…" },
    // one entry PER enabled, region-claimed merchant method:
    { "payment_method_id": "pm_…", "name": "Bank transfer",
      "kind": "manual", "instructions": "IBAN BG…",
      "fee_amount": null, "fee_label": null },
    { "payment_method_id": "pm_…", "name": "Cash on delivery",
      "kind": "cod", "instructions": null,
      "fee_amount": 4.99, "fee_label": "COD fee" }
    // pp_giftcard is INTERNAL tender and is never listed
  ],
  "count": 3, "offset": 0, "limit": 3
}
```

- **Selecting a method** — initiate the session with the method id alone:
  `POST …/payment-sessions { payment_method_id: "pm_…" }`. The server
  validates it (tenant's, enabled, claimed for the cart's region — 400
  otherwise), the session lands with `provider_id` NULL, and the method's
  identity is snapshotted into `session.data`
  (`payment_method_id/name/kind`) so payment surfaces say "Bank
  transfer" without a join. Render `instructions` to the shopper after
  selection and on the confirmation screen. `fee_amount`/`fee_label` let
  the checkout PREDICT the fee before the session exists — the authority
  stays the server totals (`payment_method_fee_total`).
- **Errors** — none beyond the standard envelope (empty list when nothing
  is enabled); initiate 400s on unknown/disabled/foreign method ids and
  `payment_method_not_in_region` for an unclaimed region.
- **SDK** — `checkout.listPaymentProviders(client, {region_id, cart_id})`.
- **Components** — payment picker.
- **Settings** — Stripe connects in Settings, Payments (provisions
  `pp_stripe` + credentials); payment methods live in the same screen
  (the COD switch + named manual methods, each with optional
  `fee_amount`/`fee_label` and per-region availability); checkout rules
  (`target_type=payment_method`, method entries participate under their
  `payment_method_id`) + `checkout_method_order`.

```bash
curl -sf "$BASE/api/store/payment-providers?cart_id=$CART_ID" \
  -H "x-client-id: $CLIENT_ID" | grep -q '"payment_method_id"'
PAY_JSON=$(curl -sf "$BASE/api/store/payment-providers?region_id=$REGION_ID&cart_id=$CART_ID" \
  -H "x-client-id: $CLIENT_ID")
echo "$PAY_JSON" | grep -q '"payment_method_id"'
# The seeded Bank transfer method carries the rest of this page.
PM_ID=$(echo "$PAY_JSON" | grep -o '"payment_method_id":"pm_[^"]*"' | head -1 | cut -d'"' -f4)
test -n "$PM_ID"
```

---

## POST /api/store/carts/:id/prepare-checkout — the atomic Buy click

ONE call writes everything the customer toggled on /checkout, in the only
safe order: **address first** (option pricing reads the destination) →
**shipping method** → **payment collection** at the shipped total →
**payment session LAST** at the FINAL amount (real Stripe PaymentIntent,
idempotency key = session id; a plain NULL-provider row for a payment
method). A method's fee only applies once its session exists, so amounts
are re-synced after it. Fully compensated: any failure rolls back session
→ collection → shipping method → addresses/metadata to the pre-call
snapshot (recorded in the execution ledger, workflow `prepare-checkout`,
states done/reverted; failures also land in `checkout_error_logs`, step
`prepare-checkout`).

- **Auth** — anon `x-client-id`.
- **Request** (`.strict()`; DTO verbatim from
  `src/lib/checkout-orchestration/prepare.ts`) — all address fields
  required except `address_2`/`company`/`province`; `phone` is required
  (courier recovery channel). The tender is exactly ONE of
  `payment_provider` (a connected processor — `pp_stripe`, never
  `pp_giftcard`) or `payment_method_id` (a merchant method from the
  listing):

```jsonc
{
  "shipping_address": {
    "first_name": "Jane", "last_name": "Dow",
    "address_1": "Vitosha 1", "address_2": "",
    "company": "", "province": "",
    "city": "Sofia", "postal_code": "1000",
    "country_code": "bg", "phone": "+359888123456"
  },
  "shipping_method_id": "so_…",          // a shipping-option id
  "shipping_method_data": {},            // optional, stored on the method row
  "carrier_metadata": {                  // optional, opaque per-carrier keys
    "office_code": "X1", "office_name": "Center"
  },
  "payment_method_id": "pm_…",           // XOR payment_provider: "pp_stripe"
  "save_payment_method": false           // optional — subscription carts only;
                                         // same semantics + consent duty as on
                                         // payment-sessions below
}
```

  Billing mirrors shipping (own row). `carrier_metadata` merges into
  `cart.metadata`; keys written by the PREVIOUS prepare call are removed
  first (tracked under the reserved `_prepared_carrier_keys` marker) —
  switching carriers can never leak the old carrier's fields into the
  order.

- **Response** (verbatim `PrepareCheckoutResult`):

```jsonc
{
  "cart_id": "cart_…",
  "payment_collection_id": "pc_…",
  "client_secret": "pi_…_secret_…",   // Stripe only; null for method sessions AND zero-remainder carts
  "provider_id": null,                // the processor, when one was chosen
  "payment_method_id": "pm_…"         // the method, when one was chosen
}
```

- **Zero-remainder gift path** — when applied gift cards cover the whole
  total, the tender session is skipped entirely (`client_secret`,
  `provider_id` and `payment_method_id` come back null) and the cart
  completes on the gift session alone — no Stripe involved
  ([gift-cards.md](gift-cards.md)).
- **Errors** — 404 `cart_not_found` | `shipping_option_not_found`; 409
  `cart_completed`; 400 `validation_failed` | `invalid_provider`
  (pp_giftcard) | `shipping_price_missing` | `stripe_not_configured`.
- **SDK** — `checkout.prepareCheckout(client, cartId, input)`.
- **Components** — the checkout form's Buy button; carrier/locker pickers
  feed `carrier_metadata`.
- **Settings** — Stripe credentials (admin integrations), COD fee, gift
  cards; checkout rules are enforced at the listings and at complete, not
  here.

```bash
PREP_JSON=$(curl -sf -X POST "$BASE/api/store/carts/$CART_ID/prepare-checkout" \
  -H "x-client-id: $CLIENT_ID" -H "content-type: application/json" \
  -d '{"shipping_address":{"first_name":"Doc","last_name":"Run",
        "address_1":"Vitosha 1","city":"Sofia","postal_code":"1000",
        "country_code":"bg","phone":"+359888123456"},
       "shipping_method_id":"'"$SO_ID"'",
       "carrier_metadata":{"office_code":"X1"},
       "payment_method_id":"'"$PM_ID"'"}')
echo "$PREP_JSON" | grep -q '"payment_method_id":"'"$PM_ID"'"'
echo "$PREP_JSON" | grep -q '"client_secret":null'
PC_ID=$(echo "$PREP_JSON" | grep -o '"payment_collection_id":"pc_[^"]*"' | cut -d'"' -f4)
test -n "$PC_ID"

# Error contract: pp_giftcard is never a selectable provider.
GC_RES=$(curl -s -X POST "$BASE/api/store/carts/$CART_ID/prepare-checkout" \
  -H "x-client-id: $CLIENT_ID" -H "content-type: application/json" \
  -d '{"shipping_address":{"first_name":"Doc","last_name":"Run",
        "address_1":"Vitosha 1","city":"Sofia","postal_code":"1000",
        "country_code":"bg","phone":"+359888123456"},
       "shipping_method_id":"'"$SO_ID"'",
       "payment_provider":"pp_giftcard"}')
echo "$GC_RES" | grep -q '"code":"invalid_provider"'
```

---

## POST /api/store/carts/:id/sync-payment-amount — align amounts in place

Aligns the pending provider session with the cart's CURRENT total, in
place when possible — the happy path returns the **same** `client_secret`
so `<Elements>` never remounts (the fix for the "InitiateCheckout fires
four times when I change shipping" bug class). Call after anything that
changes the total while checkout is mounted (quantity change, gift card
applied/removed, shipping switch).

- **Auth** — anon `x-client-id`.
- **Request** — `{provider_id? | payment_method_id?}` (`.strict()`; empty
  object fine, never both). Passing a DIFFERENT tender than the pending
  session's forces rotation to it.
- **Response matrix** (verbatim `src/lib/checkout-orchestration/sync.ts`):

| state | response |
|---|---|
| completed cart | `{"synced":false,"reason":"cart-completed"}` |
| no payment collection | `{"synced":false,"reason":"no_payment_collection"}` |
| no pending provider session (gift sessions excluded) | `{"synced":false,"reason":"no_pending_session"}` |
| tender matches, amount current | `{"synced":true,"rotated":false,"client_secret":…,"provider_id":…,"payment_method_id":…}` (no-op) |
| tender matches, amount drifted | in-place update (Stripe `paymentIntents.update`; plain field for method sessions) → `{"synced":true,"rotated":false,…}` — same secret |
| tender mismatch OR update refused (terminal PI) | rotation: old session retired (+ PI voided best-effort), fresh session at the new remainder → `{"synced":true,"rotated":true,…}` |

  A session's tender identity is its `provider_id` for processors and its
  snapshot `payment_method_id` for NULL-provider method sessions. Rotation
  retires the old session BEFORE recomputing so session-dependent totals
  (the method fee) settle for the NEW tender; a final resync pass aligns
  collection + session + PI. `client_secret` is null for method sessions.

- **Errors** — 404 `cart_not_found`; 400 `validation_failed` |
  `stripe_not_configured`. Failures land in `checkout_error_logs`
  (step `sync-payment-amount`).
- **SDK** — `checkout.syncPaymentAmount(client, cartId, {provider_id?,
  payment_method_id?})`.
- **Components** — checkout totals watcher (debounced), payment-method
  switcher (pass the new tender id).

```bash
# No-drift no-op on the prepared method cart: same-session, not rotated.
SYNC_JSON=$(curl -sf -X POST "$BASE/api/store/carts/$CART_ID/sync-payment-amount" \
  -H "x-client-id: $CLIENT_ID" -H "content-type: application/json" -d '{}')
echo "$SYNC_JSON" | grep -q '"synced":true'
echo "$SYNC_JSON" | grep -q '"rotated":false'
echo "$SYNC_JSON" | grep -q '"payment_method_id":"pm_'
```

---

## POST /api/store/carts/:id/refresh-payment-if-terminal — dead-PI recovery

A Stripe PaymentIntent can die out-of-band (canceled in the Dashboard,
Stripe's 24h auto-cancel, captured externally) while the local session
stays `pending`; mounting Elements on the dead `client_secret` fails with
"PaymentIntent is in a terminal state". This route reconciles against
Stripe's ACTUAL PI and rotates a fresh session/PI only when the intent is
truly dead. **Call it reactively** — Elements `loaderror` / page mount for
aged carts — never proactively per render (the proactive variant caused a
production reload loop).

- **Auth** — anon `x-client-id`. No body.
- **Response** (verbatim `src/lib/checkout-orchestration/refresh.ts`) —
  rotated: `{"rotated":true,"reason":"pi-terminal"|"pi-missing",
  "previous_status":…}` (terminal = `succeeded`/`canceled`/
  `requires_capture`, or a `resource_missing` PI). Not rotated:
  `cart-completed` | `no-stripe-session` (also when the pending session is
  non-Stripe) | `no-pi-id` | `stripe-not-configured` | `still-usable`
  (+ `status`) | `stripe-error` (+ `error`) — **any transient Stripe error
  refuses to rotate** (rotating on transient failures was the loop bug).
  Every rotation writes an audit row (`checkout_error_logs` step
  `refresh-payment`, code `rotated`).
- **Errors** — 404 `cart_not_found`.
- **SDK** — `checkout.refreshPaymentIfTerminal(client, cartId)`.
- **Components** — Stripe Elements mount error handler.

```bash
# Method session ⇒ documented no-op reason (Stripe-specific rotation
# needs STRIPE credentials — proven by tests/store/checkout-orchestration-sync.test.ts).
curl -sf -X POST "$BASE/api/store/carts/$CART_ID/refresh-payment-if-terminal" \
  -H "x-client-id: $CLIENT_ID" | grep -q '"reason":"no-stripe-session"'
```

---

## POST /api/store/carts/:id/complete — place the order

The last call of every checkout. Sequence server-side: idempotency check →
CAS lock → validation → **checkout-rules completion guard** → inventory
reservation (kit-aware) → order creation (rows copied cart→order) →
**subscription contracts** (carts with plan lines: one contract per plan,
cycle 1 tied to this order, cycle 2 scheduled at the next CHARGE date;
guests are refused with 400 `customer_required`) → **payment authorization
LAST** (gift tender redeemed atomically first; real Stripe authorize for
`pp_stripe`; best-effort stub for method sessions) → `order.placed`
(+ `subscription.created` per contract) on the durable bus. Any failure
before authorize compensates fully (order deleted, contracts deleted,
inventory released, gift tender reversed, cart unlocked) — the cart stays
open and retryable. Note: subscription carts auto-save the card at the
payment-session step (see `save_payment_method` above) — by complete time
the mandate already exists.

- **Auth** — anon `x-client-id` (guest checkout). Store setting
  `accounts_mode='required'` → guest carts (no attached customer) get
  **403 `account_required`**; `disabled`/`optional` leave guests untouched.
- **Request** — `POST`, empty body.
- **Response** — `200 {"type":"order","order":{…}}` — the order with
  `summary` and flattened `items`. Idempotent: re-calling returns the SAME
  order; concurrent completes are serialized by the CAS lock (the loser
  returns the winner's order or 409 `cart_locked`).
  > Contract note (code wins over store-api.md): the documented
  > `{type:"cart", cart, error}` failure union is never returned — failures
  > throw the standard error envelope.
- **Errors** —
  - 400 validation: `cart_email_required` | `cart_empty` |
    `shipping_address_required` | `shipping_method_required` (only when a
    line `requires_shipping` — digital-only carts, e.g. digital gift
    cards, skip it) | `payment_collection_required` |
    `payment_session_required` | `insufficient_inventory` |
    `customer_required` (plan lines on a guest cart — subscribing needs an
    account; normally already refused at the payment-session step).
  - 400 `checkout_method_hidden` — **the checkout-rules security
    boundary**: every live payment session's chosen tender (the method's
    `payment_method_id` for NULL-provider sessions, else the provider id;
    internal `pp_giftcard` exempt) and every chosen shipping option is
    re-validated against the live rules with the full cart context. A
    stale session
    that picked a method before a rule started matching, or a hostile
    client that skipped the filtered listings, is rejected here and the
    rejection is recorded in `checkout_error_logs` (step `complete`).
  - 402 payment family: `requires_action` (3DS — `details.client_secret`
    carries the intent to confirm) | `payment_not_authorized` |
    `payment_not_initiated` (Stripe session without a PI — re-initiate) |
    `payment_incomplete` (gift tender no longer covers a session-less
    total) | `gift_card_insufficient_balance` (lost double-spend race) |
    `gift_card_not_redeemable`.
  - 403 `account_required`; 409 `cart_locked`.
- **SDK** — `carts.completeCart(client, cartId)` (module
  `@cartbase/storefront/api/carts`).
- **Components** — Buy button (orchestrated path), order-confirmation
  page.
- **Settings** — checkout rules; `accounts_mode`; the payment method fee
  (**timing**: a method's fee exists only while ITS live session does — it
  appears on the cart at prepare as `payment_method_fee_total`, rides
  `cart.total`, and is carried onto the order via
  `order_summaries.totals`, where waybill COD amounts read it); gift-card
  tender (zero-remainder carts complete on the gift session alone).

```bash
# Complete the prepared method cart → a real order, no Stripe env needed.
ORDER_JSON=$(curl -sf -X POST "$BASE/api/store/carts/$CART_ID/complete" \
  -H "x-client-id: $CLIENT_ID" -H "content-type: application/json" -d '{}')
echo "$ORDER_JSON" | grep -q '"type":"order"'
ORDER_ID=$(echo "$ORDER_JSON" | grep -o '"id":"order_[^"]*"' | head -1 | cut -d'"' -f4)
test -n "$ORDER_ID"

# Idempotency: completing again returns the SAME order.
ORDER_ID2=$(curl -sf -X POST "$BASE/api/store/carts/$CART_ID/complete" \
  -H "x-client-id: $CLIENT_ID" -H "content-type: application/json" -d '{}' \
  | grep -o '"id":"order_[^"]*"' | head -1 | cut -d'"' -f4)
test "$ORDER_ID" = "$ORDER_ID2"

# Post-completion contracts: mutations 409, sync/refresh report the reason.
STATUS=$(curl -s -o /dev/null -w '%{http_code}' -X POST \
  "$BASE/api/store/carts/$CART_ID/line-items" \
  -H "x-client-id: $CLIENT_ID" -H "content-type: application/json" \
  -d '{"variant_id":"variant_01tst000000000000000003","quantity":1}')
test "$STATUS" = 409
curl -sf -X POST "$BASE/api/store/carts/$CART_ID/sync-payment-amount" \
  -H "x-client-id: $CLIENT_ID" -H "content-type: application/json" -d '{}' \
  | grep -q '"reason":"cart-completed"'
curl -sf -X POST "$BASE/api/store/carts/$CART_ID/refresh-payment-if-terminal" \
  -H "x-client-id: $CLIENT_ID" | grep -q '"reason":"cart-completed"'
```

---

## POST /api/store/checkout-errors — browser-side error reporting

The browser half of checkout error capture. The server logs every money-path
failure into the merchant's checkout error log on its own; failures that
happen only in the customer's browser — a Stripe.js confirm error, a 3DS
return that comes back not-succeeded, a place-order rejection — are reported
through this endpoint. `useCheckoutOrchestration` reports them **by
default**; you only call this yourself if you replaced the hook's `logError`
and still want the platform log.

Body (`.strict()`): `error_type` (≤64 chars), `message` (≤2000),
optional `cart_id`, optional `context` object (redacted values only — ids,
codes, flags; **never card data, never addresses**; oversized context is
stored as `{truncated: true}`). Answers `204` always on accepted input;
`400` malformed; `429` past 60 reports/store/minute. Fire-and-forget: the
SDK's `reportCheckoutError()` swallows every failure — reporting an error
must never take a checkout down.

## Modifying checkout — the laws

Checkout is **locked space** (LOCK_BOUNDARIES): critical-to-function code is
closed; customize through props, slots and tokens, never by editing the
package's files. What that means in practice:

- **Fork the layout, never the logic.** `useCheckoutOrchestration` is the
  one brain — session guard, amount sync, dead-PI recovery, 3DS return,
  compensation-aware completion. A fork of the hook once dropped the
  session guard and produced zombie Stripe sessions; the hook exists so
  that class of bug is structurally impossible. Build your own screens on
  top of the hook; do not reimplement it.
- **The server owns every amount.** The client never sends an amount;
  sessions charge `total − gift_card_total` computed server-side. Any
  checkout change that puts a number in a request body is wrong by
  construction.
- **Logging is not optional.** Money failures must reach the merchant: the
  hook's default sink does this. If you override `logError`, either call
  `reportCheckoutError()` yourself or accept that browser failures vanish —
  and that is a defect, not a preference.
- **Debug output is opt-in.** `useCheckoutOrchestration({ debug: true })`
  turns on verbose `[buy-click]` console output for local work. It prints
  the full prepare payload (name, phone, email, address), so it must never
  ship enabled.
- **Test against the real wire.** Every request/response shape on this page
  is executable against a store; a checkout change ships with its route
  driven end to end, error branches included.

## Manual path — collections + sessions (step-by-step)

### POST /api/store/payment-collections

- **Purpose** — ensure the cart's payment collection (ONE per cart,
  idempotent; the amount is refreshed to the CURRENT decorated total on
  every call).
- **Auth** — anon `x-client-id`.
- **Request** — `{cart_id}`.
  > Contract note (code wins over store-api.md): the contract's
  > `provider_id`/`data` fields are ignored — the provider is chosen when
  > initiating the session.
- **Response** — `201 {payment_collection}` when created, `200` when the
  existing one was refreshed. `{id, amount, currency_code,
  status:"not_paid", payment_sessions:[…]}`. The moment a collection
  exists, applied gift-card tender is composed as an internal
  `pp_giftcard` session.
- **Errors** — 404 `cart_not_found`; 400 `validation_failed`.
- **SDK** — `checkout.createPaymentCollection(client, {cart_id})`.

### POST /api/store/payment-collections/:id/payment-sessions

- **Purpose** — mint (or repair) the tender session — idempotent per
  tender. For Stripe the PaymentIntent is minted FIRST (idempotency key
  = session id) so a Stripe session row can never exist without its
  intent; amount drift syncs the PI in place; terminal PIs self-heal by
  rotation. Method sessions share ONE NULL-provider row per collection —
  switching methods updates its snapshot in place.
- **Auth** — anon `x-client-id`.
- **Request** — `{provider_id? XOR payment_method_id?, data?,
  save_payment_method?}` — exactly one tender. Keys the server owns
  (`payment_intent_id`, `client_secret`, `status`, `stripe_customer_id`,
  `setup_future_usage`, and the method snapshot
  `payment_method_id/name/kind`) are stripped from `data` — they cannot
  be forged from the client.
- **`save_payment_method`** — saves the card for future off-session
  renewal charges: the server resolves the CART'S customer (never a
  client-supplied id), ensures a Stripe Customer for them, and mints the
  PaymentIntent with `setup_future_usage: "off_session"`. **Automatic for
  subscription carts**: when the cart carries plan lines the server
  applies the mandate even without the flag (a subscription cannot renew
  without it — the server owns the decision). Requires a logged-in
  customer — a guest cart is a 400 `customer_required` (subscribing needs
  an account), raised HERE, before any payment. **Consent**: the mandate
  moment — the storefront MUST render the saved-card consent text with
  the plan selection / next to the payment element (e.g. "Your card will
  be saved for future subscription charges"). Re-initiating an existing
  session with the flag (or after a plan line appears) upgrades the live
  intent in place (same `client_secret`). No card to save on method
  sessions (COD/manual subscriptions renew offline) — the account gate
  still applies. Never set the flag on ordinary checkouts.
- **Response** — `201 {payment_session}` when created, `200` when the
  existing one was returned/repaired: `{id, provider_id, amount,
  currency_code, status:"pending", authorized_at:null, data}` — for
  Stripe, `data` carries `payment_intent_id` + `client_secret` (mount
  Elements with it); with `save_payment_method` it also carries
  `setup_future_usage: "off_session"` + `stripe_customer_id`. For a
  method, `provider_id` is null and `data` carries the snapshot
  (`payment_method_id`, `payment_method_name`, `payment_method_kind`).
  The session `amount` is `collection.amount − gift_card_total` — the
  remainder.
- **Errors** — 404 `payment_collection_not_found`; 400 `invalid_provider`
  (pp_giftcard, or an id the catalog doesn't know — the dead pp_ ids land
  here) | `payment_provider_disabled` | `payment_provider_not_in_region` |
  `payment_method_not_in_region` | `stripe_not_configured` |
  `customer_required` | `validation_failed`.
- **SDK** — `checkout.initiatePaymentSession(client, pcId, {provider_id?,
  payment_method_id?, save_payment_method?})`.

### POST /api/store/carts/:id/shipping-methods

- **Purpose** — set the cart's shipping method manually (single-method
  model: the previous method rows are replaced).
- **Auth** — anon `x-client-id`.
- **Request** — `{option_id, data?}` (`.strict()`).
- **Response** — `200 {cart}` (decorated; `shipping_total` now non-zero).
- **Errors** — 404 `cart_not_found` | `shipping_option_not_found`; 409
  `cart_completed`; 400 `shipping_price_missing` | `validation_failed`.
- **SDK** — `checkout.addShippingMethod(client, cartId, {option_id})`.

```bash
# The whole manual path, executable: cart → method → collection → session → order.
CART2_JSON=$(curl -sf -X POST "$BASE/api/store/carts" \
  -H "x-client-id: $CLIENT_ID" -H "content-type: application/json" \
  -d '{"email":"checkout-doc-manual-'"$RUN"'@example.test",
       "items":[{"variant_id":"variant_01tst000000000000000002","quantity":1}],
       "shipping_address":{"first_name":"Doc","last_name":"Manual",
         "address_1":"Vitosha 2","city":"Sofia","postal_code":"1000",
         "country_code":"bg","phone":"+359888123457"}}')
CART2_ID=$(echo "$CART2_JSON" | grep -o '"id":"cart_[^"]*"' | head -1 | cut -d'"' -f4)

curl -sf -X POST "$BASE/api/store/carts/$CART2_ID/shipping-methods" \
  -H "x-client-id: $CLIENT_ID" -H "content-type: application/json" \
  -d '{"option_id":"'"$SO_ID"'"}' \
  | grep -q '"shipping_option_id":"'"$SO_ID"'"'

# Fresh cart, no collection yet → sync reports why it can't sync.
curl -sf -X POST "$BASE/api/store/carts/$CART2_ID/sync-payment-amount" \
  -H "x-client-id: $CLIENT_ID" -H "content-type: application/json" -d '{}' \
  | grep -q '"reason":"no_payment_collection"'

PC2_JSON=$(curl -sf -X POST "$BASE/api/store/payment-collections" \
  -H "x-client-id: $CLIENT_ID" -H "content-type: application/json" \
  -d '{"cart_id":"'"$CART2_ID"'"}')
echo "$PC2_JSON" | grep -q '"status":"not_paid"'
PC2_ID=$(echo "$PC2_JSON" | grep -o '"id":"pc_[^"]*"' | head -1 | cut -d'"' -f4)

SES_JSON=$(curl -sf -X POST \
  "$BASE/api/store/payment-collections/$PC2_ID/payment-sessions" \
  -H "x-client-id: $CLIENT_ID" -H "content-type: application/json" \
  -d '{"payment_method_id":"'"$PM_ID"'"}')
echo "$SES_JSON" | grep -q '"provider_id":null'
echo "$SES_JSON" | grep -q '"payment_method_name"'
echo "$SES_JSON" | grep -q '"status":"pending"'

# Error contract: the internal gift tender is not initiable.
GCS_RES=$(curl -s -X POST \
  "$BASE/api/store/payment-collections/$PC2_ID/payment-sessions" \
  -H "x-client-id: $CLIENT_ID" -H "content-type: application/json" \
  -d '{"provider_id":"pp_giftcard"}')
echo "$GCS_RES" | grep -q '"code":"invalid_provider"'

curl -sf -X POST "$BASE/api/store/carts/$CART2_ID/complete" \
  -H "x-client-id: $CLIENT_ID" -H "content-type: application/json" -d '{}' \
  | grep -q '"type":"order"'
```

```bash
# save_payment_method on a GUEST cart is refused — subscribing needs an
# account (provider-independent: fires before any Stripe call).
CART3_JSON=$(curl -sf -X POST "$BASE/api/store/carts" \
  -H "x-client-id: $CLIENT_ID" -H "content-type: application/json" \
  -d '{"email":"checkout-doc-guest-sub-'"$RUN"'@example.test",
       "items":[{"variant_id":"variant_01tst000000000000000002","quantity":1}]}')
CART3_ID=$(echo "$CART3_JSON" | grep -o '"id":"cart_[^"]*"' | head -1 | cut -d'"' -f4)

PC3_JSON=$(curl -sf -X POST "$BASE/api/store/payment-collections" \
  -H "x-client-id: $CLIENT_ID" -H "content-type: application/json" \
  -d '{"cart_id":"'"$CART3_ID"'"}')
PC3_ID=$(echo "$PC3_JSON" | grep -o '"id":"pc_[^"]*"' | head -1 | cut -d'"' -f4)

curl -s -X POST "$BASE/api/store/payment-collections/$PC3_ID/payment-sessions" \
  -H "x-client-id: $CLIENT_ID" -H "content-type: application/json" \
  -d '{"payment_method_id":"'"$PM_ID"'","save_payment_method":true}' \
  | grep -q '"code":"customer_required"'
```

---

## Stripe specifics (needs STRIPE credentials — not executable here)

```bash
# doc-noexec — requires the store's Stripe integration (admin-configured
# credentials); the mocked equivalents run in
# tests/store/checkout-orchestration.test.ts + checkout-stripe.test.ts.
PREP=$(curl -sf -X POST "$BASE/api/store/carts/$CART_ID/prepare-checkout" \
  -H "x-client-id: $CLIENT_ID" -H "content-type: application/json" \
  -d '{"shipping_address":{…},"shipping_method_id":"so_…","payment_provider":"pp_stripe"}')
# → {"cart_id":…,"payment_collection_id":"pc_…","client_secret":"pi_…_secret_…","provider_id":"pp_stripe"}
# Storefront: stripe.confirmPayment({clientSecret}) → POST …/complete.
# 3DS never-returned / redirect flows: the payment_intent.succeeded webhook
# (POST /api/webhooks/payment/complete-on-success, configured in Stripe)
# completes the cart server-side through the SAME complete flow.
```

Sync/refresh behavior with Stripe follows the matrices above: in-place
`paymentIntents.update` keeps the secret stable; provider mismatch or a
terminal PI rotates (old PI voided best-effort); `refreshPaymentIfTerminal`
rotates only on `succeeded`/`canceled`/`requires_capture`/missing.

## Admin-config-dependent contracts (documented, proven by the suite)

- **`checkout_method_hidden` (400)** — requires an admin checkout rule;
  exercised by `tests/store/checkout-rules.test.ts`.
- **`account_required` (403)** — requires `accounts_mode='required'` on
  the store; exercised by `tests/store/customer-accounts-policy.test.ts`.
- **Payment method fee** — any method may carry `fee_amount`/`fee_label`
  (the COD method included); exercised by
  `tests/store/payment-method-fee.test.ts` (method-switch switches the
  fee) and `tests/store/checkout-orchestration.test.ts` (fee-inclusive
  session on prepare with the COD method).

## Cleanup / accretion note

This page creates two carts and completes two method-tender orders on the
shared dev tenant — the same inert accretion the checkout test suites
produce (no store-facing delete exists for either; suites always create
their own carts/orders and never re-read foreign ones).