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

### Monetary Values

All amounts are **integers in minor currency units** (cents). `$19.99` = `1999`. Floating-point is prohibited.

### Messages

The `messages[]` array allows merchant-to-agent communication:
- Inform the agent about restrictions, policies, or required actions
- Messages have types (info, warning, error) that influence agent behavior

### Links

The `links[]` array provides actionable URLs with spec-defined link types:
- `terms_of_use` — Merchant terms of use page
- `privacy_policy` — Merchant privacy policy page
- `seller_shop_policies` — Merchant shop policies page

### Create Flow

1. Agent sends items + optional buyer info + optional address
2. Merchant validates items against inventory
3. Merchant computes line items, fulfillment options, totals
4. Returns session with `not_ready_for_payment` or `ready_for_payment`

### Update Flow

1. Agent sends modified items, address, fulfillment choice, or buyer info
2. Merchant revalidates and recomputes everything
3. Returns updated session with new status

### Complete Flow

1. Agent sends payment data (SPT from delegated payment)
2. Merchant processes payment via PSP
3. On success: returns session with `completed` status + order details
4. On 3DS required: returns `authentication_required` + authentication challenge
5. Agent must handle 3DS and retry complete with authentication result

### Error Handling

- All errors return flat objects: `type`, `code`, `message`, `param`
- Use `param` (JSONPath) to indicate which field caused the error
- Handle idempotency conflicts (422) and in-flight duplicates (409)

Fetch the OpenAPI spec for exact request/response schemas, field types, and all possible error codes before implementing.