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 and external 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. |
media | array of objects | — | Filter by product media. Each entry is an object with a type field and asserts that the product has at least one media item of that type. Entries combine with AND. Supported types are image, video, external_video, and model_3d. Unsupported types 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 Catalog sourcesCatalog sources
Catalog sources are in beta. Behavior and fields can change during the beta.
Catalog sources are in beta. Behavior and fields can change during the beta.
Your use of external product data is governed by the Shopify API License and Terms of Use and the usage requirements for external offers. Shopify doesn't verify external product data and provides it as is.
Your use of external product data is governed by the Shopify API License and Terms of Use and the usage requirements for external offers. Shopify doesn't verify external product data and provides it as is.
By default, Global Catalog returns offers published by Shopify merchants. In the beta, you can also search external offers: products indexed from a merchant's own website rather than published through Shopify. An external offer helps a shopper or agent find a product. The full listing, and any purchase, remain on the merchant's site.
Anchor to Selecting sourcesSelecting sources
search_catalog accepts a catalog.sources array. lookup_catalog and get_product don't take sources. They resolve whatever ID you pass, including external IDs.
catalog.sources requires version 2026-08-25 or draft and an API client that Shopify has enabled. For other clients, search_catalog ignores catalog.sources but still applies a saved catalog's sources, and variants don't include source.
| Field | Type | Default | Description |
|---|---|---|---|
sources | array | ["shopify"] | Catalog sources that the search ranks over. Well-known values are "shopify" (offers published by Shopify merchants) and "external" (offers indexed from merchants' own websites, purchased on the merchant's site through the variant url). Pass both values to get a single ranked list across sources. When catalog_id is present, the saved catalog's configured sources are both the default and the limit. Requested values outside that limit are dropped. Otherwise, the default is ["shopify"]. Unrecognized values are ignored and returned in messages. |
Anchor to The source fieldThe source field
source fieldEvery variant includes source, so you can label, group, or filter results in your experience without inspecting IDs.
| Field | Type | Description |
|---|---|---|
variants[].source | string | "shopify" or "external". Present on every variant, including results that come only from Shopify, when catalog sources are available to your client. |
Anchor to External variant differencesExternal variant differences
External offers use the same product and variant shape as Shopify offers, with the following differences. Fields that aren't listed here behave as documented elsewhere on this page.
| Field | External behavior |
|---|---|
id | The product ID uses the same universal gid://shopify/p/… format as Shopify products. Variant IDs are gid://catalog/ExternalVariant/…. lookup_catalog and get_product accept external variant IDs. catalog.like doesn't accept external variant IDs. To find similar items, pass the product ID or an image. An ID stops resolving when the offer is no longer available. |
url | The product page on the merchant's own site. This is the only path to view the full listing or make a purchase. |
checkout_url | Absent. There's no Shopify cart or checkout for external offers. |
eligible.native_checkout | Always false. |
seller | seller.id is gid://catalog/ExternalMerchant/…. seller.name and seller.url (the merchant's site) are present. seller.domain is present when known. seller.links (policies) might be absent. |
price | The price observed on the merchant's page at the last refresh, in the merchant's currency. Might be absent. Treat it as indicative. The merchant's page is authoritative. |
availability | Stock levels aren't tracked for external offers. available is true whenever the offer is listed, and doesn't indicate current stock. Confirm availability on the merchant's page before you present an item as in stock. running_low and status are absent. |
condition | ["new"] or ["secondhand"]. |
description | plain only, with no html. A variant's description is the description from the merchant's product data, with HTML removed. If a variant has no description, then it uses the product description. |
media | Variant media contains images only. Each image url is a cached copy of the merchant's image, served unaltered. Cached images might be refreshed or removed to reflect the merchant's site, so an image URL can stop resolving. |
requires | Absent. Shipping, selling plan, and bundle requirements aren't known for external offers. |
placement | Absent. External offers are never promoted placements. Refer to Promoted placements for external offers. |
| Inferred fields | Might be present (metadata.* and normalized options). The same caveats apply as in Inferred product fields. |
Anchor to Usage requirements for external offersUsage requirements for external offers
External product data is indexed from merchants' own websites rather than published through Shopify. You must meet these requirements whenever you display an external offer. They apply in addition to the API Terms of Use, and they're designed so that shoppers can find products through your experience while the listing, the traffic, and the sale remain with the merchant.
- Link every external offer to its source. When you display an external offer, the product (its title, image, or card) must link to
variants[].url, the merchant's product page. In chat, voice, or other surfaces without a clickable card, you must present the merchant's name and a link to the product page alongside the offer. - Send purchases to the merchant. You must not create carts, checkouts, or payment flows for external offers, and you must not present Shop Pay or Shopify checkout as available for them. This is why
eligible.native_checkoutisfalseandcheckout_urlis absent. - Identify the seller accurately. You must display
seller.name(andseller.domainwhere space allows) with each external offer. You must not present an external offer as sold by Shopify or by a Shopify merchant, or as affiliated with, sponsored by, or endorsed by Shopify or any other brand. When your experience mixes sources, the distinction must be visible to the shopper. For example, label results usingvariants[].source. - Display only, with no redistribution or training. External product data is made available solely for display in your own agent, app, or site in response to a shopper's request. You must not redistribute, resell, sublicense, bulk-export, or syndicate external product data. You must not include it in feeds, datasets, or indexes that you provide to others, or use it to train, fine-tune, or evaluate machine-learning models. These restrictions apply in addition to, and might be narrower than, the permissions in the API Terms of Use for other Catalog API data.
- Use images as returned. Images served from Shopify CDN URLs can be cached within the caching limits in Usage guidelines. You can display other external image URLs as returned, and cache them only as permitted by their HTTP cache headers. You must not re-host, mirror, or store those images beyond that. Apart from the Shopify CDN resize and padding parameters, you must not crop, edit, overlay, watermark, or remove branding from any external image, and you must not use it other than to represent the offer that it belongs to. Your experience must handle an image that no longer resolves.
- Don't reassemble the listing. You must not combine fields from an external offer into a reproduction of the merchant's product page. You can cache external offer data only within the caching limits in Usage guidelines. When a cached price or availability value expires, query again rather than reuse it.
- Expect offers to disappear. External offers might be removed at any time, including when a product is no longer listed on the merchant's site, or at the request of the merchant or a rights holder. Your experience must handle IDs that stop resolving, and you must not continue to display an external offer after the API no longer returns it.
Anchor to Promoted placements for external offersPromoted placements for external offers
Promoted placements and commission aren't available for external offers.
Anchor to CoverageCoverage
External offers currently cover merchants selling to the United States.
The following search_catalog parameters don't work for external offers:
catalog.filters.ships_towith a non-US countrycatalog.filters.ships_fromcatalog.filters.availableset tofalsecatalog.filters.shopswith an external merchant IDcatalog.filters.price_tiercatalog.like
Anchor to Rich mediaRich media
Product and variant media arrays use core UCP media in 2026-04-08, 2026-08-25, and draft. These fields are part of core UCP, not Shopify extension fields. See the core UCP media schema and the 2026-04-08 media schema.
The type field identifies the media type. Known values are image, video, external_video, and model_3d. If your agent doesn't recognize a media type, then ignore that media item or use its preview and name to present it.
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 |
|---|---|---|---|
type | string | All media | Media type: image, video, external_video, or model_3d. |
url | string | All media | Resource to render: an image, a playable video file or streaming manifest, a third-party player for external_video, or a 3D model file. |
name | string | All media | Human-readable title or label that's distinct from accessibility-oriented alt_text. |
alt_text | string | All media | Accessibility text describing the media. |
width, height | integer | Images and videos | Intrinsic pixel dimensions. A rendition's dimensions are on its sources entry. |
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 | video and external_video | Video duration in seconds. |
sources | array | Images, videos, and 3D models | Alternate encodings, sizes, or formats. Not used for external_video. |
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 an image or video rendition. |
height | integer | Pixel height of an image or 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 external_video, url identifies the third-party player that your agent embeds, not the watch page:
Your agent can decline to load third-party active content because of its security, privacy, or presentation policy and use preview and name 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 for Shopify sellers in Global Catalog responses. For external sellers, refer to External variant differences.
seller.name and seller.links are part of the base UCP spec and always present for Shopify sellers in Global Catalog responses. For external sellers, refer to External variant differences.
Anchor to Example responseExample response
The following example shows a search_catalog response with Global Catalog extension fields: