Checkout API

2.1 Capability Identifier

The checkout capability namespace is dev.ucp.shopping.checkout. It is UCP’s most essential transaction capability, defining the complete flow from creating a shopping session to completing payment.

2.2 Checkout Session State Machine

A checkout session transitions through 6 well-defined states during its lifecycle:

State	Meaning	Can Transition To
`incomplete`	Session created; buyer or product information is incomplete	`requires_escalation`, `ready_for_complete`, `canceled`
`requires_escalation`	Human intervention required (age verification, high-risk review, inventory confirmation, etc.)	`incomplete`, `ready_for_complete`, `canceled`
`ready_for_complete`	All necessary information is ready; session can be submitted	`complete_in_progress`, `canceled`
`complete_in_progress`	Complete operation submitted; processing in progress	`completed`, `incomplete`
`completed`	Transaction successfully completed; order created	Terminal state
`canceled`	Transaction canceled	Terminal state

State Transition Diagram:

  incomplete ---------> requires_escalation
      |                        |
      +-------> ready_for_complete <---+
      |              |
      |        complete_in_progress
      |              |
      |          completed (terminal)
      |
      +-------> canceled (terminal)

Key design decisions: The requires_escalation state allows merchants to hand control to a human when the AI cannot process a scenario automatically (e.g., legal compliance confirmation for high-value goods). The fallback path from complete_in_progress to incomplete handles exceptions such as payment failures.

2.3 Five Operations

Create — Create Checkout Session

POST /ucp/checkout/sessions
Content-Type: application/json
Authorization: Bearer {access_token}
UCP-Agent: profile="https://agent.example/profiles/shopping.json"

{
  "line_items": [
    {
      "product_id": "prod_abc123",
      "variant_id": "var_001",
      "quantity": 2
    }
  ],
  "buyer": {
    "email": "buyer@example.com"
  }
}

Response:

{
  "checkout_session": {
    "id": "cs_20260411_abc123",
    "status": "incomplete",
    "created_at": "2026-04-11T10:00:00Z",
    "line_items": [
      {
        "id": "li_001",
        "product_id": "prod_abc123",
        "variant_id": "var_001",
        "name": "Classic Canvas Sneakers - White Size 9",
        "quantity": 2,
        "unit_price": {
          "amount": 7900,
          "currency_code": "USD"
        },
        "line_total": {
          "amount": 15800,
          "currency_code": "USD"
        }
      }
    ],
    "pricing": {
      "subtotal": { "amount": 15800, "currency_code": "USD" },
      "shipping": null,
      "tax": null,
      "total": { "amount": 15800, "currency_code": "USD" }
    }
  }
}

Get — Query Checkout Session

GET /ucp/checkout/sessions/{session_id}
Authorization: Bearer {access_token}

Returns the complete current state of the session, including all line items, pricing, buyer information, and shipping options.

Update — Update Checkout Session

PATCH /ucp/checkout/sessions/{session_id}
Content-Type: application/json
Authorization: Bearer {access_token}

{
  "buyer": {
    "name": "Jane Smith",
    "email": "jane.smith@example.com",
    "phone": "+1-555-012-3456",
    "shipping_address": {
      "line1": "123 Main Street",
      "city": "San Francisco",
      "state": "CA",
      "postal_code": "94102",
      "country_code": "US"
    }
  },
  "fulfillment": {
    "method": "standard_shipping"
  },
  "payment": {
    "handler": "com.stripe.payment",
    "token": "tok_xxxxxxxxxxxx"
  }
}

The Update operation can be called multiple times to incrementally provide information. Once all required information is present, the status automatically transitions to ready_for_complete.

Complete — Submit for Completion

POST /ucp/checkout/sessions/{session_id}/complete
Authorization: Bearer {access_token}

Can only be called when the status is ready_for_complete. After invocation, the status changes to complete_in_progress as the merchant asynchronously processes payment and order creation. On success, the status changes to completed; on failure, it falls back to incomplete. Response:

{
  "checkout_session": {
    "id": "cs_20260411_abc123",
    "status": "complete_in_progress",
    "order_id": null
  }
}

Final response after completion (retrieved via Get or webhook callback):

{
  "checkout_session": {
    "id": "cs_20260411_abc123",
    "status": "completed",
    "order_id": "ord_20260411_xyz789",
    "completed_at": "2026-04-11T10:05:00Z"
  }
}

Cancel — Cancel Session

POST /ucp/checkout/sessions/{session_id}/cancel
Authorization: Bearer {access_token}

{
  "reason": "buyer_changed_mind"
}

Cancellation is allowed from any state except the two terminal states (completed and canceled).

2.4 ISO 4217 Amount Handling

UCP strictly requires all monetary amounts to be expressed in ISO 4217 minor units, avoiding floating-point precision issues:

Currency	currency_code	Minor Unit	Representation of $79.00
US Dollar	`USD`	Cent (1/100)	`7900`
Euro	`EUR`	Cent (1/100)	`7900`
Japanese Yen	`JPY`	Yen (no decimals)	`79`
Kuwaiti Dinar	`KWD`	Fils (1/1000)	`79000`

{
  "amount": 7900,
  "currency_code": "USD"
}

Developer note: Different currencies have different minor-unit exponents. USD and EUR use 2 digits (divide by 100), JPY uses 0 digits (use directly), and KWD uses 3 digits (divide by 1000). Always consult the ISO 4217 exponent definition during implementation.

2.5 Embedded Checkout UI

When an AI agent cannot complete checkout in pure API mode (e.g., complex payment verification, 3D Secure authentication), UCP supports an embedded UI mode:

Mode	Description	Use Case
API mode	AI agent completes all operations directly via REST/MCP	Simple checkout, linked identity
Embedded UI	Merchant provides a checkout page URL for the AI agent to present to the user	Complex payment verification, first-time authorization

The embedded UI is triggered via the requires_escalation state. The merchant returns a UI URL in the response:

{
  "checkout_session": {
    "id": "cs_20260411_abc123",
    "status": "requires_escalation",
    "escalation": {
      "type": "embedded_ui",
      "url": "https://store.example.com/checkout/embed/cs_20260411_abc123",
      "reason": "payment_verification_required"
    }
  }
}

The embedded UI supports bidirectional communication. After the user completes the required action on the merchant’s page, the session status updates automatically.

2.6 Price Transparency Requirements

UCP mandates complete price transparency. The pricing object in a checkout session must include:

Field	Description	Required
`subtotal`	Item subtotal	Yes
`shipping`	Shipping cost	Yes (may be 0)
`tax`	Tax amount	Yes (may be 0)
`discount`	Discount amount	Conditional (required when a discount is applied)
`total`	Final total price	Yes

Before calling the Complete operation, the AI agent must present the full price breakdown to the consumer and obtain confirmation.

Next chapter: Identity Linking — OAuth 2.0 Authorization Code flow, token revocation, and scope management

UCP protocol architecture and core concepts UCP identity linking with OAuth 2.0

Start

Learning Paths

Getting Started with AI Commerce

OTR Open Trust Registry

UCP Universal Commerce Protocol

ACP Agentic Commerce Protocol

MCP Model Context Protocol

SEO for the AI Era

ORBEXA Integrated Solution

Templates & Prompts

Glossary

UCP checkout API and state machine

Checkout API

2.1 Capability Identifier

2.2 Checkout Session State Machine

2.3 Five Operations

Create — Create Checkout Session

Get — Query Checkout Session

Update — Update Checkout Session

Complete — Submit for Completion

Cancel — Cancel Session

2.4 ISO 4217 Amount Handling

2.5 Embedded Checkout UI

2.6 Price Transparency Requirements

​Checkout API

​2.1 Capability Identifier

​2.2 Checkout Session State Machine

​2.3 Five Operations

​Create — Create Checkout Session

​Get — Query Checkout Session

​Update — Update Checkout Session

​Complete — Submit for Completion

​Cancel — Cancel Session

​2.4 ISO 4217 Amount Handling

​2.5 Embedded Checkout UI

​2.6 Price Transparency Requirements

Checkout API

2.1 Capability Identifier

2.2 Checkout Session State Machine

2.3 Five Operations

Create — Create Checkout Session

Get — Query Checkout Session

Update — Update Checkout Session

Complete — Submit for Completion

Cancel — Cancel Session

2.4 ISO 4217 Amount Handling

2.5 Embedded Checkout UI

2.6 Price Transparency Requirements