Shopify UCP Global Catalog: Lessons From Building a Catalogue Explorer
Shopify's Global Catalog is no longer a slide in a keynote. It is a live MCP endpoint agents can query today, and the product records it returns are built from the same admin data merchants already maintain.
I spent several weeks building the UCP Catalogue Explorer, a reference app that searches Global Catalog through the Universal Commerce Protocol, renders results on an infinite WebGL canvas, and stress-tests pagination, variant resolution, and data quality in the wild. The protocol docs describe the happy path. Production catalog search surfaces gaps in product architecture, channel visibility, and client-side discovery patterns that most merchants have not audited yet.
This article validates those findings against UCP specification text, Shopify's catalog documentation, and the explorer codebase. If you sell on Shopify, the practical question is not whether UCP exists. It is whether your catalog data and channel rules still make sense when discovery happens outside your theme.
Introduction
Agentic commerce runs on two layers: Catalog for discovery and Checkout for authoritative transactions. UCP defines how agents call both. Shopify co-developed the protocol with Google; Global Catalog implements dev.ucp.shopping.catalog.search and dev.ucp.shopping.catalog.lookup at https://catalog.shopify.com/api/ucp/mcp.
Shopify's own guidance is explicit on a point many merchants miss: catalog responses reflect current terms but are not binding commitments. The UCP catalog overview states that eligibility and policy enforcement must occur at checkout time using binding transaction data. Agents can see a product. Checkout decides whether the price, discount, or buyer qualification actually applies.
That separation is why our explorer is useful as a diagnostic surface. It shows what discovery layers see before checkout guardrails run, similar to how the Shopify Claude connector exposes messy admin data to AI interpreters without fixing the underlying catalogue.
Try the tool: Launch the UCP Catalogue Explorer (opens in a new tab). On-site overview: /tools/ucp-catalogue-explorer/.
What the explorer actually does
The app is a Next.js reference implementation, not a production shopping agent. Each search runs server-side through UCP's search_catalog with an agent profile, country context, and available: true shipping filters. Product images render from merchant CDN URLs in the browser. Results are not cached, matching Shopify catalog usage guidelines.
Results open on an infinite canvas. As you move through space, the client requests more inventory. That UX exposed pagination limits quickly, which drove most of the engineering work.
| UCP tool | Role in the explorer | Spec note |
|---|---|---|
| search_catalog | Category search and diversified "load more" batches | Cursor pagination; limit is not guaranteed count |
| lookup_catalog | Media enrichment when search payloads lack images | Up to 50 IDs (Global); client correlation via inputs |
| get_product | Product detail modal, variant expansion, option availability | selected + preferences for interactive narrowing |
Lesson 1: Product data architecture matters more than ever
My first assumption was that Global Catalog would return neat, complete product cards. Often it does not. Search payloads frequently include a featured variant and partial option context. Descriptions may be thin. Media arrays are sometimes empty until a follow-up lookup or get_product call.
That behaviour matches the spec. UCP lookup returns one featured variant per product in batch responses. get_product returns a subset of variants matching effective selections, not necessarily the full admin matrix. When selectable option values outnumber returned variants, the client must iterate.
Our catalog client detects that gap with shouldExpandVariants() and fires parallel get_product calls per option value, merging variant lists afterward. Without that expansion step, the modal showed a single SKU for products with six sizes or multiple denominations.
Variants split across products
We also saw catalog clustering effects: related SKUs appear as separate product entries or offers under Universal Product IDs rather than one clean parent product. That is tolerable for comparison shopping agents. It is painful for merchants who already struggle with duplicate listings, legacy splits, or marketplace-style variant rows in admin.
If your Shopify catalogue has:
- duplicate product records for colour or size splits,
- incomplete option names,
- missing GTINs or taxonomy categories,
- thin descriptions copied from supplier feeds,
agents will inherit that mess. Shopify's catalog blog post is clear: clearer, more specific, current data makes matching easier. It does not guarantee ranking, but weak data is a structural disadvantage.
This connects directly to stack work we already do on audits: metaobject models, variant architecture, and PIM-like discipline inside Shopify admin. See Fix Metaobject Filters and Storefront Search and The Anatomy of a High-Performance Shopify Theme for related foundation patterns.
Lesson 2: Storefront visibility and catalog eligibility diverge
Shopify states eligible products can appear in Catalog by default, with merchant controls in Agentic admin for which AI channels receive data. That is a different control plane from Online Store theme navigation or collection membership.
While testing searches across categories, we surfaced products that looked operationally internal: staff-style naming, aggressive price gaps, or positioning inconsistent with public merchandising. Some offers included checkout URLs. In other cases checkout guardrails blocked or adjusted the cart as expected.
Because catalog is provisional and checkout is authoritative, the risk pattern is not "agents bypass Shopify forever." The risk is ** unintended discovery**: buyers or agents reaching SKUs you treated as operational, wholesale, or hidden from the storefront without reviewing Catalog eligibility holistically.
Merchants should audit product status and publishing rules, Agentic Storefronts channel toggles, discount architectures that assume a logged-in staff tag, and B2B or segmented catalogs that relied on theme gating alone. The same catalogue hygiene problems that drive app sprawl and margin erosion become visible faster when an agent reads your product graph directly.
I will expand this section with anonymised examples in an update once final test cases are documented. If you have seen similar patterns, treat Agentic admin as part of your channel mix, not an experimental sidebar.
Lesson 3: UCP is early days for deep browse UX
From a developer perspective, UCP catalog tooling is usable but young. Shopify renamed Storefront MCP tools to UCP shapes in Spring 2026 (search_catalog, lookup_catalog, get_product), with legacy names deprecated until 15 June 2026. Forum threads document breaking changes mid-rollout with little notice, which is the normal cost of standing on a moving spec.
Documentation quality is improving, but edge behaviour still has to be discovered by building.
Pagination became the bottleneck
The UCP search spec defines opaque cursor pagination. has_next_page is required; limit may be clamped silently. That is fine for "next page" buttons. It is awkward for infinite spatial browse, where users expect a continuous stream of new products.
In the explorer, cursor-only loading repeated inventory within a few batches. The codebase documents this directly: Global Catalog cursor pagination is treated as unreliable for deep scroll.
Our response was diversified search planning rather than fighting the cursor forever.
Hint harvesting and query diversification
When a cursor stops yielding new product IDs, the client increments a batch counter and calls planDiversifiedSearch():
- Hint strategy (even batches): harvest tokens from already-loaded product titles and seller names via
harvestSearchHints(), then append a rotating hint to the base query ("running shoes Nike","running shoes Brooks", etc.). Hints exclude words already in the original query to avoid noise. - Price band strategy (odd batches): keep the original query but shift
filters.pricethrough logarithmic bands (under $25, $25–$50, $50–$100, and so on). - Query reshape fallback: if no hints exist yet, rotate token order, drop leading or trailing tokens, or isolate a single keyword from multi-word queries.
Each diversified batch also sets context.intent to describe the exploration purpose, which UCP allows as a provisional buyer signal.
The infinite canvas tracks duplicate and empty batches, stops after configurable thresholds, and falls back from cursor mode to diversification when the same cursor appears twice. That combination turned a broken infinite scroll into a usable demo, at the cost of more API calls and more client complexity than the spec implies.
If you are designing agent browse UX, plan for discovery orchestration on the client. Do not assume cursor pagination equals inexhaustible inventory.
lookup_catalog and get_product rough edges
Additional limits we hit in code:
- 422 errors on large
lookup_catalogbatches, mitigated by batch sizes of 10 for media enrichment and 50 max otherwise. - Variant expansion requiring multiple
get_productcalls withpreferencesordering (size and denomination options relaxed last, matching UCP's "drop from end of preferences list" rule). - Rate limits (429) surfaced to users because catalog results cannot be cached away.
These are implementation realities, not spec violations. They do affect cost and latency models for agents.
Current UCP catalog limitations worth planning for
| Area | Limitation | Practical impact |
|---|---|---|
| Pagination | Cursor opaque; page size not guaranteed; overlap possible | Infinite browse needs diversification or filters, not cursors alone |
| Lookup batch size | 10 IDs (storefront), 50 IDs (global); larger batches may 422 | Media enrichment and cart validation must chunk requests |
| Variant detail | Search/listing payloads feature one variant; full matrix needs get_product | PDP-style agents need extra round trips per product |
| Caching | Shopify forbids caching search results and reusing CDN images offline | Higher API volume; no CDN scrape shortcuts |
| Personalisation | Buyer-linked personalised search marked "coming soon" in docs | Today’s results are context hints, not account-aware catalogues |
| Spec churn | Tool renames and schema shifts during 2026 rollout | Budget maintenance time; pin UCP version in agent profiles |
| Authority boundary | Catalog ≠ checkout for price, discounts, eligibility | Merchants must enforce commercial rules at checkout, not assume catalog hiding |
Community reports mirror this fragility. Shopify Developer Community threads from April 2026 document overnight search_shop_catalog removals and mandatory migration to UCP tool names with wrapped catalog arguments, so production agents need monitoring and pinned UCP versions in agent profiles rather than one-off integration sprints.
What merchants should do now
- Open Agentic admin and confirm which channels receive catalog data. Treat it like a sales channel audit, not a future feature.
- Review product records for duplicate splits, weak descriptions, missing media, and option naming. Agents amplify catalogue debt.
- Map checkout guardrails for staff, VIP, or wholesale pricing. If discovery can reach a SKU, assume an agent might try
checkout_url. - Developers: implement chunked lookup, variant expansion, and diversified search if you need browse depth beyond the first page.
For a structured pass across theme, apps, data model, and channels, start with a Shopify stack audit rather than patching individual SKUs reactively.
Conclusion
Building the UCP Catalogue Explorer did not just produce a demo. It surfaced how agentic discovery stress-tests catalogue architecture that was originally designed for human theme navigation.
UCP gives developers a standard vocabulary. Shopify Global Catalog gives it real inventory. Neither removes the merchant obligation to maintain clean product data, explicit channel rules, and checkout enforcement for sensitive pricing.
The explorer is live for developers who want to reproduce the behaviour: UCP Catalogue Explorer. If you want help auditing how your stack appears to agents and what to fix first, book a stack assessment with oContis Studio.
