Skip to main content

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.

Anchor to [object Object], Look up multiple products
POST
 Look 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 results, rather than the comprehensive detail returned by the single Lookup endpoint.

Anchor to Request bodyRequest 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•BooleanDefault: 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•BooleanDefault: true

Include secondhand products.

When true, include secondhand products in the result.

ships_to•StringDefault: US

An ISO 3166 country code. For example, US

ships_from•String

An ISO 3166 country code. For example, US

Anchor to Bulk lookup response schemaBulk 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, along with variants that include an input field for correlating results back to the input IDs.

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•Hash[]Inferred

Array of product attributes as name-value pairs.

description•stringInferred

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

The unique selling point for the product.

variants•Variant[]

Array of product variants with input correlation.

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

Represents a specific product variant with pricing, availability, and checkout information. Includes an input field for correlating results to input IDs.

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.

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

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.

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

Correlates a variant in the response back to an input ID from the request.

Anchor to PropertiesProperties

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

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

Represents a product option like Size or Color.

Anchor to PropertiesProperties

name•string

The option name (for example, "Size" or "Color").

values•OptionValue[]

Array of possible values for this option.

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

Represents a product option value.

Anchor to PropertiesProperties

value•string

Option value, configured by the merchant. For example, US5.5

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

Represents the minimum and maximum prices for a product or collection of variants.

Anchor to PropertiesProperties

max•Price

Maximum price in the range.

min•Price

Minimum price in the range.

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

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.

Was this page helpful?