Headless commerce-migratie — Shopify → Medusa.js / Saleor zonder SEO-verlies

De klant betaalde 280 EUR/maand voor Shopify Advanced, met 12 000 SKU's, 4 magazijnen, B2B + B2C dual pricing en 65 % organisch verkeer uit Slowaakse en Tsjechische Google. De headless migratie naar Medusa.js eindigde na 4 maanden, twee weken voor Black Friday. Geen organisch ranking is verloren gegaan, geen openstaande bestelling is verdwenen, en de Stripe-integratie ging van 14 handmatige stappen per nieuw product naar nul. Dit artikel beschrijft wat we deden, wat we verprutsten en wat we anders zouden doen.

Waarom headless — en wanneer NIET

Headless commerce heeft twee geldige redenen:

1. 1.Flexibiliteit voor custom checkout / B2B / multi-storefront. Shopify (zowel Advanced als Plus) heeft een vaste checkout-pipeline. Voor B2B met net-60-betalingstermijnen, custom pricing tiers, multi-warehouse splitting of complexe belastingregels (SK-DE-AT cross-border) wordt Shopify een gevecht met API-limieten en Liquid-templates.
2. 2.Storefront-performance + UX. Een Next.js storefront met ISR (Incremental Static Regeneration) + edge caching haalt LCP < 1,2 s op 4G. Een Shopify Liquid-rendered storefront heeft LCP 2,5–4,0 s. Voor een SEO-gedreven business is dat een meetbaar revenue-verschil.

Wanneer NIET headless: - Catalogus < 500 SKU + standaard B2C-checkout → Shopify of BigCommerce blijft goedkoper en sneller - Het team heeft geen capaciteit voor een eigen Next.js storefront (custom CMS, custom checkout, integraties) - De roadmap voor betalingen/boekhouding/marketing is volledig Shopify-native (Shopify Payments, Shopify Tax, Shopify Email)

Voor die klanten is het soepelere bestaande "semi-headless" beter — Shopify Hydrogen + Oxygen, dat een headless storefront-frontend biedt zonder het Shopify-ecosysteem te verlaten.

Stack-beslissingen in 2026

Backend: Medusa.js vs Saleor vs Commerce.js

Medusa.js v2.x - Node.js, PostgreSQL, Redis - Modulair, plugin-architectuur - Beste developer experience in 2026 - Zwakker B2B-feature set out-of-the-box (plugin of eigen code voor quotes, approvals, customer hierarchy nodig) - Prijs: open source self-hosted, of Medusa Cloud vanaf 200 EUR/maand - Wanneer: B2C + light B2B, dev-team met Node-ervaring

Saleor - Python, Django, GraphQL-first - Sterkste B2B-feature set (customer groups, channel-based pricing, quote requests) - Multilanguage + multi-currency native - Steilere leercurve, GraphQL-overhead - Prijs: open source self-hosted, of Saleor Cloud vanaf 500 EUR/maand - Wanneer: B2B-first, multi-storefront, complex pricing

Commerce.js / Swell.is - Alleen hosted, geen self-host - Snelle setup, maar vendor lock-in - Wanneer: PoC / MVP, kleine catalogus

Voor een retailer met 12k SKU en 30 % B2B kozen we Medusa.js v2 — self-hosted via Hetzner Cloud (CCX23, 4 vCPU + 16 GB RAM, 35 EUR/maand), PostgreSQL 16 op een aparte node, Redis voor cache + queue.

Frontend: Next.js 16 met App Router

• ISR voor productpagina's — revalidate every 60s
• Edge runtime voor /api routes (Cloudflare Workers of Vercel Edge)
• Tailwind 4 + shadcn/ui voor snelle UI-development
• Server Components voor product-detail (snelle TTFB), Client Components voor cart / interactive elements
• Bundle size target: < 180 KB shipped JS voor home page

Periferieservices

Totale OPEX: ~750 EUR/maand (vs. Shopify Advanced 280 EUR + overbodige Shopify Apps 350 EUR = 630 EUR oorspronkelijk).

Migration plan — 4 maanden, 6 fasen

Maand 1: Audit + data preparation

Week 1–2: Catalog audit - Export Shopify product CSV + Metafields export - Mapping Shopify product schema → Medusa product schema (variants, options, prices, tax_rates) - Identificatie van data quality issues (ontbrekende SEO-descriptions, duplicate handles, broken images) - 12 000 SKU's vielen uiteen in: 9 200 unieke products × gemiddeld 1,3 variant = 12 100 product_variants in Medusa

Week 3: URL-audit voor 301 mapping - Crawl van alle Shopify URL's via Screaming Frog → 14 800 unieke URL's - Categoriseer: product pages (12 000), collection pages (240), CMS pages (45), pagination URL's (2 200), overig (300) - Plan: behoud product handle (URL slug) → Medusa zelfde handle → 0 redirect nodig voor 11 800 URL's - Plan: collection pages mapping → meestal 1:1, maar Shopify smart collections vertalen niet direct naar Medusa product categories → 80 handmatige mappings - Pagination URL's (?page=2) → Medusa zelfde structuur, natuurlijk behouden

Week 4: Customer + order export - 18 400 customers met activiteit in de afgelopen 24 maanden → import naar Medusa - 47 000 historische orders → migratie naar read-only archief in Medusa (niet nodig in actief systeem, wel nodig voor legal compliance + customer support) - B2B customer groups + pricing tiers (Bronze/Silver/Gold) → Medusa customer_group + price_list

Maand 2: Backend build + integrations

Week 5–6: Medusa setup + custom modules - Hetzner Cloud setup, Coolify voor Docker-orchestration, GitHub Actions CI/CD - Medusa modules: product, order, customer, fulfillment, payment (Stripe), tax (Avalara plugin) - Custom modules: - SK-specifieke btw-afhandeling (23 % standaard, 5 % verlaagd, vrijgesteld) - SK-specifieke facturatie (vereist IČO, DIČ, IČ DPH, datum uitgifte, datum levering, vervaldatum) - B2B quote request flow (custom Medusa workflow + admin UI)

Week 7–8: Periferal integrations - Algolia: products + variants index, faceting (categorie, prijs, merk, beschikbaarheid), synoniemen (SK + CZ) - Klaviyo: customer + order webhook → Klaviyo events (cart_abandoned, ordered_product etc.) - Avalara: order_placed webhook → AvaTax calculation → store tax breakdown op order - Sentry: backend + frontend error tracking, source maps upload

Maand 3: Frontend build + SEO continuity

Week 9–10: Storefront core pages - Next.js 16 setup, Tailwind 4, shadcn/ui - Home, Category, Product Detail, Cart, Checkout (multi-step), Account, Order History - ISR voor Product + Category (revalidate 60s) - Server Components default, Client Components alleen voor cart/wishlist state

Week 11: SEO-migratie - Sitemap-continuïteit: Next.js sitemap.xml genereert dezelfde URL's als Shopify, plus nieuwe als die ontstonden - 301-redirect map: /apps/customer-portal/* → /account/*, /collections/ → /c/* (we hebben de URL-structuur van categorieën gewijzigd) - Structured data: Product schema (price, availability, sku, brand, aggregateRating, review), Offer schema, BreadcrumbList, Organization - Open Graph + Twitter Card: og:image gegenereerd via Next.js dynamic OG image route (1200×630, branding, product hero, prijs) - robots.txt + meta robots: behoud noindex voor /account/*, /cart, /checkout - Canonical URLs: expliciete canonical op elke productpagina, reden: Shopify gebruikte ze met ?variant=-parameter, Medusa doet dit via een aparte URL of client-side state — een canonical naar de base product URL is nodig

Week 12: Cutover-plan - DNS-cutover-plan (TTL 60s 24h voor de cutover) - Database-snapshot Shopify → Medusa-import (last delta) - Stripe-webhook switch (Shopify Stripe → Medusa Stripe) - Klaviyo-webhook switch - Klantcommunicatie: "zaterdagnacht van 02:00 tot 04:00 webshop niet bereikbaar"

Maand 4: Cutover + stabilisatie

Week 13: Soft launch - Subdomain shop-new.domain.sk → Next.js storefront + Medusa backend - 5 % van het verkeer via Cloudflare Workers split test - Sentry watch: nul nieuwe errors in 48 u - Klaviyo-monitoring: cart abandonment rate stabiel

Week 14: Full cutover - DNS-cutover (apex-domein → new infra) - 301-redirect map deployed op Cloudflare Workers (pre-DNS-cutover al actief) - Shopify blijft 30 dagen in read-only mode (legal archive van past orders) - Customer support ticket spike monitor

Week 15: Post-launch fix - 12 uur bugfixing in de eerste 72 u (geen critical, maar 8 minor — checkout edge cases, B2B quote workflow, enkele Algolia-synoniemen)

Week 16: Performance tuning + SEO-check - Lighthouse-audit, LCP target < 1,5 s (gehaald 1,1 s) - Search Console: indexing-status check, geen nieuwe 404's, geen rank-drop boven 5 % op top 50 keywords - A/B-test nieuwe product-detailpagina vs Shopify-style → +14 % conversion rate

Wat ons heeft beschadigd (en wat we anders zouden doen)

Langzaam: SK-specifieke facturatie

Plan: 4 dagen ontwikkeling voor een custom invoicing-module.

Werkelijkheid: 3 weken.

De Slowaakse wettelijke factuurvereiste omvat 14 verplichte velden (§ 74 wet op de btw), plus electronic invoicing voor B2B boven 5 000 EUR heeft eigen EDI-vereisten (E-faktúra Finančná správa). Plus VAT OSS voor cross-border EU-verkoop heeft per-transaction reporting naar MyTaxOffice nodig. Plus rovers (rožďanský factuurregel-format) voor cash transactions heeft eigen eisen.

Les: schat de SK/EU compliance-overhead op 3× de oorspronkelijke schatting. Geen enkele EU-compliance-feature is een "2-day implementation".

Snel: Algolia-sync

Plan: 5 dagen voor Algolia-integratie + indexering.

Werkelijkheid: 2 dagen.

Medusa heeft een first-party Algolia-plugin (@medusajs/algolia) die webhook-events emit-te (product.created, product.updated, product.deleted) → Algolia-reindex. Setup was de configuratie van API-keys + indexschema. Reëel 2 dagen.

Les: zoek eerst naar een first-party/community-plugin. Bestaat die en heeft hij 1k+ GitHub-stars, begin geen custom integratie.

Langzaam: B2B-quote-workflow

Plan: 1 week.

Werkelijkheid: 3 weken.

Een B2B-klant wil een "quote request" voor een order boven 5 000 EUR. Workflow: 1. De klant voegt producten toe aan zijn cart → klikt "Cenovou ponuku" aanvragen (in plaats van "In winkelmandje") 2. Een quote ontstaat in het admin panel; sales rep keurt goedkeurt, eventueel met aanpassingen aan prijs/verzending/betalingsvoorwaarden 3. De klant ontvangt een e-mail met een link naar de quote → kan deze accepteren (creëert een order met aangepaste condities) of weigeren

Medusa v2 heeft een quote-module in alpha in 2026, maar workflow + UI hebben we custom moeten bouwen. Plus admin-permissions voor verschillende sales reps. Plus e-mailtemplates in het SK.

Les: B2B-specifieke workflows in headless commerce zijn altijd custom. Saleor zou hier mogelijk 1 week hebben bespaard (heeft een ingebouwde quote-module in stable), maar de Medusa-beslissing was onderbouwd door de developer experience voor de rest van de stack.

Snel: 301-redirect-SEO-behoud

Plan: 1 week voor 301-mapping + monitoring.

Werkelijkheid: 3 dagen.

Truc: behoud de product handle (URL slug) van Shopify naar Medusa. Shopify URL was /products/produkt-handle, Medusa zelfde pattern. 11 800 van 14 800 URL's bleven identiek — geen redirect nodig.

Voor de rest (collections, customer portal, enkele CMS-pagina's) hebben we een 301-map op Cloudflare Workers geplaatst (URL Rewrite Rules) — 280 expliciete regels + 12 regex patterns. Zero geïndexeerde URL's verloren in Search Console na 60 dagen.

Les: kunt u de URL-pattern behouden, doe het. Moet u wijzigen, bouw de redirect-map *vóór* de cutover, niet erna.

SEO-checklist — wat te verifiëren vóór cutover

1. 1.Sitemap-pariteit: Next.js sitemap.xml moet alle URL's uit de oorspronkelijke Shopify-sitemap bevatten. Diff via een sitemap-diff-script in CI.
2. 2.301-redirect map: elke non-trivial URL-wijziging geïndexeerd in redirects.json, gevalideerd tegen production load tests.
3. 3.Canonical URLs: expliciete canonical op elke pagina; Shopify gebruikte query params (?variant=), de nieuwe stack mogelijk path-based URL's — canonical voorkomt duplicate content-penalty.
4. 4.Structured data-continuïteit: Product schema (offers, availability, price, sku) pariteit met de oorspronkelijke Shopify. Test via Google Rich Results Test vóór cutover.
5. 5.Open Graph-migratie: og:image, og:title, og:description per pagina. Dynamic OG image generation via Next.js dynamic route + edge runtime.
6. 6.robots.txt: noindex behouden voor admin, account, cart, checkout. Voeg Sitemap:-directive toe.
7. 7.Internal linking: breadcrumbs, related products, category navigation. Spider crawl via Screaming Frog om te bevestigen dat geen enkele pagina een orphan is.
8. 8.Core Web Vitals: LCP, FID/INP, CLS-doel voor de top 50 landing pages. Lighthouse CI in de deployment-pipeline.
9. 9.Search Console-herverificatie: nieuwe property voor nieuwe infra (als DNS niet verandert, geen nieuwe verification nodig, maar URL-property is aanbevolen).
10. 10.Monitoring: 30-daags post-launch watch voor indexing-status, rangewijzigingen op de top 100 keywords, organisch verkeer delta.

ROI-cutoff — wanneer migratie de moeite waard is

Een headless-migratie van deze omvang kost 40–80 k EUR aan engineering-kosten (incl. interne tijd + externe dev shop), plus een tijdlijn van 4 maanden.

Terugverdientijd over 3 jaar:

ROI: ~2,5 jaar bij 60 k EUR investering.

Voor wie het zich NIET terugverdient: - < 2 000 SKU, < 500 orders/maand → Shopify blijft goedkoper - Geen dev-team of committed externe partner voor 3-jarige onderhoudsperiode - De roadmap noemt geen B2B / multi-storefront / custom checkout

Praktisch advies

Migratie is geen "we kopen Medusa, programmeurs regelen het". Het is een business + tech + SEO + ops-project van 3–6 maanden. De grootste mislukkingen die we zagen:

1. 1.EU-compliance onderschat. SK-facturatie, OSS VAT, GDPR — alles vreet meer tijd dan een PoC met test-data belooft.
2. 2.Geen 301-plan = verloren rankings. 90 dagen verlies in organisch verkeer = 30–50 % omzetverlies. Eén slechte cutover volstaat.
3. 3.Geen customer-support runbook. Een cutover zonder 24/7-incident-plan = paniekreset naar Shopify na de eerste crisis.
4. 4.Data-migratie onderschat. 47k historische orders is geen "CSV-import in een weekend".

---

*Wij doen headless commerce-migraties voor 2k–50k SKU-catalogi, full-stack (Medusa.js / Saleor + Next.js + integraties + SEO-continuïteit). Overweegt u Shopify of BigCommerce te verlaten, dan doorloopt de eerste project assessment (4-uur workshop) de stack-beslissing, de tijdlijn, het budget en het 301-redirect-plan voor uw concrete catalogus voordat u zich aan de migratie verbindt.*