Catalog API reference

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 JWT token.

The response will contain:

access_token: A JWT access token that can be used to interact with the Catalog API.
scope: The list of access scopes that were granted to your API key.
expires_in: The number of seconds until the access token expires.

Include your token as a Authorization: Bearer {token} header on all API queries. JWT tokens created from Dev Dashboard credentials have a 60-minute TTL. You can use a JWT decoder tool like jwt.io to investigate more details related to how Shopify issues this token.

Learn more about building agentic commerce experiences.

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//{resource}.

The Catalog API provides three main endpoints:

Lookup: Get detailed product information using a Universal Product ID (UPID).
Lookup by variant: Get detailed product information using a Variant ID (VID).
Search: Search for products across the global Shopify Catalog.

The references and examples 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.

200 OK

The request was successful.

400 Bad Request

The request contains invalid parameters. Check the errors object in the response for details.

401 Unauthorized

The bearer token is missing or invalid.

404 Not Found

The requested product (UPID) was not found.

429 Too Many Requests

Rate limit exceeded. Wait before retrying.

{} Sample error responses

{

"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"]

}

{

"error": "Unauthorized"

}

{

"errors": {

"product": [

"Not found"

]

}

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"
    ]
  }
}

Was this page helpful?