Universal Commerce Protocol (UCP)

UCP is an open standard that lets AI agents discover, search, and purchase your products and services — through a standard JSON file and a set of structured endpoints. This page is the complete reference for implementing UCP.

Introducing UCP

UCP plays the role of your business's "machine-readable menu." Exactly as robots.txt tells search engine crawlers which sections to crawl, a UCP file tells AI agents what capabilities your business has and where to call each one. This file must always be available at the fixed address https://yoursite.com/.well-known/ucp, responding with Content-Type: application/json.

Quick Start

The fastest way to get started is the free UCP generator: enter your business information and the capabilities you need, and a complete, deploy-ready ucp.json file is generated. For manual authoring, use the field and capability reference below.

ucp.json Reference

{
  "protocol": "ucp/v1",
  "merchant_name": "Example Store",
  "description": "An online electronics store",
  "website": "https://example.com",
  "capabilities": [
    {
      "name": "search_offers",
      "description": "Search products",
      "endpoint": "https://api.example.com/v1/ucp/search",
      "method": "GET"
    }
  ],
  "payment_methods": ["credit_card"],
  "supported_languages": ["en", "fa"],
  "currency": "USD"
}

Capabilities Reference

Each member of the capabilities array includes name, description, endpoint, and method. The eight standard capabilities:

Sample Request & Response: search_offers

GET /v1/ucp/search?query=headphones&limit=5

200 OK
{
  "results": [
    { "id": "sku_123", "name": "Model X Wireless Headphones", "price": 129.00, "currency": "USD", "in_stock": true }
  ]
}

Sample Request & Response: initiate_checkout

POST /v1/ucp/checkout
{ "cart_id": "cart_789", "customer": { "name": "...", "phone": "..." } }

200 OK
{ "order_id": "order_456", "status": "pending_payment", "payment_url": "https://..." }

Authentication

UCP keeps the manifest file itself public (no authentication needed to read it), but operational endpoints must be secure:

• Make all endpoints available only over HTTPS
• Use an API token or Bearer token for sensitive endpoints (checkout, wallet)
• Protect mutating requests (POST) with a request signature or a one-time-use nonce

Payments

The initiate_checkout capability usually starts a transaction with your existing payment gateway and returns a payment URL or transaction ID — UCP doesn't replace your payment gateway, it's a standard layer on top of it. For any store, this means connecting to the same gateway you already use (Stripe, PayPal, or any other PSP) from behind this same endpoint.

Error Handling

Error responses must always be valid JSON, never an HTML page or free text:

404 Not Found
{ "error": { "code": "product_not_found", "message": "The requested product was not found" } }

Testing & Validation

• curl -i https://yoursite.com/.well-known/ucp — check for a 200 response and valid JSON
• Check the output in an online JSON validator
• Test each capability individually with Postman
• Make sure error states also return a structured JSON response

Versioning

The protocol field carries the current version (e.g. ucp/v1). Breaking changes must be announced by bumping the version number so agents that still implement an older version don't encounter unexpected errors.

FAQ