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. **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. **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
| Functie | Keuze 2026 | Prijs | |---------|------------|-------| | Search | Algolia | 0,50 EUR / 1k search ops, ~180 EUR/maand voor 12k SKU + 400k maandelijkse searches | | Payments | Stripe (Standard + Connect voor B2B) | 1,4 % + 0,25 EUR per transactie EU, B2B Connect 0,5 % flat | | Email / Marketing | Klaviyo | 90 EUR/maand voor 10k profielen | | Observability | Sentry + PostHog | Sentry 26 EUR/maand, PostHog 0 EUR (free tier tot 1M events) | | Image CDN | Cloudflare Images | 5 EUR/maand + 1 EUR / 100k delivery | | DAM (Digital Asset Management) | Cloudinary of self-hosted Imgproxy | 90 EUR/maand of 15 EUR self-hosted | | Tax | Avalara AvaTax (SK + EU OSS) | 250 EUR/maand | | Shipping | Packeta API + Slovenská pošta API | 0 EUR (consumption-based) | | Reviews | Trustpilot Business | 200 EUR/maand |
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. **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. **301-redirect map:** elke non-trivial URL-wijziging geïndexeerd in `redirects.json`, gevalideerd tegen production load tests. 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. **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. **Open Graph-migratie:** og:image, og:title, og:description per pagina. Dynamic OG image generation via Next.js dynamic route + edge runtime. 6. **robots.txt:** noindex behouden voor admin, account, cart, checkout. Voeg `Sitemap:`-directive toe. 7. **Internal linking:** breadcrumbs, related products, category navigation. Spider crawl via Screaming Frog om te bevestigen dat geen enkele pagina een orphan is. 8. **Core Web Vitals:** LCP, FID/INP, CLS-doel voor de top 50 landing pages. Lighthouse CI in de deployment-pipeline. 9. **Search Console-herverificatie:** nieuwe property voor nieuwe infra (als DNS niet verandert, geen nieuwe verification nodig, maar URL-property is aanbevolen). 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:**
| Voordeel | Jaarbesparing | |----------|--------------| | Shopify Advanced + Apps savings | 4 200 EUR | | LCP improvement → +6 % conversion | 12k SKU × 20 EUR AOV × 1,2k orders/mnd × 0,06 = ~17 280 EUR | | Eliminated Shopify Plus upgrade (zou de volgende stap zijn, 25k+ USD/jaar) | 23 000 EUR | | Sneller B2B quote handling | 12 000 EUR (1 FTE-dag × 24 maanden) | | **Totaal 3-jaarsbesparing** | **170 940 EUR** |
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. **EU-compliance onderschat.** SK-facturatie, OSS VAT, GDPR — alles vreet meer tijd dan een PoC met test-data belooft. 2. **Geen 301-plan = verloren rankings.** 90 dagen verlies in organisch verkeer = 30–50 % omzetverlies. Eén slechte cutover volstaat. 3. **Geen customer-support runbook.** Een cutover zonder 24/7-incident-plan = paniekreset naar Shopify na de eerste crisis. 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.*