Agentic commerce needs a protocol boundary between AI agents and merchant catalog systems. A buyer-facing agent cannot safely scrape product pages, guess variant identifiers, or invent availability. It needs a structured way to search products, resolve identifiers, retrieve current product detail, and defer binding commitments such as price, tax, shipping, eligibility, and payment until checkout.
The Universal Commerce Protocol catalog capability and Shopify’s catalog interfaces show the core pattern: separate broad discovery from authoritative lookup. Search returns candidate products based on query text, filters, and coarse context. Lookup turns stable product or variant identifiers into current product detail, option state, availability signals, and messages that the agent can render or pass to a checkout flow.
This topic treats catalog protocols as a reusable interface design problem. The same design applies to marketplace search, internal procurement agents, travel inventory, ticketing, and B2B catalogs: expose bounded tools, return structured resources with provenance, keep buyer-provided context provisional, and make every follow-up step revalidate against authoritative inventory.
Search is exploratory. It accepts text, filters, and contextual hints, then returns candidates that may be ranked, clustered, paginated, or localized. Lookup is authoritative. It accepts identifiers that came from search, saved lists, deep links, carts, or merchant data, then resolves those identifiers to product and variant records.
Agents need stable product and variant identifiers because natural-language product descriptions are ambiguous. A product can have many variants, and each variant can differ by option selections, price, inventory, shipping eligibility, and checkout URL. Catalog protocols should model product, variant, options, selected values, and availability as first-class fields.
Search can use coarse signals such as location, locale, currency, budget, and preferences, but these signals are not binding. The protocol should distinguish buyer-provided context from platform-provided signals and merchant-authoritative state. Final eligibility belongs at checkout, where verified shipping, billing, account, and policy data are available.
A catalog result is evidence for a recommendation, not a contract. Prices, availability, option combinations, and merchant policy can change between search and checkout, so agents must revalidate the selected item before purchase.
The agent starts with a catalog search tool. The tool returns product summaries with identifiers, price ranges, media, descriptions, and variant hints. The agent then calls lookup or get-product on one or more identifiers before rendering a detail view, asking the buyer to choose options, or constructing a cart line item.
{
"tool": "search_catalog",
"arguments": {
"query": "waterproof trail running shoes",
"filters": {
"price": {"max": 15000, "currency": "USD"},
"availability": "in_stock"
},
"context": {
"country": "US",
"locale": "en-US"
}
}
}Lookup accepts product IDs, variant IDs, and sometimes secondary identifiers such as SKU, handle, barcode, or URL. The response should not rely on request order; each returned variant should carry correlation metadata explaining which input identifier resolved to it and whether the match was exact or selected as a featured representative.
{
"tool": "lookup_catalog",
"arguments": {
"ids": ["gid://commerce/Product/1001", "SKU-TRAIL-BLUE-10"],
"filters": {"price": {"max": 15000, "currency": "USD"}}
}
}A shopping assistant can search across a global catalog, compare offers, ask clarifying questions, and then lookup selected items before showing a purchase-ready detail page. The agent stays grounded because every recommendation contains machine-readable identifiers and current merchant-provided data.
A storefront agent can expose the same capability against one merchant’s catalog. That agent may support richer extensions such as collections, selling plans, gift cards, local availability, and merchant-specific filters while preserving the generic search and lookup shape.
Enterprise agents can use catalog protocols for approved vendor lists, hardware requests, SaaS licenses, or inventory pulls. The same interface separates discovery from policy enforcement: search suggests allowed items, while lookup and checkout enforce budget, approvals, and compliance.
Expose search, lookup, and product-detail operations as separate tools or endpoints. Search can tolerate fuzzy results; lookup should be strict, deduplicated, and explicit about missing or ambiguous identifiers.
type CatalogSearchRequest = {
query?: string;
filters?: Record<string, unknown>;
context?: Record<string, unknown>;
page?: {cursor?: string; limit?: number};
};
type CatalogLookupRequest = {
ids: string[];
filters?: Record<string, unknown>;
context?: Record<string, unknown>;
};
async function resolveForAgent(request: CatalogLookupRequest) {
const ids = [...new Set(request.ids)];
if (ids.length > MAX_LOOKUP_IDS) throw new Error("request_too_large");
const products = await catalog.resolve(ids, request.filters);
return {ucp: protocolMetadata(), products, messages: validationMessages(products)};
}Accept coarse context during search and finer context later. A postal region might be enough for search ranking, while exact shipping address should wait until checkout. This reduces privacy exposure and prevents agents from treating weak signals as authoritative facts.