Global Catalog REST API Migration: Shopify App Owner's Plan
The Global Catalog REST API stops serving traffic on November 2, 2026. Here is a practical migration plan for Shopify apps that still read catalog data over REST.
The Global Catalog REST API stops serving traffic on November 2, 2026. If your Shopify app or internal tooling still reads catalog data over REST, a Global Catalog REST API migration is now a dated project, not a backlog item.
The good news: the replacement surface is the GraphQL Catalog API, and the work is mostly mechanical once you know which calls break. The bad news: catalog data sits under storefronts, pricing and inventory, so a sloppy cutover is visible to shoppers. This plan walks through scoping, mapping, testing and rollout — the same sequence we run for clients on our Shopify app engagements.
What the Global Catalog REST API shutdown means for your app
The Global Catalog REST API is the REST surface Shopify apps use to read catalog-level data — products, variants, collections and related metadata — outside the context of a single store. Once it stops serving traffic, any request to it fails. There is no grace period and no read-only fallback.
Two things matter for scoping:
- Hard deadline. November 2, 2026. Treat it as an API removal, not a deprecation warning.
- Scope is catalog reads and writes, not everything REST. Orders, customers and other REST resources follow their own timelines. Do not assume a full REST-to-GraphQL rewrite is required — audit first.
If your app only touches a single store's products through the Admin REST API, your exposure is different from an app that aggregates catalogs across merchants. Know which one you are before you estimate.
Which catalog reads and writes break on November 2, 2026
Start with a call inventory. Grep your codebase and your logs for REST paths that touch catalog entities, then group them by what they actually do.
| REST pattern | What it does | Migration target |
|---|---|---|
| GET /products, /products/{id} | Read product and variant data | GraphQL Catalog API product queries |
| GET /collections, /collections/{id} | Read collection membership | GraphQL Catalog API collection queries |
| Paginated list reads | Bulk catalog sync | GraphQL cursor pagination, batched |
| PUT/POST product writes | Update fields, variants, metafields | GraphQL mutations |
| Webhook-driven refreshes | React to catalog changes | Same webhooks, new read path |
Practical checklist:
- Export every REST catalog call from production logs for the last 30 days.
- Tag each call as read, write or sync.
- Mark calls with no matching GraphQL field — these need a design decision, not a find-and-replace.
- Note rate-limit behaviour per call, because GraphQL uses a cost-based budget, not a request count.
That last point catches most teams. A REST sync that fired 40 requests per page may become one GraphQL query with a calculated cost. Your throttling and retry logic has to change with it.
Mapping REST catalog calls to the GraphQL Catalog API
Do the mapping on paper before you touch code. For each REST call, write down the fields you consume, the pagination model, and the error cases you handle.
Reads and pagination
REST list endpoints return pages with a count. GraphQL returns connections with cursors. Rewrite your sync loop around cursors, request only the fields you use, and cap page sizes so a single query does not blow the cost budget.
Writes and mutations
Product and variant writes move to mutations. Two rules that save time:
- Batch where the API allows it. One mutation per variant does not scale.
- Read back after write. GraphQL mutations return the updated object, so you can drop the follow-up GET entirely.
Metafields and custom data
Metafields are where naive migrations break. Field names, types and namespaces must match exactly, and a wrong type fails silently in some flows. Validate metafield definitions against a staging store before you migrate production data.
Rate limits and cost
Replace request-per-second throttling with cost-aware throttling. Log the actual cost of each query in staging, then set your retry and backoff thresholds from real numbers rather than guesses.
Testing the migration without breaking live storefronts
Never test a catalog migration against a live merchant store. Use a development store with a realistic catalog — a few thousand products, variants with multiple options, collections with manual and automated rules, and metafields in use.
Test sequence:
- Shadow reads. Run the new GraphQL path alongside the old REST path and diff the results field by field. Any mismatch is a bug, not noise.
- Write parity. Apply the same write through both paths on separate stores and compare the resulting objects.
- Load test. Push your largest expected sync through the new path and watch cost consumption and error rates.
- Webhook regression. Confirm catalog webhooks still trigger the right refresh logic on the new read path.
Keep the diff harness. It is the fastest way to prove correctness to a merchant or an app reviewer.
Rollout, monitoring and rollback for a catalog migration
Ship behind a flag, not in one release.
- Phase 1 — internal. New GraphQL path on for your own stores only.
- Phase 2 — opt-in. Enable per merchant, starting with the largest catalog you have.
- Phase 3 — default. New path on for everyone; REST path still present but unused.
- Phase 4 — cleanup. Delete REST catalog code after 30 days of clean metrics.
Monitor three things: error rate per query, cost budget consumption, and sync lag between Shopify and your downstream system. Set alerts on all three before Phase 2.
Rollback is the flag, not a redeploy. Keep the REST path compiled and reachable until Phase 4. If you deleted it early, you will be rebuilding under pressure.
One more discipline: AI can draft the query rewrites and the diff harness quickly, but nothing goes live without a human reviewing the mapped fields. That is how we run every build — AI proposes, the customer approves.
When to hand the migration to a Shopify app team
Hand it over if any of these are true:
- You have no reliable inventory of REST catalog calls.
- Your catalog sync is load-bearing for pricing or inventory.
- You have a public app listing and cannot risk a visible regression.
- Your team has no capacity before the November 2026 date.
A migration like this is scoped work: audit, mapping, staging parity, phased rollout. If you want it off your plate, our Shopify app team runs exactly this sequence, and we take over existing projects as well as new builds.
Related reading
Frequently asked questions
When exactly does the Global Catalog REST API stop working?
It stops serving traffic on November 2, 2026. Plan for a hard removal: after that date, requests to the Global Catalog REST API fail, so the migration must be complete and rolled out before then.
Does the shutdown affect all Shopify REST APIs?
No. The Global Catalog REST API is a specific surface. Other REST resources follow their own timelines. Audit which catalog endpoints your app actually calls before assuming a full REST-to-GraphQL rewrite is needed.
What replaces the Global Catalog REST API?
The GraphQL Catalog API. Reads become connection queries with cursor pagination, writes become mutations, and throttling moves from request counts to a cost-based budget.
How long does a Global Catalog REST API migration take?
It depends on how many catalog calls you have and whether writes are involved. A read-only sync is a short project; an app with product and variant writes, metafields and webhook-driven refreshes takes longer because each path needs staging parity testing.
Can I test the migration without touching a live store?
Yes, and you should. Use a development store with a realistic catalog, run shadow reads against the old REST path, diff the results, and load test the new path before enabling it for any merchant.
Can you take over a half-finished catalog migration?
Yes. We audit the existing mapping, rebuild the staging parity harness, and finish the phased rollout. Taking over existing projects is a normal part of how we work.
Migrate before the November 2026 deadline
Tell us which catalog calls your app makes and we will scope the migration: audit, GraphQL mapping, staging parity and phased rollout. Nothing ships without your review.