Skip to main content

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.

Anchor to [object Object], Get details about a product variant
GET
 Get 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).

Anchor to ParametersParameters

_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 country code. For example, US

ships_to•StringDefault: US

An ISO 3166 country code.

shop_ids•String

Filter by specific shops. For example, gid://shopify/Shop/1234 or 1234

Anchor to Lookup by variant response schemaLookup by variant response schema

The Lookup by variant 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 ,[object Object], resourceThe UniversalProduct resource

Represents a high-level product grouping that may contain multiple variants or offers from different shops.

Anchor to PropertiesProperties

attributes•Attribute[]Inferred

Array of product attributes.

description•stringInferred

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•stringInferred

The unique selling point for the product.

variants•Variant[]

Array of product variants. Default: 5.

Anchor to The ,[object Object], resourceThe Variant resource

Represents a specific product variant with pricing, availability, and checkout information.

Anchor to PropertiesProperties

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•booleanInferred

Whether the variant is secondhand.

shop•Shop

Shop offering this variant.

variantUrl•string

URL for the variant's product page.

Anchor to The ,[object Object], resourceThe Shop resource

Represents the shop offering the product. In Lookup responses, Shop includes policy information.

Anchor to PropertiesProperties

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.

Anchor to The ,[object Object], resourceThe ProductOption resource

Represents a product option like Size or Color.

Anchor to PropertiesProperties

name•string

Option name. For example, Color or Size

values•OptionValue[]

Array of possible values for this option.

Anchor to The ,[object Object], resourceThe OptionValue resource

Represents a product option value. In Lookup responses, OptionValue includes availability information.

Anchor to PropertiesProperties

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

Anchor to The ,[object Object], resourceThe Attribute resource

Represents a product attribute with a name and array of values.

Anchor to PropertiesProperties

name•string

Attribute name.

values•string[]

Array of attribute values.

Anchor to The ,[object Object], resourceThe Status resource

Indicates the state of the requested variant, including whether it was redirected, expired, or fell back to a different selection.

Anchor to PropertiesProperties

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

Anchor to The ,[object Object], resourceThe Policy resource

Represents a shop policy document.

Anchor to PropertiesProperties

url•string

URL to the policy document.

Anchor to The ,[object Object], resourceThe Media resource

Represents product media. Currently returns images only.

Anchor to PropertiesProperties

altText•string

Alt text for the media.

url•string

URL of the media asset.

Anchor to The ,[object Object], resourceThe Price resource

Represents a monetary value with currency.

Anchor to PropertiesProperties

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).

Anchor to The ,[object Object], resourceThe Rating resource

Represents product or variant rating information.

Anchor to PropertiesProperties

count•integer

The total number of ratings.

rating•number

The average rating value.

Anchor to The ,[object Object], resourceThe VariantOption resource

Represents a selected option for a specific variant.

Anchor to PropertiesProperties

name•string

The name of the option (e.g., Color, Size).

value•string

The selected value for this option (e.g., Blue, Medium).

Was this page helpful?