Catalog API reference
Agentic commerce is rolling out to Dev Dashboard. Sign up to be notified.
The Catalog API provides access to product data across all eligible Shopify merchants, enabling agentic commerce applications to search, discover, and retrieve detailed product information to render product details pages.
Anchor to AuthenticationAuthentication
All Catalog API requests require a valid bearer token.
API keys created in the Dev Dashboard provide a client ID and secret that can be used to generate a bearer token.
/auth/access_token
Include your token as a Authorization: Bearer {token} header on all API queries.
Learn more about building agentic commerce experiences.
/global/v2/search
Anchor to Endpoints and requestsEndpoints and requests
Catalog API endpoints are organized by resource type. You’ll need to use different endpoints depending on your agent's requirements.
All Catalog API endpoints follow this pattern: https://discover.shopifyapps.com/global/{API_VERSION}/{resource}.
The Catalog API provides two main endpoints:
- Search: Search for products across the global Shopify Catalog
- Lookup: Get detailed product information using a Universal Product ID (UPID)
The references and examples below document https://discover.shopifyapps.com/global/v2/search as the endpoint, which assumes Search and Lookup against the entire Shopify catalog.
If you want your agents to make requests against a saved catalog you've created in Dev Dashboard, update the endpoint URLs accordingly.
For usage guidelines, see About Catalog.
Anchor to Status and error codesStatus and error codes
All API queries return HTTP status codes that can tell you more about the response.
The request was successful.
The request contains invalid parameters. Check the errors object in the response for details.
The bearer token is missing or invalid.
The requested product (UPID) was not found.
Rate limit exceeded. Wait before retrying.
{} Sample error responses
400
{
"errors": {
"limit": ["must be greater than or equal to 1"],
"max_price": ["must be greater than 0"],
"categories": {
"0": ["must be a Shopify Taxonomy category identifier"]
}
}
}401
{
"error": "Unauthorized"
}404
{
"errors": {
"product": [
"Not found"
]
}
}Anchor to SearchSearch
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 Shopify CatalogGET Retrieve products from Shopify 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.
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.
Append additional supported parameters from the table below to the path.
Anchor to ParametersParameters
Keywords for search. For example, Running Shoes
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.
Comma-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 products.
When 1, include secondhand products in the results.
Max results to return.
Maximum price.
Minimum price (currency determined by ships_to). API accepts decimals.
The maximum number of variants to return per Universal Product.
ISO country code. For example, US
An ISO 3166 country code.
Filter by specific shops. For example, gid://shopify/Shop/1234 or 1234
/global/v2/search
{} Response
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.
| Response type |
|---|
UniversalProduct[] |
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
Array of product attributes as name-value pairs.
Detailed product description.
Unique identifier for the universal product.
For example, gid://shopify/p/1UT1zYWaL8WeTNCllgUbsM
URL for subsequent calls to the Lookup endpoint.
Product media from the top-ranked variant. Currently returns images only.
Array of product options/variants.
Price range from the top-ranked variant.
Universal product rating information.
Array of technical specifications.
Product title from the top-ranked variant.
Array of top product features.
The unique selling point for the product.
Array of product variants.
{} UniversalProduct
Anchor to The Variant resourceThe Variant resource
Represents a specific product variant with pricing, availability, and checkout information.
Anchor to PropertiesProperties
Whether the variant is available for purchase.
Direct checkout URL for this variant.
Display name for the variant.
Whether the variant supports native checkout. This field is not returned by default and requires opt-in from Shopify.
Unique variant identifier.
URL for looking up this variant.
Media for this variant. Currently returns images only.
Array of options for this variant.
Price information for this variant.
ID of the parent product.
Rating information for this variant.
Whether the variant is secondhand.
Shop offering this variant.
URL for the variant's product page.
{} Variant
Anchor to The Shop resourceThe Shop resource
Represents the shop offering the product. In Search responses, Shop contains only basic information.
Anchor to PropertiesProperties
Unique shop identifier. For example, gid://shopify/Shop/54623456
Shop name.
Shop page URL.
Shop's permanent domain. For example, mock-shop.myshopify.com. This field is null if the client is not opted in to receive eligibleForNativeCheckout.
{} Shop
Anchor to The ProductOption resourceThe Product
Represents a product option like Size or Color.
Anchor to PropertiesProperties
Option name. For example, Color or Size
Array of possible values for this option.
{} ProductOption
Anchor to The OptionValue resourceThe Option
Represents a product option value. In Search responses, OptionValue contains only the value.
Anchor to PropertiesProperties
Option value, configured by the merchant. For example, US5.5
{} OptionValue
Anchor to The PriceRange resourceThe Price
Represents the minimum and maximum prices for a product or collection of variants.
Anchor to PropertiesProperties
Maximum price in the range.
Minimum price in the range.
{} PriceRange
Anchor to LookupLookup
Retrieve details of a single UniversalProduct.
This example illustrates how to retrieve detailed information for a single product using the UniversalProduct resource and the /global{API_VERSION}/p/{upid} endpoint.
Replace {upid} with the Universal Product ID for the product of interest and {bearer_token} with the bearer token you generated in the Authentication section.
Use this endpoint to retrieve comprehensive variant information, including availability and option filtering.
Anchor to [object Object], Retrieve detailed information about a Universal ProductGET Retrieve detailed information about a Universal Product
Retrieve details of a single UniversalProduct.
This example illustrates how to retrieve detailed information for a single product using the UniversalProduct resource and the /global{API_VERSION}/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.
Use this endpoint to retrieve comprehensive variant information, including availability and option filtering.
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
Reference to the Catalog Search which generated the URL. Optional, and pre-populated in Catalog Search Results.
For example, xuUi3kiX3Fzt
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 products.
When 1 include secondhand products in the result, not that only secondhand products will appear in the results.
Maximum number of results to return.
Maximum price (currency determined by ships_to). API accepts decimals.
Minimum price (currency determined by ships_to). API accepts decimals.
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
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
Keywords for search. For example, Running Shoes
An ISO 3166 country code. For example, US
An ISO 3166 country code.
Filter by specific shops. For example, gid://shopify/Shop/1234 or 1234
Preselect this product variant. For example, 46731565826293
/global/v2/p/{upid}
{} Response
The schema returned by the Universal Product ID query (Catalog Lookup) is the same returned by the Catalog Search, except for the UniversalProduct's url param, which is omitted.
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.
{} Response
/global/v2/p/{uid}
{} Response
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.
| Response type |
|---|
UniversalProduct |
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
Array of product attributes.
Detailed product description.
The ID of the featured variant for this product.
Media for the featured variant. Currently returns images only.
Unique identifier for the universal product.
For example, gid://shopify/p/1UT1zYWaL8WeTNCllgUbsM
Array of product options/variants.
Universal product rating information.
Array of selected variant options.
Product status information.
Array of technical specifications.
Array of top product features.
The unique selling point for the product.
Array of product variants. Default: 5.
{} UniversalProduct
Anchor to The Variant resourceThe Variant resource
Represents a specific product variant with pricing, availability, and checkout information.
Anchor to PropertiesProperties
Whether the variant is available for purchase.
Direct checkout URL for this variant.
Display name for the variant.
Whether the variant supports native checkout. This field is not returned by default and requires opt-in from Shopify.
Unique variant identifier.
Media for this variant. Currently returns images only.
Price information for this variant.
Description of the parent product.
ID of the parent product.
Rating information for this variant.
Whether the variant is secondhand.
Shop offering this variant.
URL for the variant's product page.
{} Variant
Anchor to The Shop resourceThe Shop resource
Represents the shop offering the product. In Lookup responses, Shop includes policy information.
Anchor to PropertiesProperties
Unique shop identifier. For example, gid://shopify/Shop/54623456
Shop name.
Shop page URL.
Shop's permanent domain. For example, mock-shop.myshopify.com. This field is null if the client is not opted in to receive eligibleForNativeCheckout.
Shop's privacy policy.
Shop's refund policy.
Shop's shipping policy.
Shop's terms of service.
{} Shop
Anchor to The ProductOption resourceThe Product
Represents a product option like Size or Color.
Anchor to PropertiesProperties
Option name. For example, Color or Size
Array of possible values for this option.
{} ProductOption
Anchor to The OptionValue resourceThe Option
Represents a product option value. In Lookup responses, OptionValue includes availability information.
Anchor to PropertiesProperties
Whether a variant with this option is available for sale.
Whether a variant with this option exists.
Option value, configured by the merchant. For example, US5.5
{} OptionValue
Anchor to The Attribute resourceThe Attribute resource
Represents a product attribute with a name and array of values.
Anchor to PropertiesProperties
Attribute name.
Array of attribute values.
{} Attribute
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
Indicates if the requested filters caused a fallback. Value: fallback
Indicates if the requested product ID was redirected or expired. Values: redirected, expired
Indicates if the requested variant caused a fallback. Value: fallback
{} Status
Anchor to The Policy resourceThe Policy resource
Represents a shop policy document.
Anchor to PropertiesProperties
URL to the policy document.
{} Policy
The following resources are identical in both Search and Lookup responses.
Anchor to The Media resourceThe Media resource
Represents product media. Currently returns images only.
Anchor to PropertiesProperties
Alt text for the media.
URL of the media asset.
Anchor to The Price resourceThe Price resource
Represents a monetary value with currency.
Anchor to PropertiesProperties
The price amount in the smallest currency unit (e.g., cents for USD).
The 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
The total number of ratings.
The average rating value.
Anchor to The VariantOption resourceThe Variant
Represents a selected option for a specific variant.
Anchor to PropertiesProperties
The name of the option (e.g., Color, Size).
The selected value for this option (e.g., Blue, Medium).
Anchor to Status and error codesStatus and error codes
All API queries return HTTP status codes that can tell you more about the response.
The request was successful.
The request contains invalid parameters. Check the errors object in the response for details.
The bearer token is missing or invalid.
The requested product (UPID) was not found.
Rate limit exceeded. Wait before retrying.
{} Sample error responses
400
{
"errors": {
"limit": ["must be greater than or equal to 1"],
"max_price": ["must be greater than 0"],
"categories": {
"0": ["must be a Shopify Taxonomy category identifier"]
}
}
}401
{
"error": "Unauthorized"
}404
{
"errors": {
"product": [
"Not found"
]
}
}