Here is the structural fact most teams get wrong about Shopify's agent surface: there is not one catalog. There are two.
They sit on different endpoints, return different fields, accept different filters and rank by different logic. Pushing the same optimisation work at both gets neither right.
Key takeaways
- Global Catalog (
catalog.shopify.com/api/ucp/mcp) spans the whole ecosystem, clusters offers by UPID and accepts nine filter families. - Storefront Catalog (
{yourdomain}/api/ucp/mcp) returns only your products and accepts three filters: categories, price, available. - UPID clustering means the buy box is back in commodity categories — except the referee is now an agent.
ships_fromfilters by the merchant's country of origin. Cross-border sellers can be excluded in a single call.attributesaccepts Color, Size and Target gender only. Every other attribute name is ignored and reported back inmessages.
Global Catalog: the cross-store battlefield
Two mechanisms define it.
Clustering by UPID. The official wording: "Results are clustered by Universal Product ID (UPID) and include offers from multiple merchants." Identical products collapse into one cluster and several merchants' offers compete inside it. If you sell commodity or widely-distributed goods, you are no longer presenting a product — you are presenting an offer against named rivals, and brand, price, rating and fulfilment decide it.
It has also begun indexing inventory from merchants who are not on Shopify at all, marked source: "external" in the response.
Nine filter families. This is the real optimisation surface:
Filter | Accepts | What it means for you |
|---|---|---|
| Standard taxonomy GIDs | Mis-categorised products never enter the candidate set |
| Color, Size, Target gender — only these three | Custom metafield attributes are ignored |
| Minor units of the context currency | Market and currency configuration decides correctness |
| low / medium / high, relative to the category | A premium brand can be found deliberately |
|
| Computed per variant, not as a product average |
| new / secondhand | Matters for refurb and resale catalogs |
| Destination country | Market configuration must be real |
| Merchant's country of origin | A new, excludable dimension for cross-border sellers |
| image / video / external_video / model_3d | Rich media becomes an entry ticket, not a description |
| Up to 1,000 shop GIDs | Enables brand-scoped agent experiences |
Two of these deserve a second read.
rating is per variant. The threshold is satisfied if at least one variant meets it, with a minimum review count. A healthy store average hides nothing and helps nothing; your hero variant's rating is its own KPI.
ships_from is a country filter on you. A buyer, or an agent acting for a buyer, can now ask to see only goods shipping from particular countries. That capability did not exist in classic search in this form. For cross-border sellers the mitigations are concrete: make overseas warehouse fulfilment real in configuration, and if you cannot, publish honest delivery facts so the agent has something to say.
Storefront Catalog: being read, not compared
Your own endpoint returns only your products. On a live store it exposed 15 tools covering catalog, locations, cart, checkout and orders. Its filters are three: categories, price, available. No rating filter, no media filter, no price tier.
That is the right design — nobody filters one store's inventory by rating — but it changes what the endpoint is for. Here you are not competing; you are being read. The quality bar is completeness and accuracy rather than competitive positioning. The field list is short enough that we counted it: 14 top-level fields, with ratings, reviews, video and 3D appearing zero times.
Splitting the work
Objective | Global Catalog | Storefront Catalog |
|---|---|---|
Be found at all | Standard taxonomy, title carries the category term, GTIN filled | Taxonomy and availability accurate |
Survive filtering | Hero-variant rating and review count, correct price tier, rich media present, ships-to and ships-from real | Stock state truthful |
Win the comparison | Brand recognition via | Not applicable |
Close in the chat |
| Cart and checkout tools reachable |
The common failure is doing column two's work and expecting column one's outcome. Cleaning up your own product data does not get you through a rating filter you never looked at.
Where paid fits
The Global Catalog also has a paid slot. Promoted placement is blended into the ranked results rather than shown as a separate block, with Shopify paying a 0.3% base commission and merchants able to top it up. We cover the mechanics and the disclosure rules in promoted placement. It is worth knowing before you benchmark your "organic" agent visibility, because the two are not cleanly separable.
FAQ
Do I need to do anything to be in the Global Catalog? You need to be eligible: a paid plan, no password protection, complete terms, privacy and returns policies, agentic storefront terms accepted, products published to Online Store or a headless channel, each with a title, at least one image and a price above zero. The Fall '26 release added a self-check for store eligibility.
Which catalog do ChatGPT and Gemini use? Shopping surfaces generally reach the cross-store catalog; an agent browsing a specific brand's store can reach that store's own endpoint, and in-browser agents use the WebMCP tools on the page. Assume all three paths exist simultaneously.
Is UPID clustering the same as a marketplace buy box? Functionally similar, structurally different. There is no single winner slot — the cluster carries several offers. But an agent summarising a cluster in prose will usually name one, which is the practical equivalent.