Lookup
Retrieve details of a single UniversalProduct.
Use this endpoint to retrieve comprehensive variant information, including availability and option filtering.
Anchor to [object Object], Get details about a Universal ProductGET Get details about a Universal Product
This example illustrates how to retrieve detailed information for a single product using the UniversalProduct resource and the /global/p/{upid} endpoint.
Replace {upid} with the variant ID of a previous Search query or more generally the Universal Product ID for the product of interest and {BEARER_TOKEN} with the bearer token you generated in the Authentication section.
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).
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).
Anchor to ParametersParameters
_gsid•StringReference 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: 10Maximum number of results to return.
option.{name}•StringOption 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•StringComma-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•StringKeywords for search. For example, Running Shoes
ships_from•StringAn ISO 3166 country code. For example, US
ships_to•StringDefault: USAn ISO 3166 country code.
shop_ids•StringFilter by specific shops. For example, gid://shopify/Shop/1234 or 1234
variant_id•IntPreselect this product variant. For example, 46731565826293
Anchor to ExamplesExamples
Use options to pre-select variants.
By specifying options, you can ensure that the relevant variant is selected when users are redirected to onlineStoreUrl and checkoutUrl.
For example, consider product gid://shopify/p/def456GHI789jklMNO123pq which has multiple color and size options.
Using the request's option params, a color and size combination of Navy/Large can be specified.
The returned payload's onlineStoreUrl and checkoutUrl will pre-select these options for the user.
If no variant exists with the combination of options that were requested, a relaxation of option filters will occur to find the next best variant.
The parameter option_preferences can be used to decide the order in which options are relaxed.
If no variant exists with the combination of options that were requested, a relaxation of option filters will occur to find the next best variant.
The parameter option_preferences can be used to decide the order in which options are relaxed.
Anchor to Lookup response schemaLookup response schema
The Lookup endpoint returns a single UniversalProduct object with comprehensive product details for building product detail pages.
Anchor to Inferred fieldsInferred 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.
Anchor to The UniversalProduct resourceThe Universal
Represents a high-level product grouping that may contain multiple variants or offers from different shops.
Anchor to PropertiesProperties
attributes•Attribute[]InferredArray of product attributes.
description•stringInferredDetailed product description.
featuredVariantId•stringThe ID of the featured variant for this product.
featuredVariantMedia•Media[]Media for the featured variant. Currently returns images only.
id•stringUnique identifier for the universal product.
For example, gid://shopify/p/1UT1zYWaL8WeTNCllgUbsM
options•ProductOption[]InferredArray of product options/variants.
rating•RatingUniversal product rating information.
selectedOptions•VariantOption[]Array of selected variant options.
status•StatusProduct status information.
techSpecs•string[]InferredArray of technical specifications.
topFeatures•string[]InferredArray of top product features.
uniqueSellingPoint•stringInferredThe unique selling point for the product.
variants•Variant[]Array of product variants. Default: 5.
Anchor to The Variant resourceThe Variant resource
Represents a specific product variant with pricing, availability, and checkout information.
Anchor to PropertiesProperties
availableForSale•booleanWhether the variant is available for purchase.
checkoutUrl•stringDirect checkout URL for this variant.
displayName•stringDisplay name for the variant.
eligibleForNativeCheckout•booleanWhether the variant supports native checkout. This field is not returned by default and requires opt-in from Shopify.
id•stringUnique variant identifier.
media•Media[]Media for this variant. Currently returns images only.
price•PricePrice information for this variant.
productDescription•stringDescription of the parent product.
productId•stringID of the parent product.
rating•RatingRating information for this variant.
secondhand•booleanInferredWhether the variant is secondhand.
shop•ShopShop offering this variant.
variantUrl•stringURL for the variant's product page.
Anchor to The Shop resourceThe Shop resource
Represents the shop offering the product. In Lookup responses, Shop includes policy information.
Anchor to PropertiesProperties
id•stringUnique shop identifier.
For example, gid://shopify/Shop/54623456
name•stringShop name.
onlineStoreUrl•stringShop page URL.
permanentDomain•stringShop's permanent domain. For example, mock-shop.myshopify.com. This field is null if the client is not opted in to receive eligibleForNativeCheckout.
privacyPolicy•PolicyShop's privacy policy.
refundPolicy•PolicyShop's refund policy.
shippingPolicy•PolicyShop's shipping policy.
termsOfService•PolicyShop's terms of service.
Anchor to The ProductOption resourceThe Product
Represents a product option like Size or Color.
Anchor to PropertiesProperties
name•stringOption name. For example, Color or Size
values•OptionValue[]Array of possible values for this option.
Anchor to The OptionValue resourceThe Option
Represents a product option value. In Lookup responses, OptionValue includes availability information.
Anchor to PropertiesProperties
availableForSale•booleanWhether a variant with this option is available for sale.
exists•booleanWhether a variant with this option exists.
value•stringOption value, configured by the merchant. For example, US5.5
Anchor to The Attribute resourceThe Attribute resource
Represents a product attribute with a name and array of values.
Anchor to PropertiesProperties
name•stringAttribute name.
values•string[]Array of attribute values.
Anchor to The Status resourceThe Status resource
Indicates the state of the requested UPID or variant, including whether it was redirected, expired, or fell back to a different selection.
Anchor to PropertiesProperties
requestedFilters•stringIndicates if the requested filters caused a fallback. Value: fallback
requestedId•stringIndicates if the requested product ID was redirected or expired. Values: redirected, expired
requestedVariantId•stringIndicates if the requested variant caused a fallback. Value: fallback
Anchor to The Policy resourceThe Policy resource
Represents a shop policy document.
Anchor to PropertiesProperties
url•stringURL to the policy document.
Anchor to The Media resourceThe Media resource
Represents product media. Currently returns images only.
Anchor to PropertiesProperties
altText•stringAlt text for the media.
url•stringURL of the media asset.
Anchor to The Price resourceThe Price resource
Represents a monetary value with currency.
Anchor to PropertiesProperties
amount•integerThe price amount in the smallest currency unit (e.g., cents for USD).
currency•stringThe three-letter ISO 4217 currency code (e.g., USD, EUR).
Anchor to The Rating resourceThe Rating resource
Represents product or variant rating information.
Anchor to PropertiesProperties
count•integerThe total number of ratings.
rating•numberThe average rating value.
Anchor to The VariantOption resourceThe Variant
Represents a selected option for a specific variant.
Anchor to PropertiesProperties
name•stringThe name of the option (e.g., Color, Size).
value•stringThe selected value for this option (e.g., Blue, Medium).