Skip to content
Universal Commerce Protocol Universal Commerce Protocol Protocol registry / en
The UCP standardUCP vs ACPImplementAgentic commerceFramework
ConceptGEOllms.txtGlossaryAgentic paymentsAP2Visa and MastercardB2B agentic commerceMethodologyUse CasesWhy NowFor WhomManifestoFAQResourcesSourcesEcosystemValidatorReadiness diagnosticAboutContact
FR Run the diagnostic →

Reference note

UCP Catalog: Search, Lookup, and stable product IDs

How to expose a UCP catalog with Search and Lookup, stabilize identifiers, and connect product discovery to Checkout.

Published . Part of catalog readability for AI agents.

The UCP Catalog capability separates two needs. Search discovers products from a query and filters. Lookup resolves identifiers the platform already knows. This prevents every catalog access from becoming an approximate search.

Key takeaways

  • Catalog has 2 negotiable capabilities: Search and Lookup.
  • A product groups one or more purchasable variants.
  • Catalog prices inform discovery; Checkout remains transactionally authoritative.

This note follows release 2026-08-25. That release keeps Search and Lookup separate and extends Catalog with fractional sale units, product-level policies, and extension-defined actions.

What does Catalog cover?

The Catalog specification covers free-text search, category browsing, filtering, batch retrieval, and price comparison across variants. It uses shared entities for context, signals, and attribution.

A Product carries its title, description, media, and variants. A Variant is a purchasable combination with selected options, price, and availability. Amounts use the currency’s minor unit and always include an ISO 4217 currency code.

As of release 2026-08-25, variants[].quantity_unit can also declare the sale unit, scale, and increment. When it is absent, the variant is sold by each. This distinction matters for products sold by weight, volume, length, or time.

When should Search be used?

Search answers an intent such as “waterproof shoes under 120 euros.” The platform sends query text, market context, and filters. The merchant remains responsible for ranking and interpreting those criteria.

An empty search is not necessarily a transport error. A valid response can contain an empty product list and explanatory messages. The agent must distinguish no results from an unavailable catalog.

Quality depends on exposed data: discriminating titles, normalized variants, explicit prices, current availability, and usable media. The GEO-readable catalog guide explains that semantic base.

When should Lookup be used?

Lookup provides two operations. lookup_catalog receives an ids[] array and returns matching products. get_product receives one known identifier and returns the detail needed for a decision, including variant selection.

Implementations must accept product and variant IDs. They may also support SKU, handle, or URL when the returned object exposes the same field. Duplicate inputs must be deduplicated, and the same product must appear only once.

Need Operation
resolve several identifiers lookup_catalog
render a compact list lookup_catalog
load full product detail get_product
choose a variant get_product

How does Catalog connect to Checkout?

The variant ID returned by Catalog should match checkout.line_items[].item.id. This contract removes an implicit translation layer between discovery and transaction.

Catalog prices and availability reflect current terms for the request, but they are not transactional commitments. They may be session-specific and should not be reused without validation. Checkout remains authoritative at purchase time.

Design mistakes to avoid

  1. Running Search to resolve an exact SKU.
  2. Exposing different IDs in Catalog and Checkout.
  3. Mixing product and variant in an untyped identifier field.
  4. Caching a search price as if it were guaranteed.
  5. Omitting currency or the minor-unit convention.
  6. Returning partial results without messages for unresolved IDs.

Catalog quality checklist

  • advertise Search and Lookup separately;
  • assign stable, purchasable variant IDs;
  • apply filters after identifier resolution;
  • return price, currency, and availability;
  • declare quantity_unit and its increment for non-each sales;
  • report unknown IDs without discarding valid matches;
  • revalidate the final price in Checkout.

These contracts fit into the broader UCP implementation guide.

Sources

Back to catalog readability for AI agents · All notes · Lire en français