UCP Product Catalog: Schema and Endpoint Reference

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:

{
  "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

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.

string

required

Clear, descriptive product name. Agents use this to match customer requests. Avoid internal codes or abbreviations.

string

required

Product description. Minimum 50 characters for adequate AI comprehension. For Google AI Mode eligibility, aim for 150+ characters.

integer

required

Price in the smallest currency unit. Cents for USD, pence for GBP, paisa for INR. 12999 means

129.99 — not

12,999.

string

required

ISO 4217 currency code (e.g. "USD", "GBP", "INR").

string

required

Stock status. Must be one of: in_stock, out_of_stock, preorder, backorder.

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.

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.

Each variant object requires:

string

required

Unique variant identifier. Passed as variant_id in checkout requests.

object

required

Key-value map of what makes this variant distinct. Common keys: size, color, material, style.

object

required

Variant-level price object with amount and currency. May differ from the base product price.

string

required

Per-variant availability status. A base product may be in_stock even if some variants are out_of_stock.

Pricing

Prices must always be in the smallest currency unit:

// $129.99 USD
{ "amount": 12999, "currency": "USD" }

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

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

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.

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:

{
  "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:

string

Keyword search query (e.g. ?q=running+shoes).

string

Filter by product category (e.g. ?category=footwear).

integer

Minimum price in smallest currency unit (e.g. ?min_price=5000 for $50.00).

integer

Maximum price in smallest currency unit (e.g. ?max_price=15000 for $150.00).

string

Filter by stock status. One of: in_stock, out_of_stock, preorder, backorder.

Example filtered request:

GET /ucp/products?q=running+shoes&category=footwear&max_price=15000&availability=in_stock

Common issues

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.

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.

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.

Validate your catalog

Use the Readiness Score tool to check catalog health, or run the API:

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

Checkout and payments

Handle purchases with the checkout endpoint — cart creation, order confirmation, and PSP integration.

Feed specs and formatting

Prepare feeds for Google Merchant Center and ACP.

Get Started

UCP

ACP

Attribution

Guides

UCP Product Catalog: Schema and Endpoint Reference

Product object schema

Required product fields

Optional but recommended fields

Variant structure

Pricing

Availability statuses

Filtering parameters

Common issues

Validate your catalog

Next steps

Checkout and payments

Feed specs and formatting

​Product object schema

​Required product fields

​Optional but recommended fields

​Variant structure

​Pricing

​Availability statuses

​Pagination

​Filtering parameters

​Common issues

​Validate your catalog

​Next steps

Checkout and payments

Feed specs and formatting

Product object schema

Required product fields

Optional but recommended fields

Variant structure

Pricing

Availability statuses

Pagination

Filtering parameters

Common issues

Validate your catalog

Next steps