--- title: About Shopify Catalog description: >- Search and discover products across the global Shopify ecosystem using Catalog APIs. source_url: html: 'https://shopify.dev/docs/agents/catalog' md: 'https://shopify.dev/docs/agents/catalog.md' --- # About Shopify Catalog Shopify Catalog is a global index of products from merchants across the Shopify platform. Your AI agent queries it to help buyers discover and compare products, then routes them to a merchant checkout to finish their purchase. The Catalog interfaces implement the Discovery capabilities of the [Universal Commerce Protocol (UCP)](https://ucp.dev/documentation/core-concepts/), the open standard for agentic commerce. **Catalog capability in UCP:** Shopify's Catalog MCP is evolving toward the UCP spec [Catalog capability](https://ucp.dev/latest/specification/catalog/) and [MCP binding](https://ucp.dev/latest/specification/catalog/mcp/). Tool names, request and response shapes differ, so follow this documentation to build with Catalog on Shopify. ![Sequence diagram showing AI chat user asking for running shoes, AI partner querying Shopify Catalog, and redirecting to merchant checkout](https://shopify.dev/assets/assets/images/agents/agent-light-icons-C5jZgSSt.png) *** ## How it works Product discovery follows a two-step flow: 1. **Search**: Your agent queries Catalog based on buyer preferences (keywords, price, location) and receives a list of matching products clustered by Universal Product ID (UPID). 2. **Lookup**: Your agent uses the UPID or variant ID to retrieve full product details, then renders a product detail page where buyers can explore options and add to cart. *** ## Available interfaces Catalog supports three interfaces: * **[Catalog MCP](https://shopify.dev/docs/agents/catalog/mcp)**: For most use cases. Provides tools for searching across all Shopify products and retrieving individual product details. Requires [authentication via JWT tokens](https://shopify.dev/docs/agents/get-started/authentication). * **[Storefront MCP](https://shopify.dev/docs/agents/catalog/storefront-mcp)**: Scopes product search to a single merchant store. Useful for managing rate limits or when your agent serves one shop. No authentication required. * **[Catalog REST API](https://shopify.dev/docs/api/catalog-api)**: The underlying REST API that Catalog MCP wraps. Query it directly if you need lower-level access. *** ## Search Use Search to find products across eligible Shopify merchants based on buyer preferences like keywords, price range, and shipping location. For each integration path, search is performed with: * **Catalog MCP**: The [`search_global_products`](https://shopify.dev/docs/agents/catalog/mcp#search_global_products) tool * **Storefront MCP**: The [`search_shop_catalog`](https://shopify.dev/docs/agents/catalog/storefront-mcp#search_shop_catalog) tool * **Catalog REST API**: The [`Search`](https://shopify.dev/docs/api/catalog-api/search) endpoint Search results are clustered by UPID, which prevents duplicate products when the same item is sold by multiple merchants. Each result includes: * Product details (title, description, images) * Price range across all offers * Available options (size, color, and so on) * A list of shops selling the product with their specific prices and checkout URLs * The UPID, used with Lookup to retrieve full product data ## Search response ##### Catalog MCP ```json { "offers": [ { "id": "gid://shopify/p/abc123def456", "title": "Organic Cotton Crewneck Sweater", "priceRange": { "min": { "amount": "89.00", "currencyCode": "USD" }, "max": { "amount": "89.00", "currencyCode": "USD" } }, "options": [ { "name": "Size", "values": [ { "value": "S", "availableForSale": true }, { "value": "M", "availableForSale": true } ] } ], "products": [ { "checkoutUrl": "https://ecowear-example.myshopify.com/cart/11111111111:1?payment=shop_pay", "price": { "amount": "89.00", "currencyCode": "USD" }, "shop": { "name": "EcoWear", "onlineStoreUrl": "https://ecowear-example.myshopify.com" } } ], "availableForSale": true, "rating": { "value": 4.8, "count": 124 } } ] } ``` ##### Catalog REST API ```json [ { "id": "gid://shopify/p/abc123XYZ789defGHI456jk", "title": "Classic Crewneck Sweatshirt", "priceRange": { "min": { "amount": "45.00", "currency": "USD" }, "max": { "amount": "55.00", "currency": "USD" } }, "options": [ { "name": "Color", "values": [{ "value": "Heather Gray" }] }, { "name": "Size", "values": [{ "value": "Medium" }] } ], "variants": [ { "id": "gid://shopify/ProductVariant/2000000000001?shop=10000000001", "availableForSale": true, "price": { "amount": "45.00", "currency": "USD" }, "checkoutUrl": "https://mock.shop/cart/2000000000001:1?payment=shop_pay", "shop": { "name": "Mock Shop", "onlineStoreUrl": "https://mock.shop" } } ], "lookupUrl": "https://discover.shopifyapps.com/global/v2/p/abc123XYZ789defGHI456jk", "rating": { "rating": 4.5, "count": 128 } } ] ``` *** ## Lookup Use UPIDs and variant IDs from Search results to retrieve full product details and render product detail pages where buyers can explore options before adding to cart. For each integration path, lookup is performed with: * **Catalog MCP**: The [`get_global_product_details`](https://shopify.dev/docs/agents/catalog/mcp#get_global_product_details) tool * **Catalog REST API**: The [`Lookup`](https://shopify.dev/docs/api/catalog-api/lookup) and [`Lookup by variant`](https://shopify.dev/docs/api/catalog-api/lookup-by-variant) endpoints Storefront MCP doesn't support Lookup. Use Catalog MCP or the Catalog REST API for product detail retrieval. Lookup includes relaxation logic for available option combinations via [option preferences](https://shopify.dev/docs/api/catalog-api/lookup#examples), which helps your agent handle cases where a buyer's exact variant isn't available. The Lookup endpoint returns: * All available product options and option combinations * Detailed pricing for each variant * Checkout URLs for each shop's offer * Product description, key features, and tech specs to support agent-to-buyer conversations ## Lookup response ##### Catalog MCP ```json { "product": { "id": "gid://shopify/p/xyz789abc123", "title": "Organic Cotton Crewneck Sweater", "options": [ { "name": "Size", "values": [ { "value": "S", "availableForSale": true, "exists": true }, { "value": "M", "availableForSale": true, "exists": true }, { "value": "L", "availableForSale": true, "exists": true } ] } ], "products": [ { "checkoutUrl": "https://ecowear-example.myshopify.com/cart/11111111111:1?payment=shop_pay", "price": { "amount": "89.00", "currencyCode": "USD" }, "shop": { "name": "EcoWear" }, "selectedProductVariant": { "id": "gid://shopify/ProductVariant/11111111111?shop=1111111111", "availableForSale": true, "options": [{ "name": "Size", "value": "M" }] } } ], "topFeatures": ["100% organic cotton", "Relaxed fit", "GOTS certified"], "techSpecs": ["Material: 100% Organic Cotton", "Fit: Relaxed"] } } ``` ##### Catalog REST API ```json { "id": "gid://shopify/p/abc123XYZ789defGHI456jk", "description": "A comfortable everyday sweatshirt with a classic fit.", "options": [ { "name": "Color", "values": [{ "value": "Heather Gray", "availableForSale": true, "exists": true }] }, { "name": "Size", "values": [{ "value": "Medium", "availableForSale": true, "exists": true }] } ], "variants": [ { "id": "gid://shopify/ProductVariant/2000000000001?shop=10000000001", "availableForSale": true, "price": { "amount": "45.00", "currency": "USD" }, "checkoutUrl": "https://mock.shop/cart/2000000000001:1?payment=shop_pay", "shop": { "name": "Mock Shop", "onlineStoreUrl": "https://mock.shop" } } ], "topFeatures": ["50/50 cotton polyester blend", "Classic crewneck design"], "techSpecs": ["Weight: 8.0 oz", "Material: 50% cotton, 50% polyester"] } ``` *** ## Usage guidelines These guidelines apply to both the Catalog MCP server and the Catalog API: * **Don't cache or re-use images**: Images may only be used in connection with the related merchant's product listing and must be rendered in real-time (not downloaded to servers). * **Don't cache search results**: Catalog results reflect merchant preferences on pricing, availability, and presentation. Caching results isn't allowed. * **Rate limits**: Catalog queries are subject to rate limits. You can request a rate limit increase under your API key's settings in Dev Dashboard. * **Inferred fields**: Some fields might be inferred by Shopify's AI and might not always be present or have varying accuracy depending on available product data. Inferred fields are marked throughout the Catalog MCP and API reference docs with the `Inferred` label. * **Endpoint URLs may change**: API URLs are subject to change. *** ## Saved Catalogs By default, Catalog queries return products from any eligible merchant on the Shopify platform. You can narrow these results at runtime using parameters like price range, shipping origin, shops, or product taxonomies. If your agent consistently uses the same parameters, then you can save a Catalog configuration in the Dev Dashboard to avoid repeating them on every request. ![Dev Dashboard Catalog create + overrides](https://shopify.dev/assets/assets/images/agents/catalog-new-DcNg4hGB.png) Catalog filter options include: * **Inputs**: Whether the Catalog queries all of Shopify or products from a specific store. * **Overrides**: Custom filters applied to queries that limit results by attributes like only those belonging to certain Taxonomy category IDs. * **Access**: Where the custom URL for your saved Catalog can be retrieved, as well as requesting access to additional features related to agentic commerce. You can test your catalog configuration in the **Preview** panel. After you're happy with the results, click **Save**. If a slug for a saved catalog is provided in Catalog Search operations, then its parameters and filters always take precedence. *** ## Next steps [Search the Catalog\ \ ](https://shopify.dev/docs/agents/get-started/search-catalog) [Walk through product discovery end-to-end.](https://shopify.dev/docs/agents/get-started/search-catalog) [Catalog MCP reference\ \ ](https://shopify.dev/docs/agents/catalog/mcp) [Reference for UCP-compliant product discovery on Shopify.](https://shopify.dev/docs/agents/catalog/mcp) [Catalog REST API\ \ ](https://shopify.dev/docs/api/catalog-api) [Query the Catalog API directly.](https://shopify.dev/docs/api/catalog-api) [Storefront MCP\ \ ](https://shopify.dev/docs/agents/catalog/storefront-mcp) [Search products scoped to individual merchant stores.](https://shopify.dev/docs/agents/catalog/storefront-mcp) ***