Skip to main content

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:

FieldTypeDefaultDescription
availablebooleantrueWhen true (default), only sale-ready items are returned. Set to false to include unavailable items.
conditionarray—Product condition filter. Known values: "new", "secondhand". Multiple values use OR logic. Absent means no condition filter.
ships_toobject—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_fromobject—Filter by merchant origin country. Accepts country (required, ISO 3166-1 alpha-2).

search_catalog also accepts these additional filters:

FilterTypeDefaultDescription
shop_idsarray—Restrict results to specific shops by GID.
categoriesarray—Filter by product category. Each item is a taxonomy category GID (for example, "gid://shopify/TaxonomyCategory/123"). Multiple values use OR logic.
{
"catalog": {
"query": "running shoes",
"filters": {
"available": true,
"condition": ["new"],
"ships_to": {"country": "US"},
"ships_from": {"country": "US"}
}
}
}

Anchor to Similarity searchSimilarity search

Use catalog.like in a search_catalog request to find products similar to a reference product or image. Pass 1–2 items, each as one of:

  • Item Reference: A product or variant GID: {"id": "gid://shopify/p/..."}.
  • Image Content: A base64-encoded image with its MIME type: {"image": {"content_type": "image/jpeg", "data": "<base64>"}}.

You can combine like with query in a single request to narrow similarity results by keyword:

{
"catalog": {
"query": "trail running shoes",
"like": [
{"id": "gid://shopify/p/7f3a2b8c1d9e"}
],
"filters": {
"ships_to": {"country": "US"}
}
}
}

Anchor to Product fieldsProduct fields

All three tool responses include these additional fields on each product:

FieldTypeDescription
metadata.attributesArray[Attribute]ML-inferred product attributes such as material, style, and occasion.
metadata.tech_specsArray[string]ML-inferred technical specifications.
metadata.top_featuresArray[string]ML-inferred top product features.
metadata.unique_selling_pointsArray[string]ML-inferred unique selling propositions.

Anchor to AttributesAttributes

Each attribute object contains:

FieldTypeDescription
namestringAttribute name (for example, "Material", "Style").
valuestringAttribute value (for example, "Cotton", "Casual").

Anchor to Variant fieldsVariant fields

Variants include checkout URLs, purchase requirements, inventory signals, and seller identity:

FieldTypeDescription
checkout_urlstringDirect checkout URL for this variant.
requires.shippingbooleanWhether a shipping address is needed. When false, checkout can skip address collection.
requires.componentsbooleanWhether the variant requires bundle components. When true, the variant can only be purchased as a parent bundle.
conditionArray[string]Product condition labels for this variant. Known values: "new", "secondhand".
eligible.native_checkoutbooleanWhether this variant supports native (non-redirect) checkout. Default false.
availability.running_lowbooleanWhether inventory is limited. Only meaningful when available is true.
seller.idstringThe shop GID.
seller.urlstringThe storefront URL.
seller.domainstringThe primary domain of the shop.
Info

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:

{
"result": {
"structuredContent": {
"ucp": {
"version": "2026-04-08",
"capabilities": {
"dev.ucp.shopping.catalog.search": [{"version": "2026-04-08"}],
"dev.shopify.catalog.global": [{"version": "2026-04-08"}]
}
},
"products": [
{
"id": "gid://shopify/p/7f3a2b8c1d9e",
"title": "Trail Runner Pro",
"description": {"html": "<p>Lightweight trail running shoe for road and light trail.</p>"},
"price_range": {
"min": {"amount": 8999, "currency": "USD"},
"max": {"amount": 12999, "currency": "USD"}
},
"metadata": {
"attributes": [
{"name": "Material", "value": "Mesh"},
{"name": "Style", "value": "Athletic"}
],
"top_features": ["Lightweight", "Breathable mesh upper", "Cushioned sole"],
"unique_selling_points": ["Designed for road and light trail", "Responsive foam midsole"]
},
"variants": [
{
"id": "gid://shopify/ProductVariant/12345678",
"title": "Black / Size 10",
"price": {"amount": 8999, "currency": "USD"},
"checkout_url": "https://example-running.myshopify.com/cart/12345678:1",
"condition": ["new"],
"eligible": {"native_checkout": true},
"availability": {
"available": true,
"status": "in_stock",
"running_low": false
},
"requires": {"shipping": true, "selling_plan": false, "components": false},
"seller": {
"name": "Example Running",
"id": "gid://shopify/Shop/987654321",
"domain": "example-running.myshopify.com",
"url": "https://example-running.myshopify.com",
"links": [
{"type": "refund_policy", "url": "https://example-running.myshopify.com/policies/refunds"}
]
}
}
]
}
]
}
}
}
Was this page helpful?