Checkout Capability Specification

Basic Information

• Capability Name: dev.ucp.shopping.checkout
• Version: 2026-01-11
• Official Specification: checkout.md

Overview

The Checkout capability allows platforms to initiate and manage checkout sessions.

Key Features

• Business maintains Merchant of Record status
• No requirement for business to be PCI DSS compliant
• Supports continue_url for checkout handoff
• Optional AP2 Mandates extension support for autonomous checkout

Status Lifecycle

┌────────────┐    ┌─────────────────────┐
│ incomplete │◀──▶│ requires_escalation │
└─────┬──────┘    └──────────┬──────────┘
      │                      │
      │ Info collection      │ continue_url
      │ complete             │
      ▼                      │
┌──────────────────┐         │
│ready_for_complete│         │
└────────┬─────────┘         │
         │                   │
         │ Complete Checkout │
         ▼                   │
┌────────────────────┐       │
│complete_in_progress│       │
└─────────┬──────────┘       │
          │                  │
          └────────┬─────────┘
                   ▼
            ┌─────────────┐
            │  completed  │
            └─────────────┘

            ┌─────────────┐
            │  canceled   │  (can occur from any state)
            └─────────────┘

Status Value Descriptions

Error Handling

Severity Types

Error Handling Algorithm

1. Filter messages with type = "error"
2. Group by severity:
   - recoverable
   - requires_buyer_input
   - requires_buyer_review
3. If recoverable is not empty:
   - Attempt to fix each error
   - Call Update Checkout
   - Re-evaluate response
4. If requires_buyer_input is not empty:
   - Handoff context = "Session incomplete, needs additional input"
5. If requires_buyer_review is not empty:
   - Handoff context = "Ready, awaiting user final review"

Error Example

{
  "status": "requires_escalation",
  "messages": [
    {
      "type": "error",
      "code": "invalid_phone",
      "severity": "recoverable",
      "content": "Phone number format is invalid"
    },
    {
      "type": "error",
      "code": "schedule_delivery",
      "severity": "requires_buyer_input",
      "content": "Please select a delivery time"
    },
    {
      "type": "error",
      "code": "high_value_order",
      "severity": "requires_buyer_review",
      "content": "Orders over $500 require additional verification"
    }
  ]
}

Continue URL

Availability Requirements

Format Requirements

• MUST be an absolute HTTPS URL
• SHOULD maintain checkout state for seamless handoff

Implementation Methods

Server-side state (recommended):

https://business.example.com/checkout-sessions/{checkout_id}

Checkout permalink: Stateless URL, directly encoding checkout state

Operation List

Implementation Guidelines

Platform Requirements

• MAY use agent assistance for checkout (e.g., adding items, selecting addresses)
• MUST use continue_url when status = requires_escalation
• SHOULD prefer business-provided continue_url over platform-constructed permalinks
• MAY return user from trusted UI to agent at any time

Business Requirements

• MUST send confirmation email after checkout completion
• SHOULD provide accurate error messages
• MUST handle checkout session logic deterministically
• MUST provide continue_url when returning status = requires_escalation
• MUST include at least one message with severity: escalation when returning status = requires_escalation
• SHOULD provide continue_url in all non-terminal state responses
• Checkout sessions are considered immutable after reaching completed status

Transport Bindings

The Checkout capability supports the following transport protocols:

• REST Binding: Using OpenAPI 3.x
• MCP Binding: Using OpenRPC
• A2A Binding: Using Agent Card
• Embedded Binding: Using OpenRPC

Related Entities

Buyer

A structure containing buyer contact information.

Payment

• handlers: List of payment handlers supported by the business
• instruments: Payment credentials collected by the platform

Fulfillment

Implemented as an extension, modeled as an optional module.

Line Items

Item entries in the shopping cart.

Totals

Including subtotal, tax, discount, shipping, etc.

Dependencies

• Payment Architecture: Payment architecture
• Optional Dependency: AP2 Mandates Extension (for autonomous checkout)

Next Steps

• Checkout REST Binding
• AP2 Mandates Extension
• Payment Handler Guide