Checkout REST Binding

Overview

This document specifies the REST binding for the Checkout Capability.

Protocol Fundamentals

Base URL

All UCP REST endpoints are relative to the business’s base URL, discovered through the UCP profile at /.well-known/ucp.

Content Types

  • Request: application/json
  • Response: application/json

Transport Security

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

Operations

OperationMethodEndpointDescription
Create CheckoutPOST/checkout-sessionsCreate a checkout session
Get CheckoutGET/checkout-sessions/{id}Get a checkout session
Update CheckoutPUT/checkout-sessions/{id}Update a checkout session
Complete CheckoutPOST/checkout-sessions/{id}/completePlace the order
Cancel CheckoutPOST/checkout-sessions/{id}/cancelCancel a checkout session

HTTP Headers

UCP-Agent Header

All requests MUST include the UCP-Agent header containing the platform profile URI:

UCP-Agent: profile="https://platform.example/profile"

Idempotency-Key

Operations that modify state SHOULD support idempotency via the Idempotency-Key header.

Example: Create Checkout

Request:

POST /checkout-sessions HTTP/1.1
UCP-Agent: profile="https://platform.example/profile"
Content-Type: application/json

{
  "line_items": [
    {
      "item": {
        "id": "item_123",
        "title": "Red T-Shirt",
        "price": 2500
      },
      "quantity": 2
    }
  ],
  "currency": "USD"
}

Response:

{
  "ucp": {
    "version": "2026-01-11",
    "capabilities": [
      {
        "name": "dev.ucp.shopping.checkout",
        "version": "2026-01-11"
      }
    ]
  },
  "id": "chk_1234567890",
  "status": "incomplete",
  "currency": "USD",
  "line_items": [...],
  "totals": [...],
  "links": [...],
  "payment": {
    "handlers": [...]
  }
}

Example: Complete Checkout

Request:

POST /checkout-sessions/{id}/complete HTTP/1.1
UCP-Agent: profile="https://platform.example/profile"
Content-Type: application/json

{
  "payment_data": {
    "id": "pi_gpay_5678",
    "handler_id": "com.google.pay",
    "type": "card",
    "credential": {
      "type": "PAYMENT_GATEWAY",
      "token": "examplePaymentMethodToken"
    }
  }
}

Response:

{
  "ucp": {
    "version": "2026-01-11",
    "capabilities": [...]
  },
  "id": "chk_123456789",
  "status": "completed",
  "currency": "USD",
  "order": {
    "id": "ord_99887766",
    "permalink_url": "https://merchant.com/orders/ord_99887766"
  }
}

Status Codes

Status CodeDescription
200 OKThe request was successful
201 CreatedThe resource was successfully created
400 Bad RequestThe request was invalid
404 Not FoundThe requested resource could not be found
409 ConflictIdempotent key reused with different parameters
500 Internal Server ErrorAn unexpected error occurred

Error Responses

Error responses follow the standard UCP error structure:

{
  "status": "requires_escalation",
  "messages": [
    {
      "type": "error",
      "code": "invalid_cart_items",
      "content": "One or more cart items are invalid",
      "severity": "requires_buyer_input"
    }
  ]
}

Security

Authentication

When authentication is required, REST transport MAY use:

  1. Open API: No authentication for public operations
  2. API Keys: Via X-API-Key header
  3. OAuth 2.0: Via Authorization: Bearer {token} header
  4. Mutual TLS: For high-security environments

See Also