UCP Checkout — REST Binding#

Before writing code#

Fetch live spec: Web-search site:ucp.dev specification checkout-rest and fetch the page for the exact current endpoint shapes, required headers, request/response schemas, and status codes.

Also fetch https://ucp.dev/specification/reference/ for all data type definitions (Buyer, LineItem, Total, Message, etc.).

Conceptual Architecture#

Five REST Operations#

OperationHTTPPathIdempotent?Create CheckoutPOST/checkout-sessionsYes (via Idempotency-Key)Get CheckoutGET/checkout-sessions/{id}NaturallyUpdate CheckoutPUT/checkout-sessions/{id}Yes (full replace)Complete CheckoutPOST/checkout-sessions/{id}/completeYes (via Idempotency-Key)Cancel CheckoutPOST/checkout-sessions/{id}/cancelYes (via Idempotency-Key)

Required Headers (every request)#

• UCP-Agent: Platform's profile URI in RFC 8941 structured field format — profile="https://..."
• Idempotency-Key: UUID for mutating operations; Business caches 24+ hours
• Request-Id: UUID for distributed tracing
• Request-Signature: Cryptographic signature for request integrity verification
• Content-Type: application/json

Status State Machine#

text

incomplete → requires_escalation → ready_for_complete → complete_in_progress → completed
     |               |                    |                      |
     +---------------+--------------------+----------------------+--------→ canceled

The canceled state is reachable from any non-terminal state (incomplete, requires_escalation, ready_for_complete, complete_in_progress).

The agent's job is to drive the session from incomplete to ready_for_complete by resolving messages, then call complete.

Negotiation in Every Response#

Every response includes a ucp object with the negotiated version and capabilities. The Business computes the intersection of its own capabilities with the Platform's profile, prunes orphaned extensions, and returns only what both sides support.

Error Handling Pattern#

Responses include a messages array. Each message has:

• type: error / warning / info
• code: Machine-readable error code
• content: Human-readable description
• severity: recoverable / requires_buyer_input / requires_buyer_review (these are the 3 formal enum values; note: escalation appears in some spec sections but is NOT part of the formal severity enum — this is a spec inconsistency)
• path: JSONPath pointing to the problematic field

Agent behavior by severity:

• recoverable → Agent fixes automatically (e.g., update with missing address)
• requires_buyer_input → Ask the human user
• requires_buyer_review → Show totals/terms for human confirmation
• escalation → Redirect to continue_url

Implementation Checklist#

Business (merchant server):

1. Parse UCP-Agent header and fetch platform profile for negotiation
2. Validate Idempotency-Key — return cached response if duplicate
3. Create checkout session with line items, compute totals
4. Return negotiated ucp object + full session state + messages
5. Handle Update by recalculating totals, re-validating, updating messages
6. Handle Complete by processing payment credential, creating order
7. Handle Cancel by cleaning up session
8. Return proper HTTP status codes (201 Created, 200 OK, 400/409/429, etc.)

Platform (agent client):

1. Discover Business profile at /.well-known/ucp
2. Send UCP-Agent header with own profile URI
3. Create checkout, inspect status and messages
4. Loop: resolve messages → update checkout → re-check status
5. When ready_for_complete: acquire payment credential, call complete
6. Handle requires_escalation by surfacing continue_url to user

Monetary Values#

All amounts are integers in minor currency units (e.g., $29.99 = 2999). Never use floating point.

TLS Requirement#

All UCP REST endpoints MUST be served over HTTPS with minimum TLS 1.3.