The Shopify Catalog API, explained: AI product search without scraping

If you have ever tried to build a shopping agent on top of a real storefront, you know the failure mode. You scrape the product page, parse the title and price out of the HTML, and it works on Tuesday. On Wednesday the merchant renames the product, swaps the theme, or A/B tests the layout, and your parser silently returns garbage. You are reverse-engineering a presentation layer that was never meant to be an API, and you are doing it across thousands of stores that all render differently.

Shopify's Catalog API, which reached general availability on June 17, 2026 as part of the Spring '26 Edition, is the platform-native answer to that problem. Instead of you scraping a rendered page, Shopify exposes the product catalog as structured, queryable infrastructure that AI agents can search and resolve directly. This post walks through what it does, how you call it, and why it matters if you are building AI search, discovery, or a shopping agent.

What the Catalog API actually is

Shopify describes the Catalog API as turning Shopify's product data into structured, queryable infrastructure for AI agents so they can discover products, understand them, and present them correctly across AI surfaces. The same catalog powers Shopify's own agentic placements (the announcement names ChatGPT, Copilot, and the Shop app) and is open to any developer building a new experience on top of it.

There are two scopes in the docs. The Global Catalog searches products across every Shopify merchant from a single endpoint, which is what you want for a broad shopping agent or a discovery surface. The Storefront Catalog scopes discovery to one merchant's storefront. This post focuses on the Global Catalog, since that is the one most agent builders reach for first.

One detail worth flagging up front: the docs present the Global Catalog MCP (a Model Context Protocol server) as the current, recommended way in. There is an older REST surface, and the search reference page for it carries an explicit deprecation notice pointing you to the MCP tools instead. So build against the MCP tools, not the REST paths.

The three tools

The Global Catalog MCP exposes three tools. Read them as a funnel: search to find candidates, look up to resolve known references, get-product to drill into one item before checkout.

• search_catalog finds products across all Shopify merchants. It accepts a text query, an image, both together (multi-modal), or a reference to find visually similar items.
• lookup_catalog resolves known identifiers, including product URLs, to their current catalog data. This is the endpoint that turns a product URL into a real catalog match instead of a scraped guess.
• get_product takes a product or variant ID and returns full detail: variant options, live pricing and availability, and seller checkout links.

Image search and multi-modal search

The headline capability is that search_catalog is not limited to keywords. According to the docs, you pass a text query in catalog.query and an image (or item reference) in catalog.like. Send only catalog.query for a classic text search. Send only an image in catalog.like for pure visual similarity. Send both for multi-modal search, where the text refines what the image alone would return.

Concretely: a shopper screenshots a jacket from Instagram and types "but in olive, under 150". Your agent passes the image in catalog.like, the text in catalog.query, and a price ceiling in catalog.filters, and gets back real, buyable products from across Shopify. No image classifier of your own, no per-store scraper.

1// ILLUSTRATIVE. A JSON-RPC tools/call to the Global Catalog MCP.2// Confirm the agent-profile and argument shapes against the live docs3// (spec version 2026-04-08): https://shopify.dev/docs/agents/catalog/global-catalog4{5  "jsonrpc": "2.0",6  "method": "tools/call",7  "id": 1,8  "params": {9    "name": "search_catalog",10    "arguments": {11      "meta": {12        "ucp-agent": { "profile": "https://your-agent.example/ucp-profile.json" }13      },14      "catalog": {15        "query": "olive utility jacket",16        "like": ["<image content or item reference>"],17        "filters": { "price": { "max": 15000 } },18        "context": { "address_country": "US" }19      }20    }21  }22}

URL lookup: from a link to a real match

The lookup capability is the quiet workhorse. Agents constantly handle product URLs: a user pastes a link, a model cites a page, a comparison flow collects a handful of candidates. lookup_catalog resolves those known identifiers (URLs included) into the real catalog records, so you read live pricing and availability rather than whatever was cached in the HTML when the page was last crawled. Shopify's announcement describes resolving a set of product URLs into actual Catalog matches, with the lookup path designed for bulk resolution in a single request.

This is the difference between "I think this product costs 49 dollars and is probably in stock" and "this variant is 4900 cents, ships to the buyer's country, and here is the checkout link." For an agent that is about to spend someone's money, that gap is the whole game.

Access, auth, and Sign in with Shop

Getting in is deliberately low-friction. The announcement is explicit: Catalog access takes an API key, with no approval required. In practice the docs describe creating an API key in the Dev Dashboard, which gives you a client ID and secret you exchange for a bearer token, then sending that token as an Authorization: Bearer header on requests.

The other piece is identity. The Catalog API supports Sign in with Shop, so a shopper can connect their Shop account and carry saved details into your experience. You get buyer identity without building and securing your own login and address book, which also unlocks more relevant, personalized results.

Why this beats scraping

Scraping treats a storefront's HTML as an accidental API. It is brittle by construction: it breaks on every theme change, it returns stale prices, it cannot see real-time inventory, and it has no concept of variants, shipping eligibility, or a checkout link. You spend your engineering budget maintaining parsers instead of building product.

The Catalog API inverts that. The data is structured at the source, it is live, and it is consistent across every merchant. Shopify also reports a commercial signal that matters if you are pitching this internally: AI searches powered by the Shopify Catalog convert at roughly twice the rate of those using scraped data. That tracks with intuition, since accurate price, availability, and a working checkout link remove exactly the friction that kills agent-driven purchases.

Where to start

1. Read the Global Catalog MCP docs and note the current spec version before you write anything.
2. Create an API key in the Dev Dashboard and confirm you can call search_catalog with a plain text query.
3. Add an image to catalog.like to see visual and multi-modal search, then resolve a real product URL with lookup_catalog.
4. Layer in Sign in with Shop once the search and lookup flows work end to end.

The mental model shift is the important part. You are no longer a guest scraping someone's storefront. You are querying commerce infrastructure that was built to be queried, which is a far more durable thing to build a product on.

Sources: Shopify, Agentic commerce for every developer: The Spring '26 Edition; Shopify Dev, Global Catalog MCP and About Catalogs.