# Documenter — F-022 Checkout orchestrator with idempotency

## Summary
Checkout orchestrates cart -> pricing -> inventory -> promotions -> shipping -> orders -> reservation -> payment. It owns no business data and exposes a single endpoint with idempotency_key.

## Public API notes

| Route | Access | Result |
|---|---|---|
| POST /checkout | authenticated | Returns order summary, reservedVariantIds and payment intent reference |

## Errors
- `CHECKOUT_CART_EMPTY` — 409
- `CHECKOUT_STOCK_UNAVAILABLE` — 409
- `CHECKOUT_PRICE_MISSING` — 409
- `CHECKOUT_PROMO_INVALID` — 422
- `CHECKOUT_SHIPPING_ZONE_NOT_FOUND` — 422
- `CHECKOUT_RESERVATION_FAILED` — 409
- `CHECKOUT_IDEMPOTENCY_CONFLICT` — 409

## Idempotency
- `idempotencyKey` is required.
- Reusing the same `(userId, idempotencyKey)` returns the existing order without re-reserving stock or creating a new payment intent.

## Metrics
- `checkout_success_total` increments on successful checkout.
- `checkout_failure_total` increments on any 4xx/5xx checkout error.

## Evidence
- `work/artifacts/F-022/architect.md`
- `work/artifacts/F-022/implementer.md`
- `work/artifacts/F-022/reviewer.json`
- `work/artifacts/F-022/security.json`
- `work/artifacts/F-022/qa.json`