Checkout Capability - REST Binding

Checkout Capability - REST Binding

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, which is discovered through the UCP profile at /.well-known/ucp. The endpoint for the checkout capability is defined in the rest.endpoint field of the business profile.

Content Types

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

All request and response bodies MUST be valid JSON as specified in RFC 8259.

Transport Security

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

Operations

Operation	Method	Endpoint	Description
Create Checkout	POST	/checkout-sessions	Create a checkout session.
Get Checkout	GET	/checkout-sessions/{id}	Get a checkout session.
Update Checkout	PUT	/checkout-sessions/{id}	Update a checkout session.
Complete Checkout	POST	/checkout-sessions/{id}/complete	Place the order.
Cancel Checkout	POST	/checkout-sessions/{id}/cancel	Cancel a checkout session.

Examples

Create Checkout

=== “Request”

```json
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
      },
      "id": "li_1",
      "quantity": 2
    }
  ]
}
```

=== “Response”

```json
HTTP/1.1 201 Created
Content-Type: application/json

{
  "ucp": {
    "version": "2026-01-11",
    "capabilities": {
      "dev.ucp.shopping.checkout": [
        {"version": "2026-01-11"}
      ]
    }
  },
  "id": "chk_1234567890",
  "status": "incomplete",
  "messages": [
    {
      "type": "error",
      "code": "missing",
      "path": "$.buyer.email",
      "content": "Buyer email is required",
      "severity": "recoverable"
    }
  ],
  "currency": "USD",
  "line_items": [...],
  "totals": [...],
  "payment": {...}
}
```

=== “Error Response”

All items out of stock — no checkout resource is created:

```json
HTTP/1.1 200 OK
Content-Type: application/json

{
  "ucp": { "version": "2026-01-11", "status": "error" },
  "messages": [
    {
      "type": "error",
      "code": "out_of_stock",
      "content": "All requested items are currently out of stock",
      "severity": "unrecoverable"
    }
  ],
  "continue_url": "https://merchant.com/"
}
```

HTTP Headers

Specific Header Requirements

• UCP-Agent: All requests MUST include the UCP-Agent header containing the platform profile URI using Dictionary Structured Field syntax (RFC 8941). Format: profile="https://platform.example/profile".
• Idempotency-Key: Operations that modify state SHOULD support idempotency. When provided, the server MUST:
  1. Store the key with the operation result for at least 24 hours.
  2. Return the cached result for duplicate keys.
  3. Return 409 Conflict if the key is reused with different parameters.

Protocol Mechanics

Status Codes

UCP uses standard HTTP status codes to indicate the success or failure of an API request.

Status Code	Description
200 OK	The request was successful.
201 Created	The resource was successfully created.
400 Bad Request	The request was invalid or cannot be served.
401 Unauthorized	Authentication is required and has failed or has not been provided.
403 Forbidden	The request is authenticated but the user does not have the necessary permissions.
409 Conflict	The request could not be completed due to a conflict (e.g., idempotent key reuse).
422 Unprocessable Entity	The profile content is malformed (discovery failure).
424 Failed Dependency	The profile URL is valid but fetch failed (discovery failure).
429 Too Many Requests	Rate limit exceeded.
503 Service Unavailable	Temporary unavailability.
500 Internal Server Error	An unexpected condition was encountered on the server.

Message Signing

Platforms MAY choose among authentication mechanisms (API keys, OAuth, mTLS, HTTP Message Signatures). When using HTTP Message Signatures, checkout operations follow the Message Signatures specification.

Request Signing

When HTTP Message Signatures are used, requests MUST include valid Signature-Input and Signature headers (and Content-Digest when a body is present) per RFC 9421:

Header	Required	Description
Signature-Input	Yes	Describes signed components
Signature	Yes	Contains the signature value
Content-Digest	Cond.*	SHA-256 hash of request body

* Required for requests with a body (POST, PUT)

Security Considerations

Authentication

Authentication is optional and depends on business requirements. When authentication is required, the REST transport MAY use:

1. Open API: No authentication required for public operations.
2. API Keys: Via X-API-Key header.
3. OAuth 2.0: Via Authorization: Bearer {token} header, following RFC 6749.
4. Mutual TLS: For high-security environments.
5. HTTP Message Signatures: Per RFC 9421 (see Message Signing above).