About Shopify Catalog

Shopify Catalog contains products from merchants across the Shopify platform. The Catalog MCP serves as your foundation for agentic commerce, acting as the primary Discovery toolkit for implementing the Universal Commerce Protocol (UCP).

It allows you to 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 discovering products. Your AI agent translates buyer prompts and preferences into queries against a Catalog.

How you perform that query largely depends on the needs of your agent experience:

• Catalog MCP: For most use cases, we recommend building with the Catalog MCP. It provides tools for searching across all Shopify products, as well as retrieving details on individual products. Catalog MCP requires authentication via JWT tokens.
• Storefront MCP: Storefront MCP enables your agentic experiences to search for and discover products, but scoped to individual merchant stores. This can be beneficial to manage rate limits on Catalog MCP, or if your agent only serves a single shop. Storefront MCP doesn't require authentication.
• Catalog REST API: Catalog MCP wraps this REST API, but you can also query the Catalog API directly.

Whichever path you choose for your agents, each has two main endpoints that help buyers discover products: Search and Lookup.

Anchor to SearchSearch

Use Search to find products across all eligible Shopify merchants based on buyer preferences like keywords, price range, and shipping location. For each API this is performed with:

• Catalog MCP: The search_global_products tool
• Storefront MCP: The search_shop_catalog tool
• Catalog REST API: The Search endpoint

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, and so on)
• 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

Unique Universal Product IDs (UPIDs) and variant IDs for each Search result can be used to render product details pages that allow buyers to click through and explore options on those results. For each API this is performed with:

• Catalog MCP: The get_global_product_details tool
• Catalog REST API: The Lookup and Lookup by variant endpoints

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: Catalog queries are subject to rate limits.
• Inferred fields: Some fields might be inferred by Shopify's AI. These fields might not always be present or might have varying accuracy depending on the available product data. Inferred fields are marked throughout the Catalog MCP and API reference docs with the Inferred label.
• 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 return responses that 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 can also save a Catalog through Dev Dashboard, if your requests consistently contain the same parameters.

Catalog filter options include:

• 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.

You can run your catalog and see requests from the Preview panel. After you're happy with the results, click Save.

The parameters and filters you set for a saved catalog always take precedence when its slug is provided in Catalog Search operations.

Anchor to Next stepsNext steps

Search the Catalog

Walk through product discovery end-to-end.

Catalog MCP reference

Reference for UCP-compliant product discovery on Shopify.

Catalog REST API

Query the Catalog API directly.

Storefront MCP

Search products scoped to individual merchant stores.