acp-checkout-rest

ACP Checkout — REST Binding

Before writing code

Fetch live docs:

1. Fetch https://developers.openai.com/commerce/specs/checkout/ for the canonical checkout specification
2. Web-search site:github.com agentic-commerce-protocol spec openapi checkout for the latest OpenAPI YAML
3. Fetch https://developers.openai.com/commerce/guides/key-concepts/ for data model details
4. Web-search site:docs.stripe.com agentic-commerce protocol specification for Stripe's merchant-side reference

Conceptual Architecture

Five Checkout Operations

Operation	Method	Path	Success
Create	POST	/checkout_sessions	201
Update	POST	/checkout_sessions/{id}	200
Retrieve	GET	/checkout_sessions/{id}	200
Complete	POST	/checkout_sessions/{id}/complete	200
Cancel	POST	/checkout_sessions/{id}/cancel	200

Session State Machine

not_ready_for_payment → ready_for_payment → completed
         |                      |                |
         +──────────────────────+→ canceled ←────+
                                |
                           in_progress
                                |
                      authentication_required

The five core status enum values are: not_ready_for_payment, ready_for_payment, completed, canceled, in_progress. Note that authentication_required is a transitional/conditional state (returned during 3DS flows), not one of the five core status values.

The merchant controls status transitions. The agent reads the status and reacts.

Required Headers (Every Request)

• Authorization: Bearer <token> — REQUIRED
• API-Version: YYYY-MM-DD — REQUIRED
• Idempotency-Key: <UUID> — REQUIRED on all POST
• Content-Type: application/json

Core Data Objects

• CheckoutSession — The central primitive: ID, status, currency, line items, fulfillment options, totals, messages, links, payment provider
• Item — id + quantity (sent by agent in create/update)
• LineItem — Merchant's expanded view: base amount, discount, subtotal, tax, total, name, description, images
• Total — Typed breakdown: items_base_amount, items_discount, subtotal, discount, fulfillment, tax, fee, total
• FulfillmentOption — Shipping/digital/pickup/local delivery with pricing and windows
• Address — Buyer's fulfillment address
• Buyer — First name, last name, email, optional phone