Headless Migration Checklist: 25 Items Before Cutover

Going headless is the single biggest architecture change a Shopify store can make, and most teams underestimate the number of small cutover tasks that sit between a working staging build and a healthy production launch. This checklist exists because we kept seeing the same gaps in migrations that slipped, broke SEO, or lost revenue for a week after switching DNS. Twenty five items, grouped by phase, each one a hard gate before you send real traffic to the new stack.

If you are still weighing whether to go headless at all, start with our comparison on headless Shopify vs Liquid and the performance baseline work in the Shopify speed optimization playbook. Headless is only worth the complexity when a well optimized Liquid theme has already plateaued. If you have not exhausted theme level gains, fix those first. If you have, this checklist keeps the cutover from turning into a three week incident.

The structure below mirrors how we run migrations inside headless development engagements. Architecture decisions first, then SEO parity, then performance, then checkout, then the post launch watch window. Skip a phase and you will discover the missing work at 2am on launch night, which is always more expensive than catching it in staging.

Pre-migration architecture

Framework and hosting are the two decisions that cascade into everything else. Hydrogen 2 is the path of least resistance if you plan to stay fully inside the Shopify ecosystem, host on Oxygen, and use Shopify primitives for cart, customer accounts, and analytics. Next.js is the right call when you need more flexibility, want Vercel or Cloudflare hosting, or have content outside Shopify (CMS, PIM, custom search) that needs first class integration. Nuxt is viable for Vue teams but the Shopify community tooling is thinner, so factor that into hiring risk.

Hosting follows from framework. Oxygen is free with Hydrogen, edge rendered, and tightly integrated with Shopify environments. Vercel gives you richer preview deploys, broader observability, and a larger ecosystem of integrations. Self hosting on Cloudflare Workers, Fly, or a custom Kubernetes cluster is only worth it if you have specific compliance or data residency needs that the managed platforms cannot cover. Pick hosting before you start writing code because middleware, caching, and edge features differ.

Storefront API connection testing is deceptively important. You need a private app or custom app with the right scopes, rate limit handling, and a clear split between server side and client side token usage. Never ship the Admin API token to the client. Customer Account API, which replaces the legacy Customer API, handles login, orders, and account management. Get it wired up early because the redirect based login flow is the piece most teams leave until too late and then rush.

Server side rendering needs to be verified on every route type: home, collection, product, article, search, policies, 404. View source on each and confirm the critical content is in the initial HTML. If a route renders empty and hydrates client side, it will either tank SEO or fail Core Web Vitals. Route by route verification is tedious and non negotiable.

SEO and schema

SEO parity is where most headless migrations lose traffic for the first six weeks. The default Next.js or Hydrogen template does not ship with production grade metadata, canonicals, or structured data. You have to build that layer deliberately.

Meta tags first. Title, description, OpenGraph, Twitter card, canonical URL, and hreflang if you run multi region. Canonicals must match the production hostname exactly, including trailing slash convention. A canonical pointing to staging or to a non canonical variant will deindex pages faster than you can fix it. Write a metadata helper and use it on every page. Do not rely on per page hand rolled tags.

Structured data matters more headless than on Liquid because you lose the default schema that comes with many themes. You need Product schema with price, availability, SKU, and review aggregate on every PDP. Breadcrumb schema on every non home page. Organization schema site wide, with logo and sameAs for social profiles. Article schema on blog posts. FAQPage schema where it applies. Use JSON LD, validate with Google Rich Results Test, and keep the schema generator centralized so you are not repeating yourself across routes.

Sitemap generation needs to be dynamic, pulling from the Storefront API at build or request time, and it must include every indexable URL: products, collections, articles, pages. Exclude staging, filter parameters, and non canonical variants. Submit the sitemap through Search Console the day cutover happens. Robots.txt should allow all production crawlers, block staging entirely (separate robots on the staging host), and reference the sitemap URL.

One trap: if you run a staging subdomain, make absolutely sure it is password protected or returning X Robots Tag noindex. Google will crawl it otherwise and you will have duplicate indexed content fighting your production URLs.

Performance and CDN

Headless is sold on performance, but a naive headless build can be slower than a tuned Liquid theme. The difference is in how you handle images, caching, and third party scripts.

Image optimization pipeline is the single biggest lever. Shopify CDN serves images with query string transforms (width, height, format). Use those transforms, serve AVIF or WebP with fallback, and set correct width and sizes attributes so the browser picks the right variant. If you need more control, proxy through a dedicated image CDN and cache aggressively. Do not ship original resolution product shots and let the browser resize.

Core Web Vitals need to be green on all four key page types: home, collection, product, article. Run PageSpeed Insights and field data from CrUX, not just lab scores. LCP is usually the hero image on PDP and collection, so preload it and make sure the image pipeline is serving optimized formats. CLS hides in font swap and late loading banners, fix both. INP replaces FID and is brutal to third party scripts, so audit every embedded pixel and analytics tag.

CDN caching rules deserve their own review. Static assets (JS, CSS, fonts, images) should have long cache TTLs with content hashed filenames. HTML should be cached at the edge with revalidation on product and content changes, using ISR or equivalent. API responses from the Storefront API should be cached where safe, with careful invalidation on inventory or price changes. Get this wrong and either your store is slow or prices are stale.

Performance budget needs a number. Pick targets (LCP under 2.0s, INP under 150ms, total JS under 200KB gzipped on PDP) and wire them into CI. If a PR blows the budget, it fails the build. Without enforcement, performance degrades one commit at a time until you are back where you started on Liquid.

Checkout and integrations

Shopify Checkout stays. This is the most important sentence in the whole document. Shop Pay, local payment methods, tax compliance, fraud analysis, and the entire post purchase ecosystem are tied to Shopify Checkout. Leaving it means rebuilding all of that, usually badly, and losing conversion in the process.

Integration verification means testing the cart to checkout handoff end to end, on desktop, mobile, iOS Safari, and Android Chrome. Cart tokens must survive the handoff. Discounts and gift cards must apply correctly. Shop Pay button must render and work. Test with real payment methods in a test store, not just with the API mock.

Cart persistence is the non obvious piece. On Liquid, the cart lives in session. Headless, you choose: local storage, cookies, server session, or Customer Account attached cart. We recommend local storage for guest users plus Customer Account sync for logged in users, so the cart follows them across devices. Test the edge cases: adding items while logged out, then logging in; clearing cookies mid session; opening a second tab.

App compatibility is a full audit, not a guess. Every app in your current Shopify stack needs a ruling: does it work headless (many storefront side apps do not), is there an API version, can it be replaced, or does it go away. Reviews, subscriptions, loyalty, search, and personalization apps are the usual casualties. Build a spreadsheet, get product owners for each app to sign off, and budget replacement work before cutover, not after.

Analytics means three layers: GA4 (client side, with consent mode if you are in the EU), server side tagging (for attribution resilience and ad platform conversions), and native Shopify analytics (still the source of truth for revenue reporting). Wire all three before launch, verify events land, and reconcile numbers between layers so you are not debugging attribution during peak season.

301 redirects are where SEO migrations live or die. Map every old URL (from Liquid theme, from legacy collections, from old blog paths) to the new headless equivalent. Export the old sitemap, diff against the new one, and write redirects for everything that moved. Shopify admin supports URL redirects, but for headless you usually manage these at the edge in middleware for speed. Test a sample of 50 URLs before cutover.

Post-launch

Launch day is not the finish line. The first 14 days after cutover determine whether the migration holds its SEO and conversion numbers.

Soft launch cohort is the safest pattern. Route 5 to 10 percent of traffic (by geography or feature flag) to headless, watch conversion and errors for 48 hours, then ramp. Full cutover on day one is only appropriate if staging has been battle tested and you have a real rollback path. The Shopify development team pattern is to keep the old Liquid theme published and unpromoted, so a DNS or middleware flip can restore it in minutes if needed.

Error logging and monitoring needs to be in place before traffic flips. Sentry or equivalent for application errors, with alerting into Slack or PagerDuty. Real user monitoring for Core Web Vitals in the wild, not just lab. Uptime monitoring on the hosting platform. Log aggregation for API errors from Storefront API and Customer Account API.

SEO crawl and indexation monitoring for the first 30 days. Run Screaming Frog against production once a week, check for broken links, missing canonicals, and noindex leaks. Watch Search Console for coverage drops, crawl errors, and soft 404s. Traffic will dip in week one or two regardless, because Google recrawls and reevaluates. If it has not recovered by week four, something is wrong with the migration.

Rollback trigger documented means a written decision: what metric, what threshold, who decides. Example: if conversion rate drops more than 15 percent for 24 hours, or if organic sessions drop more than 30 percent for 72 hours, or if any P1 bug blocks checkout, roll back. Ambiguity here turns a recoverable incident into a week long meltdown. Write the trigger, rehearse the rollback, and move on.

Closing

Four arrows for the back pocket.

Arrow 1: If you are not sure you need headless, you do not. The complexity only pays off when a well tuned Liquid theme has genuinely hit the ceiling, which is rarer than most teams admit. Fix the theme first.

Arrow 2: Keep Shopify Checkout. The moment someone on the project pitches replacing checkout, push back hard. You lose Shop Pay, local payments, fraud protection, and most of the conversion advantage that Shopify gives you. It is almost never worth it.

Arrow 3: SEO parity is the hardest part, not the build. Metadata, canonicals, schema, sitemaps, redirects. Build the SEO layer first, verify it in staging, and treat it as a launch blocker.

Arrow 4: Soft launch, measure, ramp. Full cutover on day one is ego, not engineering. A 5 percent cohort for 48 hours costs nothing and catches the problems you missed in staging every single time.