--- title: "Catalog API: Lookup by variant" description: Get detailed product information using Variant IDs with the Catalog Lookup API. source_url: html: https://shopify.dev/docs/api/catalog-api/lookup-by-variant md: https://shopify.dev/docs/api/catalog-api/lookup-by-variant.md --- **Deprecated:** This REST API is deprecated. Use the [Global Catalog MCP tools](https://shopify.dev/docs/agents/catalog/global-catalog) instead. # Lookup by variant Retrieve details of a single `UniversalProduct` using a Variant ID. Use this endpoint to retrieve comprehensive product information when you already have a specific variant ID. *** ## GETGet details about a product variant This example illustrates how to retrieve detailed information for a single product using a Variant ID and the `/global{API_VERSION}/p/by-variant/{vid}` endpoint. Replace `{vid}` with the Variant ID of the product you want to look up and `{BEARER_TOKEN}` with the bearer token you generated in the Authentication section. **Variant selection behavior:** If no variant matches the passed option filters, a relaxation of filters occurs to select the closest matching variant. If no match is found, the rightmost option filter is dropped until a match is found. The `selectionState` field in the response indicates whether the variant is a `match` (exact match) or `fallback` (relaxed match). #### Parameters *** `_gsid`•`String` Reference to the Catalog Search which generated the URL. Optional, and pre-populated in Catalog Search Results.\ \ For example, `xuUi3kiX3Fzt` *** `available_for_sale`•`Int (0,1)``Default: 1 (only available items)` Filter by availability.\ \ When `1`, only products available for sale are included in the result. When `0`, unavailable items are included if they're a good match for the query. *** `include_secondhand`•`Int (0,1)``Default: 1 (include)` Include secondhand products.\ \ When `1` include secondhand products in the result. *** `limit`•`Integer (1-100)``Default: 10` Maximum number of results to return. *** `option.{name}`•`String` Option for inclusive and exclusive filtering. Filter products by appending `option.{NAME}={VALUE}` to the URL. Multiple options can be included per request. Different option keys are combined using **AND** logic. This affects the selected variant on `onlineStoreUrl` and `checkoutUrl`.\ \ For example, `option.color=red&option.material=steel` *** `option_preferences`•`String` Comma-delimited list of option names. If no variant matches passed filters, a relaxation of filters occurs to select the closest matching variant. If no match is found, the rightmost option filter is dropped until a match is found.\ \ For example, `color, material` *** `query`•`String` Keywords for search. For example, `Running Shoes` *** `ships_from`•`String` An [ISO 3166](https://www.iso.org/iso-3166-country-codes.html) country code. For example, `US` *** `ships_to`•`String``Default: US` An [ISO 3166](https://www.iso.org/iso-3166-country-codes.html) country code. *** `shop_ids`•`String` Filter by specific shops. For example, `gid://shopify/Shop/1234` or `1234` *** GET ## /global/v2/p/by-variant/{vid} ```bash curl -X GET \ 'https://discover.shopifyapps.com/global/v2/p/by-variant/{vid}' \ -H 'Authorization: Bearer {BEARER_TOKEN}' ``` ## {} Response ```json { "id": "gid://shopify/p/abc123XYZ789defGHI456jk", "description": "A comfortable everyday sweatshirt with a classic fit and soft cotton-polyester blend.", "options": [ { "name": "Color", "values": [ { "value": "Heather Gray", "availableForSale": true, "exists": true } ] }, { "name": "Size", "values": [ { "value": "Medium", "availableForSale": true, "exists": true } ] } ], "selectedOptions": [ { "name": "Color", "value": "Heather Gray" }, { "name": "Size", "value": "Medium" } ], "rating": { "rating": 4.5, "count": 128 }, "featuredVariantId": "gid://shopify/ProductVariant/2000000000001?shop=10000000001", "featuredVariantMedia": [ { "url": "https://cdn.shopify.com/s/files/1/0000/0001/0002/files/classic-crewneck-front.webp?v=1700000001", "altText": "Classic Crewneck Sweatshirt" } ], "variants": [ { "id": "gid://shopify/ProductVariant/2000000000001?shop=10000000001", "productId": "gid://shopify/Product/1000000000001", "displayName": "Classic Crewneck Sweatshirt - Heather Gray / Medium", "productDescription": "A comfortable everyday sweatshirt with a classic fit.", "availableForSale": true, "price": { "amount": 4500, "currency": "USD" }, "media": [ { "url": "https://cdn.shopify.com/s/files/1/0000/0001/0002/files/classic-crewneck-front.webp?v=1700000001", "altText": "Classic Crewneck Sweatshirt" } ], "shop": { "id": "gid://shopify/Shop/10000000001", "name": "Mock Shop", "onlineStoreUrl": "https://mock.shop", "privacyPolicy": { "url": "https://checkout.shopify.com/10000000001/policies/20000000001.html" }, "refundPolicy": { "url": "https://checkout.shopify.com/10000000001/policies/20000000002.html" }, "termsOfService": { "url": "https://checkout.shopify.com/10000000001/policies/20000000003.html" }, "shippingPolicy": { "url": "https://checkout.shopify.com/10000000001/policies/20000000004.html" }, "permanentDomain": "mock-shop.myshopify.com" }, "variantUrl": "https://mock.shop/products/classic-crewneck-sweatshirt?variant=2000000000001", "checkoutUrl": "https://mock.shop/cart/2000000000001:1?payment=shop_pay", "eligibleForNativeCheckout": false, "rating": { "rating": 4.7, "count": 89 }, "secondhand": false } ], "uniqueSellingPoint": "Features a soft cotton-polyester blend with ribbed details.", "topFeatures": [ "50/50 cotton polyester blend provides softness and durability", "Classic crewneck design suitable for layering", "Ribbed collar, cuffs, and hem ensure a secure fit" ], "techSpecs": [ "Weight: 8.0 oz", "Material: 50% cotton, 50% polyester", "Available Sizes: S, M, L, XL, 2XL" ], "attributes": [ { "name": "Fabric", "values": ["Cotton", "Polyester"] }, { "name": "Neckline", "values": ["Crew"] }, { "name": "Pattern", "values": ["Solid"] }, { "name": "Age group", "values": ["Adults"] }, { "name": "Target gender", "values": ["Unisex"] } ] } ``` **Note:** The schema returned by Lookup by variant is identical to Lookup by UPID, except the endpoint path differs. *** ## Lookup by variant response schema The Lookup by variant endpoint returns a single `UniversalProduct` object with comprehensive product details for building product detail pages. ### 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`•`Attribute[]``Inferred` Array of product attributes. *** `description`•`string``Inferred` Detailed product description. *** `featuredVariantId`•`string` The ID of the featured variant for this product. *** `featuredVariantMedia`•`Media[]` Media for the featured variant. Currently returns images only. *** `id`•`string` Unique identifier for the universal product.\ \ For example, `gid://shopify/p/1UT1zYWaL8WeTNCllgUbsM` *** `options`•`ProductOption[]``Inferred` Array of product options/variants. *** `rating`•`Rating` Universal product rating information. *** `selectedOptions`•`VariantOption[]` Array of selected variant options. *** `status`•`Status` Product status information. *** `techSpecs`•`string[]``Inferred` Array of technical specifications. *** `topFeatures`•`string[]``Inferred` Array of top product features. *** `uniqueSellingPoint`•`string``Inferred` The unique selling point for the product. *** `variants`•`Variant[]` Array of product variants. Default: 5. *** ## {} UniversalProduct ```json { "id": "gid://shopify/p/abc123XYZ789defGHI456jk", "description": "A comfortable everyday sweatshirt.", "featuredVariantId": "gid://shopify/ProductVariant/2000000000001", "featuredVariantMedia": [ { "url": "https://cdn.shopify.com/.../variant.webp", "altText": "Featured variant" } ], "options": [ { "name": "Color", "values": [ { "value": "Heather Gray", "availableForSale": true, "exists": true }, { "value": "Navy", "availableForSale": false, "exists": true } ] } ], "selectedOptions": [ { "name": "Color", "value": "Heather Gray" } ], "status": null, "variants": [ { "id": "gid://shopify/ProductVariant/2000000000001", "productId": "gid://shopify/Product/1000000000001", "displayName": "Classic Crewneck - Heather Gray", "availableForSale": true, "price": { "amount": 4500, "currency": "USD" }, "shop": { "id": "gid://shopify/Shop/10000000001", "name": "Mock Shop", "permanentDomain": "mock-shop.myshopify.com" } } ], "rating": { "rating": 4.5, "count": 120 } } ``` ### The `Variant` resource Represents a specific product variant with pricing, availability, and checkout information. #### 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. *** `media`•`Media[]` Media for this variant. Currently returns images only. *** `price`•`Price` Price information for this variant. *** `productDescription`•`string` Description of the parent product. *** `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", "productId": "gid://shopify/Product/1000000000001", "displayName": "Classic Crewneck - Heather Gray", "productDescription": "A comfortable everyday sweatshirt.", "availableForSale": true, "price": { "amount": 4500, "currency": "USD" }, "media": [ { "url": "https://cdn.shopify.com/.../variant.webp", "altText": "Heather Gray variant" } ], "shop": { "id": "gid://shopify/Shop/10000000001", "name": "Mock Shop", "permanentDomain": "mock-shop.myshopify.com" }, "variantUrl": "https://mock.shop/products/crewneck?variant=2000000000001", "checkoutUrl": "https://mock.shop/cart/2000000000001:1", "eligibleForNativeCheckout": true, "rating": { "rating": 4.8, "count": 24 }, "secondhand": false } ``` ### The `Shop` resource Represents the shop offering the product. In Lookup responses, Shop includes policy information. #### 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`. *** `privacyPolicy`•`Policy` Shop's privacy policy. *** `refundPolicy`•`Policy` Shop's refund policy. *** `shippingPolicy`•`Policy` Shop's shipping policy. *** `termsOfService`•`Policy` Shop's terms of service. *** ## {} Shop ```json { "id": "gid://shopify/Shop/10000000001", "name": "Mock Shop", "onlineStoreUrl": "https://mock.shop", "permanentDomain": "mock-shop.myshopify.com", "privacyPolicy": { "url": "https://checkout.shopify.com/.../privacy.html" }, "refundPolicy": { "url": "https://checkout.shopify.com/.../refund.html" }, "shippingPolicy": { "url": "https://checkout.shopify.com/.../shipping.html" }, "termsOfService": { "url": "https://checkout.shopify.com/.../terms.html" } } ``` ### The `ProductOption` resource Represents a product option like Size or Color. #### Properties *** `name`•`string` Option name. For example, `Color` or `Size` *** `values`•`OptionValue[]` Array of possible values for this option. *** ## {} ProductOption ```json { "name": "Color", "values": [ { "value": "Heather Gray", "availableForSale": true, "exists": true }, { "value": "Navy", "availableForSale": false, "exists": true } ] } ``` ### The `OptionValue` resource Represents a product option value. In Lookup responses, OptionValue includes availability information. #### Properties *** `availableForSale`•`boolean` Whether a variant with this option is available for sale. *** `exists`•`boolean` Whether a variant with this option exists. *** `value`•`string` Option value, configured by the merchant. For example, `US5.5` *** ## {} OptionValue ```json { "value": "Heather Gray", "availableForSale": true, "exists": true } ``` ### The `Attribute` resource Represents a product attribute with a name and array of values. #### Properties *** `name`•`string` Attribute name. *** `values`•`string[]` Array of attribute values. *** ## {} Attribute ```json { "name": "Fabric", "values": ["Cotton", "Polyester"] } ``` ### The `Status` resource Indicates the state of the requested variant, including whether it was redirected, expired, or fell back to a different selection. #### Properties *** `requestedFilters`•`string` Indicates if the requested filters caused a fallback. Value: `fallback` *** `requestedId`•`string` Indicates if the requested product ID was redirected or expired. Values: `redirected`, `expired` *** `requestedVariantId`•`string` Indicates if the requested variant caused a fallback. Value: `fallback` *** ## {} Status ```json { "requestedId": "redirected", "requestedVariantId": null, "requestedFilters": null } ``` ### The `Policy` resource Represents a shop policy document. #### Properties *** `url`•`string` URL to the policy document. *** ## {} Policy ```json { "url": "https://checkout.shopify.com/.../policies/privacy.html" } ``` ### 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 } ``` ### 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" } ``` ***