Skip to main content
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

​
id
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.
​
name
string
required
Clear, descriptive product name. Agents use this to match customer requests. Avoid internal codes or abbreviations.
​
description
string
required
Product description. Minimum 50 characters for adequate AI comprehension. For Google AI Mode eligibility, aim for 150+ characters.
​
price.amount
integer
required
Price in the smallest currency unit. Cents for USD, pence for GBP, paisa for INR. 12999 means 129.99—not129.99 — not 12,999.
​
price.currency
string
required
ISO 4217 currency code (e.g. "USD", "GBP", "INR").
​
availability
string
required
Stock status. Must be one of: in_stock, out_of_stock, preorder, backorder.
FieldWhy it matters
categoryEnables agents to filter and recommend products contextually
brandRequired for Google Merchant Center UCP eligibility
imagesDisplayed to users on AI surfaces; must be absolute HTTPS URLs
urlLets agents link back to the product page for more detail
variantsRequired for any product with multiple options (size, color, etc.)
skuSimplifies 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:
​
variants[].id
string
required
Unique variant identifier. Passed as variant_id in checkout requests.
​
variants[].attributes
object
required
Key-value map of what makes this variant distinct. Common keys: size, color, material, style.
​
variants[].price
object
required
Variant-level price object with amount and currency. May differ from the base product price.
​
variants[].availability
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

StatusMeaning
in_stockAvailable to purchase immediately
out_of_stockNot available; agents will not offer this to customers
preorderAvailable for pre-order; include an expected ship date where possible
backorderNot 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:
​
q
string
Keyword search query (e.g. ?q=running+shoes).
​
category
string
Filter by product category (e.g. ?category=footwear).
​
min_price
integer
Minimum price in smallest currency unit (e.g. ?min_price=5000 for $50.00).
​
max_price
integer
Maximum price in smallest currency unit (e.g. ?max_price=15000 for $150.00).
​
availability
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

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.
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.
A price of 129 is interpreted as 1.29,not1.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.