Global Catalog extension
The Global Catalog extension adds Shopify-specific fields to the base UCP catalog tools. This page documents additional filters, variant fields, and inferred product fields that Global Catalog responses can include.
- Extension name:
dev.shopify.catalog.global. - Versions:
2026-04-08,2026-08-25, anddraft. - Extends:
dev.ucp.shopping.catalog.search,dev.ucp.shopping.catalog.lookup.
This extension is scoped to the global catalog — products from across all Shopify merchants. For the single-store extension, see Storefront Catalog extension.
Anchor to FiltersFilters
All three tools (search_catalog, lookup_catalog, and get_product) accept a catalog.filters object with the following Shopify-specific fields:
| Field | Type | Default | Description |
|---|---|---|---|
available | boolean | true | When true (default), only sale-ready items are returned. Set to false to include unavailable items. |
condition | array | — | Product condition filter. Known values: "new", "secondhand". Multiple values use OR logic. Absent means no condition filter. |
ships_to | object | — | Filter to products that ship to a given location. When country matches context.address_country, the implementation might enrich with context region and postal code. Accepts country (required, ISO 3166-1 alpha-2), region, and postal_code. |
ships_from | array | — | Filter by merchant origin country. Each entry accepts country (required, ISO 3166-1 alpha-2). Multiple entries use OR logic. Digital products that don't require shipping can still match this filter. |
shops | array | — | Restrict results to specific shops by GID. You can pass up to 1000 shop IDs per request. |
search_catalog also accepts these additional filters:
| Filter | Type | Default | Description |
|---|---|---|---|
categories | array | — | Filter by product category. Each item is a taxonomy category GID (for example, "gid://shopify/TaxonomyCategory/123"). Multiple values use OR logic. |
attributes | array | — | Filter by Shopify taxonomy attributes. Supported names are Color, Size, and Target gender. Entries combine with AND logic. Values within one entry combine with OR logic. Unsupported attribute names are ignored and returned in messages. |
rating | object | — | Filter by variant rating. Accepts variant, which matches products with at least one variant whose rating meets the given thresholds. variant.min sets the minimum rating value (0–5 scale) and variant.min_count sets the minimum number of reviews. |
price_tier | array | — | Filter by relative price tier within each product's category. Supported values are low, medium, and high. Multiple values use OR logic. Unsupported values are ignored and returned in messages. |
Anchor to Similarity searchSimilarity search
Use catalog.like in a search_catalog request to find products similar to a reference product, variant, or image. Pass one item as one of:
- Item reference: A product or variant GID. For example,
{"id": "gid://shopify/p/..."},{"id": "gid://shopify/Product/..."}, or{"id": "gid://shopify/ProductVariant/..."}. - Image content: A base64-encoded image with its MIME type. For example,
{"image": {"content_type": "image/jpeg", "data": "<base64>"}}.
You can combine like with query in a single request to narrow similarity results by keyword. When like contains an image and query is present, Global Catalog uses multimodal search. Multimodal search uses the text query to describe what the agent is looking for and the image to provide visual context, such as style, shape, or pattern. When like contains only an image, Global Catalog uses visual similarity search, which returns items that visually resemble the image without additional text intent.
Anchor to Rich mediaRich media
Rich media fields are available only in the draft version of the Global Catalog extension.
Rich media fields are available only in the draft version of the Global Catalog extension.
In the draft version, product and variant media arrays can include images, videos, and 3D models. The type field identifies the media type. Known values are image, video, and model_3d. If your agent doesn't recognize a media type, then ignore that media item.
Each media item has a primary url. Videos and 3D models can also include preview images and multiple source files so that your agent can select a supported format or rendition.
| Field | Type | Applies to | Description |
|---|---|---|---|
name | string | All media | Human-readable title or label that's distinct from accessibility-oriented alt_text. |
preview | object | All media | Poster or thumbnail image to render before or instead of the primary resource. Includes url and can include width and height. |
duration | integer | Videos | Video duration in seconds. |
embed_url | string | Externally hosted videos | Player embed URL. When present, url identifies the video's watch page. |
sources | array | Videos and 3D models | Complete set of available video renditions or 3D model encodings. |
Each entry in sources can include these fields:
| Field | Type | Description |
|---|---|---|
url | string | URL of the rendition file or streaming manifest. |
mime_type | string | IANA media type, such as video/mp4 or model/gltf-binary. |
format | string | Short format token, such as mp4, m3u8, glb, or usdz. |
width | integer | Pixel width of a video rendition. |
height | integer | Pixel height of a video rendition. |
filesize | integer | File size in bytes. |
When sources is present and url identifies a rendition, sources should include an entry with the same URL. Adaptive-streaming manifests can omit width, height, and filesize. If your agent selects a video rendition from sources, then use that source's dimensions instead of the media item's dimensions.
The following example includes a video with two renditions and a 3D model with GLB and USDZ encodings:
For an externally hosted video, url identifies the watch page and embed_url identifies third-party active player content:
Your agent may decline to load third-party active content because of its security, privacy, or presentation policy and use the watch-page url instead.
Anchor to Inferred product fieldsInferred product fields
All three tool responses can include fields inferred or enriched by Shopify. These fields might not always be present or might vary in accuracy depending on available product data. Treat them as discovery and merchandising signals, not as merchant-authored source text.
| Field | Type | Tag | Description |
|---|---|---|---|
description | object | Inferred | Product description generated or enriched by Shopify. |
options | Array[ProductOption] | Inferred | Product options normalized for catalog discovery and variant selection. |
metadata.attributes | Array[Attribute] | Inferred | Product attributes such as material, style, and occasion. |
metadata.tech_specs | Array[string] | Inferred | Technical specifications. |
metadata.top_features | Array[string] | Inferred | Top product features. |
metadata.unique_selling_points | Array[string] | Inferred | Unique selling propositions. |
variants[].condition | Array[string] | Inferred | Product condition labels for this variant. Known values are "new" and "secondhand". |
Anchor to Variant fieldsVariant fields
Variants include checkout URLs, purchase requirements, inventory signals, and seller identity:
| Field | Type | Description |
|---|---|---|
checkout_url | string | Direct checkout URL for this variant. |
requires.shipping | boolean | Whether a shipping address is needed. When false, checkout can skip address collection. |
requires.components | boolean | Whether the variant requires bundle components. When true, the variant can only be purchased as a parent bundle. |
condition | Array[string] | Product condition labels for this variant. Known values: "new", "secondhand". |
eligible.native_checkout | boolean | Whether this variant supports native (non-redirect) checkout. Default false. |
availability.running_low | boolean | Whether inventory is limited. Only meaningful when available is true. |
seller.id | string | The shop GID. |
seller.url | string | The storefront URL. |
seller.domain | string | The primary domain of the shop. |
seller.name and seller.links are part of the base UCP spec and always present in Global Catalog responses.
seller.name and seller.links are part of the base UCP spec and always present in Global Catalog responses.
Anchor to Example responseExample response
The following example shows a search_catalog response with Global Catalog extension fields: