Catalog API vs Storefront API
Shopify offers multiple APIs for accessing product data. Understanding the differences between the Catalog API and Storefront API helps you choose the right tool for your project.
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 | Page size 1 to 50, cursor pagination, up to 1,000 results | Configurable (up to 250) |
| Checkout | Via Cart/Checkout MCP or Shop MCP (not in this tool) | Full checkout flow |
| Cart Management | Via Cart/Checkout MCP or Shop MCP (not in this tool) | Yes |
| Customer Accounts | No | Yes |
| Collections | Categories only | Full collection data |
| Search Type | Semantic / AI-powered | Keyword-based |
When to Use the Catalog API
Choose the Catalog API when you need to:
- 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
Catalog Search links to the merchant exactly as Shopify returns the URL. Cart/Checkout MCP and Shop MCP also support agent purchasing and Shop Pay checkout; these flows are not built into this tool.
When to Use the Storefront API
Choose the Storefront API when you need to:
- 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
The Storefront API gives you complete control over a single store's shopping experience.
Using Both Together
In many applications, you'll use both APIs together:
- Discovery with Catalog API: Use the Catalog API to help users find products across multiple stores. This works well for search interfaces, AI assistants, or comparison tools.
- Purchase with an appropriate checkout stack: Use the returned merchant link, Cart/Checkout MCP, Shop MCP or the Storefront API where appropriate. Catalog Search preserves the returned merchant URL and does not provide checkout.
This pattern is common in agentic commerce, where an AI agent searches broadly with the Catalog API and can use Cart/Checkout MCP, Shop MCP, Storefront API, or a returned merchant link for purchase.
Key Differences in Search
The search capabilities differ significantly between the two APIs:
Catalog API Search
Uses semantic search that understands intent. A search for “comfortable work from home chair” returns ergonomic office chairs even if those exact words aren't in the product title. Results come from all participating merchants.
Storefront API Search
Traditional keyword-based search within a single store's catalog. More predictable but less flexible. Returns only products from the specific store you're querying.