Skip to main content

Global Catalog MCP

The Global Catalog MCP server enables AI agents to search and discover products across the entire Shopify ecosystem, helping buyers find products from multiple merchants.

Global Catalog MCP implements the UCP Catalog capability and its MCP binding. The names, request and response shapes of tools conform to the UCP specification.

Anchor to When to use Global Catalog MCPWhen to use Global Catalog MCP

Use Global Catalog MCP when your agent needs to discover products across multiple Shopify merchants — for example, comparison shopping, cross-merchant discovery, or recommendations not tied to a specific store. For single-store agents, use Storefront Catalog MCP.


Product discovery follows a two-step flow:

  1. Discover: Your agent finds matching products using search_catalog or lookup_catalog. search_catalog supports a text query, an image, or a set of product IDs to find similar items. lookup_catalog resolves known identifiers to their current catalog data. Results are clustered by Universal Product ID (UPID) and include offers from multiple merchants.
  2. Evaluate: Your agent calls get_product with a product or variant ID to explore available options and refine selection — for example, which colors are available in size medium — then retrieve pricing and seller checkout links for the buyer's chosen variant.

Responses can include merchant product handles on products and variants. A handle belongs to a merchant's product, not to the universal product cluster. Use the returned IDs for subsequent API calls.


Anchor to Use with the AI ToolkitUse with the AI Toolkit

The Shopify AI Toolkit installs the ucp skill, which lets agents in Cursor, Claude Code, and other compatible IDEs reach the Global Catalog by name. Ask your assistant in natural language ("find me crewneck sweaters under $50") and the skill picks the right UCP CLI command, or run ucp catalog directly in a terminal. The skill also knows when to search the global catalog and when to scope to a single merchant.

Omit --business to query the global catalog; pass --business <url> to scope a search to a single merchant's storefront.

ucp catalog search \
--set '/query=trail running shoes' \
--set /context/address_country=US \
--view :compact \
--format md
ucp catalog lookup \
--set '/ids/0=gid://shopify/ProductVariant/12345678'
ucp catalog get_product gid://shopify/p/7f3a2b8c1d9e \
--set '/selected/0={"name":"Color","label":"Black"}'

Pass a buyer-linked token to return personalized search_catalog results for a signed-in Shop customer. Request the dev.ucp.shopping.catalog.search:read scope when you create the buyer-linked token.


Pass catalog.view: "compact" to search_catalog, lookup_catalog, or get_product to omit seller policy links from the API response. Omit catalog.view for the default representation. Refer to Response views for the response behavior and how this differs from CLI presentation options.


Anchor to Filter by merchant domainFilter by merchant domain

In search_catalog, lookup_catalog, and get_product, catalog.filters.shops accepts merchant domains as well as shop GIDs. For example, use "shops": ["example-running.myshopify.com"]. You can pass up to 1000 entries, including at most 50 domains. Refer to Shop domains for URL handling and unresolved-domain behavior.


Anchor to Prices and list pricesPrices and list prices

Each variant includes price, the price the buyer pays, when a price is available. A variant can also include list_price, the merchant's compare-at price for the buyer's market. Use list_price to show a strikethrough price next to price.

list_price is returned only when both of the following are true:

  • The merchant shares compare-at prices with Shopify Catalog.
  • The variant's compare-at price is higher than its price.

Like price, list_price is in minor currency units and uses the same currency as price.


The examples use fictional products, IDs, URLs, attribution values, and delivery dates. Replace IDs and option selections with values from your own responses. Response examples show representative offers and selected optional fields, not live product listings. The JSON responses show MCP payloads before any CLI output formatting.

Use product and checkout URLs exactly as returned, including their attribution parameters. Pass pagination cursors back unchanged rather than constructing them.


The /api/ucp/mcp endpoint requires an agent profile. Every request must include a meta.ucp-agent.profile URL pointing to your agent's UCP profile. The returned tools depend on the capabilities your agent advertises.

If you host your own profile, declare both the base UCP capabilities and Shopify's extensions: the base capabilities unlock the tools, the extensions unlock Shopify's enriched fields, and an extension without its base capability is pruned in negotiation. For the Catalog, that means dev.ucp.shopping.catalog.search and dev.ucp.shopping.catalog.lookup plus dev.shopify.catalog.global (or dev.shopify.catalog on a merchant storefront). The hosted profile used in the examples below declares all of them.

UCP catalog specification

These tools conform to the Universal Commerce Protocol catalog specification. Refer to the UCP spec for the complete request/response schema.

For Shopify-specific extension fields, such as additional filters, variant fields, and inferred metadata, see Global Catalog extension.

Anchor to Inferred response fieldsInferred response fields

Some Global Catalog response fields are generated or enriched by Shopify, and are marked Inferred in the reference. 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.

FieldTagNotes
descriptionInferredProduct description generated or enriched by Shopify.
optionsInferredProduct options normalized for catalog discovery and variant selection.
metadata.attributesInferredProduct attributes such as material, style, and occasion.
metadata.tech_specsInferredTechnical specifications.
metadata.top_featuresInferredTop product features.
metadata.unique_selling_pointsInferredUnique selling propositions.
variants[].conditionInferredProduct condition labels, such as "new" or "secondhand".
POST

https://catalog.shopify.com/api/ucp/mcp

{
"jsonrpc": "2.0",
"method": "tools/list",
"id": 1,
"params": {
"arguments": {
"meta": {
"ucp-agent": {
"profile": "https://shopify.dev/ucp/agent-profiles/examples/2026-08-25/valid-with-capabilities.json"
}
}
}
}
}

Searches for products across all Shopify merchants.

The response conforms to the UCP catalog search response, including a UCP metadata envelope; products with title, description, price range (minor units), media, and variants with price and, when available, list_price.

When to use:

  • A customer asks "I'm looking for trail running shoes under $150."
  • You need to find products matching criteria from any merchant.
  • A customer wants to compare products across multiple stores.

All parameters are wrapped in a catalog object. Refer to the UCP catalog search spec for the complete schema.


catalog.query•string

Free-text search query. For example, "trail running shoes", "organic coffee beans". On version 2026-08-25, you can omit query and like to browse within a shop scope. Include at least one shop in catalog.filters.shops. Other filters alone, such as price or category, don't establish a bounded scope and return a browse_scope_required error. Version 2026-04-08 requires a query or similarity input.

A browse response includes a browse_partial message because results are a ranked subset, not a complete inventory. Don't use browsing for bulk export or inventory synchronization. For example:

{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "search_catalog",
"arguments": {
"meta": {
"ucp-agent": {
"profile": "https://shopify.dev/ucp/agent-profiles/examples/2026-08-25/valid-with-capabilities.json"
}
},
"catalog": {
"filters": {
"shops": [
"gid://shopify/Shop/987654321"
],
"price": {
"max": 15000
}
},
"context": {
"address_country": "US"
},
"pagination": {
"limit": 10
}
}
}
}
}

catalog.catalog_id•string

ID of a catalog configuration saved in the Dev Dashboard. Its filters set the request boundaries: values within them narrow the results, while values outside them fall back to the saved filters. The saved query prefix is prepended to catalog.query, combining both queries.

You can enable promoted placement for a saved catalog. Refer to Earn with promoted placements for setup, payouts, and disclosure details.


catalog.saved_catalog_slug•string

Deprecated compatibility alias for catalog.catalog_id. Use catalog.catalog_id for new integrations. If you pass both fields, then catalog.catalog_id takes precedence.


catalog.like•array

Similar item to search by. Use either an item reference or image content.

Pass both catalog.query and an image in catalog.like for 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. Pass only an image for visual similarity search, which returns items that visually resemble the image without additional text intent.


catalog.context•object

Buyer signals for relevance and localization (address_country, address_region, postal_code, language, currency, and intent).


catalog.filters.available•boolean

Filter by availability. Defaults to true (only sale-ready items). Set to false to include unavailable items.


catalog.filters.ships_to•object

Filter to products that ship to a given location. Accepts country (ISO 3166-1 alpha-2), region, and postal_code.


catalog.filters.ships_from•array

Filter by merchant origin country. Each entry accepts country (ISO 3166-1 alpha-2). Multiple entries use OR logic. Digital products that don't require shipping can still match this filter.


catalog.filters.price•object

Price range in minor currency units. Accepts min and max integers. For example, {"min": 5000, "max": 20000} = $50.00–$200.00 USD.


catalog.filters.condition•array

Product condition filter. Known values: "new", "secondhand". Multiple values use OR logic.


catalog.filters.shops•array

Filter to specific shops. Accepts an array of shop GIDs, for example gid://shopify/Shop/987654321. You can pass up to 1000 shop IDs per request.


catalog.filters.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.


catalog.filters.rating•object

Filter by variant rating. variant matches products with at least one variant whose rating meets the given thresholds. Set variant.min for the minimum rating value (0–5 scale) and variant.min_count for the minimum number of reviews. Responses can include variant ratings in variants[].rating, independently of the product-level rating.


catalog.filters.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.


catalog.filters.media•array

Filter by product media. Each entry is an object with a type field, and matches products that have at least one media item of that type. Supported types are image, video, external_video, and model_3d. video matches only Shopify-hosted videos. Use external_video for videos that are hosted on a third-party platform. Entries combine with AND logic. Unsupported types are ignored and returned in messages. For example, [{"type": "video"}, {"type": "model_3d"}] returns only products that have a video and a 3D model.


catalog.filters.categories•array

Filter by product category using taxonomy IDs. Each item accepts id (required) and taxonomy (optional, defaults to Shopify's standard taxonomy). Multiple values use OR logic.


catalog.pagination•object

Cursor-based pagination controls. Accepts cursor (string, opaque cursor from a previous response) and limit (integer, min 1, default 10, max 50). Pass the returned pagination.cursor as catalog.pagination.cursor to request the next page. The cursor preserves pagination state. Pass it unchanged; the request's limit controls the requested page size. You can paginate up to 1,000 results. Beyond that depth, has_next_page is false regardless of how many results match.

The total_count field in the response is an estimate of how many results match the query, not an exact count. Don't rely on it for precise totals or to calculate an exact number of pages.


Anchor to Call from the Shopify AI Toolkit and UCP CLICall from the Shopify AI Toolkit and UCP CLI

With the Shopify AI Toolkit installed, ask your assistant in natural language ("find trail running shoes under $150") and the ucp skill picks the right UCP CLI command. You can also run the command directly in a terminal:

Search

ucp catalog search \
--input '{
"query": "trail running shoes",
"view": "compact",
"filters": {
"shops": [
"example-running.myshopify.com",
"gid://shopify/Shop/987654321"
],
"ships_to": {
"country": "US",
"region": "NY",
"postal_code": "10001"
},
"ships_from": [
{
"country": "US"
},
{
"country": "CA"
}
],
"price": {
"max": 15000
},
"available": true,
"attributes": [
{
"name": "Color",
"values": [
"Black"
]
},
{
"name": "Size",
"values": [
"10",
"10.5"
]
}
],
"rating": {
"variant": {
"min": 4.5,
"min_count": 10
}
},
"price_tier": [
"low",
"medium"
]
},
"context": {
"address_country": "US",
"intent": "Customer runs marathons and needs road shoes"
},
"pagination": {
"limit": 1
}
}' \
--view :compact \
--format md

Anchor to Call the tool directlyCall the tool directly

POST

https://catalog.shopify.com/api/ucp/mcp

{
"jsonrpc": "2.0",
"method": "tools/call",
"id": 1,
"params": {
"name": "search_catalog",
"arguments": {
"meta": {
"ucp-agent": {
"profile": "https://shopify.dev/ucp/agent-profiles/examples/2026-08-25/valid-with-capabilities.json"
}
},
"catalog": {
"query": "trail running shoes",
"view": "compact",
"filters": {
"shops": ["example-running.myshopify.com", "gid://shopify/Shop/987654321"],
"ships_to": {"country": "US", "region": "NY", "postal_code": "10001"},
"ships_from": [{"country": "US"}, {"country": "CA"}],
"price": {"max": 15000},
"available": true,
"attributes": [
{"name": "Color", "values": ["Black"]},
{"name": "Size", "values": ["10", "10.5"]}
],
"rating": {"variant": {"min": 4.5, "min_count": 10}},
"price_tier": ["low", "medium"]
},
"context": {
"address_country": "US",
"intent": "Customer runs marathons and needs road shoes"
},
"pagination": {
"limit": 1
}
}
}
}
}
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"structuredContent": {
"ucp": {
"version": "2026-08-25",
"capabilities": {
"dev.ucp.shopping.catalog.search": [
{
"version": "2026-08-25",
"spec": "https://ucp.dev/2026-08-25/specification/shopping/catalog/",
"schema": "https://ucp.dev/2026-08-25/schemas/shopping/catalog_search.json"
}
],
"dev.ucp.shopping.catalog.lookup": [
{
"version": "2026-08-25",
"spec": "https://ucp.dev/2026-08-25/specification/shopping/catalog/",
"schema": "https://ucp.dev/2026-08-25/schemas/shopping/catalog_lookup.json"
}
],
"dev.shopify.catalog.global": [
{
"version": "2026-08-25",
"spec": "https://shopify.dev/docs/agents/catalog/global-catalog",
"schema": "https://shopify.dev/ucp/schemas/2026-08-25/shopify_catalog_global.json",
"extends": [
"dev.ucp.shopping.catalog.search",
"dev.ucp.shopping.catalog.lookup"
],
"requires": {
"protocol": {
"min": "2026-08-25"
}
}
}
]
},
"status": "success"
},
"products": [
{
"id": "gid://shopify/p/7f3a2b8c1d9e",
"handle": "trail-runner-pro",
"title": "Trail Runner Pro",
"description": {
"plain": "Lightweight trail running shoe designed for road and light trail."
},
"price_range": {
"min": {"amount": 5999, "currency": "USD"},
"max": {"amount": 5999, "currency": "USD"}
},
"media": [
{
"type": "image",
"url": "https://cdn.shopify.com/products/trail-runner-pro.jpg",
"alt_text": "Trail Runner Pro running shoes"
}
],
"options": [
{
"name": "Size",
"values": [
{"label": "8"},
{"label": "9"},
{"label": "10"},
{"label": "11"}
]
},
{
"name": "Color",
"values": [
{"label": "Black"},
{"label": "Blue"}
]
}
],
"variants": [
{
"id": "gid://shopify/ProductVariant/12345678",
"handle": "trail-runner-pro",
"title": "Trail Runner Pro",
"description": {"plain": "Lightweight trail running shoe designed for road and light trail."},
"price": {"amount": 5999, "currency": "USD"},
"list_price": {"amount": 11999, "currency": "USD"},
"url": "https://example-running.myshopify.com/products/trail-runner-pro?variant=12345678&_gsid=7f3a2b8c1d9e&utm_source=shopify&utm_medium=catalog",
"checkout_url": "https://example-running.myshopify.com/buy/12345678:1?ucp/version=2026-08-25&attribution/utm_source=shopify&attribution/utm_medium=catalog&attribution/click_id_tag=_gsid&attribution/click_id_value=7f3a2b8c1d9e&_gsid=7f3a2b8c1d9e",
"seller_product_id": "gid://shopify/Product/7654321",
"rating": {"value": 4.5, "scale_min": 1, "scale_max": 5, "count": 120},
"condition": ["new"],
"eligible": {"native_checkout": true},
"availability": {"available": true},
"options": [
{"name": "Size", "label": "10"},
{"name": "Color", "label": "Black"}
],
"seller": {
"name": "Example Running",
"id": "gid://shopify/Shop/987654321",
"domain": "example-running.myshopify.com",
"url": "https://example-running.myshopify.com"
}
}
],
"rating": {"value": 4.5, "scale_min": 1, "scale_max": 5, "count": 120}
}
],
"messages": [
{
"type": "info",
"code": "price_filter_applied",
"path": "$.filters.price",
"content": "Price filtering was applied on a USD basis; returned prices are contextualized to the buyer's market and may differ.",
"data": {
"request_currency": "USD",
"applied_usd": {
"max": 150
},
"conversion": {
"max": "native_usd"
}
}
}
],
"pagination": {
"cursor": "eyJvZmZzZXQiOjEsInRvdGFsX2NvdW50IjoxNDIsInJldHVybmVkIjoxfQ",
"has_next_page": true,
"total_count": 142
}
}
}
}

Retrieves products or variants by identifier from across all Shopify merchants.

The response includes products with inputs correlation on matched variants and not_found messages for unresolved identifiers. The UCP catalog lookup response describes the base representation. Unlike the base schema, versions 2026-04-08 and 2026-08-25 can retain unmatched sibling variants without inputs, so handle its absence. Draft omits unmatched variants. Variants include list_price when available. Refer to Prices and list prices.

When to use:

  • You have product or variant IDs from search results or deep links.
  • You need to resolve multiple identifiers in a single request.
  • You're validating cart items against current catalog data.

All parameters are wrapped in a catalog object. Refer to the UCP catalog lookup spec for the complete schema.


catalog.ids•arrayRequired

Array of product or variant identifiers (1 to 50). Accepts gid://shopify/p/{upid}, gid://shopify/Product/{id}, gid://shopify/ProductVariant/{id}, and http or https Shopify product URLs. Multiple IDs that resolve to the same universal product are grouped into a single product in the response. When a variant includes inputs, use it to correlate the result with your requested identifiers. Dated versions can also return unmatched sibling variants without this field. For external variant IDs, refer to External variant differences.


catalog.filters.ships_to•object

Filter to products that ship to a given location. Accepts country, region, and postal_code.


catalog.filters.ships_from•array

Filter by merchant origin country. Each entry accepts country (ISO 3166-1 alpha-2). Multiple entries use OR logic. Digital products that don't require shipping can still match this filter.


catalog.filters.available•boolean

Filter by availability. Defaults to true (only sale-ready items). Set to false to include unavailable items.


catalog.filters.condition•array

Product condition filter. Known values: "new", "secondhand". Multiple values use OR logic.


catalog.filters.shops•array

Filter to specific shops. Accepts an array of shop GIDs, for example gid://shopify/Shop/987654321. You can pass up to 1000 shop IDs per request.


catalog.context•object

Buyer context for localization (address_country, address_region, postal_code, language, currency, and intent).


Anchor to Call from the Shopify AI Toolkit and UCP CLICall from the Shopify AI Toolkit and UCP CLI

With the Shopify AI Toolkit installed, ask your assistant in natural language ("look up this variant") and the ucp skill picks the right UCP CLI command. You can also run the command directly in a terminal:

Lookup

ucp catalog lookup \
--input '{
"ids": [
"gid://shopify/Product/67890",
"gid://shopify/ProductVariant/87654321",
"https://example-running.myshopify.com/products/trail-runner-pro"
],
"filters": {
"ships_to": {
"country": "US",
"region": "NY",
"postal_code": "10001"
}
},
"context": {
"address_country": "US"
}
}'

Anchor to Call the tool directlyCall the tool directly

POST

https://catalog.shopify.com/api/ucp/mcp

{
"jsonrpc": "2.0",
"method": "tools/call",
"id": 1,
"params": {
"name": "lookup_catalog",
"arguments": {
"meta": {
"ucp-agent": {
"profile": "https://shopify.dev/ucp/agent-profiles/examples/2026-08-25/valid-with-capabilities.json"
}
},
"catalog": {
"ids": [
"gid://shopify/Product/67890",
"gid://shopify/ProductVariant/87654321",
"https://example-running.myshopify.com/products/trail-runner-pro"
],
"filters": {
"ships_to": {"country": "US", "region": "NY", "postal_code": "10001"}
},
"context": {
"address_country": "US"
}
}
}
}
}
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"structuredContent": {
"ucp": {
"version": "2026-08-25",
"capabilities": {
"dev.ucp.shopping.catalog.search": [
{
"version": "2026-08-25",
"spec": "https://ucp.dev/2026-08-25/specification/shopping/catalog/",
"schema": "https://ucp.dev/2026-08-25/schemas/shopping/catalog_search.json"
}
],
"dev.ucp.shopping.catalog.lookup": [
{
"version": "2026-08-25",
"spec": "https://ucp.dev/2026-08-25/specification/shopping/catalog/",
"schema": "https://ucp.dev/2026-08-25/schemas/shopping/catalog_lookup.json"
}
],
"dev.shopify.catalog.global": [
{
"version": "2026-08-25",
"spec": "https://shopify.dev/docs/agents/catalog/global-catalog",
"schema": "https://shopify.dev/ucp/schemas/2026-08-25/shopify_catalog_global.json",
"extends": [
"dev.ucp.shopping.catalog.search",
"dev.ucp.shopping.catalog.lookup"
],
"requires": {
"protocol": {
"min": "2026-08-25"
}
}
}
]
},
"status": "success"
},
"products": [
{
"id": "gid://shopify/p/7f3a2b8c1d9e",
"handle": "trail-runner-pro",
"title": "Trail Runner Pro",
"description": {
"plain": "Lightweight trail running shoe designed for road and light trail."
},
"price_range": {
"min": {"amount": 5999, "currency": "USD"},
"max": {"amount": 5999, "currency": "USD"}
},
"variants": [
{
"id": "gid://shopify/ProductVariant/12345678",
"handle": "trail-runner-pro",
"title": "Trail Runner Pro",
"description": {"plain": "Lightweight trail running shoe designed for road and light trail."},
"price": {"amount": 5999, "currency": "USD"},
"list_price": {"amount": 11999, "currency": "USD"},
"url": "https://example-running.myshopify.com/products/trail-runner-pro?variant=12345678&_gsid=8g4b3c9d2e1f&utm_source=shopify&utm_medium=catalog",
"checkout_url": "https://example-running.myshopify.com/buy/12345678:1?ucp/version=2026-08-25&attribution/utm_source=shopify&attribution/utm_medium=catalog&attribution/click_id_tag=_gsid&attribution/click_id_value=8g4b3c9d2e1f&_gsid=8g4b3c9d2e1f",
"seller_product_id": "gid://shopify/Product/7654321",
"rating": {"value": 4.5, "scale_min": 1, "scale_max": 5, "count": 120},
"condition": ["new"],
"eligible": {"native_checkout": true},
"availability": {"available": true},
"inputs": [
{"id": "gid://shopify/Product/67890", "match": "featured"},
{"id": "https://example-running.myshopify.com/products/trail-runner-pro", "match": "featured"}
],
"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"
}
]
}
}
]
}
],
"messages": [
{
"type": "info",
"code": "not_found",
"content": "gid://shopify/ProductVariant/87654321"
}
]
}
}
}

Retrieves full details for a single product with optional variant selection. Variants can also include product disclosures, such as safety warnings, when the Global Catalog extension is active and disclosure data is available.

The response conforms to the UCP catalog get_product response, including product.selected reflecting effective option selections, option values with available and exists signals, and variants matching the selection. Variants include list_price when available. Refer to Prices and list prices.

When to use:

  • A customer has selected a product and needs full details.
  • You need to show variant options with availability signals.
  • A customer is making option selections (Color, Size, and so on).

Option values can also include swatch.image_url. Use this field to display image selectors. Swatches are optional and appear only in get_product, not in search or lookup responses. Refer to Option swatches for the field reference and fallback behavior.

All parameters are wrapped in a catalog object. Refer to the UCP catalog lookup spec for the complete schema.


catalog.id•stringRequired

Product or variant identifier. Accepts gid://shopify/p/{upid}, gid://shopify/Product/{id}, or gid://shopify/ProductVariant/{id}. Use a Shopify Product GID when you know a merchant's product ID rather than its Universal Product ID. The response still uses the universal product representation. For external variant IDs, refer to External variant differences.


catalog.selected•array

Option selections for variant narrowing. For example, [{"name": "Color", "label": "Blue"}, {"name": "Size", "label": "10"}]. The response reflects these selections in product.selected and filters the returned variants accordingly.


catalog.preferences•array

Option names in relaxation priority order. When an exact match isn't available, options are dropped from the end of this list first. For example, ["Color", "Size"] drops Size before Color.


catalog.filters.ships_to•object

Filter to products that ship to a given location. Accepts country, region, and postal_code.


catalog.filters.ships_from•array

Filter by merchant origin country. Each entry accepts country (ISO 3166-1 alpha-2). Multiple entries use OR logic. Digital products that don't require shipping can still match this filter.


catalog.filters.available•boolean

Filter by availability. Defaults to true (only sale-ready items). Set to false to include unavailable items.


catalog.filters.condition•array

Product condition filter. Known values: "new", "secondhand". Multiple values use OR logic.


catalog.filters.shops•array

Filter to specific shops. Accepts an array of shop GIDs, for example gid://shopify/Shop/987654321. You can pass up to 1000 shop IDs per request.


catalog.context•object

Buyer context for localization (address_country, address_region, postal_code, language, currency, and intent).


Anchor to Call from the Shopify AI Toolkit and UCP CLICall from the Shopify AI Toolkit and UCP CLI

With the Shopify AI Toolkit installed, ask your assistant in natural language ("show me this product in black") and the ucp skill picks the right UCP CLI command. You can also run the command directly in a terminal:

Get product

ucp catalog get_product gid://shopify/Product/67890 \
--input '{
"selected": [
{
"name": "Color",
"label": "Black"
}
],
"filters": {
"ships_to": {
"country": "US",
"region": "NY",
"postal_code": "10001"
}
},
"context": {
"address_country": "US"
}
}'

Anchor to Call the tool directlyCall the tool directly

POST

https://catalog.shopify.com/api/ucp/mcp

{
"jsonrpc": "2.0",
"method": "tools/call",
"id": 1,
"params": {
"name": "get_product",
"arguments": {
"meta": {
"ucp-agent": {
"profile": "https://shopify.dev/ucp/agent-profiles/examples/2026-08-25/valid-with-capabilities.json"
}
},
"catalog": {
"id": "gid://shopify/Product/67890",
"selected": [
{"name": "Color", "label": "Black"}
],
"filters": {
"ships_to": {"country": "US", "region": "NY", "postal_code": "10001"}
},
"context": {
"address_country": "US"
}
}
}
}
}
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"structuredContent": {
"ucp": {
"version": "2026-08-25",
"capabilities": {
"dev.ucp.shopping.catalog.search": [
{
"version": "2026-08-25",
"spec": "https://ucp.dev/2026-08-25/specification/shopping/catalog/",
"schema": "https://ucp.dev/2026-08-25/schemas/shopping/catalog_search.json"
}
],
"dev.ucp.shopping.catalog.lookup": [
{
"version": "2026-08-25",
"spec": "https://ucp.dev/2026-08-25/specification/shopping/catalog/",
"schema": "https://ucp.dev/2026-08-25/schemas/shopping/catalog_lookup.json"
}
],
"dev.shopify.catalog.global": [
{
"version": "2026-08-25",
"spec": "https://shopify.dev/docs/agents/catalog/global-catalog",
"schema": "https://shopify.dev/ucp/schemas/2026-08-25/shopify_catalog_global.json",
"extends": [
"dev.ucp.shopping.catalog.search",
"dev.ucp.shopping.catalog.lookup"
],
"requires": {
"protocol": {
"min": "2026-08-25"
}
}
}
]
},
"status": "success"
},
"product": {
"id": "gid://shopify/p/7f3a2b8c1d9e",
"handle": "trail-runner-pro",
"title": "Trail Runner Pro",
"description": {
"plain": "Lightweight trail running shoe designed for road and light trail."
},
"price_range": {
"min": {"amount": 5999, "currency": "USD"},
"max": {"amount": 5999, "currency": "USD"}
},
"media": [
{
"type": "image",
"url": "https://cdn.shopify.com/products/trail-runner-pro-black.jpg",
"alt_text": "Trail Runner Pro in Black"
}
],
"options": [
{
"name": "Color",
"values": [
{"label": "Black", "available": true, "exists": true, "swatch": {"image_url": "https://cdn.example.com/products/black-swatch.png"}},
{"label": "Blue", "available": true, "exists": true}
]
},
{
"name": "Size",
"values": [
{"label": "8", "available": true, "exists": true},
{"label": "9", "available": true, "exists": true},
{"label": "10", "available": true, "exists": true},
{"label": "11", "available": false, "exists": true},
{"label": "12", "available": true, "exists": true}
]
}
],
"selected": [
{"name": "Color", "label": "Black"}
],
"variants": [
{
"id": "gid://shopify/ProductVariant/12345678",
"handle": "trail-runner-pro",
"title": "Trail Runner Pro",
"description": {"plain": "Lightweight trail running shoe designed for road and light trail."},
"disclosures": [
{
"type": "custom",
"title": "Material notice",
"content": "Contains natural rubber latex.",
"jurisdictions": [
"US"
]
}
],
"price": {"amount": 5999, "currency": "USD"},
"list_price": {"amount": 11999, "currency": "USD"},
"url": "https://example-running.myshopify.com/products/trail-runner-pro?variant=12345678&_gsid=9h5c4d2e3f6g&utm_source=shopify&utm_medium=catalog",
"checkout_url": "https://example-running.myshopify.com/buy/12345678:1?ucp/version=2026-08-25&attribution/utm_source=shopify&attribution/utm_medium=catalog&attribution/click_id_tag=_gsid&attribution/click_id_value=9h5c4d2e3f6g&_gsid=9h5c4d2e3f6g",
"seller_product_id": "gid://shopify/Product/7654321",
"rating": {"value": 4.5, "scale_min": 1, "scale_max": 5, "count": 120},
"condition": ["new"],
"eligible": {"native_checkout": true},
"availability": {"available": true},
"options": [
{"name": "Color", "label": "Black"},
{"name": "Size", "label": "10"}
],
"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"
}
]
}
}
],
"rating": {
"value": 4.5,
"scale_min": 1,
"scale_max": 5,
"count": 120
}
}
}
}
}

Was this page helpful?