> ## Documentation Index
> Fetch the complete documentation index at: https://docs.asva-ai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Implement UCP: Enable AI-Native Commerce on Your Store

> Set up Universal Commerce Protocol endpoints so AI agents on Google AI Mode, Gemini, and other UCP surfaces can discover and purchase your products.

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

<Steps>
  <Step title="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.

    ```json /.well-known/ucp theme={null}
    {
      "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](https://asva-ai.com/tools/manifest) to generate this file automatically from your endpoint URLs.
  </Step>

  <Step title="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.

    ```json theme={null}
    {
      "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"
            }
          ]
        }
      ]
    }
    ```

    <Note>
      Prices must be in the smallest currency unit — cents for USD, pence for GBP. `12999` means $129.99, not $12,999.
    </Note>
  </Step>

  <Step title="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.

    ```json theme={null}
    // 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"
      }
    }
    ```

    ```json theme={null}
    // Response from your backend
    {
      "order_id": "order_abc123",
      "status": "confirmed",
      "total": { "amount": 13598, "currency": "USD" },
      "estimated_delivery": "2026-04-17"
    }
    ```
  </Step>

  <Step title="Test and validate">
    Confirm each endpoint responds correctly before going live.

    ```bash theme={null}
    # 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:

    ```bash theme={null}
    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](https://asva-ai.com/tools/readiness)
  </Step>
</Steps>

## What the Readiness Score checks

The [Readiness Score tool](https://asva-ai.com/tools/readiness) 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

<CardGroup cols={2}>
  <Card title="UCP capability discovery" icon="file-code" href="/ucp/well-known">
    Full reference for the `.well-known/ucp` manifest — all fields, hosting options, and validation.
  </Card>

  <Card title="Product catalog endpoint" icon="boxes-stacked" href="/ucp/product-catalog">
    Structuring variants, pricing, availability, images, and pagination correctly.
  </Card>

  <Card title="Checkout and payments" icon="credit-card" href="/ucp/checkout-and-payments">
    Checkout flows, error handling, and PSP integration (Stripe, Razorpay, PayPal).
  </Card>

  <Card title="Shopify guide" icon="shopify" href="/ucp/shopify">
    Native UCP on Shopify using Checkout Kit and the Storefront API.
  </Card>
</CardGroup>