Skip to main content

​
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:
StateMeaningCan Transition To
incompleteSession created; buyer or product information is incompleterequires_escalation, ready_for_complete, canceled
requires_escalationHuman intervention required (age verification, high-risk review, inventory confirmation, etc.)incomplete, ready_for_complete, canceled
ready_for_completeAll necessary information is ready; session can be submittedcomplete_in_progress, canceled
complete_in_progressComplete operation submitted; processing in progresscompleted, incomplete
completedTransaction successfully completed; order createdTerminal state
canceledTransaction canceledTerminal 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:
Currencycurrency_codeMinor UnitRepresentation of $79.00
US DollarUSDCent (1/100)7900
EuroEURCent (1/100)7900
Japanese YenJPYYen (no decimals)79
Kuwaiti DinarKWDFils (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:
ModeDescriptionUse Case
API modeAI agent completes all operations directly via REST/MCPSimple checkout, linked identity
Embedded UIMerchant provides a checkout page URL for the AI agent to present to the userComplex 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:
FieldDescriptionRequired
subtotalItem subtotalYes
shippingShipping costYes (may be 0)
taxTax amountYes (may be 0)
discountDiscount amountConditional (required when a discount is applied)
totalFinal total priceYes
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