Skip to main content
UCP (Universal Commerce Protocol) gives AI agents a standardized way to browse your catalog and complete purchases — without the customer ever leaving the AI experience. Once your endpoints are live, any UCP-compatible agent can discover your products, check availability, and place orders on the customer’s behalf. This guide covers the minimum viable implementation: capability discovery, product catalog, and checkout.

​
Prerequisites

  • Domain with HTTPS (required for /.well-known/ucp)
  • Ability to create API endpoints on any backend stack
  • Product catalog data in a structured format (JSON or XML)
  • A payment processor already in place (Stripe, Razorpay, PayPal, Square, or similar)

​
Quickstart

1

Set up capability discovery

Create a /.well-known/ucp file at your domain root. This tells AI agents what commerce capabilities your store supports and where to call them.
/.well-known/ucp
{
  "version": "1.0",
  "capabilities": {
    "product_catalog": {
      "endpoint": "https://yourstore.com/ucp/products",
      "format": "json"
    },
    "checkout": {
      "endpoint": "https://yourstore.com/ucp/checkout",
      "supported_methods": ["POST"]
    }
  }
}
Use the Manifest Generator to generate this file automatically from your endpoint URLs.
2

Expose your product catalog

Create a GET /ucp/products endpoint that returns your catalog in UCP format. Every product with multiple options must include explicit variant objects — agents cannot infer variants from a base product alone.
{
  "products": [
    {
      "id": "prod_123",
      "name": "Running Shoes",
      "description": "High-performance running shoes for trail and road.",
      "price": {
        "amount": 12999,
        "currency": "USD"
      },
      "availability": "in_stock",
      "images": ["https://yourstore.com/images/shoes.jpg"],
      "variants": [
        {
          "id": "var_123_10_black",
          "attributes": { "size": "10", "color": "Black" },
          "price": { "amount": 12999, "currency": "USD" },
          "availability": "in_stock"
        }
      ]
    }
  ]
}
Prices must be in the smallest currency unit — cents for USD, pence for GBP. 12999 means 129.99,not129.99, not 12,999.
3

Implement the checkout endpoint

Create a POST /ucp/checkout endpoint. The agent sends a cart and shipping address; your backend responds with a session ID and shipping options. A second POST /ucp/checkout/:id/confirm call processes the payment.
// POST /ucp/checkout — request from the AI agent
{
  "cart": {
    "items": [
      {
        "product_id": "prod_123",
        "variant_id": "var_123_10_black",
        "quantity": 1
      }
    ]
  },
  "shipping_address": {
    "street": "123 Main St",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94102",
    "country": "US"
  },
  "payment_method": {
    "token": "payment_token_from_psp"
  }
}

// Response from your backend
{
  "order_id": "order_abc123",
  "status": "confirmed",
  "total": { "amount": 13598, "currency": "USD" },
  "estimated_delivery": "2026-04-17"
}
4

Test and validate

Confirm each endpoint responds correctly before going live.
# Verify the manifest is reachable
curl https://yourstore.com/.well-known/ucp

# Test the catalog endpoint
curl https://yourstore.com/ucp/products

# Dry-run a checkout request
curl -X POST https://yourstore.com/ucp/checkout \
  -H "Content-Type: application/json" \
  -d '{"cart":{"items":[{"product_id":"prod_123","quantity":1}]},"dry_run":true}'
Then run the full Asva audit to catch any structural issues:
curl -X POST https://asva-ai.com/api/audit \
  -H "Authorization: Bearer $ASVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "yourstore.com"}'
Or use the free browser tool: asva-ai.com/tools/readiness

​
What the Readiness Score checks

The Readiness Score tool runs a full UCP audit of your domain and flags:
  • Whether /.well-known/ucp is accessible and returns valid JSON
  • Whether your product catalog endpoint returns properly structured products
  • Whether your checkout endpoint accepts POST requests
  • Whether HTTPS is correctly configured on all endpoints
  • Whether required product attributes (id, name, price, availability) are present on every product

​
Next steps

UCP capability discovery

Full reference for the .well-known/ucp manifest — all fields, hosting options, and validation.

Product catalog endpoint

Structuring variants, pricing, availability, images, and pagination correctly.

Checkout and payments

Checkout flows, error handling, and PSP integration (Stripe, Razorpay, PayPal).

Shopify guide

Native UCP on Shopify using Checkout Kit and the Storefront API.