Catalog Search Capability
Catalog Search Capability
Section titled “Catalog Search Capability”- Capability Name:
dev.ucp.shopping.catalog.search
Performs a search against the business’s product catalog. Supports free-text queries, filtering by category and price, and pagination.
Operation
Section titled “Operation”| Operation | Description |
|---|---|
| Search Catalog | Search for products using provided inputs and filters. |
Search Inputs
Section titled “Search Inputs”A valid search request MUST include at least one of: a query string,
one or more filters, or an extension-defined input. When query is
omitted, the request represents a browse operation — the business returns
products matching the provided filters without text-relevance ranking.
Extensions MAY define additional inputs (e.g., visual similarity,
product references).
Implementations MUST validate that incoming requests contain at least one
recognized input and SHOULD reject empty or invalid requests with an
appropriate error. Implementations define and enforce their own rules for
input presence and content — for example, requiring query, rejecting
empty query strings, or accepting filter-only requests for category browsing.
Search Filters
Section titled “Search Filters”Filter criteria for narrowing search results. Standard filters are defined below;
merchants MAY support additional custom filters via additionalProperties.
| Field | Type | Description |
|---|---|---|
categories | array | Filter by category identifiers |
price | object | Price range filter (see Price Filter below) |
Price Filter
Section titled “Price Filter”| Field | Type | Description |
|---|---|---|
min | integer | Minimum price in minor currency units |
max | integer | Maximum price in minor currency units |
Price filter values are denominated in context.currency. When the
presentment currency differs, businesses SHOULD convert before applying.
Pagination
Section titled “Pagination”Cursor-based pagination for list operations. Cursors are opaque strings that implementations MAY encode as stateless keyset tokens.
Page Size
Section titled “Page Size”The limit parameter is a requested page size, not a guaranteed count.
Implementations SHOULD accept a page size of at least 10. When the
requested limit exceeds the implementation’s maximum, implementations
MAY clamp to their maximum silently — returning fewer results without
error. Clients MUST NOT assume the response size equals the requested limit.
Pagination Request
Section titled “Pagination Request”| Field | Type | Description |
|---|---|---|
limit | integer | Requested number of results per page |
cursor | string | Opaque cursor from previous response for next page |
Pagination Response
Section titled “Pagination Response”| Field | Type | Description |
|---|---|---|
cursor | string | Cursor for fetching the next page |
has_next_page | boolean | Whether more results are available |
total_count | integer | Total number of matching results (when available) |
Transport Bindings
Section titled “Transport Bindings”- REST Binding:
POST /catalog/search - MCP Binding:
search_catalogtool