Shopify Catalog API Playbook: What AI Agencies Should Actually Build

Shopify's agentic discovery surface is real and documented - but it is not the GTIN-and-JSON-LD story that circulated in September 2026. It is a UCP catalog exposed over MCP, keyed on Shopify's own product and variant GIDs. Agencies that build for the right pipe get the work; agencies that build for the wrong one ship a client integration that contradicts Shopify's own published usage rules.

There are three product-data pipes into AI-mediated shopping, and they carry different fields to different consumers: schema.org markup on the client's own pages, a catalog API that an agent queries at run time, and a merchant-pushed product feed. Treating them as one thing is the most expensive mistake in the agentic-commerce work landing on agency desks now, because each pipe has a different consumer, a different field contract and a different failure mode.

This playbook covers what Shopify actually documents about its Catalog API, where product identifiers really live, what the availability contract does and does not promise, and the build checklist to run before quoting a client. Every number and every quoted span below traces to the sources at the foot of the page; where the public evidence is absent, the gap is named instead of filled.

The shift: AI agents read records, not pages

Keyword SEO was a competition over a rendered page: title tags, header order, internal anchors, alt text, word counts. An agentic shopping flow barely touches any of it. The consumer is a program that calls an endpoint, receives a structured record, and decides from the fields it recognises. The page still exists, but it is no longer the interface the recommendation is read from.

The clearest statement of that split comes from the consultant who wrote the post everyone was quoting in September 2026: “An AI agent consuming the Catalog API reads records, not pages. Your carefully crafted collection-page copy does not travel through this channel. Only the structured product record does.” That is a SECONDARY source speaking, not a vendor standard - but the protocol the vendor ships says the same thing in its own words: “Agents use the merchant-provided content instead of scraping storefront HTML.” Both point at one deliverable for an agency: the product record has to be complete, typed and correct independently of how the collection page reads.

The practical consequence is a division of labour, not the death of SEO. The shift from keyword SEO to Shopify Catalog API structured data is not a rebrand of on-page work: Google Search still reads schema.org markup on the page, and that is where GTIN and MPN carry genuine requirements, while agents querying a catalog API read a JSON record instead. An agency that sells one discipline as a substitute for the other is selling half the work.

What Shopify actually ships: two catalogs, three tools

“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.”

The two surfaces are the same protocol spoken at different scopes: Global Catalog at POST https://catalog.shopify.com/api/ucp/mcp searches across all Shopify merchants, and Storefront Catalog at POST https://STORE_DOMAIN/api/ucp/mcp is scoped to a single store. Both are keyless, but every request carries an agent profile - meta.ucp-agent.profile - pointing at the caller's own UCP profile. There is no API key to buy and no paid tier that lifts the ceiling.

Three tools are documented on both surfaces, and they map onto the three moments of a shopping flow. Search is the entry point: “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.” Lookup is the refresh path - the docs describe it as the call to use when the agent already holds a product id and needs current data without running a new search - and it is the call an agency will abuse first, because batching is where the rate limits bite. A single Global Catalog request resolves up to 50 identifiers, while Storefront Catalog supports up to 10. Product detail is the last hop: “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.”

Two operating rules belong in the client's build, not in a footnote. “Catalog queries are subject to rate limits. Keyless catalog access doesn't support rate limit increases. To request a rate limit increase, go to the Shopify Help Center , select Chat with us , log in, and choose your Partner organization to contact us.” And the no-cache rules are unlike anything in a normal analytics build: “Don't cache search results : Catalog results reflect merchant preferences on pricing, availability, and presentation. Caching results isn't allowed.” An agency-side dashboard that snapshots catalog results for reporting is not a neutral tool - it is a documented breach of the surface's usage guidelines, and it is the kind of thing a client discovers from an email rather than from you.

The identity layer: GID and UPID, not GTIN

This is where the circulating framing gets it backwards, and it is the section that decides whether the integration works. Shopify's catalog keys on Shopify's own identifiers. A product carries a Global ID of the form gid://shopify/p/<upid>, search results are clustered by that Universal Product ID, and a variant carries a variant GID that the spec documents as “Global ID (GID) uniquely identifying this variant. Used as item.id in checkout.” The SEO-facing field is the handle, and the spec is candid about the hierarchy: “URL-safe slug for SEO-friendly URLs (e.g., 'blue-runner-pro'). Use id for stable API references.” The canonical page URL rides along as “Canonical product page URL.”

GTIN, MPN and barcodes are a different story, and the honest version of it is a count rather than an opinion. A case-insensitive scan of the seven Shopify catalog documentation pages fetched for this analysis returns zero occurrences of gtin, zero of mpn and zero of barcode; sku appears only in prose about linking to a variant URL, not as a returned field. The protocol permits more than the platform documents: the UCP variant schema defines a barcodes array whose types are “Barcode standard. Well-known values: UPC, EAN, ISBN, GTIN, JAN.” and the agent-side feed schema describes a barcode as “Machine-readable identifier attached to a variant, such as a GTIN or UPC.” Permission is not a guarantee. The UCP lookup capability is explicit about the difference: “Implementations MUST support lookup by product ID and variant ID. Implementations MAY additionally support secondary identifiers such as SKU or handle, provided these are also fields on the returned product object.” The protocol's own floor for a batch is also lower than Shopify's documented ceiling: “Implementations SHOULD accept at least 10 identifiers per request. Implementations MAY enforce a maximum batch size”.

So build the identity audit before anything else. Stable variant ids in the feed, a consistent handle-and-url pair per variant, and - where the client also sells on Google surfaces - GTIN and MPN in the page's schema.org markup, where the requirements are real and specific: “While you can use the generic gtin property for all GTINs, we recommend that you use the most specific GTIN that applies to your product, as this is the most accurate representation of the product.” and “Make sure the GTIN value is in the numerical form; we don't support the URL form for GTINs.” Google defines the manufacturer part number as “The manufacturer part number. This property uniquely identifies the product for a given manufacturer.” There is no equivalent definition anywhere in the Shopify catalog reference, the UCP schemas or the ACP schemas - which is why an agency that promises GTIN-based lookup against a Shopify catalog is promising a capability the documentation does not offer.

Availability is a signal, not a reservation

The claim that a catalog API gives buyers real-time stock is half true, and the missing half is the one that ends in a support ticket. Shopify documents an availability filter that is on by default: “When true (default), only sale-ready items are returned. Set to false to include unavailable items.” Variants carry an availability object, and the status vocabulary is an enum rather than a boolean: “Qualifies available with fulfillment state. Well-known values: `in_stock`, `backorder`, `preorder`, `out_of_stock`, `discontinued`.” The agent-side feed schema extends the same vocabulary: “Extensible fulfillment state for the variant. Known values include in_stock, limited_stock, backorder, preorder, out_of_stock, and discontinued.”

What no pipe promises is a hold on stock. The feed RFC lists reservation as a non-goal in as many words: “Availability in a feed does not reserve inventory. Reservation semantics, if any, occur during checkout.” It also settles which side wins when discovery data and checkout disagree: “Agents MUST treat checkout responses as authoritative even when they differ from feed data.” The freshness contract is a timestamp on the feed itself - “RFC 3339 timestamp for the most recent update applied to the feed.” - plus a readback that returns the current product set, so an agent can see how stale the catalog state it holds actually is.

Sell the accuracy of the availability signal, then. A build that maps inventory into the documented status ladder, keeps the feed's updated-at honest, and treats checkout as authoritative is defensible. A build that advertises real-time inventory sync through the Catalog API overstates a documented non-goal, and the first oversold item is the client's problem, not the platform's.

Three pipes, three jobs

Keeping the pipes separate is the whole discipline. They share a product, not a contract.

Two surface-specific rules are worth memorising because they contradict the instinct to reuse copy. Price display is not portable: “Unlike product snippets, merchant listing experiences require a price greater than zero.” while catalog search returns price ranges in minor units. And the feed path is not a second copy of the page - Google's own framing for its AI surfaces is that the same Merchant Center data already does the discovery work: “Use your existing Merchant Center account shopping feeds to capture high-intent customers during discovery.” You remain the merchant of record and keep the customer relationship; the catalog is the input.

One absence deserves its own line, because it is the most common error in agency drafts. The string json-ld does not appear anywhere in Shopify's catalog documentation, the UCP specification or the ACP specification as fetched for this analysis - zero hits across 22 files. JSON-LD is a Google-side contract, not the agentic-catalog contract. A sentence telling a client that AI agents read their JSON-LD needs to name the surface it means, or it is unsupported.

Implementation examples for each pipe

The shapes below are illustrative, built from the field names each specification documents - they are starting points for a client build, not vendor-published samples, and endpoint behaviour should be re-verified against the current reference before anyone commits to it. Shopify states that catalog endpoint URLs are subject to change.

1. The page: schema.org markup for Google merchant listings

{
  "@context": "https://schema.org",
  "@type": "Product",
  "name": "Blue Runner Pro",
  "sku": "BRP-100",
  "gtin13": "0123456789012",
  "mpn": "BRP-100-M",
  "brand": { "@type": "Brand", "name": "Example" },
  "offers": {
    "@type": "Offer",
    "price": "89.00",
    "priceCurrency": "USD",
    "availability": "https://schema.org/InStock"
  }
}

Use the most specific GTIN property that applies, in numeric form, and keep the value identical on every variant that shares it. This is the only one of the three pipes where a missing GTIN is a documented defect rather than an optional nicety.

2. The agent pipe: a UCP catalog call

POST https://catalog.shopify.com/api/ucp/mcp
{
  "meta": { "ucp-agent": { "profile": "https://client.example/ucp-profile.json" } },
  "tool": "search_catalog",
  "arguments": {
    "query": "waterproof trail running shoe",
    "filters": { "available": true, "ships_to": "US" }
  }
}

Then refresh by identifier rather than re-searching, batch the ids, and keep a local map from the client's own catalogue to the GIDs the surface returns. Do not build a lookup path that assumes a GTIN, an MPN or an SKU will resolve - the protocol treats those as optional secondary identifiers and Shopify's catalog pages do not document them at all.

3. The checkout pipe: an ACP feed upsert

PATCH /feeds/<feed_id>/products
{
  "products": [
    {
      "id": "sku-or-stable-variant-id",
      "title": "Blue Runner Pro - Medium",
      "availability": { "status": "in_stock" },
      "barcodes": [ { "type": "GTIN", "value": "0123456789012" } ]
    }
  ]
}

The upsert semantics are the trap: “Products omitted from the request remain unchanged.” Removing a product therefore needs an explicit unavailable or discontinued state, or a full replacement - silence is not a withdrawal. And a variant id has to survive the round trip, which the RFC states as a requirement rather than a preference: “Variant IDs SHOULD be stable across feed updates. If a merchant uses different identifiers for catalog variants and checkout items, the merchant MUST provide a deterministic mapping outside this RFC or ensure the feed `Variant.id` is accepted as an ACP checkout item ID.”

Finally, decide which fields are yours and which are generated. Shopify labels the difference and the label matters at pitch time: “Some Global Catalog response fields are generated or enriched by Shopify, and are marked Inferred in the reference. These fields might not always be present or might vary in accuracy depending on available product data. Treat them as discovery and merchandising signals, not as merchant-authored source text.” An agency that treats a generated description as client copy, or assumes a labelled attribute will always be present, is building on sand.

The attribution on this story is wrong

The post that carried this topic into agency feeds in September 2026 was widely shared as a statement from Shopify's chief executive, and that attribution is wrong. The post was written by the account TaylorSicard, published 2026-09-16 at 12:02:43 UTC, and the tweet id attached to the claim in circulation - x.com/tobi/status/2100134442111516672 - returns HTTP 404, while a control request in the same run returned HTTP 200, so the endpoint was working and the id was dead.

The Shopify Catalog API is how your products surface inside AI agents. Clean, identifier-rich, structured data gets recommended. Thin or image-only data gets skipped. No algorithm to game, just data quality. - TaylorSicard, X, 2026-09-16T12:02:43Z

Two further details compound the correction. The post links to a blog article that is dated “Published June 2026” - a re-share of earlier consultant material rather than a new corporate standard - and no Shopify executive statement matching that framing was found while preparing this page. That is absence of evidence, not proof of absence, and it is why this page cites the post as SECONDARY commentary and leads with the specifications instead. If a client forwards you the claim, the useful answer is not who said it but what the vendor's own docs actually return.

The build checklist for AI agencies

Ask for Shopify agentic commerce best practices and you will usually be handed a page-side checklist. The build that decides whether an agent can actually find and buy the product runs in this order - the first three items are corrections to the brief most clients arrive with, and the rest are build steps.

1. Separate the three pipes in the scope document. One section per path, no mixing of page markup with catalog feeds, and a named consumer for each.
2. Drop the real-time inventory promise. Sell availability-signal accuracy and the documented status ladder instead.
3. Drop the GTIN-lookup promise. Design on GIDs, and treat SKU or barcode lookup as a capability to probe per surface, not an assumption.
4. Audit the identity layer first. Stable variant ids, one handle and canonical URL per variant, and GTIN or MPN in page markup wherever the client also sells on Google surfaces.
5. Map the taxonomy to leaf nodes. Filtered discovery is taxonomy-id driven; a leaf-node mapping error silently removes a product from results instead of erroring.
6. Treat the variant as the unit of work. Variants carry the price, the options, the media, the availability state and the purchasable identifier.
7. Honour the caching rules in the architecture. Images are rendered live from the merchant's listing, and catalog results may not be cached - which rules out the snapshot-reporting pattern most agency dashboards are built on.
8. Design for rate limits from day one. Batch lookups instead of re-searching, keep a local id map, and note that keyless access has no rate-limit-increase path.
9. Give the client an availability ladder, not a boolean. Map inventory into the documented statuses and keep the feed's updated-at timestamp honest.
10. Ship the same facts on the page and in the pipe, then test both. Validate the markup against Google's merchant-listing requirements and exercise the catalog surface with the agent profile flow.
11. Instrument what you cannot see. Nothing in these documents exposes per-agent ranking for third-party agents; claiming rank visibility across assistants would be speculation.
12. Write the disclaimer into the deliverable. Platform APIs change, and endpoint behaviour has to be re-verified against the vendor's documentation before a client build.

The commercial framing sits one level above this list, and this page is the technical half of it: see the service-line case for the same platform and what changed at the MCP protocol layer in 2026. The scope here is not a page refresh - it is an identity and availability data project with a validation harness, and it should be priced and staffed like one. The step-by-step version of this validation work, with the test and the captured response behind each stage, is published as a Shopify catalog readiness audit checklist.

What to stop promising clients

• That the Catalog API delivers real-time inventory. Reservation is a documented non-goal.
• That GTIN or MPN is what makes an agent recommend a product. Neither is a documented field of the catalog surface; the identity contract is GID, handle and URL.
• That AI agents read JSON-LD. No JSON-LD reference exists in the Shopify, UCP or ACP material reviewed; the markup matters on Google's surfaces.
• That ranking inside third-party assistants is measurable from these APIs. It is not exposed.
• That a cached snapshot of catalog results is a harmless reporting convenience. It is not permitted.

Frequently asked questions

Sources

• Shopify: catalog documentation index (About Catalogs): shopify.dev
• Shopify: Global Catalog MCP: shopify.dev
• Shopify: Storefront Catalog MCP: shopify.dev
• Shopify: Global Catalog extension: shopify.dev
• Shopify: Storefront extension: shopify.dev
• UCP specification overview: ucp.dev
• UCP schemas (product, variant, availability): raw.githubusercontent.com
• ACP product-feed RFC: raw.githubusercontent.com
• ACP feed JSON Schema (2026-04-17): raw.githubusercontent.com
• Google: Universal Commerce Protocol (UCP) Guide: developers.google.com
• Google: Merchant listing (Product, Offer) structured data: developers.google.com
• TaylorSicard: the Shopify Catalog API post the X thread links to (published June 2026): taylorsicard.com
• X post, TaylorSicard, 2026-09-16T12:02:43Z: x.com
• CatalogScan: Agentic Storefronts checklist (third-party audit rubric): catalogscan.com

Accuracy note: endpoint URLs, field names and identifier behaviour on this page were verified against the sources above on September 18, 2026, from saved copies of each document. Nothing here is legal, tax or platform-policy advice. Shopify states that catalog endpoint URLs are subject to change, so re-verify against the vendor's current documentation before a client build. Where the public documentation is silent - GTIN, MPN and barcode fields on Shopify catalog responses - this page reports the absence as a count rather than an inference about intent.