Universal Commerce Protocol

https://ucp.dev
Admin
The Universal Commerce Protocol (UCP) is an open-source standard defining building blocks and a...
Tokens:604,797
Snippets:3,433
Trust Score:7.4
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Start Notification Example (Cart)

Source: https://ucp.dev/2026-08-25/specification/embedded-protocol

Example of a start notification for the cart capability (ep.cart.start). Use when the embedded context notifies the host that the UI is ready and includes the full current state of the cart. The host must not respond.

```json
{
    "jsonrpc": "2.0",
    "method": "ep.cart.start",
    "params": {
        "cart": {
            "id": "cart_123",
            "currency": "USD",
            "totals": [ ... ],
            "line_items": [ ... ],
            "buyer": { ... }
        }
    }
}
```

--------------------------------

### Get Product Example - Request and Response

Source: https://ucp.dev/2026-08-25/specification/shopping/catalog/mcp

Request and response pair for the get_product tool call. The request specifies the product ID, selected options, preferences, and context. The response returns the product details including price range, media, options, variants, and rating.

```json
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "get_product",
    "arguments": {
      "meta": {
        "ucp-agent": {
          "profile": "https://platform.example/profiles/v2026-01/shopping-agent.json"
        }
      },
      "catalog": {
        "id": "prod_abc123",
        "selected": [
          { "name": "Color", "label": "Blue" }
        ],
        "preferences": ["Color", "Size"],
        "context": {
          "address_country": "US"
        }
      }
    }
  }
}
```

```json
{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "structuredContent": {
      "ucp": {
        "version": "2026-08-25",
        "capabilities": {
          "dev.ucp.shopping.catalog.lookup": [
            {"version": "2026-08-25"}
          ]
        }
      },
      "product": {
        "id": "prod_abc123",
        "handle": "runner-pro",
        "title": "Runner Pro",
        "description": {
          "plain": "Lightweight running shoes with responsive cushioning."
        },
        "url": "https://business.example.com/products/runner-pro",
        "price_range": {
          "min": { "amount": 12000, "currency": "USD" },
          "max": { "amount": 15000, "currency": "USD" }
        },
        "media": [
          {
            "type": "image",
            "url": "https://cdn.example.com/products/runner-pro-blue.jpg",
            "alt_text": "Runner Pro in Blue"
          }
        ],
        "options": [
          {
            "name": "Color",
            "values": [
              {"label": "Blue", "available": true, "exists": true},
              {"label": "Red", "available": true, "exists": true},
              {"label": "Green", "available": false, "exists": true}
            ]
          },
          {
            "name": "Size",
            "values": [
              {"label": "8", "available": true, "exists": true},
              {"label": "9", "available": true, "exists": true},
              {"label": "10", "available": true, "exists": true},
              {"label": "11", "available": false, "exists": false},
              {"label": "12", "available": true, "exists": true}
            ]
          }
        ],
        "selected": [
          { "name": "Color", "label": "Blue" }
        ],
        "variants": [
          {
            "id": "prod_abc123_blu_10",
            "sku": "BRP-BLU-10",
            "title": "Blue, Size 10",
            "description": { "plain": "Blue, Size 10" },
            "price": { "amount": 12000, "currency": "USD" },
            "availability": { "available": true },
            "options": [
              { "name": "Color", "label": "Blue" },
              { "name": "Size", "label": "10" }
            ]
          },
          {
            "id": "prod_abc123_blu_12",
            "sku": "BRP-BLU-12",
            "title": "Blue, Size 12",
            "description": { "plain": "Blue, Size 12" },
            "price": { "amount": 15000, "currency": "USD" },
            "availability": { "available": true },
            "options": [
              { "name": "Color", "label": "Blue" },
              { "name": "Size", "label": "12" }
            ]
          }
        ],
        "rating": {
          "value": 4.5,
          "scale_max": 5,
          "count": 128
        }
      }
    }
  }
}
```

--------------------------------

### Signed GET request example (no body, no idempotency)

Source: https://ucp.dev/2026-08-25/specification/signatures

GET request example with no body and no idempotency key. Only the required components (@method, @authority, @path) are signed.

```http
GET /checkout-sessions/chk_123 HTTP/1.1
Host: merchant.example.com
Signature-Input: sig1=("@method" "@authority" "@path");keyid="platform-2026"
Signature: sig1=:6G4i8TS6oUkGrx8KnCFUpsSPwd74...:
```

--------------------------------

### Non-UCP query parameters example

Source: https://ucp.dev/latest/specification/permalink

Shows example non-UCP query parameters that are not inserted into initialized shopping data.

```text
utm_source=social&ref=creator_42&gclid=...
```

--------------------------------

### ep.cart.start notification example

Source: https://ucp.dev/latest/specification/shopping/cart/embedded

Example notification message for ep.cart.start, sent after a successful ep.cart.ready handshake. The payload includes the full cart object.

```json
{
    "jsonrpc": "2.0",
    "method": "ep.cart.start",
    "params": {
        "cart": {
            "id": "cart_123",
            "currency": "USD",
            "totals": [ ... ],
            "line_items": [ ... ],
            "buyer": { ... }
            // ...other cart fields...
        }
    }
}

```

--------------------------------

### available_instruments resolution example: platform, business, and response

Source: https://ucp.dev/latest/specification/payment/guide

Three inline JSON examples showing the available_instruments values from the platform profile, business profile, and the resolved response. The response excludes Discover because the business's PSP is not configured for it, even though the platform supports it.

```json
[{type: "card", constraints: {properties: {brand: {enum: ["visa", "mastercard", "amex", "discover"]}}}}]
```

```json
[{type: "card", constraints: {properties: {brand: {enum: ["visa", "mastercard", "amex"]}}}}]
```

```json
[{type: "card", constraints: {properties: {brand: {enum: ["visa", "mastercard", "amex"]}}}}]
```

--------------------------------

### GET /checkout-sessions/{id}

Source: https://ucp.dev/2026-08-25/specification/signatures

Example of a signed GET request to retrieve a checkout session, with no body or idempotency key.

```APIDOC
## GET /checkout-sessions/{id}

### Description
Example of a signed GET request to retrieve a checkout session, with no body or idempotency key.

### Method
GET

### Endpoint
/checkout-sessions/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The checkout session identifier

#### Headers
- **Signature-Input** (string) - Required - Signature input header
- **Signature** (string) - Required - Signature header

### Request Example
```
GET /checkout-sessions/chk_123 HTTP/1.1
Host: merchant.example.com
Signature-Input: sig1=("@method" "@authority" "@path");keyid="platform-2026"
Signature: sig1=:6G4i8TS6oUkGrx8KnCFUpsSPwd74...:
```

### Response
#### Success Response (200)
No response body documented.

#### Response Example
No response example provided.
```

--------------------------------

### Step 2: Example SDK Usage or API Call

Source: https://ucp.dev/2026-08-25/specification/payment/template

Placeholder for the code example in Step 2 of the payment protocol. The actual SDK usage or API call is not provided in the source.

```javascript
// Example SDK usage or API call
```

--------------------------------

### First-time setup: install Python deps, validator backend, and pre-commit hooks

Source: https://ucp.dev/documentation/schema-authoring

Run these commands once to set up the local development environment. Installs Python dependencies with uv, the ucp-schema validator backend with cargo, and installs both pre-commit and pre-push hooks. The --hook-type pre-push flag is required to opt into the full enforcement story.

```shell
uv sync                                   # Python deps
cargo install ucp-schema                  # validator backend
uv tool install pre-commit                # if not already installed
pre-commit install --hook-type pre-commit --hook-type pre-push

```

--------------------------------

### Fulfillment methods example (shipping and pickup)

Source: https://ucp.dev/2026-08-25/specification/shopping/extensions/fulfillment

Example of a product variant with two fulfillment methods: shipping and pickup. The shipping method includes options (Standard, Express) and a description previewing the delivery range; the pickup method references a resolved location by id and omits options. Each method has its own availability and a directly renderable description.

```json
{
  "ucp": { "version": "2026-08-25" },
  "products": [
    {
      "id": "prod_kettle",
      "title": "Electric Kettle",
      "description": { "plain": "1.7L electric kettle." },
      "price_range": {
        "min": { "amount": 4999, "currency": "USD" },
        "max": { "amount": 4999, "currency": "USD" }
      },
      "variants": [
        {
          "id": "var_ss",
          "title": "Stainless Steel",
          "description": { "plain": "Stainless steel finish." },
          "price": { "amount": 4999, "currency": "USD" },
          "availability": { "available": true, "status": "in_stock" },
          "fulfillment": {
            "methods": [
              {
                "type": "shipping",
                "description": { "plain": "Ships to your address in 1–4 business days" },
                "availability": { "available": true, "status": "in_stock" },
                "options": [
                  {
                    "id": "std",
                    "title": "Standard",
                    "description": { "plain": "Arrives in 4 business days" }
                  },
                  {
                    "id": "exp",
                    "title": "Express",
                    "description": { "plain": "Next business day" }
                  }
                ]
              },
              {
                "type": "pickup",
                "description": { "plain": "Pickup today at Downtown Store" },
                "location": "loc_downtown",
                "availability": { "available": true, "status": "in_stock" }
              }
            ]
          }
        }
      ]
    }
  ]
}
```

--------------------------------

### Fulfillment Get Product

Source: https://ucp.dev/latest/specification/reference

Documentation for the Fulfillment Get Product request and response structures.

```APIDOC
## Fulfillment Get Product Request

### Description
Retrieves a product with full detail, supporting variant narrowing, filtering, and contextual signals.

### Parameters
#### Request Body
- **id** (string) - Required - Product or variant identifier. Implementations MUST support product ID and variant ID.
- **selected** (Array[Selected Option]) - Optional - Partial or full option selections for interactive variant narrowing. When provided, response option values include availability signals (available, exists) relative to these selections.
- **preferences** (Array[string]) - Optional - Option names in relaxation priority order. When no exact variant matches all selections, the server drops options from the end of this list first. E.g., ['Color', 'Size'] keeps Color and relaxes Size.
- **filters** (Search Filters) - Optional - Filter criteria to narrow returned variants. All specified filters combine with AND logic.
- **context** (Context) - Optional - Provisional buyer signals for relevance and localization—not authoritative data. Businesses SHOULD use these values when verified inputs (e.g., shipping address) are absent, and MAY ignore or down-rank them if inconsistent with higher-confidence signals (authenticated account, risk detection) or regulatory constraints (export controls). Eligibility and policy enforcement MUST occur at checkout time using binding transaction data. Context SHOULD be non-identifying and can be disclosed progressively—coarse signals early, finer resolution as the session progresses. Higher-resolution data (shipping address, billing address) supersedes context.
- **signals** (Signals) - Optional - Environment data provided by the platform to support authorization and abuse prevention. Values MUST NOT be buyer-asserted claims — platforms provide signals based on direct observation or independently verifiable third-party attestations. All signal keys MUST use reverse-domain naming to ensure provenance and prevent collisions when multiple extensions contribute to the shared namespace.
- **attribution** (Attribution) - Optional - Platform-emitted referral and conversion-event context — campaign identifiers, click IDs, source/medium markers, etc. The same parameters platforms communicate via URL query parameters in browser-based flows.
- **filters** (any) - Optional - Catalog filters extended with a fulfillment destination filter and a method-type filter.

### Response
#### Success Response
- **ucp** (any) - Required - UCP metadata for catalog responses.
- **product** (object) - Required - The requested product with full detail. Singular — this is a single-resource operation.
- **actions** (Actions) - Optional - Outstanding extension-defined Actions for this product response.
- **messages** (Array[Message]) - Optional - Warnings or informational messages about the product (e.g., price recently changed, limited availability).
- **policies** (Array[Policy]) - Optional - Policies (e.g., return/refund terms) that apply to this product. `applies_to` targets are relative to the response root; when absent or empty, refer to the URLs in `links[]`.
- **product** (any) - Required - A get_product detail product (carrying selected/options availability signals) whose variants are fulfillment-enriched. Used by get_product.
```

--------------------------------

### Example Response Config

Source: https://ucp.dev/latest/specification/payment/examples/processor-tokenizer-payment-handler

JSON response config for checkout, containing runtime information about available instruments and configuration.

```json
{
  "id": "processor_tokenizer",
  "version": "2026-08-25",
  "available_instruments": [
    {
      "type": "card",
      "constraints": {
        "properties": { "brand": { "enum": ["visa", "mastercard", "amex"] } }
      }
    }
  ],
  "config": {
    "environment": "production",
    "business_id": "merchant_xyz789"
  }
}

```

--------------------------------

### ec.messages.change Example Message

Source: https://ucp.dev/latest/specification/shopping/checkout/embedded

Example JSON-RPC notification for checkout message updates. Includes errors, warnings, and informational notices.

```json
{
    "jsonrpc": "2.0",
    "method": "ec.messages.change",
    "params": {
        "checkout": {
            "id": "checkout_123",
            "messages": [
                {
                    "type": "error",
                    "code": "invalid_address",
                    "path": "$.buyer.shipping_address",
                    "content": "We cannot ship to this address",
                    "severity": "recoverable"
                },
                {
                    "type": "info",
                    "code": "free_shipping",
                    "content": "Free shipping applied!"
                }
            ]
            // ...
        }
    }
}
```

--------------------------------

### Resolved URL example

Source: https://ucp.dev/2026-08-25/specification/overview

Shows the resolved URL when the OpenAPI path '/checkout-sessions' is appended to the endpoint from the service declaration example.

```http
POST https://business.example.com/api/v2/checkout-sessions
```

--------------------------------

### Buyer-directed purchase link initialized data

Source: https://ucp.dev/latest/specification/permalink

Initialized data for the buyer-directed purchase link example.

```json
{
  "line_items": [
    {
      "item": { "id": "sku_kit" },
      "quantity": 3
    },
    {
      "item": {
        "id": "gid://shopify/ProductVariant/70881412"
      },
      "quantity": 2
    }
  ],
  "discounts": {
    "codes": ["VIP20", "WELCOME"]
  },
  "buyer": {
    "email": "alice@foo.com",
    "phone_number": "123-456-7890"
  },
  "context": {
    "address_country": "US",
    "postal_code": "94105",
    "language": "en-US",
    "payment": [{ "handler": "com.example.wallet" }]
  },
  "attribution": {
    "ref": "creator_42",
    "utm_source": "social"
  }
}
```

--------------------------------

### Example Error Response

Source: https://ucp.dev/2026-08-25/specification/embedded-protocol

Example JSON-RPC error response for an authentication request, containing an error message with code and severity.

```json
{
    "jsonrpc": "2.0",
    "id": "auth_1",
    "result": {
        "ucp": { "version": "2026-08-25", "status": "error" },
        "messages": [
            {
                "type": "error",
                "code": "timeout_error",
                "content": "An internal service timed out when fetching the required authorization data.",
                "severity": "recoverable"
            }
        ]
    }
}
```

--------------------------------

### Campaign link with discount and continuation initialized data

Source: https://ucp.dev/latest/specification/permalink

Initialized data for the campaign link example.

```json
{
  "line_items": [
    {
      "item": { "id": "sku_123" },
      "quantity": 1
    },
    {
      "item": { "id": "sku_456" },
      "quantity": 2
    }
  ],
  "discounts": {
    "codes": ["SPRING10"]
  },
  "attribution": {
    "utm_source": "email"
  }
}
```

--------------------------------

### Order Object JSON Example

Source: https://ucp.dev/

Example of a UCP order object. Use this to understand the structure of an order, including checkout ID, line items, fulfillment expectations, events, and adjustments. The example shows a delivered order with tracking information and a refund adjustment.

```json
{
  "ucp": { ... },
  "id": "order_123456789",
  "checkout_id": "chk_123456789",
  "permalink_url": ...,
  "line_items": [ ... ],
  "fulfillment": {
    "expectations": [
      {
        "id": "exp_1",
        "line_items": [{ "id": "li_1", "quantity": 1 }],
        "method_type": "shipping",
        "destination": {
          "first_name": "Elisa",
          "last_name": "Beckett",
          "street_address": "1600 Amphitheatre Pkwy",
          "address_locality": "Mountain View",
          "address_region": "CA",
          "postal_code": "94043",
          "address_country": "US"
        },
        "description": "Arrives in 2-3 business days",
        "fulfillable_on": "now"
      }
      ...
    ],
    "events": [
      {
        "id": "evt_1",
        "occurred_at": "2026-01-11T10:30:00Z",
        "type": "delivered",
        "line_items": [{ "id": "li_1", "quantity": 1 }],
        "tracking_number": "123456789",
        "tracking_url": "https://fedex.com/track/123456789",
        "description": "Delivered to front door"
      }
    ]
  },
  "adjustments": [
    {
      "id": "adj_1",
      "type": "refund",
      "occurred_at": "2026-01-12T14:30:00Z",
      "status": "completed",
      "line_items": [{ "id": "li_1", "quantity": -1 }],
      "totals": [{ "type": "total", "amount": -26550 }],
      "description": "Defective item"
    }
  ],
  "totals": [ ... ]
}

```
Tokens:
Raw