mercadodevida/work/artifacts/F-022/documenter.md

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