Catalog Capability

Catalog Capability

Overview

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

Capabilities

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.

Key Concepts

• 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.

Relationship to Checkout

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.

Shared Entities

Context

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. Response prices include explicit currency codes confirming the resolution.

Product

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.

Variant

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.

Messages and Error Handling

All catalog responses include an optional messages array that allows businesses to provide context about errors, warnings, or informational notices.

Message Types

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, AGE_RESTRICTED
info	Additional context without issues	PROMOTIONAL_PRICING, LIMITED_AVAILABILITY

Note: All catalog errors use severity: "recoverable" - agents handle them programmatically (retry, inform user, show alternatives).

Common Scenarios

Empty Search

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.

Backorder Warning

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",
      "variants": [
        {
          "id": "var_abc",
          "title": "12-piece Set",
          "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.

Identifiers Not Found

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.

Transport Bindings

The capabilities above are bound to specific transport protocols:

• REST Binding: RESTful API mapping.
• MCP Binding: Model Context Protocol mapping via JSON-RPC.