A UCP agent doesn't read your product pages. It asks your catalogue, and gets back the products as data: what each one is, what it costs, what can be bought and whether it's in stock. Here is what that looks like, call by call, on a real store.
The first result search_catalog returned for "roses" on Northlight Flowers, our test store, split into the parts an agent uses.
{
"id": "bouquet_roses",
"title": "Bouquet of Red Roses",
"url": "https://flowers.ucpsandbox.com/products/bouquet_roses",
1id, title, url
What it is
A stable id the agent can look up again or put in a cart, the name it shows the buyer, and the page to send them to.
Every product has an id and a title; an id that changes between calls breaks the cart.
"description": {
"plain": "A classic dozen of long-stem red roses."
},
2description
What the buyer is told
Plain text the agent can quote or summarise. The store can also send markdown or HTML, and the agent has to strip it.
Plain text always, and an HTML version too if the description has formatting. On our test store this was the one rule to consider: no product sends an HTML version.
Each size or colour as its own id, price and stock, with the ways it can reach the buyer (here shipping or pickup). The variant id, not the product id, is what usually goes in the cart.
Every variant has an id, a price and an availability.
"media": [
{
"type": "image",
"url": "https://flowers.ucpsandbox.com/images/flowers/bouquet_roses.webp",
"alt_text": "Bouquet of Red Roses"
}
]
}
5media[]
What it looks like
Images the agent can show beside its answer, with alt text it can read out.
Image URLs are https and load; alt text describes the product.
The Catalog Validator checks every product a search returns against 33 rules like these. Run it on your store.
From a search to an order
Discovery is the first three calls: read the profile, list the tools, search. The other four are what discovery is for. Choose a call to see what was sent and what came back.
Recorded on 16 October 2026 against Northlight Flowers, our test store at flowers.ucpsandbox.com (release 2026-08-25, test cards, nothing is for sale). Responses are trimmed to the fields that matter, nothing added; long ids are cut short with …, and the agent's own profile is shown as agent.example.
Agentflowers.ucpsandbox.com
1
Read the profile
The agent asks the store's fixed address what it offers, before it sends anything else.
GET /.well-known/ucp HTTP/1.1
Host: flowers.ucpsandbox.com
Accept: application/json
What the agent knows now. 27 matches, 3 per page. A price of 3500 in USD is $35.00: amounts are in minor units. The variant id is what goes in the cart.
4
Put it in a cart
dev.ucp.shopping.cart
A line item is an id from the catalogue and a quantity. The store prices it and returns the cart.
What the agent knows now. Status incomplete, and the store says exactly why: no delivery option yet. Three to choose from.
6
Choose delivery
dev.ucp.shopping.fulfillment
An update replaces the checkout, so the agent sends all of it again with the option chosen. Sending only the change was refused: "line_items is required on update."
What the agent knows now. ready_for_complete: nothing missing. $35.00 with free shipping.
7
Pay and place the order
dev.ucp.shopping.checkout
Only the payment, through a handler the store declared, and a fresh idempotency key so a retry cannot charge twice. This is the one call that places an order.
How an agent finds what a store sells without reading its web pages. It fetches the store's UCP profile at /.well-known/ucp, checks that catalogue search is declared, and calls search_catalog on the endpoint the profile names. The store answers with typed products: ids, prices, variants, stock and images.
How is it different from a product feed or Google Shopping?
A feed is a copy of your catalogue sent to someone else's index, refreshed on their schedule. Discovery asks your store at the moment the buyer asks, so price and stock are current, and the same endpoint takes the cart and the checkout.
Which agents can do it?
Any agent with an MCP or REST client. MCP is the transport most stores declare: 98.4% of the verified stores we check that declare catalogue search offer it.
What does a store need to declare?
dev.ucp.shopping.catalog.search or dev.ucp.shopping.catalog.lookup for discovery. To go on and buy, an agent also needs cart or checkout and at least one payment handler. The capabilities page lists them all.
How do I know my product data is good enough?
Run the Catalog Validator on your store with a real search term. It makes the same calls as the run above and checks what comes back against 33 rules: ids, prices in minor units, variants, availability, images and descriptions.
Where do these numbers come from?
From the latest check of each verified store in the directory: what its UCP profile declares. A store that drops catalogue search leaves the count, and one that adds it joins.
