create-cartbase 0.0.1 → 0.1.0

package/template/app/docs/checkout.md

@@ -0,0 +1,611 @@
+# Checkout — shipping options, payment, the Buy click, complete
+
+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})
+        │                         ONE atomic call, compensated on failure
+        ├─ pp_stripe → stripe.confirmPayment(client_secret) ─┐
+        └─ pp_cod / pp_manual ───────────────────────────────┤
+                                                             ▼
+                                            completeCart(cart) → {type:"order", order}
+```
+
+While checkout stays mounted: `syncPaymentAmount()` after anything that
+changes the total; `refreshPaymentIfTerminal()` from Stripe Elements
+`loaderror` (never proactively).
+
+**Manual (Medusa-style, 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": "fp_manual", "service_zone_id": "sz_…",
+    "shipping_option_type_id": "sotype_…", "shipping_profile_id": "sp_…",
+    "data": null,
+    "type": { "…": "shipping_option_types row (label/code/description)" },
+    "amount": 5,                 // flat price in the cart currency; null without cart_id
+    "price_type": "flat"         // calculated-rate carriers not wired yet
+  }],
+  "count": 1, "offset": 0, "limit": 1
+}
+```
+
+- **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:
+
+```jsonc
+{
+  "payment_providers": [
+    { "id": "pp_manual", "is_enabled": true, "created_at": "…" }
+    // pp_stripe / pp_cod appear when their integrations are enabled;
+    // pp_giftcard is INTERNAL tender and is never listed
+  ],
+  "count": 1, "offset": 0, "limit": 1
+}
+```
+
+- **Errors** — none beyond the standard envelope (empty list when nothing
+  is enabled).
+- **SDK** — `checkout.listPaymentProviders(client, {region_id, cart_id})`.
+- **Components** — payment picker.
+- **Settings** — admin integrations provision providers (enabling COD
+  provisions `pp_cod` + its fee config; enabling Stripe provisions
+  `pp_stripe` + credentials); checkout rules
+  (`target_type=payment_method`) + `checkout_method_order`.
+
+```bash
+curl -sf "$BASE/api/store/payment-providers?cart_id=$CART_ID" \
+  -H "x-client-id: $CLIENT_ID" | grep -q '"pp_manual"'
+curl -sf "$BASE/api/store/payment-providers?region_id=$REGION_ID&cart_id=$CART_ID" \
+  -H "x-client-id: $CLIENT_ID" | grep -q '"pp_manual"'
+```
+
+---
+
+## 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; plain row for `pp_cod`/`pp_manual`). For
+`pp_cod` the native fee only applies once the 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). `payment_provider` = `pp_stripe` | `pp_cod` |
+  `pp_manual`, never `pp_giftcard`:
+
+```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_provider": "pp_manual",
+  "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 pp_cod/pp_manual AND zero-remainder carts
+  "provider_id": "pp_manual"          // null when zero-remainder skipped the provider session
+}
+```
+
+- **Zero-remainder gift path** — when applied gift cards cover the whole
+  total, the provider session is skipped entirely (`client_secret` and
+  `provider_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_provider":"pp_manual"}')
+echo "$PREP_JSON" | grep -q '"provider_id":"pp_manual"'
+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?}` (`.strict()`; empty object fine). Passing
+  a DIFFERENT provider 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"}` |
+| provider matches, amount current | `{"synced":true,"rotated":false,"client_secret":…,"provider_id":…}` (no-op) |
+| provider matches, amount drifted | in-place update (Stripe `paymentIntents.update`; plain field for pp_cod/pp_manual) → `{"synced":true,"rotated":false,…}` — same secret |
+| provider mismatch OR update refused (terminal PI) | rotation: old session retired (+ PI voided best-effort), fresh session at the new remainder → `{"synced":true,"rotated":true,"client_secret":…,"provider_id":…}` |
+
+  Rotation retires the old session BEFORE recomputing so session-dependent
+  totals (the COD fee) settle for the NEW provider; a final resync pass
+  aligns collection + session + PI. `client_secret` is null for non-Stripe
+  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})`.
+- **Components** — checkout totals watcher (debounced), payment-method
+  switcher (pass the new `provider_id`).
+
+```bash
+# No-drift no-op on the prepared pp_manual 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 '"provider_id":"pp_manual"'
+```
+
+---
+
+## 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
+# pp_manual 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 `pp_cod`/`pp_manual`) → `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 provider (except internal
+    `pp_giftcard`) 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`; COD fee (**timing**: the
+  fee exists only while a live `pp_cod` session does — it appears on the
+  cart at prepare, 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 pp_manual 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"'
+```
+
+---
+
+## Manual path — collections + sessions (Medusa-style)
+
+### 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 provider session — idempotent per
+  provider. 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.
+- **Auth** — anon `x-client-id`.
+- **Request** — `{provider_id, data?, save_payment_method?}`. Keys the
+  server owns (`payment_intent_id`, `client_secret`, `status`,
+  `stripe_customer_id`, `setup_future_usage`) 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-op on non-card providers
+  (COD/manual subscriptions renew offline). 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`. The session
+  `amount` is `collection.amount − gift_card_total` — the remainder.
+- **Errors** — 404 `payment_collection_not_found`; 400 `invalid_provider`
+  (pp_giftcard) | `stripe_not_configured` | `customer_required` |
+  `validation_failed`.
+- **SDK** — `checkout.initiatePaymentSession(client, pcId, {provider_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 '{"provider_id":"pp_manual"}')
+echo "$SES_JSON" | grep -q '"provider_id":"pp_manual"'
+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 '{"provider_id":"pp_manual","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`.
+- **COD fee** — requires the admin COD integration
+  (`{config:{fee_amount, fee_label}}`); exercised by
+  `tests/store/checkout-cod-fee.test.ts` and
+  `tests/store/checkout-orchestration.test.ts` (fee-inclusive session on
+  prepare with `pp_cod`).
+
+## Cleanup / accretion note
+
+This page creates two carts and completes two `pp_manual` 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).