Shopify Catalog API

What is the Catalog API?

The Shopify Catalog API is a federated product search API that enables querying products across multiple Shopify stores simultaneously. Unlike the Storefront API, which queries a single store, the Catalog API aggregates product data from participating merchants into a unified search experience.

This API is the foundation of Shopify's Universal Commerce Protocol (UCP), enabling new commerce experiences like AI-powered shopping assistants and cross-store product discovery.

Capabilities

  • Search products across all participating Shopify stores
  • Filter by price range, categories, and availability
  • Filter by specific shop IDs for targeted searches
  • Semantic search that understands product intent
  • Returns rich product data including variants, images, and pricing
  • Supports shipping destination filtering
  • Includes shop metadata for attribution

Limitations

Understanding the API's limitations helps you build better integrations:

  • Returns a maximum of 10 products per request (no pagination currently)
  • Only returns products from merchants who haven't opted out of UCP (all merchants are included by default)
  • Requires authentication via Bearer token (JWT)
  • No direct checkout—redirects to merchant storefronts for purchase
  • Limited to product search; no customer, order, or inventory management
  • Results may vary based on merchant catalog completeness
  • Rate limits apply for high-volume applications

Use Cases

AI Shopping Assistants

Build conversational commerce experiences where AI agents search for products on behalf of users.

Product Discovery Platforms

Create aggregated shopping experiences that surface products from multiple merchants.

Developer Tools

Build debugging and testing tools (like Catalog Search) for working with UCP integrations.

Price Comparison

Compare similar products across different merchants with unified search queries.

Example Request

Here's a basic example of querying the Catalog API:

curl -X POST "https://ucp.dev/api/catalog/search" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "query": "wireless headphones",
    "min_price": 50,
    "max_price": 200,
    "available_for_sale": 1
  }'

To obtain a JWT token, exchange your client credentials (client ID and secret from the Dev Dashboard) at the /auth/access_token endpoint. Tokens are valid for approximately 60 minutes.

Use Catalog Search to generate curl commands for your specific queries.

Response Structure

The API returns products with their variants, each containing:

  • id — Unique product identifier
  • title — Product name
  • description — Product description
  • images — Array of product images
  • variants — Array of product variants with pricing
  • shop — Merchant information for each variant

For complete API documentation, see the official Shopify Catalog API docs.