# Catalog Search: Complete Documentation

> The primary explorer and diagnostic tool for Shopify's Catalog API and the Universal Commerce Protocol (UCP).

This document provides comprehensive information about Catalog Search, the Shopify Catalog API, and Universal Commerce Protocol for AI systems and developers.

---

## Overview

Catalog Search (https://catalogsearch.dev) is a free web application for searching products across Shopify stores using the Catalog API. Built by The Pages Media for developers, agencies, and merchants exploring agentic commerce.

### Primary Use Cases

1. Test Shopify Catalog API queries with real product data
2. Understand how AI agents discover products via UCP
3. Generate curl commands for API integrations
4. View raw JSON responses for debugging
5. Learn about Universal Commerce Protocol and agentic commerce
6. Compare products across multiple Shopify stores

### Technical Capabilities

- Semantic product search across all UCP-participating Shopify stores
- Filters: price range, categories, availability, shipping destination, shop IDs
- Developer preview panel with curl generation and JSON response viewing
- Shareable search URLs with filter state preservation
- Local storage for saved searches

---

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

- Returns a maximum of 10 products per request (no pagination currently)
- Only returns products from merchants who haven't opted out of UCP
- 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
- Rate limits apply for high-volume applications

### Example API Request

```bash
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.

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

### 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 for working with UCP integrations.

**Price Comparison**: Compare similar products across different merchants with unified search queries.

---

## Catalog API vs Storefront API

### Quick Comparison

| Feature | Catalog API | Storefront API |
|---------|-------------|----------------|
| Scope | Multiple stores | Single store |
| Primary Use | Product discovery | Storefront building |
| Authentication | Bearer token (JWT) | Storefront access token |
| Results Limit | 10 products per request | Configurable (up to 250) |
| Checkout | Redirect to merchant | Full checkout flow |
| Cart Management | No | Yes |
| Customer Accounts | No | Yes |
| Collections | Categories only | Full collection data |
| Search Type | Semantic / AI-powered | Keyword-based |

### When to Use the Catalog API

- Search products across multiple Shopify stores
- Build AI shopping assistants or recommendation engines
- Create product comparison or discovery experiences
- Integrate with the Universal Commerce Protocol ecosystem
- Build tools for the agentic commerce space

### When to Use the Storefront API

- Build a custom storefront for a single merchant
- Manage carts and checkout flows
- Access customer account functionality
- Work with merchant-specific collections and navigation
- Build headless commerce experiences with full control

### Using Both Together

1. **Discovery with Catalog API**: Use the Catalog API to help users find products across multiple stores.
2. **Purchase with Storefront API**: Once a user selects a product, redirect them to the merchant's store or use the Storefront API to handle checkout.

---

## Universal Commerce Protocol (UCP)

### What is UCP?

Universal Commerce Protocol (UCP) is Shopify's open infrastructure for enabling AI agents to participate in commerce. It provides standardized APIs, data formats, and interaction patterns that allow AI systems to search products, understand availability and pricing, and facilitate purchases across millions of merchants.

Think of UCP as the "roads and signage" for AI shopping. Just as humans need storefronts, search bars, and checkout flows to shop online, AI agents need structured data and APIs to do the same. UCP provides that infrastructure.

### Why Does UCP Matter?

The way people shop is changing. Instead of visiting individual stores or browsing marketplaces, users increasingly ask AI assistants for help. "Find me a good laptop for video editing under $1500" or "What's the best gift for a 10-year-old who likes science?"

Without protocols like UCP, AI agents can only scrape websites or use limited search APIs. With UCP, they have direct access to structured product data, real-time inventory, verified pricing, and merchant information.

### For Merchants: Why Participate?

**New Discovery Channel**: Your products become discoverable through AI assistants like ChatGPT, Claude, and Google's Gemini. This is a new acquisition channel beyond traditional SEO and paid ads.

**Qualified Traffic**: AI agents send users who are ready to buy. When an AI recommends your product, the user has already described their needs and the AI has matched them to your offering.

**Future-Proofing**: As more shopping moves to AI-assisted channels, merchants on UCP are positioned to capture that demand.

### For Developers: Why Build on UCP?

**Access to Millions of Products**: The Catalog API gives you instant access to product data from Shopify's merchant base without negotiating individual partnerships.

**Built for AI**: UCP is designed for AI integration from the ground up. Semantic search, structured data, and MCP compatibility make it easy to build AI shopping experiences.

**Real-Time Data**: Product data stays synchronized with merchant catalogs. Pricing, availability, and inventory reflect current state, not stale snapshots.

### The Foundation: Product Taxonomy

Before AI agents can discover your products, they need to understand them. This starts with Shopify's product taxonomy, a standardized system for categorizing products that provides first-party data to enhance discoverability.

When you assign a product category in Shopify (like "Apparel & Accessories > Clothing > Shirts"), you're creating structured metadata that AI agents can parse. These categories follow a standardized taxonomy consistent across all Shopify stores.

### UCP Storefront Catalog MCP (2026 update)

As of April 2026, Shopify's Storefront Catalog MCP implements UCP. Each participating Shopify store exposes a JSON-RPC 2.0 endpoint at:

```
POST https://{storedomain}/api/ucp/mcp
```

Three tools are available:

- **search_catalog**: free-text search scoped to a single store. Accepts `catalog.query` and optional `catalog.context` with buyer signals (`address_country`, `language`, `currency`, `intent`). Returns cursor-paginated results with `has_next_page` and `total_count`.
- **lookup_catalog**: batch resolve up to 10 product or variant GIDs in one call. Returns an `inputs[]` array correlating each request id with its result and a `match_type` of either `"exact"` (resolved) or `"featured"` (substituted). Unresolved ids appear in `not_found[]`.
- **get_product**: full product detail for one GID, with optional `catalog.selected` option choices to narrow results. Options carry per-value `exists` and `available` booleans so agents can reason about which combinations are purchasable.

All calls are JSON-RPC 2.0 with method `"tools/call"`. The agent declares its capabilities via a `meta.ucp-agent.profile` URL inside `params.arguments.meta`. No authentication beyond the profile URL is required because the endpoints are public.

**June 15, 2026 sunset**: the pre-UCP tool names (`search_shop_catalog`, `get_product_details`, etc.) continue to work through June 15, 2026. After that date agents must migrate to the new names and the per-store `/api/ucp/mcp` endpoint.

Try all three tools live against any store at https://catalogsearch.dev/demo/ucp.

### Global Catalog API vs UCP Storefront Catalog

| Dimension | Global Catalog API | UCP Storefront Catalog MCP |
|---|---|---|
| Scope | Cross-store federated | Single store (per-merchant) |
| Endpoint | discover.shopifyapps.com/global/v2 | `{store}/api/ucp/mcp` |
| Auth | Bearer token (client credentials) | Public (agent profile URL) |
| Protocol | REST/GET | JSON-RPC 2.0 POST |
| Pagination | None (max 10 products) | Cursor-based with total_count |
| Tool names | Legacy: search_shop_catalog, get_product_details (sunset 2026-06-15) | search_catalog, lookup_catalog, get_product |
| Availability signals | Variant-level availableForSale | Per-option exists/available booleans |

---

## Glossary of Agentic Commerce Terms

### Agentic Commerce
The emerging paradigm where AI agents act on behalf of users to discover, compare, and facilitate purchases. Rather than users browsing websites directly, AI assistants like ChatGPT, Claude, or Google's Gemini search for products, evaluate options, and guide purchase decisions.

### Universal Commerce Protocol (UCP)
Shopify's open protocol for enabling AI agents to interact with commerce. UCP provides a standardized way for AI systems to search product catalogs, understand pricing and availability, and facilitate purchases across participating merchants.

### Catalog Search API
Shopify's federated product search API that enables querying products across multiple stores simultaneously. Unlike the Storefront API (which queries a single store), the Catalog API aggregates product data from all participating UCP merchants.

### Model Context Protocol (MCP)
An open protocol for AI models to interact with external systems and tools. MCP standardizes how AI assistants connect to data sources, APIs, and services. In commerce, MCP enables AI agents to use tools like the Catalog API as part of their reasoning process.

### Semantic Search
Search that understands the meaning and intent behind queries, not just keyword matching. A semantic search for "something to keep my coffee hot" understands you want an insulated mug, even if those exact words don't appear in product titles.

### Zero-Click Commerce
Purchases that happen without the user visiting a traditional storefront. In zero-click commerce, an AI agent handles product discovery, selection, and checkout facilitation entirely within a conversational interface.

### Federated Search
Searching across multiple independent data sources with a single query. In e-commerce, federated search queries products from many different stores simultaneously.

### Headless Commerce
A commerce architecture where the frontend (presentation layer) is decoupled from the backend (commerce engine). Headless allows developers to build custom shopping experiences using APIs while Shopify handles inventory, payments, and fulfillment.

### Product Graph
A knowledge graph of product data including relationships between products, categories, attributes, and merchants. The Catalog API draws from Shopify's product graph to understand product relationships and improve search relevance.

### Shop ID
A unique identifier for a Shopify store within the UCP ecosystem. Shop IDs allow you to filter Catalog API searches to specific merchants or attribute products to their source stores.

---

## Frequently Asked Questions

### General

**Q: Is this tool free?**
A: Yes, Catalog Search is completely free to use. It's an open tool built by The Pages Media for the Shopify developer community. There are no usage limits for exploring the interface, though the underlying Catalog API has its own rate limits for high-volume programmatic access.

**Q: Who built this?**
A: Catalog Search is built by The Pages Media, a Shopify-focused development agency. We created it as a free tool for developers exploring the Catalog API and UCP ecosystem.

### Data and Results

**Q: What data does the Catalog API return?**
A: The Catalog API returns product data including titles, descriptions, images, variants, and pricing. Each variant includes shop information (store name and ID) for attribution. The API does not return customer data, order history, or inventory levels beyond basic availability status.

**Q: How is this different from Shopify Admin search?**
A: The Shopify Admin search lets you search within your own store's products. Catalog Search queries across all Shopify merchants who participate in the Universal Commerce Protocol. It's designed for product discovery across stores, not managing your own inventory.

**Q: Why do some searches return unexpected results?**
A: The Catalog API uses semantic search, which matches intent rather than exact keywords. This means a search for "warm winter jacket" might return insulated coats even if those words aren't in the title. Results also depend on which merchants participate in UCP and how well their product data is structured.

**Q: Why don't I see products from a specific store?**
A: All Shopify merchants are included in the Universal Commerce Protocol by default. If a store's products don't appear, they may have opted out of UCP, or their products may not match your search query.

**Q: How often is product data updated?**
A: Product data in the Catalog API stays synchronized with merchant catalogs. When merchants update prices, availability, or product details in Shopify, those changes are reflected in API responses. The data is not a stale snapshot.

### Integration

**Q: Can I use this for my own integration?**
A: The curl commands and JSON responses shown in the developer preview panel can help you build your own integrations. However, production applications should reference the official Shopify Catalog API documentation for authentication requirements and best practices.

**Q: How do I authenticate with the Catalog API?**
A: Exchange your client credentials (client ID and secret from the Dev Dashboard) at the /auth/access_token endpoint to obtain a JWT token. Tokens are valid for approximately 60 minutes.

### Purchasing

**Q: Can I purchase products directly through this tool?**
A: No. Catalog Search is for discovery only. When you find a product you want to buy, click through to the merchant's store to complete your purchase. The Catalog API is designed for product discovery, not checkout.

### UCP

**Q: What is Universal Commerce Protocol?**
A: UCP is Shopify's infrastructure for enabling AI agents to interact with commerce. It provides standardized APIs for product discovery, understanding availability, and facilitating purchases. The Catalog API is the product search component of UCP.

**Q: Are all Shopify stores included in UCP?**
A: All Shopify merchants are included by default. Merchants can opt out if they choose, but participation is automatic for most stores.

---

## How to Use Catalog Search

### Step 1: Search for Products

Enter your search query in the search bar on the homepage. The Catalog API uses semantic search, so you can describe what you're looking for naturally.

Example queries:
- "wireless noise-canceling headphones"
- "sustainable yoga mat"
- "gift for coffee lover"
- "minimalist desk lamp"

### Step 2: Apply Filters

After searching, narrow results using filters:

- **Price Range**: Set minimum and/or maximum prices
- **Categories**: Filter by product category
- **Availability**: Show only products available for sale
- **Ships To**: Filter by shipping destination country
- **Shop IDs**: Search within specific stores (comma-separated)

### Step 3: View Product Details

Click any product card to see:
- Product images and description
- Available variants with pricing
- Shop information for each variant
- Direct link to purchase on the merchant's store

### Step 4: Use Developer Tools

The developer preview panel provides:
- **curl Request**: Ready-to-use command that reproduces your search
- **JSON Response**: Raw API response for understanding data structure

---

## Site Structure

- https://catalogsearch.dev | Homepage with product search interface
- https://catalogsearch.dev/docs | Documentation index
- https://catalogsearch.dev/docs/catalog-api | Catalog API deep dive
- https://catalogsearch.dev/docs/vs-storefront-api | API comparison guide
- https://catalogsearch.dev/learn | Learning resources index
- https://catalogsearch.dev/learn/ucp | Universal Commerce Protocol explained
- https://catalogsearch.dev/learn/how-to-use | Step-by-step tutorial
- https://catalogsearch.dev/learn/glossary | Agentic commerce terminology
- https://catalogsearch.dev/learn/geo | Geographic considerations
- https://catalogsearch.dev/faq | Frequently asked questions
- https://catalogsearch.dev/about | About the project and team
- https://catalogsearch.dev/contact | Contact form

---

## Related Resources

- Official Shopify Catalog API Documentation: https://shopify.dev/docs/api/catalog-api
- Universal Commerce Protocol: https://ucp.dev
- Shopify Product Taxonomy: https://shopify.github.io/product-taxonomy/releases/latest/
- Shopify Storefront API Documentation: https://shopify.dev/docs/api/storefront
- Model Context Protocol: https://modelcontextprotocol.io

---

## About The Pages Media

Catalog Search is built by The Pages Media (https://www.thepagesmedia.com/), a boutique Shopify consultancy. We're a husband-and-wife team: Taylor handles development, Kendra manages UX and operations. We scale up with trusted collaborators as projects require.

We work directly with merchants to build custom storefronts, apps, and integrations. Catalog Search is one of our open tools for the Shopify community.

---

## Example Prompts for AI Agents

Use these example queries when interacting with Catalog Search:

- "Search for [product] on catalogsearch.dev and show me the GEO scores"
- "Use the Catalog API to find [product type] under $[price]"
- "What's the GEO readiness score for products matching [query]?"
- "Search Shopify stores for [product] and filter by availability"
- "Find [product category] products and analyze their AI discoverability"
- "Compare GEO scores across different [product type] listings"

For merchants:
- "How can I improve my product's GEO score on catalogsearch.dev?"
- "What factors affect AI discoverability for Shopify products?"
- "Request a GEO audit for my store at [store URL]"

---

## Contact

For questions about Catalog Search or to discuss Shopify projects:
https://catalogsearch.dev/contact

For general information about The Pages Media:
https://www.thepagesmedia.com/