About Catalogs

Shopify provides two catalog interfaces for AI agents to discover and retrieve products. Global Catalog searches across all Shopify merchants, while Storefront Catalog is scoped to a single merchant's store. Both implement the UCP Catalog capability, but they differ in scope, authentication, and available features.

Anchor to Catalog interfacesCatalog interfaces

Choose the catalog interface based on whether your agent needs to search across Shopify or within a single storefront.

Anchor to ToolsTools

Both catalog interfaces expose the same three tools. Which one you call depends on what your agent knows at the time of the request.

Anchor to [object Object]search_catalog

Find products by keyword. Use this when a buyer describes what they want in natural language. Global Catalog returns products from across all Shopify merchants, clustered by Universal Product ID (UPID); Storefront Catalog returns products scoped to a single store.

• Global Catalog MCP: search_catalog
• Storefront Catalog MCP: search_catalog

{
  "catalog": {
    "query": "organic cotton sweater",
    "filters": {
      "ships_to": {"country": "US"},
      "available": true
    }
  }
}

{
  "catalog": {
    "query": "organic cotton sweater"
  }
}

Anchor to [object Object]lookup_catalog

Retrieve products or variants by identifier. This is most useful at query time when your agent already has a product ID (for example, from a prior search result, a shared link, or a stored reference) and needs fresh data without running a new search. A single Global Catalog request resolves up to 50 identifiers, while Storefront Catalog supports up to 10. Unresolved IDs are reported in messages.

• Global Catalog MCP: lookup_catalog
• Storefront Catalog MCP: lookup_catalog

{
  "catalog": {
    "ids": [
      "gid://shopify/p/7f3a2b8c1d9e",
      "gid://shopify/ProductVariant/12345678"
    ],
    "context": {"address_country": "US"}
  }
}

{
  "catalog": {
    "ids": ["gid://shopify/Product/1001"]
  }
}

Anchor to [object Object]get_product

Retrieve full details for a single product, including all option combinations with availability signals and checkout links. Call this after a buyer selects a product from search or lookup results.

Pass selected to anchor a specific variant and preferences to control how the server relaxes selections when an exact match isn't available.

• Global Catalog MCP: get_product
• Storefront Catalog MCP: get_product

{
  "catalog": {
    "id": "gid://shopify/p/7f3a2b8c1d9e",
    "selected": [{"name": "Color", "label": "Black"}],
    "preferences": ["Color", "Size"]
  }
}

{
  "catalog": {
    "id": "gid://shopify/Product/1001",
    "selected": [{"name": "Color", "label": "Blue"}]
  }
}

Anchor to Usage guidelinesUsage guidelines

These guidelines apply to both catalog interfaces (Global Catalog and Storefront Catalog):

• 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. Keyless catalog access doesn't support rate limit increases. To request a rate limit increase, use an authenticated API key and contact us through Dev Dashboard.
• Inferred fields: Some fields might be inferred by Shopify's AI and might not always be present or have varying accuracy depending on available product data. Inferred fields are marked throughout the Catalog MCP and API reference docs with the Inferred label.
• Endpoint URLs might change: API URLs are subject to change.

Anchor to Saved CatalogsSaved Catalogs

Saved Catalogs are a Global Catalog feature.

By default, Global Catalog queries return products from any eligible merchant on the Shopify platform. You can narrow these results at runtime using parameters like price range, shipping origin, shops, or product taxonomies.

If your agent consistently uses the same parameters, then you can save a Catalog configuration in the Dev Dashboard to avoid repeating them on every request.

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 test your catalog configuration in the Preview panel. After you're happy with the results, click Save.

If a slug for a saved catalog is provided in Catalog Search operations, then its parameters and filters always take precedence.

Anchor to Earn with paid placementsEarn with paid placements

You can opt into promoted placements and earn revenue on attributed purchases you drive. Placements use your existing integration, extend the Global Catalog, and conform to the UCP Catalog specification.

Placements are a response-scoped extension of the existing Global Catalog response. A request field opts a call into placements. Promoted placement variants include a placement object, which is omitted for organic variants. Attribution is carried in the variant's url.

Anchor to How it worksHow it works

1. Register for placements: Shopify enrolls your developer account. Your existing Global Catalog integration stays the same.

2. Request placements: Send placements: ["affiliate"] on search_catalog calls to blend promoted placements into the ranked results. Omit placements for organic-only results.

   POST

   https://catalog.shopify.com/api/ucp/mcp

   Copy

   9

   1

   2

   3

   4

   5

   6

   {

   "catalog": {

   "query": "trail running shoes",

   "placements": ["affiliate"]

   }

   }

3. Identify promoted placements: Promoted placement variants include a placement object. Organic variants omit it. When Shopify discloses the commission, placement.commission.percentage.value returns the rate, such as 1.5 for a 1.5% commission.

   Copy

   9

   1

   2

   3

   4

   5

   6

   7

   8

   9

   {

   "id": "gid://shopify/ProductVariant/45012",

   "price": { "amount": 120, "currency": "USD" },

   "seller": { "id": "gid://shopify/Shop/42", "name": "RunWorld" },

   "placement": {

   "type": "affiliate",

   "commission": { "percentage": { "value": 1.5 } }

   }

   }

4. Send the buyer to the variant URL: Use the variant's url to send the buyer to the merchant's canonical product page with the correct SKU selected. Tracking is carried in the URL.

   • utm_source=shopify: Always present. Identifies Shopify-sourced traffic so the merchant can attribute it, regardless of placement.
   • utm_medium=catalog: Always present. Identifies Global Catalog traffic. Present on both organic and promoted placement URLs.
   • shclid: Always present. Identifies the click for attribution. Present on every Global Catalog variant URL, organic or promoted placement.
   • shdid: Present only on promoted placement URLs. Identifies the developer for attribution and payout. Organic variants omit it.

   variant URL examples

   OrganicPromoted placement

   Copy

   9

   1

   https://{merchant_site}/products/{product_handle}?variant={v}&utm_source=shopify&utm_medium=catalog&shclid={click_id}

   9

   1

   https://{merchant_site}/products/{product_handle}?variant={v}&utm_source=shopify&utm_medium=catalog&shclid={click_id}&shdid={developer_id}

   Organic

   https://{merchant_site}/products/{product_handle}?variant={v}&utm_source=shopify&utm_medium=catalog&shclid={click_id}

   Promoted placement

   https://{merchant_site}/products/{product_handle}?variant={v}&utm_source=shopify&utm_medium=catalog&shclid={click_id}&shdid={developer_id}

5. Earn commission: Shopify attributes conversions on a 7-day click window and pays out monthly. You need KYC verification before Shopify pays out.

Anchor to Global Placement objectGlobal Placement object

Promoted placement variants include a placement object in search_catalog responses. Organic variants omit it. Commission is optional. If Shopify omits commission, then the rate is private, not zero.

Anchor to Response exampleResponse example

A search_catalog response to a query with placements: ["affiliate"] can include promoted placement variants and organic variants in the same result set. Only promoted placements include the placement object and the shdid attribution parameter. Organic variants omit both. The shclid click ID is present on every variant URL.

Anchor to Next stepsNext steps

Global Catalog MCP reference

Reference for UCP-compliant product discovery on Shopify.

Storefront Catalog MCP reference

Search products scoped to individual merchant stores.

Search the Global Catalog

Walk through product discovery end-to-end.