---
title: Catalog API reference
description: >-
  Get detailed product information using Universal Product IDs with the Catalog
  Lookup API.
api_name: catalog
source_url:
  html: 'https://shopify.dev/docs/api/catalog-api'
  md: 'https://shopify.dev/docs/api/catalog-api.md'
---

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

## Authentication

All Catalog API requests require a valid bearer token.

API keys created in the [Dev Dashboard](https://dev.shopify.com/dashboard/) provide a client ID and secret that can be used to generate a JWT token.

POST

## /auth/access\_token

```bash
curl --request POST \
  --url https://api.shopify.com/auth/access_token \
  --header 'Content-Type: application/json' \
  --data '{
    "client_id": "{your_client_id}",
    "client_secret": "{your_client_secret}",
    "grant_type": "client_credentials"
  }'
```

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.

## {} Response

```json
{
    "access_token": "f8563253df0bf277ec9ac6f649fc3f17",
    "scope": "read_global_api_catalog_search",
    "expires_in": 86399
}
```

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`](https://www.jwt.io/) to investigate more details related to how Shopify issues this token.

Learn more about [building agentic commerce experiences](https://shopify.dev/docs/agents/get-started/authentication).

GET

## /global/v2/search

```bash
curl -X GET \
  'https://discover.shopifyapps.com/global/v2/search?query=glossier%20lip%20balm' \
  -H 'Authorization: Bearer {BEARER_TOKEN}'
```

***

## Endpoints 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](https://shopify.dev/docs/api/catalog-api/lookup):** Get detailed product information using a Universal Product ID (UPID).
* **[Lookup by variant](https://shopify.dev/docs/api/catalog-api/lookup-by-variant):** Get detailed product information using a Variant ID (VID).
* **[Search](https://shopify.dev/docs/api/catalog-api/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](https://shopify.dev/docs/api/catalog-api#saved-catalogs), update the endpoint URLs accordingly.

For usage guidelines, see [About Catalog](https://shopify.dev/docs/api/catalog-api#usage-guidelines).

***

## Status 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

##### 400

```json
{
  "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

```json
{
  "error": "Unauthorized"
}
```

##### 404

```json
{
  "errors": {
    "product": [
      "Not found"
    ]
  }
}
```

***