Catalog query
Make your products easy for agents to search, compare, and recommend.
Batch lookup, search with filters, single-product GET — the read side of the UCP surface.
UCP exposes two catalog operations: lookup (you know the ids you want) and search(you don't). Both are unauthenticated by default — the catalog is public — but accept a bearer if you want identity linking.
Lookup
Batch fetch up to 50 products by id.
bash
curl -X POST https://aly.store/api/ucp/v1/catalog/lookup \ -H "Content-Type: application/json" \ -d '{ "site_slug": "acme", "product_ids": ["prod_abc", "prod_def"] }'When you call on a store host (<slug>.aly.store), site_slug can be omitted — the discovery doc binds the store.
json
{ "ucp": { "version": "1" }, "products": [ { "id": "prod_abc", "site_slug": "acme", "name": "Linen Tote", "description": "...", "price": { "amount": 4200, "currency": "USD" }, "media": [{ "type": "image", "url": "https://cdn.aly.store/..." }], "variants": [ { "id": "var_1", "options": { "color": "natural" }, "price": { "amount": 4200, "currency": "USD" }, "in_stock": true } ], "tags": ["bags", "linen"], "url": "https://acme.aly.store/p/linen-tote" } ], "not_found": []}Search
Full-text + filter, paginated.
bash
curl -X POST https://aly.store/api/ucp/v1/catalog/search \ -H "Content-Type: application/json" \ -d '{ "site_slug": "acme", "query": "tote bag", "filters": { "in_stock": true, "price_min": 2000, "price_max": 8000 }, "limit": 20, "cursor": null }'Omit site_slug on the platform host (aly.store) to search every published store. On a store host the slug is bound and ignored.
json
{ "ucp": { "version": "1" }, "products": [ /* same product shape as lookup */ ], "next_cursor": "eyJsYXN0SWQiOiJwcm9kX3p6eiJ9", "total_estimate": 142}Single product
If you have a permalink and want the canonical shape:
bash
curl https://aly.store/api/ucp/v1/catalog/acme/products/prod_abcVariant resolution
When the buyer picks a variant, pass
variant_options in the checkout-session line_items. The server resolves the variant id, validates stock, and applies any variant price override.Filters
| Filter | Type | Notes |
|---|---|---|
in_stock | bool | Excludes out-of-stock variants from the product list. |
price_min / price_max | integer (minor units) | Bounds in the store currency. |
tags | string[] | OR semantics — match any. |
collection | string | Restrict to a single collection slug. |
Errors
| Status | When |
|---|---|
| 400 | Body fails Zod validation; error.details lists fields. |
| 404 | Unknown site_slug or unpublished site. |
| 429 | Catalog rate limit hit. |
Was this page helpful?