The Headless Commerce Migration Playbook — From Monolith to Composable

The $1.2M Migration That Failed

A DTC brand spent $1.2M migrating from Shopify to a fully headless stack: custom Next.js frontend, Medusa for commerce, Contentful for CMS, Algolia for search, Stripe for payments. Eighteen months of development. On launch day, conversion rate dropped 23%. Page speed was actually slower than Shopify (they'd built a poorly optimized frontend). The SEO team discovered they'd lost 40% of their organic traffic because URL redirects weren't properly mapped.

Headless isn't wrong. But migrating to headless without a playbook is how you burn $1.2M.

When Headless Makes Sense (And When It Doesn't)

Headless makes sense when:
  → You need unique frontend experiences (3D product configurators, AR try-on)
  → You sell across many channels (web, mobile app, in-store kiosk, marketplace)
  → Your content strategy requires a dedicated CMS
  → You need sub-second page loads and your current platform can't deliver
  → You have 4+ frontend engineers who can build and maintain a custom storefront

Headless does NOT make sense when:
  → You're under $10M revenue (Shopify themes are fine)
  → Your team is < 3 engineers (you can't maintain a custom frontend)
  → Your competitive advantage isn't technology (focus on product and marketing)
  → You're doing it because a vendor convinced you it's "the future"
  → You don't have performance problems with your current platform

The Migration Phases

Phase 1: Audit and Architecture (Weeks 1-4)

Before writing any code, document everything:

Content Audit:
  □ Every page URL (for redirect mapping)
  □ Every content type (PDP, PLP, landing pages, blog)
  □ Every integration (email, analytics, reviews, loyalty, chat)
  □ Every customization on the current platform
  □ SEO baseline (rankings, organic traffic, indexed pages)

Architecture Decision:
  □ Frontend framework (Next.js is the safe choice for commerce)
  □ Commerce engine (Shopify Hydrogen, Medusa, commercetools)
  □ CMS (Contentful, Sanity, Strapi, or keep Shopify for products)
  □ Search (Algolia, Typesense, native platform search)
  □ Hosting (Vercel, AWS, Cloudflare)

Phase 2: Build the Foundation (Weeks 5-12)

Start with the critical path: product page → cart → checkout:

// Start with Shopify Storefront API (if migrating from Shopify)
// This lets you build a custom frontend while keeping Shopify as the backend
const getProduct = async (handle: string) => {
  const response = await shopify.graphql(`
    query ProductByHandle($handle: String!) {
      productByHandle(handle: $handle) {
        id
        title
        description
        priceRange { minVariantPrice { amount currencyCode } }
        images(first: 10) { edges { node { url altText } } }
        variants(first: 100) {
          edges { node { id title availableForQuantity priceV2 { amount } } }
        }
      }
    }
  `, { handle });
 
  return response.productByHandle;
};

Critical rule: Keep checkout on the existing platform initially. Custom checkout is the highest-risk part of any migration. Use Shopify Checkout or your existing platform's checkout while you build the rest.

Phase 3: Parallel Run (Weeks 13-16)

Run both platforms simultaneously:

Traffic split:
  95% → Old platform (production)
  5%  → New frontend (canary)

Monitor:
  → Conversion rate (new vs old, per page type)
  → Page speed (Core Web Vitals, real user metrics)
  → Error rates (JavaScript errors, API failures)
  → SEO signals (crawl rate, index status)

Decision criteria for increasing traffic:
  → Conversion rate within 5% of old platform
  → No P1 errors in 7 days
  → Page speed metrics better than old platform
  → All integrations verified working

Phase 4: Gradual Cutover (Weeks 17-20)

Week 17: 25% traffic to new frontend
Week 18: 50% traffic (if metrics hold)
Week 19: 75% traffic
Week 20: 100% cutover (keep old platform on standby for 30 days)

Rollback plan at every stage:
  → If conversion drops > 5%, revert immediately
  → If error rate spikes > 0.5%, revert
  → Old platform remains hot standby for 30 days post-cutover

The SEO Migration Checklist

This is where most headless migrations lose organic traffic:

Pre-Migration:
  □ Export ALL URLs from current platform (including paginated, filtered)
  □ Map every old URL to new URL
  □ Set up 301 redirects for every URL change
  □ Verify meta tags, structured data, canonical URLs on new platform
  □ Submit new sitemap to Google Search Console

Post-Migration:
  □ Monitor crawl errors daily for 30 days
  □ Check index status (Google Search Console → Coverage)
  □ Monitor organic traffic daily (compare to same period last year)
  □ Fix any 404s that appear in crawl reports
  □ Verify all internal links point to new URLs

The Integration Checklist

Every integration must be verified before cutover:

Critical (block launch):
  □ Payment processing (test transactions end-to-end)
  □ Inventory sync (verify stock levels match)
  □ Order management (orders appear in OMS/ERP)
  □ Email/SMS (transactional emails fire correctly)
  □ Analytics (purchase events track accurately)

Important (verify in first week):
  □ Reviews platform (reviews display, new reviews submit)
  □ Loyalty program (points earn and redeem)
  □ Customer support chat (widget loads, data passes)
  □ Affiliate tracking (commission tracking works)

Nice to have (verify in first month):
  □ Social commerce integrations
  □ Personalization engine
  □ A/B testing platform

Headless commerce is a powerful architecture — but only if the migration is executed methodically. Build the playbook before you write the first line of code. Run in parallel before you cut over. And always, always have a rollback plan.