> ## 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.

# UCP Product Catalog: Schema and Endpoint Reference

> Build your /ucp/products endpoint correctly — product schema, variant structure, pricing rules, availability statuses, pagination, and filtering parameters.

Your `GET /ucp/products` endpoint is the primary interface between your inventory and AI agents. Agents call it to discover products, compare options, check availability, and identify the exact variant a customer wants before initiating checkout. If your catalog data is missing, malformed, or stale, agents cannot complete purchases — and customers get a broken experience.

## Product object schema

A complete product object looks like this:

```json theme={null}
{
  "products": [
    {
      "id": "prod_123",
      "name": "Running Shoes",
      "description": "High-performance running shoes for trail and road.",
      "category": "Footwear",
      "brand": "YourBrand",
      "sku": "RUN-SHOE",
      "url": "https://yourstore.com/products/running-shoes",
      "images": [
        "https://yourstore.com/images/shoes-black.jpg",
        "https://yourstore.com/images/shoes-white.jpg"
      ],
      "price": {
        "amount": 12999,
        "currency": "USD"
      },
      "availability": "in_stock",
      "variants": [
        {
          "id": "var_123_10_black",
          "sku": "RUN-SHOE-10-BLK",
          "attributes": {
            "size": "10",
            "color": "Black"
          },
          "price": {
            "amount": 12999,
            "currency": "USD"
          },
          "availability": "in_stock"
        },
        {
          "id": "var_123_11_white",
          "sku": "RUN-SHOE-11-WHT",
          "attributes": {
            "size": "11",
            "color": "White"
          },
          "price": {
            "amount": 12999,
            "currency": "USD"
          },
          "availability": "out_of_stock"
        }
      ]
    }
  ]
}
```

## Required product fields

<ParamField path="id" type="string" required>
  Unique, stable product identifier. Must not change when product details are updated — agents and order systems rely on this ID for the full purchase lifecycle.
</ParamField>

<ParamField path="name" type="string" required>
  Clear, descriptive product name. Agents use this to match customer requests. Avoid internal codes or abbreviations.
</ParamField>

<ParamField path="description" type="string" required>
  Product description. Minimum 50 characters for adequate AI comprehension. For Google AI Mode eligibility, aim for 150+ characters.
</ParamField>

<ParamField path="price.amount" type="integer" required>
  Price in the smallest currency unit. Cents for USD, pence for GBP, paisa for INR. `12999` means $129.99 — not $12,999.
</ParamField>

<ParamField path="price.currency" type="string" required>
  ISO 4217 currency code (e.g. `"USD"`, `"GBP"`, `"INR"`).
</ParamField>

<ParamField path="availability" type="string" required>
  Stock status. Must be one of: `in_stock`, `out_of_stock`, `preorder`, `backorder`.
</ParamField>

## Optional but recommended fields

| Field      | Why it matters                                                     |
| ---------- | ------------------------------------------------------------------ |
| `category` | Enables agents to filter and recommend products contextually       |
| `brand`    | Required for Google Merchant Center UCP eligibility                |
| `images`   | Displayed to users on AI surfaces; must be absolute HTTPS URLs     |
| `url`      | Lets agents link back to the product page for more detail          |
| `variants` | Required for any product with multiple options (size, color, etc.) |
| `sku`      | Simplifies order reconciliation in your backend systems            |

## Variant structure

Every product with selectable options must expose variants as explicit objects. Agents cannot infer variant IDs or availability from a base product alone.

<Warning>
  If a customer asks "do these come in size 11 white?" and your catalog has no explicit variant objects, the agent cannot answer correctly and cannot pass a valid `variant_id` to your checkout endpoint.
</Warning>

Each variant object requires:

<ParamField path="variants[].id" type="string" required>
  Unique variant identifier. Passed as `variant_id` in checkout requests.
</ParamField>

<ParamField path="variants[].attributes" type="object" required>
  Key-value map of what makes this variant distinct. Common keys: `size`, `color`, `material`, `style`.
</ParamField>

<ParamField path="variants[].price" type="object" required>
  Variant-level price object with `amount` and `currency`. May differ from the base product price.
</ParamField>

<ParamField path="variants[].availability" type="string" required>
  Per-variant availability status. A base product may be `in_stock` even if some variants are `out_of_stock`.
</ParamField>

## Pricing

Prices must always be in the smallest currency unit:

```json theme={null}
// $129.99 USD
{ "amount": 12999, "currency": "USD" }

// ₹4,999 INR
{ "amount": 499900, "currency": "INR" }

// £89.99 GBP
{ "amount": 8999, "currency": "GBP" }
```

<Tip>
  Cache catalog prices for a maximum of 5 minutes. If an agent shows a stale price to a customer and your checkout rejects it, the cart is abandoned. Stale prices are one of the most common causes of conversion drop-off in agentic commerce.
</Tip>

## Availability statuses

| Status         | Meaning                                                               |
| -------------- | --------------------------------------------------------------------- |
| `in_stock`     | Available to purchase immediately                                     |
| `out_of_stock` | Not available; agents will not offer this to customers                |
| `preorder`     | Available for pre-order; include an expected ship date where possible |
| `backorder`    | Not currently in stock but can be ordered; fulfillment delayed        |

## Pagination

For catalogs with more than 100 products, include a `pagination` object so agents can fetch your full catalog in pages:

```json theme={null}
{
  "products": [...],
  "pagination": {
    "page": 1,
    "per_page": 100,
    "total": 4820,
    "next": "https://yourstore.com/ucp/products?page=2"
  }
}
```

Agents will follow `next` URLs until the field is absent or `null`.

## Filtering parameters

If your manifest declares `"supports_search": true` and lists `supports_filters`, agents can query your catalog with these query parameters:

<ParamField query="q" type="string">
  Keyword search query (e.g. `?q=running+shoes`).
</ParamField>

<ParamField query="category" type="string">
  Filter by product category (e.g. `?category=footwear`).
</ParamField>

<ParamField query="min_price" type="integer">
  Minimum price in smallest currency unit (e.g. `?min_price=5000` for \$50.00).
</ParamField>

<ParamField query="max_price" type="integer">
  Maximum price in smallest currency unit (e.g. `?max_price=15000` for \$150.00).
</ParamField>

<ParamField query="availability" type="string">
  Filter by stock status. One of: `in_stock`, `out_of_stock`, `preorder`, `backorder`.
</ParamField>

Example filtered request:

```bash theme={null}
GET /ucp/products?q=running+shoes&category=footwear&max_price=15000&availability=in_stock
```

## Common issues

<AccordionGroup>
  <Accordion title="Missing variants causes checkout failure">
    If a customer selects "size 10 black" and your catalog only has a base `prod_123` without variant objects, the agent cannot pass a `variant_id` to your checkout endpoint. Always add variant objects for any product that has options.
  </Accordion>

  <Accordion title="Stale availability causes abandoned carts">
    If your catalog shows a product as `in_stock` but it is actually sold out, the checkout will fail after the customer has already committed to the purchase. Sync inventory updates to your catalog within 5 minutes of any stock change.
  </Accordion>

  <Accordion title="Prices in dollars instead of cents">
    A price of `129` is interpreted as $1.29, not $129.00. Always express prices in the smallest currency unit. See the pricing examples above.
  </Accordion>
</AccordionGroup>

## Validate your catalog

Use the [Readiness Score tool](https://asva-ai.com/tools/readiness) to check catalog health, or run the API:

```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", "checks": ["catalog"]}'
```

## Next steps

<CardGroup cols={2}>
  <Card title="Checkout and payments" icon="credit-card" href="/ucp/checkout-and-payments">
    Handle purchases with the checkout endpoint — cart creation, order confirmation, and PSP integration.
  </Card>

  <Card title="Feed specs and formatting" icon="table" href="/guides/feed-specs">
    Prepare feeds for Google Merchant Center and ACP.
  </Card>
</CardGroup>