Shopify currently documents Global Catalog and Storefront Catalog as two implementations of the UCP Catalog capability. Global Catalog searches across Shopify merchants. Storefront Catalog limits discovery to one merchant. Their shared capability does not make their scope or context interchangeable.
Key takeaways
- Use Global Catalog for cross-merchant discovery.
- Use Storefront Catalog when the buyer is already shopping one merchant.
- Fetch exact variant details before adding an item to cart.
- Treat authentication and rate-limit responses as runtime inputs.
When should an agent use Global Catalog?
Global Catalog fits a buyer request that is not yet tied to one store. The agent can search products across Shopify merchants from one catalog surface. This supports broad discovery, but the agent still needs to preserve the selected merchant and exact variant as the journey moves toward cart and checkout.
Do not describe Global Catalog as a complete copy of every merchant backend. Use only the fields and operations returned by the documented catalog tools.
When is Storefront Catalog the better choice?
Storefront Catalog scopes discovery to one merchant’s storefront. It is appropriate when the buyer names a store, arrives from a merchant property or must search within that merchant’s available assortment. The narrower scope removes ambiguity about which business will own the cart and checkout.
This is an intent distinction, not a quality ranking. A broad catalog is not automatically better than a merchant-scoped catalog.
Decision matrix
| Buyer context | Recommended starting surface | Reason |
|---|---|---|
| “Find running shoes across stores” | Global Catalog | Cross-merchant discovery is explicit |
| “Find a jacket from this store” | Storefront Catalog | Merchant scope is already known |
| Buyer follows a merchant product link | Storefront Catalog | Preserve merchant context |
| Buyer has not chosen a merchant | Global Catalog | Compare relevant Shopify merchants |
| Agent is rebuilding a known merchant cart | Storefront Catalog | Avoid switching business context |
This matrix is a local routing rule derived from the documented scopes. Validate it against the exact tools your agent uses.
What must be preserved after search?
Save stable identifiers from the catalog response, especially the merchant context, product and selected variant. Before cart creation, use the documented lookup or variant-detail operation to confirm the purchasable item. Natural-language similarity alone is not enough to select a size, color or configuration.
The handoff record should contain:
- Catalog surface used.
- Merchant identifier or storefront context.
- Product and variant identifiers.
- Quantity requested.
- Last observed price and availability, marked as observations rather than guarantees.
- Timestamp of the lookup.
Cart and checkout responses remain the source of current transactional state.
How do authentication and limits affect routing?
Catalog access is available across Shopify’s documented agent identity tiers, but identification affects limits and can affect personalization. A buyer-linked Token can make Global Catalog results customer-aware. Anonymous access operates at the lowest limits.
Do not hard-code an unpublished request-per-minute number. Read server responses, minimize duplicate searches and authenticate at the level required by the actual journey.
Reproducible comparison test
Choose a product known to exist in one test merchant and record:
- The same natural-language query on both catalog surfaces.
- The merchant context returned by each.
- Product and variant identifiers.
- Which fields differ by scope or identity tier.
- The cart operation created from the chosen result.
Redact buyer-linked information before publishing the trace. The value of the experiment is the documented difference between surfaces, not a claim that one catalog always returns better results.
Primary sources and review date
- Shopify catalogs for agents, reviewed 2026-08-12.
- Shopify agentic commerce documentation, reviewed 2026-08-12.