# Shopping and Checkout API

All endpoints use `/api/v1` and require authentication unless stated otherwise. Ownership is derived exclusively from the authenticated identity; request bodies never accept `userId`.

## Cart

- `GET /cart`
- `POST /cart/items` with `variantId`, `quantity`
- `PATCH /cart/items/:itemId` with `quantity`; zero removes the item
- `DELETE /cart/items/:itemId`
- `DELETE /cart`
- `PUT /cart/coupon` and `DELETE /cart/coupon`

Only one ACTIVE cart exists per user. Adding items does not reserve inventory. Responses revalidate catalogue state, availability, MOQ, business pricing, promotions, coupons, and integer-scaled totals. Unavailable items remain visible with an explanatory status.

## Wishlist

- `GET /wishlist`
- `POST /wishlist` with `productId`
- `DELETE /wishlist/:productId`

Wishlist entries are owner-scoped, contain no quantity, and never reserve stock.

## Shipping

- `POST /shipping/quote` with an owned `addressId`; subtotal is read from the authoritative cart.
- Admin CRUD: `/admin/shipping/zones`, `/admin/shipping/methods`, `/admin/shipping/rates`.

Zones match country, then optional province/district. Rates support schedules, subtotal bands, currency, and configurable free-shipping thresholds. Unsupported destinations return an explicit error. Duty mode is descriptive; tax is zero until authoritative configuration exists.

## Checkout

- `POST /checkout` requires `Idempotency-Key` and owned shipping/billing address IDs plus a shipping method ID.
- `GET /checkout/active`
- `GET /checkout/:id`
- `POST /checkout/:id/cancel`

The server recalculates all prices, shipping, discounts, and availability. Client price/total fields are rejected. Checkout snapshots commerce-critical item/address/shipping data and atomically reserves every item using sorted lock order. The cart becomes `CHECKOUT_LOCKED`. Cancellation or bounded expiry reconciliation releases reservations and restores the cart. Same user/key/payload returns the existing checkout; a changed payload conflicts.

Business checkout uses the same cart/session and revalidates active approved status, customer/tier pricing, MOQ, and volume tiers. Business credit is not consumed.

No guest cart, Order, Payment, coupon redemption, tax provider, customs calculator, shipment, or delivery workflow exists in Phase 6.