Quilzomanual

Selling to shopping agents

Shopping agents search the shop's catalogue and read its prices from the records you publish, and nothing else.

In the adminSettings

The catalogue is one listing, named in configuration, that says what the site sells. Shopping agents read it as a feed at /catalogue.json, or search it over the Universal Commerce Protocol (UCP), the protocol shopping agents use to find products and prices.

Name the catalogue

quilzo config set site.catalogue catalogue

The listing decides which products are in it, in what order, and which fields are public, exactly as it does on a page. /catalogue.json serves it with the licence terms beside the products.

Turn on UCP

quilzo config set site.base_url https://shop.example
quilzo config set ucp.catalogue true

The site then answers:

PathWhat it is
GET /.well-known/ucpThe shop's profile: the protocol version (2026-08-25), the REST endpoint, and the two capabilities it offers, catalog search and catalog lookup. Cacheable for five minutes.
POST /ucp/catalog/searchProducts matching a query, categories or a price range, a page at a time.
POST /ucp/catalog/lookupProducts by id, variant id or SKU, up to 50 at once, saying which identifiers matched nothing.
POST /ucp/catalog/productOne product in full.
curl -s https://shop.example/ucp/catalog/search \
  -H 'Content-Type: application/json' -H 'Request-Id: 1' \
  -H 'UCP-Agent: profile="https://platform.example/.well-known/ucp"' \
  -d '{"query": "brass pen", "pagination": {"limit": 10}}'

Every request carries a Request-Id and a UCP-Agent header, as the protocol requires. Every product in the listing can be found, not only the listing's first page, and prices are read from the published records on each request: a price published a minute ago is the price an agent is told. A request field the protocol does not define is refused.

site.base_url must be the site's https address: every URL an agent is given is built from it, and platforms fetch only https. Plain http is accepted for 127.0.0.1 and localhost, for trying it out.

What it does not do

Agents read; nothing is written. There are no carts, no checkout and no orders: an agent that finds something sends its person to the product's page to buy it. Nothing an agent sends changes a price, and nothing is kept from its requests.

Each address may make ucp.requests.per_hour requests an hour (600 by default), with a tenth of that at once. A request past it is answered 429 with how long to wait. When crawl.keys is set, a signed request is held to the same licence terms here as on every other path.

Next