

Shopify Global Catalog API Shutdown: MCP Migration Guide
Migrate Shopify Global Catalog search and lookup from REST to MCP and UCP with a practical mapping, test matrix, cutover plan and recovery checklist.
Shopify's deprecated Global Catalog REST API stops serving traffic on 2 November 2026. Apps that still call its search, product lookup, variant lookup or bulk lookup routes need to move to Global Catalog MCP, which implements the Universal Commerce Protocol (UCP).
This is not a general Shopify storefront outage. It affects applications that use Shopify's cross-merchant catalog for comparison shopping, recommendations, saved catalogs or agentic product discovery. The customer-facing symptom may therefore look indirect: an empty recommendation panel, a failed product comparison, stale discovery results or an AI shopping assistant that cannot find an item.
The migration is also more than an endpoint replacement. Teams must map REST operations to MCP tools, add an agent profile, adopt UCP request and response schemas, update saved-catalog handling, test partial results and decide how inferred product fields may be displayed.
VaniTech supports ecommerce development, API and system integrations, AI workflow implementation and ongoing technical support.
Four REST Operations Need a New Path
Shopify's shutdown notice identifies the affected discovery operations and their UCP replacements.
Search
Move /global/v2/search calls to search_catalog.
Product Lookup
Move product-ID lookups to get_product.
Variant Lookup
Pass a Shopify variant GID to get_product.
Bulk Lookup
Move batch identifiers to lookup_catalog.
Why this Shopify migration is trending now
Shopify deprecated the REST interface in April 2026 and published the final shutdown notice on 9 October. The critical date is now here: after 2 November, requests to the documented discover.shopifyapps.com/global routes fail, including requests made through saved-catalog URLs.
The replacement reflects a wider shift in ecommerce integration. Instead of exposing only conventional REST resources, Shopify now describes catalog discovery as UCP capabilities delivered through MCP tools. The agent declares what it supports, Shopify negotiates the compatible capability set, and product discovery returns structured content designed for an agent workflow.
That architecture can make catalog search reusable across AI assistants and commerce experiences, but it introduces new operational responsibilities. The integration must host or reference an agent profile, parse protocol metadata, distinguish transport errors from business messages, preserve buyer and market context, and handle product data that may include Shopify-inferred fields.
For technology decision-makers, the deadline is both a recovery task and an architecture checkpoint. Confirm whether the affected application still serves a useful commercial journey before recreating every legacy assumption.
First confirm whether your system is affected
Search the codebase, gateway logs, observability tools and environment configuration for the legacy host and routes. Do not limit the check to the main storefront repository. Catalog access may sit inside a recommendation service, mobile app, browser extension, partner portal, chatbot, scheduled feed job or vendor-managed integration.
Your inventory should record:
- Every component that calls
discover.shopifyapps.com/global. - The REST route, HTTP method and expected response shape.
- Whether the call searches all Shopify merchants or a saved catalog.
- The credentials, environment variables and secret owner.
- How country, region, currency, language, shipping and availability are supplied.
- Which fields drive ranking, product cards, comparison tables or recommendations.
- Timeout, retry, caching, rate-limit and fallback behaviour.
- The business owner and customer journey that depends on the result.
If the experience searches one known merchant only, verify whether Storefront Catalog MCP is the better target. Shopify positions Global Catalog for cross-merchant discovery and Storefront Catalog for a single store. Migrating to the wrong interface can preserve code while changing the business scope.

Map the REST calls to Global Catalog MCP
| Legacy use | UCP tool | Migration note |
|---|---|---|
| Search across products | search_catalog | Move the query, buyer context, filters and pagination into the catalog argument. |
| Get one product by UPID | get_product | Pass gid://shopify/p/{upid} and test option-selection behaviour. |
| Get one variant | get_product | Pass gid://shopify/ProductVariant/{id} and verify the returned product and matching variant. |
| Resolve multiple identifiers | lookup_catalog | Handle found products and unresolved identifiers as a partial business outcome. |
| Search a saved catalog | search_catalog | Send the saved configuration as catalog.catalog_id instead of calling its old endpoint URL. |
All tools are called through https://catalog.shopify.com/api/ucp/mcp. Every request must include meta.ucp-agent.profile, pointing to the UCP profile that declares the agent's protocol version and supported catalog capabilities.
The profile is not decorative metadata. Shopify uses it to intersect what the agent declares with what the platform supports. Treat the profile as a versioned integration contract: host it reliably, review capability changes and include it in deployment and rollback planning.
A seven-stage migration plan
- Inventory dependencies. Find every legacy route, saved catalog, credential, downstream field and customer journey.
- Choose the correct catalog scope. Use Global Catalog for cross-merchant discovery and Storefront Catalog for a single merchant experience.
- Define the UCP contract. Host or select an agent profile, declare only required capabilities and document the expected protocol version.
- Build an adapter. Map legacy inputs to
search_catalog,lookup_catalogandget_product, then normalize UCP output for existing application consumers. - Test for semantic parity. Compare representative queries, filters, localization, variant choice, availability, pricing and not-found behaviour—not only HTTP success.
- Cut over with observability. Deploy behind a controlled flag or routing rule, monitor errors and result quality, and retain a deliberate customer-safe fallback.
- Retire the legacy path. Remove dead secrets, routes, dashboards and fallback code after the new integration meets its acceptance window.
An adapter can reduce disruption when several interfaces depend on the old response model. It should be temporary and explicit. If it silently flattens new UCP semantics into an incomplete legacy object, the migration may appear successful while product quality degrades.
Account for the contract changes
Request envelope and capability metadata
MCP tool calls use JSON-RPC and wrap tool arguments under a named operation. UCP metadata belongs inside the arguments, including the agent-profile URL. Validate outgoing payloads against the current input schema rather than assuming the legacy request object can be reused.
Structured price and product fields
UCP responses return structured products, variants and price objects. Shopify documents monetary amounts in minor currency units, so a value such as 8999 represents 89.99 in the stated currency. Keep amount and currency together through display, comparison and analytics layers.
Messages and partial success
A lookup can return the products it found while reporting unresolved identifiers through informational messages. That is not equivalent to a transport failure. Decide whether the interface shows partial results, retries selected identifiers, records data-quality work or stops the journey.
Inferred fields
Shopify marks some descriptions, options, attributes, technical specifications, features and selling points as inferred. They may be absent or vary in accuracy. Use them as discovery or merchandising signals, not automatically as merchant-approved claims. Customer-facing factual claims should remain grounded in authoritative product data.
Pagination and saved filters
Replace page-number assumptions with the documented cursor model. For saved catalogs, use catalog.catalog_id and confirm that stored filters, runtime filters and requested sources interact as intended.
Use a business-focused test matrix
| Scenario | Evidence to capture | Failure to watch for |
|---|---|---|
| Common discovery query | Relevant products, seller mix, price range and latency | Empty, irrelevant or materially reordered results |
| Country, currency and language | Localized price, availability and product content | Wrong market, currency or unsupported locale fallback |
| Shipping and availability filters | Eligible offers for the buyer context | Unavailable or non-shippable items shown as valid choices |
| Product and variant lookup | Correct product, selected options and matching variant | Variant ID resolves but the wrong option is featured |
| Bulk lookup with an unknown ID | Found items plus explicit not-found handling | One missing identifier discards the complete batch |
| Saved catalog | Expected scope and enforced stored filters | Search unexpectedly expands outside the intended catalogue |
| Pagination | No duplicates or gaps across cursor transitions | Repeated, skipped or unstable products |
| Inferred metadata absent | Interface remains useful without optional fields | Blank layouts or invented fallback claims |
| Rate limit or timeout | Bounded retry, clear fallback and telemetry | Retry storms, long hangs or silent empty states |
| Malformed profile or schema | Actionable error and deployment alert | Generic customer error with no diagnostic trail |
Shopify provides the UCP CLI, AI Toolkit and saved-catalog Preview panel for exploration. Use them to learn the contract, then run automated integration tests against the same payload shapes your production application sends.
Plan authentication, rate limits and observability
Shopify documents token, signed and anonymous identity tiers for UCP traffic. Anonymous catalog access exists, but Shopify says its throughput is not guaranteed and should not be used for production traffic. A production design should therefore have an explicit credential strategy, secret owner and renewal path.
Measure both technical and commercial health:
- MCP transport and JSON-RPC error rate.
- Tool latency by
search_catalog,lookup_catalogandget_product. - Rate-limit responses, retry count and retry delay.
- Empty-result rate by query class, country and saved catalog.
- Partial lookup rate and unresolved identifier count.
- Product-card render failures caused by missing optional fields.
- Click-through, product selection, merchant handoff and checkout-start rates.
- Profile fetch failures and negotiated capability changes.
Technical success is necessary but not sufficient. A 200-style tool result that returns less relevant products, the wrong market or unusable variant choices can still reduce conversion.
Assign the Migration Across Four Roles
The integration is safer when commercial acceptance and technical delivery have named owners.
Product Owner
Defines affected journeys, acceptable result quality and fallback behaviour.
Integration Team
Maps contracts, implements the adapter, tests failures and removes legacy code.
Ecommerce Team
Checks product relevance, price, availability, variants and merchant handoff.
Operations Owner
Owns credentials, dashboards, alerts, incident response and vendor escalation.
If the old integration is already failing
Use an incident-style recovery sequence rather than making an untested production rewrite:
- Confirm that the failing traffic targets a retired Global Catalog REST route.
- Identify the customer surfaces and revenue journeys affected.
- Disable misleading results or switch to a clearly labelled safe fallback.
- Preserve request logs, representative payloads and the last known working response samples.
- Implement the smallest UCP adapter for the affected operations first.
- Test the top queries, saved-catalog scope, market context and variant selection.
- Deploy behind controlled routing, watch telemetry and compare business outcomes.
- Schedule the remaining hardening work: full test coverage, rate-limit handling, profile ownership, documentation and legacy-secret removal.
A fallback should be honest. Showing a smaller curated product set or a direct merchant search may be safer than presenting empty recommendations as if no products exist.
If ownership has become unclear, the shutdown is a useful trigger for a broader integration review or technical takeover. The target state should include code ownership, environment inventory, monitored dependencies and a tested release path.
Common Migration Questions
Short answers for ecommerce, product and integration teams.
Sources Checked
- Shopify: Global Catalog REST API shutdown notice
- Shopify: Global Catalog MCP reference
- Shopify: About Catalogs
- Shopify: Agent profiles and UCP negotiation
- Shopify: Discover products with Shopify Catalog
- Shopify: Create saved catalogs in the Dev Dashboard
- Shopify: Auth and rate limiting
- Universal Commerce Protocol: Catalog MCP binding
Sources and product guidance were checked on 2 November 2026. Platform endpoints, schemas and capabilities can change; confirm the current Shopify and UCP documentation before implementation.
Restore catalog discovery with a controlled migration
VaniTech can assess the affected workflow, build the UCP integration, test commercial journeys and establish ongoing monitoring and support.