Ecommerce integration team migrating product discovery from a retired API to a controlled agent-ready catalog
Back to Blog
Posted by Mahdi
Shopify Integration Migration

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.

Seven-stage workflow for migrating Shopify catalog discovery from REST to MCP and UCP
A controlled migration moves from dependency discovery and contract mapping through implementation, parity testing, cutover, monitoring and legacy retirement.

Map the REST calls to Global Catalog MCP

Legacy useUCP toolMigration note
Search across productssearch_catalogMove the query, buyer context, filters and pagination into the catalog argument.
Get one product by UPIDget_productPass gid://shopify/p/{upid} and test option-selection behaviour.
Get one variantget_productPass gid://shopify/ProductVariant/{id} and verify the returned product and matching variant.
Resolve multiple identifierslookup_catalogHandle found products and unresolved identifiers as a partial business outcome.
Search a saved catalogsearch_catalogSend 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

  1. Inventory dependencies. Find every legacy route, saved catalog, credential, downstream field and customer journey.
  2. Choose the correct catalog scope. Use Global Catalog for cross-merchant discovery and Storefront Catalog for a single merchant experience.
  3. Define the UCP contract. Host or select an agent profile, declare only required capabilities and document the expected protocol version.
  4. Build an adapter. Map legacy inputs to search_catalog, lookup_catalog and get_product, then normalize UCP output for existing application consumers.
  5. Test for semantic parity. Compare representative queries, filters, localization, variant choice, availability, pricing and not-found behaviour—not only HTTP success.
  6. Cut over with observability. Deploy behind a controlled flag or routing rule, monitor errors and result quality, and retain a deliberate customer-safe fallback.
  7. 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

ScenarioEvidence to captureFailure to watch for
Common discovery queryRelevant products, seller mix, price range and latencyEmpty, irrelevant or materially reordered results
Country, currency and languageLocalized price, availability and product contentWrong market, currency or unsupported locale fallback
Shipping and availability filtersEligible offers for the buyer contextUnavailable or non-shippable items shown as valid choices
Product and variant lookupCorrect product, selected options and matching variantVariant ID resolves but the wrong option is featured
Bulk lookup with an unknown IDFound items plus explicit not-found handlingOne missing identifier discards the complete batch
Saved catalogExpected scope and enforced stored filtersSearch unexpectedly expands outside the intended catalogue
PaginationNo duplicates or gaps across cursor transitionsRepeated, skipped or unstable products
Inferred metadata absentInterface remains useful without optional fieldsBlank layouts or invented fallback claims
Rate limit or timeoutBounded retry, clear fallback and telemetryRetry storms, long hangs or silent empty states
Malformed profile or schemaActionable error and deployment alertGeneric 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_catalog and get_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:

  1. Confirm that the failing traffic targets a retired Global Catalog REST route.
  2. Identify the customer surfaces and revenue journeys affected.
  3. Disable misleading results or switch to a clearly labelled safe fallback.
  4. Preserve request logs, representative payloads and the last known working response samples.
  5. Implement the smallest UCP adapter for the affected operations first.
  6. Test the top queries, saved-catalog scope, market context and variant selection.
  7. Deploy behind controlled routing, watch telemetry and compare business outcomes.
  8. 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.

Shopify Global Catalog FAQ

Common Migration Questions

Short answers for ecommerce, product and integration teams.

Need Shopify Integration Help?

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.