Search
Retrieve products from the Shopify Catalog using the /global/v2/search endpoint.
The resource returns an array of Universal Products, each representing a high-level product grouping that might contain multiple variants or offers from different shops.
Anchor to [object Object], Retrieve products from CatalogGET Retrieve products from Catalog
Pass a search query to retrieve products from the Shopify Catalog.
This example illustrates how to retrieve information from many products using the Search resource and the /global/v2/search endpoint.
Replace {query} with the buyer's search terms and {BEARER_TOKEN} with the bearer token you generated in the Authentication section.
Anchor to ParametersParameters
query•StringRequiredKeywords for search. For example, Running Shoes
available_for_sale•Int (0,1)Default: 1 (only available items)Filter by availability.
When 1, only products available for sale are included. When 0, unavailable items are only included if they are a good match for the query.
categories•StringComma-delimited list of global IDs for taxonomy categories. Refer to the Shopify Standard Product Taxonomy and raw category list.
For example, for shoes, use: gid://shopify/TaxonomyCategory/aa-8.
include_secondhand•Int (0,1)Default: 1 (include)Include secondhand products.
When 1, include secondhand products in the results.
limit•Integer (1-10)Default: 10Max results to return.
max_price•DecimalMaximum price (currency determined by ships_to). API accepts decimals.
min_price•DecimalMinimum price (currency determined by ships_to). API accepts decimals.
products_limit•Integer (1-10)Default: 10The maximum number of variants to return per Universal Product.
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
Anchor to Search response schemaSearch response schema
The Search endpoint returns an array of UniversalProduct objects. Each object contains product information optimized for discovery and browsing.
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•Hash[]InferredArray of product attributes as name-value pairs.
description•stringInferredDetailed product description.
id•stringUnique identifier for the universal product.
For example, gid://shopify/p/1UT1zYWaL8WeTNCllgUbsM
lookupUrl•stringURL for subsequent calls to the Lookup endpoint.
media•Media[]Product media from the top-ranked variant. Currently returns images only.
options•ProductOption[]InferredArray of product options/variants.
priceRange•PriceRangePrice range from the top-ranked variant.
rating•RatingUniversal product rating information.
techSpecs•string[]InferredArray of technical specifications.
title•stringProduct title from the top-ranked variant.
topFeatures•string[]InferredArray of top product features.
uniqueSellingPoint•stringInferredThe unique selling point for the product.
url•stringURL for the product with search context parameters preserved.
variants•Variant[]Array of product variants.
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.
lookupUrl•stringURL for looking up this variant.
media•Media[]Media for this variant. Currently returns images only.
options•VariantOption[]Array of options for this variant.
price•PricePrice information for this variant.
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 Search responses, Shop contains only basic 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.
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 Search responses, OptionValue contains only the value.
Anchor to PropertiesProperties
value•stringOption value, configured by the merchant. For example, US5.5
Anchor to The PriceRange resourceThe Price
Represents the minimum and maximum prices for a product or collection of variants.
Anchor to PropertiesProperties
max•PriceMaximum price in the range.
min•PriceMinimum price in the range.
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).
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.