Shopify Catalog API
What is the Catalog API?
Shopify Global Catalog MCP provides cross-store discovery through JSON-RPC 2.0 tools: search_catalog, lookup_catalog and get_product. Shopify's REST Global Catalog API shuts off on November 2, 2026; this site uses the Global Catalog MCP. UCP 2026-08-25 is current.
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 typed media with sources, variants, seller, options, rating, pricing and inferred metadata
- Supports shipping destination filtering
- Includes shop metadata for attribution
Limitations
Understanding the API's limitations helps you build better integrations:
- Page size 1 to 50, cursor pagination, up to 1,000 results
- Products must meet Shopify's store and product requirements. Review eligibility in Sales channels > Agentic > Sources > Shopify Catalog.
- Requires authentication via Bearer token (JWT)
- Link to merchant url or checkout_url exactly as returned; never modify parameters or add redirects
- 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:
# Exchange client credentials; keep the returned access token private.
curl -X POST "https://api.shopify.com/auth/access_token" \
-H "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "grant_type=client_credentials" \
--data-urlencode "client_id=YOUR_CLIENT_ID" \
--data-urlencode "client_secret=YOUR_CLIENT_SECRET"
curl -X POST "https://catalog.shopify.com/api/ucp/mcp" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_catalog","arguments":{"meta":{"ucp-agent":{"profile":"https://shopify.dev/ucp/agent-profiles/2026-08-25/valid-with-capabilities.json"}},"catalog":{"query":"wireless headphones","context":{"currency":"USD"},"filters":{"price":{"min":5000,"max":20000},"available":true},"pagination":{"limit":10}}}}}'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 inspect raw UCP JSON and view this curl example.
Response Structure
result.structuredContent contains:
ucp: Negotiated version and capabilitiesproducts: Product array with id, title, description.html/plain, options, rating, price_range and optional list_price_rangemetadata: ML-inferred attributes (name and value), tech_specs, top_features and unique_selling_points; attributes may be absentcategories: Optional taxonomy identifiers; category data is sourced from the storefront catalog and is usually absent in global resultsmedia: Typed image, video, external_video and model_3d entries with preview and sources (url, mime_type, format, width, height, filesize)variants: Variants with seller, url, checkout_url, price, optional list_price, availability, options and placementpagination: cursor, has_next_page and total_count; return cursor in catalog.pagination.cursormessages: Informational, warning and error messages with code and content
Worker routes
GET /api/search?query=...&limit=10&cursor=...returns raw search structuredContent.GET /api/lookup-variant?variant_id=...returns raw get_product structuredContent. Useproduct_id=...&option.Color=Whiteto narrow variants by selected options; option selection requires the product GID.GET /api/lookup?ids=...returns raw lookup_catalog structuredContent (1–50 IDs).POST /api/ucp-proxyforwards allowed per-store catalog JSON-RPC calls.
Attributes are inferred by Shopify; categories come from storefront catalogs. Both may be absent from global results. Do not cache results or images. Preserve returned merchant URLs and label promoted variants.
Prices and merchant controls
list_price is the merchant compare-at price; list_price_range summarizes it. Values appear only when the merchant shares them in Catalog Mapping (Sales channels > Agentic > Sources > Shopify Catalog > Review product data mapping), compare-at exceeds the price, and regional display rules allow it (including the EEA exception). Sharing is on by default for most stores, but off where compare-at is used as MSRP.
Search capabilities
Global search supports filters.media entries of image, video, external_video and model_3d; filters.attributes (Color, Size, Target gender), rating, price_tier, and like for image or ID similarity. catalog_id selects a saved catalog on search_catalog. Media and attribute filter inputs and similarity search are not exposed in this site UI.
Inference and availability
Shopify labels description, options, metadata.* and condition as inferred. Availability includes available, documented status where supplied, and running_low. Global endpoints currently often omit categories and metadata.attributes; storefront enrichment exposes category IDs, tags and collections, not the completed category metafield values.
Auth and rate limits
Trust tiers are Token (Bearer JWT from Dev Dashboard credentials), Signed (RFC 9421 signatures with ECDSA P-256 and a hosted agent profile), and Anonymous. This worker uses Token tier for global requests: 5 requests per second per client shared across the three catalog tools. Respect Retry-After on HTTP 429. Anonymous traffic shares a per-IP pool; merchant MCP rate limits use JSON-RPC -32000. Token-tier merchant calls require Shopify-Buyer-IP; this site calls merchant endpoints anonymously.
External brands — beta
Global search catalog.sources can include shopify and external (beta, US shoppers only). External variants have source external, eligible.native_checkout false, a product-page URL, no checkout_url and no commission. get_product works; external lookup_catalog is coming later. This worker does not expose sources yet.
Promoted Placements — beta
Promoted Placements beta and Shop Campaigns require enrollment, accepted terms, Earn commission on a saved catalog, and catalog.catalog_id on search_catalog. Shopify merchant offers can include a 0.3% base plus merchant-funded commission in placement.commission.percentage.value. Label promoted results and preserve every returned merchant URL; external brands earn no commission.
Eligibility and checkout
Products appear in Shopify Catalog when store and product requirements are met: Starter plan or higher, a public store in good standing, and a published product with a title, image, price greater than zero and an identifiable URL in an allowed category. Unlisted, search-hidden and B2B-only products are excluded. Review eligibility and reasons at Sales channels > Agentic > Sources > Shopify Catalog, and review sharing in Catalog Mapping. Channel-specific rules also apply. Catalog Search links out using the merchant URL exactly as Shopify returns it. Shopify's agent stack also includes Cart MCP, Checkout MCP, Order MCP and Shop MCP for agent shopping and Shop Pay checkout; these flows are not built into this tool.
Shopify Catalog eligibility requirements
For complete API documentation, see the official Shopify Catalog API docs.