Design an agent-friendly checkout flow on a merchant storefront

Steps

1. Expose a headless checkout API that accepts structured input (cart items, shipping address, shipping method selection, promo code) in a single or small number of API calls rather than requiring multi-step web form navigation.
2. Return machine-readable error responses: use structured error objects with a machine-readable code (e.g., INVALID_ADDRESS, PROMO_EXPIRED, ITEM_OUT_OF_STOCK) alongside a human-readable message so agents can handle errors programmatically.
3. Support idempotency keys on order creation endpoints; document the key header name and behavior clearly so agents can safely retry on network failure without creating duplicate orders.
4. Provide a checkout session URL that a human can open in a browser to complete payment; this URL should restore the cart state and pre-fill shipping details already collected by the agent, minimizing human steps.
5. Emit order confirmation data as a structured response (not just a confirmation email) including order ID, itemized summary, total, estimated delivery date, and a tracking info endpoint URL.
6. Publish your checkout API's OpenAPI spec and/or MCP tool schema so agents can discover and use it without relying on documentation written for human developers.