Migrating an e-commerce platform that generates millions in monthly revenue is like changing an airplane engine mid-flight. Here’s how we did it.
Why Headless?
Our Magento 2 monolith was reaching its limits:
- Performance: Time to First Byte > 800ms
- Scalability: Black Friday = cold sweats
- Velocity: 3 weeks for a header change
- Multi-channel: Impossible to properly feed the mobile app
Target Architecture
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Next.js │ │ Next.js │ │ App │
│ (Web FR) │ │ (Web US) │ │ Mobile │
└──────┬──────┘ └──────┬──────┘ └──────┬──────┘
│ │ │
└───────────────────┼───────────────────┘
│
┌──────▼──────┐
│ API Layer │
│ (GraphQL) │
└──────┬──────┘
│
┌───────────────────┼───────────────────┐
│ │ │
┌──────▼──────┐ ┌──────▼──────┐ ┌──────▼──────┐
│ Magento │ │ Algolia │ │ Stripe │
│ (Backend) │ │ (Search) │ │ (Payments) │
└─────────────┘ └─────────────┘ └─────────────┘The Strangler Fig Strategy
No big bang. We migrated progressively:
- Months 1-3: API Gateway + first static pages
- Months 4-6: Headless product catalog
- Months 7-9: Decoupled checkout
- Months 10-12: Customer account + loyalty
- Months 13-18: Optimizations and global rollout
Patterns That Saved the Project
Feature Flags Everywhere
if (featureFlags.isEnabled('headless_checkout', { country: user.country })) {
return <HeadlessCheckout />;
}
return <LegacyCheckout />;Canary Deployments by Country
Monaco first, then Belgium, then France. Each country was a full-scale test.
Dual-Write for Data
For 6 months, every write went to both the old AND the new system. Belt and suspenders.
Post-Migration Numbers
| Metric | Before | After | Delta |
|---|---|---|---|
| TTFB | 847ms | 89ms | -89% |
| LCP | 4.2s | 1.1s | -74% |
| Conversion | 2.1% | 2.8% | +33% |
| Deploys/week | 2 | 15 | +650% |
What We’d Do Differently
- Invest earlier in observability — We flew blind for too long
- Automate E2E tests from day 1 — Technical debt accumulates fast
- Involve business stakeholders earlier — Some legacy features were critical without us knowing
Conclusion
18 months is a long time. But today, we deploy 15 times a week without stress, our site loads in under a second, and our developers are (almost) happy.
Headless migration isn’t an end in itself — it’s the beginning of a new velocity.