--- title: 'Catalog API: Bulk lookup' description: >- Look up multiple products at once using Universal Product IDs or variant IDs with the Catalog Bulk Lookup API. api_name: catalog source_url: html: 'https://shopify.dev/docs/api/catalog-api/bulk-lookup' md: 'https://shopify.dev/docs/api/catalog-api/bulk-lookup.md' --- # Bulk lookup Retrieve details for multiple products in a single request. Use this endpoint to look up up to 50 products at once using Universal Product IDs (UPIDs) or variant IDs. *** ## POSTLook up multiple products This endpoint lets you retrieve product information for multiple products in a single request using the `/global/v2/lookup` endpoint. Pass an array of Universal Product IDs or variant IDs in the request body to get product details for each. The response returns a subset of product fields similar to [Search](https://shopify.dev/docs/api/catalog-api/search) results, rather than the comprehensive detail returned by the single [Lookup](https://shopify.dev/docs/api/catalog-api/lookup) endpoint. #### Request body The request body must be a JSON object and contains the following fields: *** `ids`•`String[]``Required` An array of Universal Product IDs (UPIDs) or variant IDs to look up. Must contain between 1 and 50 identifiers.\ \ For example, `["gid://shopify/p/abc123XYZ789defGHI456jk", "gid://shopify/ProductVariant/2000000000002"]` *** `available_for_sale`•`Boolean``Default: true` Filter by availability.\ \ When `true`, only products available for sale are included in the result. When `false`, unavailable items are included if they're a good match for the query. *** `include_secondhand`•`Boolean``Default: true` Include secondhand products.\ \ When `true`, include secondhand products in the result. *** `ships_to`•`String``Default: US` An [ISO 3166](https://www.iso.org/iso-3166-country-codes.html) country code. For example, `US` *** `ships_from`•`String` An [ISO 3166](https://www.iso.org/iso-3166-country-codes.html) country code. For example, `US` *** POST ## /global/v2/lookup ```bash curl -X POST \ 'https://discover.shopifyapps.com/global/v2/lookup' \ -H 'Authorization: Bearer {BEARER_TOKEN}' \ -H 'Content-Type: application/json' \ -d '{ "ids": [ "gid://shopify/p/abc123XYZ789defGHI456jk", "gid://shopify/ProductVariant/2000000000002" ], "ships_to": "US", "available_for_sale": true }' ``` ## {} Response ```json [ { "id": "gid://shopify/p/abc123XYZ789defGHI456jk", "title": "Classic Crewneck Sweatshirt", "description": "A comfortable everyday sweatshirt with a classic fit and soft cotton-polyester blend.", "uniqueSellingPoint": "Features a soft cotton-polyester blend with ribbed details.", "topFeatures": [ "Classic fit", "Ribbed cuffs and hem" ], "techSpecs": [ "60% cotton, 40% polyester" ], "attributes": [ { "name": "Material", "value": "Cotton-polyester blend" } ], "media": [ { "url": "https://cdn.shopify.com/.../classic-crewneck-main.webp", "altText": "Classic Crewneck Sweatshirt" } ], "priceRange": { "min": { "amount": 4500, "currency": "USD" }, "max": { "amount": 5500, "currency": "USD" } }, "lookupUrl": "https://discover.shopifyapps.com/global/v2/p/abc123XYZ789defGHI456jk", "options": [ { "name": "Color", "values": [ { "value": "Heather Gray" }, { "value": "Navy" } ] }, { ``` *** ## Bulk lookup response schema The Bulk lookup endpoint returns an array of products. Each entry contains a subset of the fields from the single Lookup's [`UniversalProduct`](https://shopify.dev/docs/api/catalog-api/lookup#the-universalproduct-resource), along with `variants` that include an `input` field for correlating results back to the input IDs. ### Inferred fields Some fields are generated using machine learning and are marked with `Inferred` in the documentation. These fields may not always be present or may have varying accuracy depending on the available product data. **Response type:** [`UniversalProduct`\[\]](#the-universalproduct-resource) ### The `UniversalProduct` resource Represents a high-level product grouping that may contain multiple variants or offers from different shops. #### Properties *** `attributes`•`Hash[]``Inferred` Array of product attributes as name-value pairs. *** `description`•`string``Inferred` Detailed product description. *** `id`•`string` Unique identifier for the universal product.\ \ For example, `gid://shopify/p/abc123XYZ789defGHI456jk` *** `lookupUrl`•`string` URL for subsequent calls to the [Lookup](https://shopify.dev/docs/api/catalog-api/lookup) endpoint. *** `media`•`Media[]` Product media from the top-ranked variant. Currently returns images only. *** `priceRange`•`PriceRange` Price range from the top-ranked variant. *** `options`•`ProductOption[]``Inferred` Array of product options. Each option includes a name and its available values. *** `rating`•`Rating` Universal product rating information. *** `techSpecs`•`string[]``Inferred` Array of technical specifications. *** `title`•`string` Product title from the top-ranked variant. *** `topFeatures`•`string[]``Inferred` Array of top product features. *** `uniqueSellingPoint`•`string``Inferred` The unique selling point for the product. *** `variants`•`Variant[]` Array of product variants with input correlation. *** ## {} UniversalProduct ```json { "id": "gid://shopify/p/abc123XYZ789defGHI456jk", "title": "Classic Crewneck Sweatshirt", "description": "A comfortable everyday sweatshirt.", "lookupUrl": "https://discover.shopifyapps.com/global/v2/p/abc123", "media": [ { "url": "https://cdn.shopify.com/.../crewneck.webp", "altText": "Crewneck" } ], "options": [ { "name": "Color", "values": [{ "value": "Heather Gray" }] }, { "name": "Size", "values": [{ "value": "Medium" }] } ], "priceRange": { "min": { "amount": 4500, "currency": "USD" }, "max": { "amount": 5500, "currency": "USD" } }, "variants": [ { "id": "gid://shopify/ProductVariant/2000000000001", "displayName": "Classic Crewneck - Heather Gray", "availableForSale": true, "price": { "amount": 4500, "currency": "USD" }, "shop": { "id": "gid://shopify/Shop/10000000001", "name": "Mock Shop" }, "input": [{ "id": "gid://shopify/p/abc123XYZ789defGHI456jk", "match": "featured" }] } ], "rating": { "rating": 4.5, "count": 120 } } ``` ### The `Variant` resource Represents a specific product variant with pricing, availability, and checkout information. Includes an input field for correlating results to input IDs. #### Properties *** `availableForSale`•`boolean` Whether the variant is available for purchase. *** `checkoutUrl`•`string` Direct checkout URL for this variant. *** `displayName`•`string` Display name for the variant. *** `eligibleForNativeCheckout`•`boolean` Whether the variant supports native checkout. This field is not returned by default and requires opt-in from Shopify. *** `id`•`string` Unique variant identifier. *** `input`•`InputCorrelation[]` Array of input correlations that map this variant back to the input IDs from the request. If multiple input IDs resolve to the same variant, they're grouped together in this array. *** `lookupUrl`•`string` URL for looking up this variant. *** `media`•`Media[]` Media for this variant. Currently returns images only. *** `options`•`VariantOption[]` Array of options for this variant. *** `price`•`Price` Price information for this variant. *** `productId`•`string` ID of the parent product. *** `rating`•`Rating` Rating information for this variant. *** `secondhand`•`boolean``Inferred` Whether the variant is secondhand. *** `shop`•`Shop` Shop offering this variant. *** `variantUrl`•`string` URL for the variant's product page. *** ## {} Variant ```json { "id": "gid://shopify/ProductVariant/2000000000001?shop=10000000001", "productId": "gid://shopify/Product/1000000000001", "displayName": "Classic Crewneck - Heather Gray / Medium", "availableForSale": true, "price": { "amount": 4500, "currency": "USD" }, "media": [ { "url": "https://cdn.shopify.com/.../variant.webp", "altText": "Heather Gray variant" } ], "options": [ { "name": "Color", "value": "Heather Gray" }, { "name": "Size", "value": "Medium" } ], "shop": { "id": "gid://shopify/Shop/10000000001", "name": "Mock Shop", "onlineStoreUrl": "https://mock.shop", "permanentDomain": "mock-shop.myshopify.com" }, "variantUrl": "https://mock.shop/products/crewneck?variant=2000000000001", "checkoutUrl": "https://mock.shop/cart/2000000000001:1", "eligibleForNativeCheckout": false, "rating": { "rating": 4.8, "count": 24 }, "secondhand": false, "lookupUrl": "https://discover.shopifyapps.com/global/v2/p/abc123", "input": [ { "id": "gid://shopify/p/abc123XYZ789defGHI456jk", "match": "featured" } ] } ``` ### The `Shop` resource Represents the shop offering the product. #### Properties *** `id`•`string` Unique shop identifier.\ \ For example, `gid://shopify/Shop/54623456` *** `name`•`string` Shop name. *** `onlineStoreUrl`•`string` Shop page URL. *** `permanentDomain`•`string` Shop's permanent domain. For example, `mock-shop.myshopify.com`. This field is `null` if the client is not opted in to receive `eligibleForNativeCheckout`. *** ## {} Shop ```json { "id": "gid://shopify/Shop/10000000001", "name": "Mock Shop", "onlineStoreUrl": "https://mock.shop", "permanentDomain": "mock-shop.myshopify.com" } ``` ### The `InputCorrelation` resource Correlates a variant in the response back to an input ID from the request. #### Properties *** `id`•`string` The input ID from the request that resolved to this variant. *** `match`•`string` How the input ID matched to this variant. Possible values: `"exact"` (the input ID directly matched this variant) or `"featured"` (the input resolved to this product and the featured variant was selected). *** ## {} InputCorrelation ```json { "id": "gid://shopify/p/abc123XYZ789defGHI456jk", "match": "featured" } ``` ### The `ProductOption` resource Represents a product option like Size or Color. #### Properties *** `name`•`string` The option name (for example, `"Size"` or `"Color"`). *** `values`•`OptionValue[]` Array of possible values for this option. *** ## {} ProductOption ```json { "name": "Color", "values": [ { "value": "Heather Gray" }, { "value": "Navy" } ] } ``` ### The `OptionValue` resource Represents a product option value. #### Properties *** `value`•`string` Option value, configured by the merchant. For example, `US5.5` *** ## {} OptionValue ```json { "value": "Heather Gray" } ``` ### The `PriceRange` resource Represents the minimum and maximum prices for a product or collection of variants. #### Properties *** `max`•`Price` Maximum price in the range. *** `min`•`Price` Minimum price in the range. *** ## {} PriceRange ```json { "min": { "amount": 2999, "currency": "USD" }, "max": { "amount": 4999, "currency": "USD" } } ``` ### The `VariantOption` resource Represents a selected option for a specific variant. #### Properties *** `name`•`string` The name of the option (e.g., `Color`, `Size`). *** `value`•`string` The selected value for this option (e.g., `Blue`, `Medium`). *** ## {} VariantOption ```json { "name": "Color", "value": "Heather Gray" } ``` ### The `Media` resource Represents product media. Currently returns images only. #### Properties *** `altText`•`string` Alt text for the media. *** `url`•`string` URL of the media asset. *** ## {} Media ```json { "url": "https://cdn.shopify.com/.../sneaker.jpg", "altText": "White running sneaker side view" } ``` ### The `Price` resource Represents a monetary value with currency. #### Properties *** `amount`•`integer` The price amount in the smallest currency unit (e.g., cents for USD). *** `currency`•`string` The three-letter ISO 4217 currency code (e.g., `USD`, `EUR`). *** ## {} Price ```json { "amount": 12999, "currency": "USD" } ``` ### The `Rating` resource Represents product or variant rating information. #### Properties *** `count`•`integer` The total number of ratings. *** `rating`•`number` The average rating value. *** ## {} Rating ```json { "rating": 4.5, "count": 128 } ``` ***