# 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).