> ## Documentation Index
> Fetch the complete documentation index at: https://learn.orbexa.io/llms.txt
> Use this file to discover all available pages before exploring further.

# UCP checkout API and state machine

> Complete technical documentation for UCP checkout — 6 states, 5 operations, ISO 4217 amounts, embedded UI, and state machine details

# 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                                          |

```text theme={null}
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

```http theme={null}
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:

```json theme={null}
{
  "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

```http theme={null}
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

```http theme={null}
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

```http theme={null}
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:

```json theme={null}
{
  "checkout_session": {
    "id": "cs_20260411_abc123",
    "status": "complete_in_progress",
    "order_id": null
  }
}
```

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

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

### Cancel — Cancel Session

```http theme={null}
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`                   |

```json theme={null}
{
  "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:

```json theme={null}
{
  "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](/en/book-3/ch3-identity) — OAuth 2.0 Authorization Code flow, token revocation, and scope management