Global Catalog extension
The Global Catalog extension adds Shopify-specific fields to the base UCP catalog tools. Every Global Catalog response includes the additional filters, variant fields, and ML-inferred metadata documented on this page.
- Extension name:
dev.shopify.catalog.global - Version:
2026-04-08 - 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 may 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. |
search_catalog also accepts these additional filters:
| Filter | Type | Default | Description |
|---|---|---|---|
shop_ids | array | — | Restrict results to specific shops by GID. You can pass up to 1000 shop IDs per request. |
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 Product fieldsProduct fields
All three tool responses include these additional fields on each product:
| Field | Type | Description |
|---|---|---|
metadata.attributes | Array[Attribute] | ML-inferred product attributes such as material, style, and occasion. |
metadata.tech_specs | Array[string] | ML-inferred technical specifications. |
metadata.top_features | Array[string] | ML-inferred top product features. |
metadata.unique_selling_points | Array[string] | ML-inferred unique selling propositions. |
Anchor to AttributesAttributes
Each attribute object contains:
| Field | Type | Description |
|---|---|---|
name | string | Attribute name (for example, "Material", "Style"). |
value | string | Attribute value (for example, "Cotton", "Casual"). |
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: