The Catalog capability allows platforms to search and browse business product catalogs. This enables product discovery before checkout, supporting use cases like:
- Free-text product search
- Category and filter-based browsing
- Batch product/variant retrieval by identifier
- Price comparison across variants
| Capability | Description |
|---|---|
dev.ucp.shopping.catalog.search |
Search for products using query text and filters. |
dev.ucp.shopping.catalog.lookup |
Retrieve products or variants by identifier. |
- Product: A catalog item with title, description, media, and one or more variants.
- Variant: A purchasable item with specific option selections (e.g., "Blue / Large"), price, and availability.
- Price: Price values include both amount (in minor currency units) and currency code, enabling multi-currency catalogs.
Catalog operations return product and variant IDs that can be used directly in
checkout line_items[].item.id. The variant ID from catalog retrieval should match
the item ID expected by checkout.
Catalog responses (pricing, availability, etc.) reflect the Business's current terms for the given request but are not transactional commitments — checkout is authoritative. Responses can be session-specific and SHOULD NOT be reused across sessions without re-validation.
Location and market context for catalog operations. All fields are optional hints for relevance and localization. Platforms MAY geo-detect context from request headers.
Context signals are provisional—not authoritative data. Businesses SHOULD use these values when verified inputs (e.g., shipping address) are absent, and MAY ignore or down-rank them if inconsistent with higher-confidence signals (authenticated account, risk detection) or regulatory constraints (export controls). Eligibility and policy enforcement MUST occur at checkout time using binding transaction data.
Businesses determine market assignment—including currency—based on context
signals. Price filter values are denominated in context.currency; when
the presentment currency differs, businesses SHOULD convert before applying
(see Price Filter). Response prices include
explicit currency codes confirming the resolution.
When context.eligibility claims are present, Businesses that accept them
MAY adjust price / list_price directly for strikethrough display and
MAY use messages with code: "eligibility_benefit" to attribute the
adjustment to a specific claim.
{{ schema_fields('types/context', 'catalog') }}
Environment data provided by the platform to support authorization and abuse prevention. Signal values MUST NOT be buyer-asserted claims. See Signals for details and privacy requirements.
{{ schema_fields('types/signals', 'catalog') }}
A catalog item representing a sellable item with one or more purchasable variants.
media and variants are ordered arrays. Businesses SHOULD return the most
relevant variant and image first—default for lookups, best match based on query
and context for search. Platforms SHOULD treat the first element as featured.
{{ schema_fields('types/product', 'catalog') }}
A purchasable item with specific option selections, price, and availability.
In lookup responses, each variant carries an inputs array for correlation:
which request identifiers resolved to this variant, and whether the match
was exact or featured (server-selected). See
Client Correlation for details.
media is an ordered array. Businesses SHOULD return the featured variant image
as the first element. Platforms SHOULD treat the first element as featured.
{{ schema_fields('types/variant', 'catalog') }}
{{ schema_fields('types/price', 'catalog') }}
{{ schema_fields('types/price_range', 'catalog') }}
{{ schema_fields('types/media', 'catalog') }}
{{ schema_fields('types/product_option', 'catalog') }}
{{ schema_fields('types/option_value', 'catalog') }}
{{ schema_fields('types/selected_option', 'catalog') }}
{{ schema_fields('types/rating', 'catalog') }}
All catalog responses include an optional messages array that allows businesses
to provide context about errors, warnings, or informational notices.
Messages communicate business outcomes and provide context:
| Type | When to Use | Example Codes |
|---|---|---|
error |
Business-level errors | NOT_FOUND, OUT_OF_STOCK, REGION_RESTRICTED |
warning |
Important conditions affecting purchase | DELAYED_FULFILLMENT, FINAL_SALE |
info |
Additional context without issues | PROMOTIONAL_PRICING, LIMITED_AVAILABILITY |
Warnings with disclosure: true carry item-anchored notices (e.g., allergen
declarations, safety warnings) that platforms must not hide or dismiss. See
Disclosures for the full rendering contract.
Note: All catalog errors use severity: "recoverable" - agents handle them programmatically (retry, inform user, show alternatives).
{{ schema_fields('types/message_error', 'catalog') }}
{{ schema_fields('types/message_warning', 'catalog') }}
{{ schema_fields('types/message_info', 'catalog') }}
When search finds no matches, return an empty array without messages.
{
"ucp": {...},
"products": []
}This is not an error - the query was valid but returned no results.
When a product is available but has delayed fulfillment, return the product with
a warning message. Use the path field to target specific variants.
{
"ucp": {...},
"products": [
{
"id": "prod_xyz789",
"title": "Professional Chef Knife Set",
"description": { "plain": "Complete professional knife collection." },
"price_range": {
"min": { "amount": 29900, "currency": "USD" },
"max": { "amount": 29900, "currency": "USD" }
},
"variants": [
{
"id": "var_abc",
"title": "12-piece Set",
"description": { "plain": "Complete professional knife collection." },
"price": { "amount": 29900, "currency": "USD" },
"availability": { "available": true }
}
]
}
],
"messages": [
{
"type": "warning",
"code": "delayed_fulfillment",
"path": "$.products[0].variants[0]",
"content": "12-piece set on backorder, ships in 2-3 weeks"
}
]
}Agents can present the option and inform the user about the delay. The path
field uses RFC 9535 JSONPath to target specific components.
When requested identifiers don't exist, return success with the found products (if any). The response MAY include informational messages indicating which identifiers were not found.
{
"ucp": {...},
"products": [],
"messages": [
{
"type": "info",
"code": "not_found",
"content": "prod_invalid"
}
]
}Agents correlate results using the inputs array on each variant. See
Client Correlation.
When a product requires a disclosure (e.g., allergen notice, safety warning),
return it as a warning with disclosure: true. The path field targets the
relevant component in the response — when it targets a product, the
disclosure applies to all of its variants.
{
"ucp": {...},
"products": [
{
"id": "prod_nut_butter",
"title": "Artisan Nut Butter Collection",
"variants": [
{
"id": "var_almond",
"title": "Almond Butter",
"price": { "amount": 1299, "currency": "USD" },
"availability": { "available": true }
},
{
"id": "var_cashew",
"title": "Cashew Butter",
"price": { "amount": 1499, "currency": "USD" },
"availability": { "available": true }
}
]
}
],
"messages": [
{
"type": "warning",
"code": "allergens",
"path": "$.products[0]",
"content": "**Contains: tree nuts.** Produced in a facility that also processes peanuts, milk, and soy.",
"content_type": "markdown",
"disclosure": true,
"image_url": "https://merchant.com/allergen-tree-nuts.svg",
"url": "https://merchant.com/allergen-info"
}
]
}See Disclosures for the full rendering contract.
The capabilities above are bound to specific transport protocols:
- REST Binding: RESTful API mapping.
- MCP Binding: Model Context Protocol mapping via JSON-RPC.