About Shopify Catalog

Shopify Catalog contains products from merchants across the Shopify platform. The Catalog API and MCP server are your foundation for agentic commerce, letting you search for products, refine the results with filters, and lookup details on individual products. That information can be used to render product details pages that allow buyers to click through and explore options on those results before adding items to their carts.

Anchor to How it worksHow it works

Building agentic commerce experiences starts with Shopify Catalog. Your AI agent translates buyer prompts and preferences into queries against the Catalog. You can query the Catalog API directly, or use the Catalog MCP server.

The Catalog API has two main endpoints that help buyers discover products: Search and Lookup.

Anchor to SearchSearch

Use the Search endpoint to find products across all eligible Shopify merchants based on buyer preferences like keywords, price range, and shipping location.

Search results are clustered by Universal Product ID (UPID), which prevents duplicate products from appearing when the same item is sold by multiple merchants. Each result includes:

• Product details (title, description, images)
• Price range across all offers
• Available options (size, color, etc.)
• A list of shops selling the product with their specific prices and checkout URLs
• Universal Product ID, used with the Lookup endpoint to retrieve data on a specific product

Anchor to LookupLookup

The unique Universal Product IDs (UPIDs) for each resulting product from Search can be used to render product details pages that allow buyers to click through and explore options on those results.

This comprehensive look into individual products is provided by the Lookup endpoint. It allows your buyers to get detailed information about a specific product using its Universal Product ID, and can be useful when they want to see all available options before adding an item to their cart.

Lookup has also been designed to help your agents render product detail pages with relaxation logic around available options with options preferences.

The Lookup endpoint returns comprehensive variant information, including:

• All available product options and option combinations
• Detailed pricing for each variant
• Checkout URLs for each shop's offer
• Robust data about the product to empower agent-to-buyer conversations (for example description, key features, and tech specs)

Anchor to Usage guidelinesUsage guidelines

These usage guidelines apply to both the Catalog MCP server and the Catalog API:

• Don't cache or re-use images: Images may only be used in connection with the related merchant's product listing and must be rendered in real-time (not downloaded to servers).
• Don't cache search results: Catalog results reflect merchant preferences on pricing, availability, and presentation. Caching results isn't allowed.
• Rate limits: During the testing phase, Catalog queries are subject to rate limits.
• Inferred fields: Some fields might be inferred by Shopify's AI. These fields are marked in the inferredFields array.
• Endpoint URLs may change: API URLs are subject to change.

Anchor to Saved CatalogsSaved Catalogs

For both the Catalog MCP server or the Catalog API, your agents can search Shopify's global catalog of products. These requests will return responses that will contain products from any of the eligible merchants on the Shopify platform.

You can modify these requests with parameters at runtime, whether that be price range, shipping origin, shops, or Product Taxonomies, to better suit your buyers.

You may find that your requests consistently contain these same parameters and that you would benefit from saving these queries. In this case, it's possible to save a Catalog through Dev Dashboard.

Click Create a catalog. From this page you can manage:

• Inputs: whether the Catalog queries all of Shopify or products from a specific store.
• Overrides: custom filters applied to queries that limit results by attributes like only those belonging to certain Taxonomy category IDs.
• Access: where the custom URL for your saved Catalog can be retrieved, as well as requesting access to additional features related to agentic commerce.

The changes you make can be run in real-time in the Preview panel, so you can test the behavior of the Catalog you are saving.