--- title: Discover products with Shopify Catalog description: >- Learn how to search for products across the global Shopify Catalog using the MCP server. source_url: html: 'https://shopify.dev/docs/agents/get-started/search-catalog' md: 'https://shopify.dev/docs/agents/get-started/search-catalog.md' --- ExpandOn this page * [What you'll learn](https://shopify.dev/docs/agents/get-started/search-catalog.md#what-youll-learn) * [Requirements](https://shopify.dev/docs/agents/get-started/search-catalog.md#requirements) * [Step 1: Create a custom catalog](https://shopify.dev/docs/agents/get-started/search-catalog.md#step-1-create-a-custom-catalog) * [Step 2: Search the Catalog](https://shopify.dev/docs/agents/get-started/search-catalog.md#step-2-search-the-catalog) * [Step 3: Apply query parameters](https://shopify.dev/docs/agents/get-started/search-catalog.md#step-3-apply-query-parameters) * [Step 4: Lookup product details](https://shopify.dev/docs/agents/get-started/search-catalog.md#step-4-lookup-product-details) * [Next steps](https://shopify.dev/docs/agents/get-started/search-catalog.md#next-steps) # Discover products with Shopify Catalog Shopify Catalog contains all eligible products sold across merchants on the Shopify platform, serving as a powerful implementation of product discovery in [UCP](https://ucp.dev/documentation/core-concepts/). You can use the Catalog MCP server to search for products and retrieve detailed product information for your AI agent. This tutorial shows you how to authenticate with the Catalog MCP server, search for products, and apply filters to refine results. In the end you will arrive at a single selected product variant chosen by a buyer. *** ## What you'll learn In this tutorial, you'll learn to: * Search for products across the global Shopify Catalog using natural language queries * Apply filters and parameters to refine product search results * Extract product variant IDs and shop domains for checkout *** ## Requirements * [An access token](https://shopify.dev/docs/agents/get-started/authentication) * [Node.js](https://nodejs.org/) installed on your development machine *** ## Step 1: Create a custom catalog First, you need to create a catalog. Catalogs can allow agents to discover products across the entire Shopify platform, or some subset of more relevant filtered results, depending on the needs of your buyers. 1. In [Dev Dashboard](https://dev.shopify.com/dashboard/) click **Catalogs** from the sidebar. 2. Click **Create a catalog**. 3. The resulting screen provides many different options and overrides for the catalog. For now keep the defaults, which place no bounds on the price of results dicovered across all of Shopify's products. ![Diagram showing cart groups flowing to Checkout Kit presentations](https://shopify.dev/assets/assets/images/agents/catalog-with-overrides-ucp-CzDyhJ1m.png) 4. Click **Save catalog** in the top right hand corner. 5. When you return to the **Catalogs** landing page, click to **Copy URL**. It will have the form `https://discover.shopifyapps.com/global/v1/search/{your_catalog_id}`. You can use this URL directly with the Catalog REST API, or the `your_catalog_id` as shown below when making tool calls. 6. Add your `your_catalog_id` to the `.env` file you previously created: ## .env ```bash BEARER_TOKEN={your_token} CATALOG_ID={your_catalog_id} ``` Sensitive variables Do not commit this file. *** ## Step 2: Search the Catalog Next, create a script to search your new catalog using the [Catalog MCP server](https://shopify.dev/docs/agents/catalog/catalog-mcp) with the [`search_global_products`](https://shopify.dev/docs/agents/catalog/catalog-mcp#search_global_products) tool: 1. Create a `search-catalog.js` file that sends a query to the Catalog MCP server: ##### search-catalog.js ```javascript import 'dotenv/config'; const bearerToken = process.env.BEARER_TOKEN; let catalogId = process.env.CATALOG_ID; fetch('https://discover.shopifyapps.com/global/mcp', { method: 'POST', headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${bearerToken}` }, body: JSON.stringify({ jsonrpc: '2.0', method: 'tools/call', id: 1, params: { name: 'search_global_products', arguments: { saved_catalog: catalogId, query: 'I need a crewneck sweater', context: 'buyer looking for sustainable fashion', limit: 3 } } }) }) .then(res => res.json()) .then(data => { if (data && data.result?.content?.[0]?.text) { // Parse the stringified text field data.result.content[0].text = JSON.parse(data.result.content[0].text); } if (data) { console.log(JSON.stringify(data, null, 2)); } }) .catch(err => console.error('Request failed:', err)); ``` ##### {} MCP input reference ```json { "jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": { "name": "search_global_products", "arguments": { "saved_catalog": "", "query": "I need a crewneck sweater", "context": "buyer looking for sustainable fashion", "limit": 3 } } } ``` ##### {} Response ```json { "jsonrpc": "2.0", "id": 1, "result": { "content": [ { "type": "text", "text": { "offers": [ { "id": "gid://shopify/p/abc123def456", "title": "Organic Cotton Crewneck Sweater", "description": "A sustainably made crewneck sweater crafted from 100% organic cotton with a relaxed fit.", "images": [ { "url": "https://cdn.shopify.com/s/files/example/organic-cotton-crewneck.jpg", "altText": "Organic Cotton Crewneck Sweater - EcoWear", "product": { "id": "gid://shopify/Product/1234567890", "title": "Organic Cotton Crewneck Sweater", "onlineStoreUrl": "https://ecowear-example.myshopify.com/products/organic-cotton-crewneck?variant=11111111111&_gsid=example123", "shop": { "name": "EcoWear", "onlineStoreUrl": "https://ecowear-example.myshopify.com" } } } ], "options": [ { "name": "Size", "values": [ { "value": "S", "availableForSale": true, "exists": true }, { "value": "M", "availableForSale": true, "exists": true }, { "value": "L", "availableForSale": true, "exists": true } ] }, { "name": "Color", "values": [ { "value": "Oatmeal", "availableForSale": true, "exists": true }, { "value": "Forest Green", "availableForSale": true, "exists": true } ] } ], "priceRange": { "min": { "amount": "89.00", "currencyCode": "USD" }, "max": { "amount": "89.00", "currencyCode": "USD" } }, "products": [ { "id": "gid://shopify/Product/1234567890", "title": "Organic Cotton Crewneck Sweater", "checkoutUrl": "https://ecowear-example.myshopify.com/cart/11111111111:1?_gsid=example123&payment=shop_pay", "description": "A sustainably made crewneck sweater crafted from 100% organic cotton. Features a relaxed fit and ribbed cuffs.", "featuredImage": { "url": "https://cdn.shopify.com/s/files/example/organic-cotton-crewneck.jpg", "altText": "Organic Cotton Crewneck Sweater - EcoWear" }, "onlineStoreUrl": "https://ecowear-example.myshopify.com/products/organic-cotton-crewneck?variant=11111111111&_gsid=example123", "price": { "amount": "89.00", "currencyCode": "USD" }, "rating": { "value": 4.8, "count": 124 }, "availableForSale": true, "shop": { "name": "EcoWear", "paymentSettings": { "supportedDigitalWallets": ["SHOPIFY_PAY"], "acceptedCardBrands": ["visa", "master", "american_express"] }, "onlineStoreUrl": "https://ecowear-example.myshopify.com", "privacyPolicy": { "url": "https://ecowear-example.myshopify.com/policies/privacy" }, "refundPolicy": { "url": "https://ecowear-example.myshopify.com/policies/refund" }, "termsOfService": { "url": "https://ecowear-example.myshopify.com/policies/terms" }, "shippingPolicy": { "url": "https://ecowear-example.myshopify.com/policies/shipping" }, "id": "gid://shopify/Shop/1111111111" }, "selectedProductVariant": { "id": "gid://shopify/ProductVariant/11111111111?shop=1111111111", "availableForSale": true, "options": [ { "name": "Size", "value": "M" }, { "name": "Color", "value": "Oatmeal" } ], "price": { "amount": "89.00", "currencyCode": "USD" }, "image": { "url": "https://cdn.shopify.com/s/files/example/organic-cotton-crewneck.jpg", "altText": "Organic Cotton Crewneck Sweater - EcoWear" } }, "secondhand": false, "requiresSellingPlan": false } ], "availableForSale": true, "rating": { "value": 4.8, "count": 124 }, "uniqueSellingPoint": "Made from 100% GOTS-certified organic cotton with carbon-neutral shipping.", "topFeatures": [ "100% organic cotton for breathable comfort", "Relaxed fit with ribbed cuffs and hem", "GOTS certified sustainable production", "Pre-washed for softness", "Classic crewneck design" ], "techSpecs": [ "Material: 100% Organic Cotton", "Fit: Relaxed", "Neckline: Crew", "Care: Machine wash cold" ], "sharedAttributes": [ { "name": "Fabric", "values": ["Cotton", "Organic"] }, { "name": "Neckline", "values": ["Crew"] }, { "name": "Target gender", "values": ["Unisex"] }, { "name": "Pattern", "values": ["Solid"] } ], "url": "https://discover.shopifyapps.com/global/v1/p/abc123def456?_gsid=example123" }, { "id": "gid://shopify/p/xyz789ghi012", "title": "Recycled Wool Blend Crewneck", "description": "A warm crewneck sweater made from recycled wool blend, perfect for layering.", "images": [ { "url": "https://cdn.shopify.com/s/files/example/recycled-wool-crewneck.jpg", "altText": "Recycled Wool Blend Crewneck - GreenThreads", "product": { "id": "gid://shopify/Product/2345678901", "title": "Recycled Wool Blend Crewneck", "onlineStoreUrl": "https://greenthreads-example.myshopify.com/products/recycled-wool-crewneck?variant=22222222222&_gsid=example123", "shop": { "name": "GreenThreads", "onlineStoreUrl": "https://greenthreads-example.myshopify.com" } } } ], "options": [ { "name": "Size", "values": [ { "value": "XS", "availableForSale": true, "exists": true }, { "value": "S", "availableForSale": true, "exists": true }, { "value": "M", "availableForSale": false, "exists": true }, { "value": "L", "availableForSale": true, "exists": true } ] } ], "priceRange": { "min": { "amount": "125.00", "currencyCode": "USD" }, "max": { "amount": "125.00", "currencyCode": "USD" } }, "products": [ { "id": "gid://shopify/Product/2345678901", "title": "Recycled Wool Blend Crewneck", "checkoutUrl": "https://greenthreads-example.myshopify.com/cart/22222222222:1?_gsid=example123&payment=shop_pay", "description": "A cozy crewneck made from 70% recycled wool and 30% organic cotton. Ethically produced with minimal environmental impact.", "featuredImage": { "url": "https://cdn.shopify.com/s/files/example/recycled-wool-crewneck.jpg", "altText": "Recycled Wool Blend Crewneck - GreenThreads" }, "onlineStoreUrl": "https://greenthreads-example.myshopify.com/products/recycled-wool-crewneck?variant=22222222222&_gsid=example123", "price": { "amount": "125.00", "currencyCode": "USD" }, "rating": { "value": 4.6, "count": 89 }, "availableForSale": true, "shop": { "name": "GreenThreads", "paymentSettings": { "supportedDigitalWallets": ["SHOPIFY_PAY"], "acceptedCardBrands": ["visa", "master", "american_express", "discover"] }, "onlineStoreUrl": "https://greenthreads-example.myshopify.com", "privacyPolicy": { "url": "https://greenthreads-example.myshopify.com/policies/privacy" }, "refundPolicy": { "url": "https://greenthreads-example.myshopify.com/policies/refund" }, "termsOfService": { "url": "https://greenthreads-example.myshopify.com/policies/terms" }, "shippingPolicy": { "url": "https://greenthreads-example.myshopify.com/policies/shipping" }, "id": "gid://shopify/Shop/2222222222" }, "selectedProductVariant": { "id": "gid://shopify/ProductVariant/22222222222?shop=2222222222", "availableForSale": true, "options": [ { "name": "Size", "value": "S" } ], "price": { "amount": "125.00", "currencyCode": "USD" }, "image": { "url": "https://cdn.shopify.com/s/files/example/recycled-wool-crewneck.jpg", "altText": "Recycled Wool Blend Crewneck - GreenThreads" } }, "secondhand": false, "requiresSellingPlan": false } ], "availableForSale": true, "rating": { "value": 4.6, "count": 89 }, "uniqueSellingPoint": "Made from 70% recycled wool sourced from post-consumer garments.", "topFeatures": [ "70% recycled wool, 30% organic cotton blend", "Warm and breathable for layering", "Ethically produced in small batches", "Classic fit with dropped shoulders", "Naturally temperature-regulating" ], "techSpecs": [ "Material: 70% Recycled Wool, 30% Organic Cotton", "Fit: Classic", "Neckline: Crew", "Care: Hand wash or dry clean" ], "sharedAttributes": [ { "name": "Fabric", "values": ["Wool", "Cotton", "Recycled"] }, { "name": "Neckline", "values": ["Crew"] }, { "name": "Target gender", "values": ["Female"] }, { "name": "Pattern", "values": ["Solid"] } ], "url": "https://discover.shopifyapps.com/global/v1/p/xyz789ghi012?_gsid=example123" }, { "id": "gid://shopify/p/mno345pqr678", "title": "Hemp Cotton Oversized Crewneck", "description": "An oversized crewneck sweater made from a sustainable hemp-cotton blend with a soft, lived-in feel.", "images": [ { "url": "https://cdn.shopify.com/s/files/example/hemp-cotton-crewneck.jpg", "altText": "Hemp Cotton Oversized Crewneck - Sustainable Basics", "product": { "id": "gid://shopify/Product/3456789012", "title": "Hemp Cotton Oversized Crewneck", "onlineStoreUrl": "https://sustainable-basics-example.myshopify.com/products/hemp-cotton-crewneck?variant=33333333333&_gsid=example123", "shop": { "name": "Sustainable Basics", "onlineStoreUrl": "https://sustainable-basics-example.myshopify.com" } } } ], "options": [ { "name": "Size", "values": [ { "value": "S", "availableForSale": true, "exists": true }, { "value": "M", "availableForSale": true, "exists": true }, { "value": "L", "availableForSale": true, "exists": true }, { "value": "XL", "availableForSale": true, "exists": true } ] }, { "name": "Color", "values": [ { "value": "Natural", "availableForSale": true, "exists": true }, { "value": "Slate", "availableForSale": true, "exists": true }, { "value": "Terracotta", "availableForSale": true, "exists": true } ] } ], "priceRange": { "min": { "amount": "68.00", "currencyCode": "USD" }, "max": { "amount": "68.00", "currencyCode": "USD" } }, "products": [ { "id": "gid://shopify/Product/3456789012", "title": "Hemp Cotton Oversized Crewneck", "checkoutUrl": "https://sustainable-basics-example.myshopify.com/cart/33333333333:1?_gsid=example123&payment=shop_pay", "description": "A relaxed oversized crewneck made from 55% hemp and 45% organic cotton. Hemp requires minimal water and no pesticides to grow.", "featuredImage": { "url": "https://cdn.shopify.com/s/files/example/hemp-cotton-crewneck.jpg", "altText": "Hemp Cotton Oversized Crewneck - Sustainable Basics" }, "onlineStoreUrl": "https://sustainable-basics-example.myshopify.com/products/hemp-cotton-crewneck?variant=33333333333&_gsid=example123", "price": { "amount": "68.00", "currencyCode": "USD" }, "rating": { "value": 4.9, "count": 256 }, "availableForSale": true, "shop": { "name": "Sustainable Basics", "paymentSettings": { "supportedDigitalWallets": ["SHOPIFY_PAY"], "acceptedCardBrands": ["visa", "master", "american_express"] }, "onlineStoreUrl": "https://sustainable-basics-example.myshopify.com", "privacyPolicy": { "url": "https://sustainable-basics-example.myshopify.com/policies/privacy" }, "refundPolicy": { "url": "https://sustainable-basics-example.myshopify.com/policies/refund" }, "termsOfService": { "url": "https://sustainable-basics-example.myshopify.com/policies/terms" }, "shippingPolicy": { "url": "https://sustainable-basics-example.myshopify.com/policies/shipping" }, "id": "gid://shopify/Shop/3333333333" }, "selectedProductVariant": { "id": "gid://shopify/ProductVariant/33333333333?shop=3333333333", "availableForSale": true, "options": [ { "name": "Size", "value": "M" }, { "name": "Color", "value": "Natural" } ], "price": { "amount": "68.00", "currencyCode": "USD" }, "image": { "url": "https://cdn.shopify.com/s/files/example/hemp-cotton-crewneck.jpg", "altText": "Hemp Cotton Oversized Crewneck - Sustainable Basics" } }, "secondhand": false, "requiresSellingPlan": false } ], "availableForSale": true, "rating": { "value": 4.9, "count": 256 }, "uniqueSellingPoint": "Hemp-cotton blend requires 50% less water than conventional cotton.", "topFeatures": [ "55% hemp, 45% organic cotton blend", "Oversized relaxed fit", "Gets softer with every wash", "Naturally antimicrobial", "Low environmental footprint" ], "techSpecs": [ "Material: 55% Hemp, 45% Organic Cotton", "Fit: Oversized", "Neckline: Crew", "Care: Machine wash cold, tumble dry low" ], "sharedAttributes": [ { "name": "Fabric", "values": ["Hemp", "Cotton", "Organic"] }, { "name": "Neckline", "values": ["Crew"] }, { "name": "Target gender", "values": ["Unisex"] }, { "name": "Pattern", "values": ["Solid"] } ], "url": "https://discover.shopifyapps.com/global/v1/p/mno345pqr678?_gsid=example123" } ], "instructions": "Use markdown to render product titles as links to their respective product pages using the URL property.\n" } } ], "isError": false } } ``` 2. Execute the script from your terminal: ## Terminal ```bash node search-catalog.js ``` The response includes product titles, descriptions, pricing, images, and detailed variant information for each matching product. 3. You can use data from the returned [`UniversalProduct`](https://shopify.dev/docs/api/catalog-api/search#the-universalproduct-resource) resource to display custom components, so that buyers can interact with individual products. For example: ```javascript let response = JSON.parse(data.result.content[0].text); let offer = response.offers[buyerSelectedIndex]; // Extract product data let product = { title: offer.title, price: offer.priceRange.min.amount, currency: offer.priceRange.min.currencyCode, image: offer.images[0]?.url, url: offer.url }; let card = `
${product.title}

${product.title}

${product.currency} $${parseFloat(product.price).toFixed(2)}

View Product
`; ``` *** ## Step 3: Apply query parameters Buyers can supply additional context that can be used to refine your catalog search by adding filters for price, shipping location, availability, and other criteria. For example, we can limit results to products between $50 and $200, shippable to the United States, and that can be second-hand items: ##### search-catalog.js ```javascript import 'dotenv/config'; const bearerToken = process.env.BEARER_TOKEN; let catalogId = process.env.CATALOG_ID; fetch('https://discover.shopifyapps.com/global/mcp', { method: 'POST', headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${bearerToken}` }, body: JSON.stringify({ jsonrpc: '2.0', method: 'tools/call', id: 1, params: { name: 'search_global_products', arguments: { saved_catalog: catalogId, query: 'I need a crewneck sweater', context: 'buyer looking for sustainable fashion', include_secondhand: true, min_price: 50, max_price: 200, ships_to: 'US', limit: 3 } } }) }) .then(res => res.json()) .then(data => { if (data && data.result?.content?.[0]?.text) { // Parse the stringified text field data.result.content[0].text = JSON.parse(data.result.content[0].text); } if (data) { console.log(JSON.stringify(data, null, 2)); } }) .catch(err => console.error('Request failed:', err)); ``` ##### {} MCP input reference ```json { "jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": { "name": "search_global_products", "arguments": { "saved_catalog": "", "query": "I need a crewneck sweater", "context": "buyer looking for sustainable fashion", "include_secondhand": true, "min_price": 50, "max_price": 200, "ships_to": "US", "limit": 3 } } } ``` ##### {} Response ```json { "jsonrpc": "2.0", "id": 1, "result": { "content": [ { "type": "text", "text": { "offers": [ { "id": "gid://shopify/p/xyz789abc123", "title": "Organic Cotton Crewneck Sweater", "description": "A soft crewneck sweater crafted from 100% organic cotton with a relaxed fit for everyday comfort.", "images": [ { "url": "https://cdn.shopify.com/s/files/example/organic-cotton-crewneck.jpg", "altText": "Organic Cotton Crewneck Sweater - EcoWear", "product": { "id": "gid://shopify/Product/1111111111111", "title": "Organic Cotton Crewneck Sweater", "onlineStoreUrl": "https://ecowear-example.myshopify.com/products/organic-cotton-crewneck?variant=11111111111&_gsid=example123", "shop": { "name": "EcoWear", "onlineStoreUrl": "https://ecowear-example.myshopify.com" } } } ], "options": [ { "name": "Size", "values": [ { "value": "S", "availableForSale": true, "exists": true }, { "value": "M", "availableForSale": true, "exists": true }, { "value": "L", "availableForSale": true, "exists": true } ] } ], "priceRange": { "min": { "amount": "89.00", "currencyCode": "USD" }, "max": { "amount": "89.00", "currencyCode": "USD" } }, "products": [ { "id": "gid://shopify/Product/1111111111111", "title": "Organic Cotton Crewneck Sweater", "checkoutUrl": "https://ecowear-example.myshopify.com/cart/11111111111:1?_gsid=example123&payment=shop_pay", "description": "A sustainable everyday essential. This crewneck sweater is made from certified organic cotton grown without harmful pesticides.", "onlineStoreUrl": "https://ecowear-example.myshopify.com/products/organic-cotton-crewneck?variant=11111111111&_gsid=example123", "price": { "amount": "89.00", "currencyCode": "USD" }, "rating": { "value": 4.8, "count": 124 }, "availableForSale": true, "shop": { "name": "EcoWear", "paymentSettings": { "supportedDigitalWallets": ["SHOPIFY_PAY"], "acceptedCardBrands": ["visa", "master", "american_express"] }, "onlineStoreUrl": "https://ecowear-example.myshopify.com", "id": "gid://shopify/Shop/1111111111" }, "selectedProductVariant": { "id": "gid://shopify/ProductVariant/11111111111?shop=1111111111", "availableForSale": true, "options": [{ "name": "Size", "value": "M" }], "price": { "amount": "89.00", "currencyCode": "USD" } }, "secondhand": false, "requiresSellingPlan": false } ], "availableForSale": true, "rating": { "value": 4.8, "count": 124 }, "uniqueSellingPoint": "Made from 100% certified organic cotton for eco-conscious comfort.", "topFeatures": ["100% organic cotton fabric", "Relaxed fit for everyday comfort", "Ribbed cuffs and hem", "Classic crew neckline"], "url": "https://discover.shopifyapps.com/global/v1/p/xyz789abc123?_gsid=example123&available_for_sale=1&max_price=200.0&min_price=50.0&query=crewneck+sweater&ships_to=US" }, { "id": "gid://shopify/p/def456ghi789", "title": "Recycled Wool Blend Crewneck", "description": "A cozy crewneck sweater made from recycled wool blend with a modern oversized silhouette.", "priceRange": { "min": { "amount": "125.00", "currencyCode": "USD" }, "max": { "amount": "125.00", "currencyCode": "USD" } }, "availableForSale": true, "rating": { "value": 4.6, "count": 89 }, "uniqueSellingPoint": "Made from 70% recycled wool for warmth with minimal environmental impact.", "url": "https://discover.shopifyapps.com/global/v1/p/def456ghi789?_gsid=example123&available_for_sale=1&max_price=200.0&min_price=50.0&query=crewneck+sweater&ships_to=US" }, { "id": "gid://shopify/p/mno321pqr654", "title": "Vintage Striped Crewneck", "description": "A pre-loved vintage crewneck sweater with classic rugby stripes in excellent condition.", "priceRange": { "min": { "amount": "68.00", "currencyCode": "USD" }, "max": { "amount": "68.00", "currencyCode": "USD" } }, "products": [ { "id": "gid://shopify/Product/3333333333333", "title": "Vintage Striped Crewneck", "secondhand": true, "requiresSellingPlan": false } ], "availableForSale": true, "rating": { "value": 4.9, "count": 42 }, "uniqueSellingPoint": "Pre-loved vintage piece in excellent condition, sustainable fashion at its best.", "url": "https://discover.shopifyapps.com/global/v1/p/mno321pqr654?_gsid=example123&available_for_sale=1&include_secondhand=1&max_price=200.0&min_price=50.0&query=crewneck+sweater&ships_to=US" } ], "instructions": "Use markdown to render product titles as links to their respective product pages using the URL property.\n" } } ], "isError": false } } ``` *** ## Step 4: Lookup product details At this point your search has resulted in three products, and the buyer may be interested in investigating additional details about them. [Lookup](https://shopify.dev/docs/api/catalog-api/lookup) within Catalog allows you to render product details not available already in Search (for example, all variants, detailed pricing, availability, and shop details) so buyers can explore available options and offers. If the buyer chooses an unavailable option, the API will relax those options to find an available variant. See the [`get_global_product_details` tool](https://shopify.dev/docs/agents/catalog/catalog-mcp#get_global_product_details) documentation for more information about options preferences. In this example, you'll modify the script to arbitrarily select a product variant result, then leverage Lookup to get additional information about that product. 1. The Catalog returns products grouped by Universal Product ID (UPID). Each product includes shop information and variant details: ##### search-catalog.js ```js import 'dotenv/config'; const bearerToken = process.env.BEARER_TOKEN; let catalogId = process.env.CATALOG_ID; fetch('https://discover.shopifyapps.com/global/mcp', { method: 'POST', headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${bearerToken}` }, body: JSON.stringify({ jsonrpc: '2.0', method: 'tools/call', id: 1, params: { name: 'search_global_products', arguments: { saved_catalog: catalogId, query: 'I need a crewneck sweater', context: 'buyer looking for sustainable fashion', include_secondhand: true, min_price: 50, max_price: 200, ships_to: 'US', limit: 3 } } }) }) .then(res => res.json()) .then(data => { // Parse the text field to get the actual offers object if (data.result && data.result.content && data.result.content[0]) { const offersData = JSON.parse(data.result.content[0].text); } // Extract first offer ID and call get_global_product_details if (data.result && data.result.content && data.result.content[0]) { const textContent = JSON.parse(data.result.content[0].text); if (textContent.offers && textContent.offers.length > 0) { const fullId = textContent.offers[0].id; // Extract UPID from gid://shopify/p/{UPID} const upid = fullId.split('/p/')[1]; // Call get_global_product_details with the extracted ID return fetch('https://discover.shopifyapps.com/global/mcp', { method: 'POST', headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${bearerToken}` }, body: JSON.stringify({ jsonrpc: '2.0', method: 'tools/call', id: 2, params: { name: 'get_global_product_details', arguments: { upid: upid product_options: [{ key: 'Size', values: ['Large (L)'] }] } } }) }); } } }) .then(res => res ? res.json() : null) .then(data => { if (data && data.result?.content?.[0]?.text) { // Parse the stringified text field data.result.content[0].text = JSON.parse(data.result.content[0].text); } if (data) { console.log(JSON.stringify(data, null, 2)); } }) .catch(err => console.error('Request failed:', err)); ``` ##### {} MCP input reference ```json { "jsonrpc": "2.0", "method": "tools/call", "id": 2, "params": { "name": "get_global_product_details", "arguments": { "upid": "" } } } ``` ##### {} Response ```json { "jsonrpc": "2.0", "id": 2, "result": { "content": [ { "type": "text", "text": { "product": { "id": "gid://shopify/p/xyz789abc123", "title": "Organic Cotton Crewneck Sweater", "description": "A soft crewneck sweater crafted from 100% organic cotton with a relaxed fit for everyday comfort.", "images": [ { "url": "https://cdn.shopify.com/s/files/example/organic-cotton-crewneck-front.jpg", "altText": "Organic Cotton Crewneck Sweater - Front" }, { "url": "https://cdn.shopify.com/s/files/example/organic-cotton-crewneck-back.jpg", "altText": "Organic Cotton Crewneck Sweater - Back" }, { "url": "https://cdn.shopify.com/s/files/example/organic-cotton-crewneck-detail.jpg", "altText": "Organic Cotton Crewneck Sweater - Detail" } ], "options": [ { "name": "Size", "values": [ { "value": "S", "availableForSale": true, "exists": true }, { "value": "M", "availableForSale": true, "exists": true }, { "value": "L", "availableForSale": true, "exists": true } ] } ], "priceRange": { "min": { "amount": "89.00", "currencyCode": "USD" }, "max": { "amount": "89.00", "currencyCode": "USD" } }, "products": [ { "id": "gid://shopify/Product/1111111111111", "title": "Organic Cotton Crewneck Sweater", "checkoutUrl": "https://ecowear-example.myshopify.com/cart/11111111111:1?_gsid=example123&payment=shop_pay", "description": "A sustainable everyday essential. This crewneck sweater is made from certified organic cotton grown without harmful pesticides.", "onlineStoreUrl": "https://ecowear-example.myshopify.com/products/organic-cotton-crewneck?variant=11111111111&_gsid=example123", "price": { "amount": "89.00", "currencyCode": "USD" }, "rating": { "value": 4.8, "count": 124 }, "availableForSale": true, "shop": { "name": "EcoWear", "paymentSettings": { "supportedDigitalWallets": ["SHOPIFY_PAY"], "acceptedCardBrands": ["visa", "master", "american_express"] }, "onlineStoreUrl": "https://ecowear-example.myshopify.com", "id": "gid://shopify/Shop/1111111111" }, "selectedProductVariant": { "id": "gid://shopify/ProductVariant/11111111111?shop=1111111111", "availableForSale": true, "options": [{ "name": "Size", "value": "M" }], "price": { "amount": "89.00", "currencyCode": "USD" }, "selectionState": { "type": "match", "requestedFilters": [] } }, "secondhand": false, "requiresSellingPlan": false } ], "availableForSale": true, "rating": { "value": 4.8, "count": 124 }, "uniqueSellingPoint": "Made from 100% certified organic cotton for eco-conscious comfort.", "topFeatures": [ "100% organic cotton fabric provides breathable comfort", "Relaxed fit for everyday wear", "Ribbed cuffs and hem for a polished look", "Classic crew neckline", "Pre-washed for softness" ], "techSpecs": [ "Material: 100% Organic Cotton", "Fit: Relaxed", "Neckline: Crew", "Pattern: Solid", "Color: Natural Beige", "Available Sizes: S, M, L, XL" ], "sharedAttributes": [ { "name": "Neckline", "values": ["Crew"] }, { "name": "Age group", "values": ["Adults"] }, { "name": "Pattern", "values": ["Solid"] }, { "name": "Fabric", "values": ["Cotton", "Organic"] }, { "name": "Target gender", "values": ["Unisex"] }, { "name": "Color", "values": ["Beige", "Natural"] } ], "url": "https://discover.shopifyapps.com/global/v1/p/xyz789abc123?_gsid=example123&available_for_sale=1&ships_to=US" }, "instructions": "Use markdown to render product titles as links to their respective product pages using the URL property.\n" } } ], "isError": false } } ``` Notice the script to gets details for the size the buyer actually wants to order using the `product_options` argument. In reality, your agent would retrieve real responses from a buyer at this point when calling the `get_global_product_details` tool. In this demo, the first result in the array of resulting products was chosen to stand-in for this behavior. 2. Inspect the response for the buyer's selected product variant. The buyer has made a selection, narrowing down their initial search into a particular product variant found at `.result.content[0].text.product.products[0].selectedProductVariant` in the previous response. ## Product variant line item ```json { "id": "gid://shopify/ProductVariant/11111111111?shop=1111111111", "availableForSale": true, "options": [ { "name": "Size", "value": "M" } ], "price": { "amount": "89.00", "currencyCode": "USD" }, "image": { "url": "https://cdn.shopify.com/s/files/example/organic-cotton-crewneck-front.jpg", "altText": "Organic Cotton Crewneck Sweater - EcoWear" }, "selectionState": { "type": "match", "requestedFilters": [] } } ``` 3. Retrieve the store's domain for the selected product variant. In that same response, you will also need to retrieve and export a `shopDomain` for the product variant selected buy the buyer. This value is located within the response at `onlineStoreUrl` within `.result.content[0].text.product.products[0].shop`: ## Shop details ```json { "name": "EcoWear", "paymentSettings": { "supportedDigitalWallets": [ "SHOPIFY_PAY" ], "acceptedCardBrands": [ "visa", "master", "american_express" ] }, "onlineStoreUrl": "https://ecowear-example.myshopify.com", "privacyPolicy": { "url": "https://ecowear-example.myshopify.com/policies/privacy" }, "refundPolicy": { "url": "https://ecowear-example.myshopify.com/policies/refund" }, "termsOfService": { "url": "https://ecowear-example.myshopify.com/policies/terms" }, "shippingPolicy": { "url": "https://ecowear-example.myshopify.com/policies/shipping" }, "id": "gid://shopify/Shop/1111111111" } ``` You will use this selected product variant `id` and the `shopDomain` when completing checkout in the next tutorial. *** ## Next steps [Complete checkout\ \ ](https://shopify.dev/docs/agents/get-started/complete-checkout) [Now that buyer intent has narrowed down on a single seleced variant, you'll use details from it's Lookup response to complete a checkout.](https://shopify.dev/docs/agents/get-started/complete-checkout) *** * [What you'll learn](https://shopify.dev/docs/agents/get-started/search-catalog.md#what-youll-learn) * [Requirements](https://shopify.dev/docs/agents/get-started/search-catalog.md#requirements) * [Step 1: Create a custom catalog](https://shopify.dev/docs/agents/get-started/search-catalog.md#step-1-create-a-custom-catalog) * [Step 2: Search the Catalog](https://shopify.dev/docs/agents/get-started/search-catalog.md#step-2-search-the-catalog) * [Step 3: Apply query parameters](https://shopify.dev/docs/agents/get-started/search-catalog.md#step-3-apply-query-parameters) * [Step 4: Lookup product details](https://shopify.dev/docs/agents/get-started/search-catalog.md#step-4-lookup-product-details) * [Next steps](https://shopify.dev/docs/agents/get-started/search-catalog.md#next-steps)