Yogateria Case Study: From WooCommerce to Headless Medusa and Next.js in 11 Weeks

Yogateria, a leading Brazilian yoga and wellness retailer, had six years of orders, a large customer base and a WooCommerce store held together by plugins. The Special Character rebuilt it as a headless commerce platform on Medusa and Next.js, moved every customer, order and coupon across, and kept every URL the store ranks on. Shoppers saw the same store. The business got a faster one that it now runs itself.
The new store is live on Yogateria's own domain, yogateria.com.br, and is taking orders. This case study covers the challenge, our approach, everything we delivered, the architecture, measured performance and the results.
The project at a glance
- Industry: e-commerce, yoga and wellness retail in Brazil
- Project type: platform migration from WooCommerce to headless commerce
- Stack: Medusa v2 and Next.js 15
- Every customer account migrated and linked on first sign-in
- Six years of order history migrated, with totals exact to the cent
- 3× faster page loads: main content in about 1 second, down from 3 seconds
- 100% of live URLs served at the same address, with no redirect hop
- 11 weeks from first commit to switching the main domain
The challenge: a successful store that had outgrown its platform
Yogateria sells yoga mats, meditation cushions, clothing and wellness products across Brazil. Over six years its WooCommerce store had collected four payment gateways, a page builder, a paid image optimiser, a feed plugin, a countdown plugin, a back-in-stock plugin, a custom checkout plugin and a one-way ERP connector.
Every one of those was a licence, an update risk and a source of slow pages. Simple changes like a new menu or a home-page shelf needed a developer. The team wanted a modern stack, but could not afford to lose search rankings, customer accounts or order history on the way. Five problems shaped the project:
- SEO risk. Product URLs were nested under a "primary category" that no other platform has. A guessed URL scheme produced 122 wrong addresses in early tests.
- Messy legacy data. Profile addresses lacked house number, neighbourhood and CPF for most customers, so a naive import would have made about 87% of addresses undeliverable.
- Brazil-specific commerce. PIX, boleto and card payments, CPF validation, postcode (CEP) lookups and delivery dates across 90,000+ postcode ranges.
- The warehouse runs on an ERP. Stock lives in Olist (Tiny) ERP. The old connector only read one endpoint, so orders, status, tracking and stock all needed a real two-way integration.
- No downtime allowed. The old store kept selling throughout, so every import had to be re-runnable as a final top-up on switch-over day.
Our approach: measure first, then prove parity before the switch
We treated the migration as an engineering project with acceptance tests, not a redesign. Every claim about the new store was checked against the live one, in four steps.
- Audit the real data. We loaded the full 2.6 GB database dump and counted everything that mattered: orders in scope, usable addresses, live coupons and active plugins. Decisions were made from those counts, not from assumptions.
- Build re-runnable importers. Catalogue, customers, orders, coupons, reviews, pages and back-in-stock subscriptions each have an importer that can run again safely. The switch-over top-up was the same command run against a fresher dump.
- Prove parity automatically. Automated gates checked that every live URL resolves, that pages match the old design pixel for pixel within set thresholds, and that checkout and sign-in work end to end in a real browser.
- Launch beside the old store. The new store went live on a subdomain first, hidden from search engines, while the old one kept selling. Once it had proved itself, the main domain moved over.
The storefront: same store for shoppers, rebuilt underneath
Customers recognise every page. Behind it is a Next.js storefront on an edge image CDN, with search and filters powered by Meilisearch.

Category pages with faceted filters, sale badges, review stars and colour swatches, all driven by search.

A three-step Brazilian checkout with CPF validation and PIX, boleto and card.

Product pages pick their layout per category. Clothing gets a stacked gallery beside a sticky buy box.
The mobile experience was built first:

Mobile-first product page.

Delivery date from the shopper's postcode.

Cart with free-shipping progress and upsells.
What we delivered: everything the plugins did, now built in
Each feature below was a separate plugin, a manual process or missing entirely on the old store. Now it is part of one codebase, with an admin screen the team uses without a developer.
Checkout and payments
- One payment provider (PagBank) for card, PIX and boleto, replacing four gateways
- Saved cards for signed-in customers
- Card data never touches our servers; it is encrypted in the browser
- Automatic reconciliation of missed payment notifications and refunds
- Stock checked before charging, so no one pays for a sold-out item
- A shipping-protection add-on and whole-real totals
Promotions
- Coupons migrated and matched case-insensitively, like the old store
- Tiered "spend R$X, save Y" order promotions
- Price lists by condition (for example 20% off a whole category) in two clicks
- Quantity tiers (1, 3 and 5 units)
- Free-shipping threshold and free gift, edited in the admin
- Campaign banners and countdown timers that switch on and off by date
Operations and ERP
- Two-way Olist (Tiny) ERP sync: orders go out; status, tracking and stock come back
- Real shipments with tracking links when the warehouse ships
- Advanced order search by coupon, CPF, date and status, with CSV export
- Back-in-stock alerts, with live subscribers carried over
- Transactional e-mails ported from the old theme, with bugs fixed
- Admin in English and Portuguese
Search, SEO and growth
- Every legacy URL preserved, plus a redirects manager
- Meilisearch behind every grid: typo-tolerant search, facets and synonyms
- Merchant drag-and-drop product order per category
- Product feeds for Google, Meta, TikTok and Pinterest at their old addresses
- GTM ecommerce events for GA4, Meta and TikTok
- Review stars from the existing review provider on every tile
Content the team edits
- Menus with a drag-to-nest editor
- Home page headline, category tiles and product shelves
- Best-sellers page sections
- 280+ pages and blog posts migrated into a visual block editor
- Product descriptions, galleries, size charts and page layouts
- One-click "refresh store" after edits
Customers and future-ready
- Passwordless sign-in with an e-mailed code, so there are no password resets to manage
- Imported customers see their full order history from 2020
- Guest orders join the account when the customer registers
- Delivery-date estimate from 90,000+ postcode ranges
- AI-agent ready: Universal Commerce Protocol, an A2A agent, llms.txt and Markdown pages
A simplified stack: twelve moving parts replaced by one platform
Before (WordPress and WooCommerce): a paid image optimiser, a page builder, a custom checkout plugin, 4 payment gateways, a feed plugin, a countdown widget, a back-in-stock plugin, a postcode delivery plugin, a one-way ERP connector, SEO-plugin redirects, a postcode cache and an SMTP plugin.
After (Medusa and Next.js), item for item:
- Paid image optimiser → Cloudflare image CDN
- Page builder → visual block editor
- Custom checkout plugin → native 3-step checkout
- 4 payment gateways → PagBank (card, PIX, boleto)
- Feed plugin → feeds module
- Countdown widget → countdown module
- Back-in-stock plugin → back-in-stock module
- Postcode delivery plugin → delivery estimate module
- One-way ERP connector → two-way Olist ERP module
- SEO-plugin redirects → routing and redirects module
- Postcode cache → live CEP lookup
- SMTP plugin → Postmark e-mail
Architecture: headless, and every piece replaceable
The storefront and the commerce engine are separate apps. Background work runs on its own worker, so imports and syncs never slow down shoppers.

Shoppers reach the Next.js storefront; it calls the Medusa server, which shares Postgres, Redis and Meilisearch with a worker. Images come from Cloudflare R2.
- Shoppers on phone and desktop reach a server-rendered, cached Next.js storefront.
- Cloudflare serves images from R2 with resizing.
- The storefront calls the Medusa server (Store and Admin API).
- A Medusa worker runs jobs, syncs and e-mail.
- Both share Postgres, Redis and Meilisearch.
- Integrations: PagBank (card, PIX, boleto), Olist ERP (orders, stock, tracking), Postmark (transactional e-mail), plus reviews and Google Tag Manager.
Performance: about 3× faster than the store it replaced
We measured the old WooCommerce store before the migration, then measured the new store the same way after launch: same machine, same script, same pages, cold cache. The main content now appears in about a second on every page type.
- 3.0 s → 1.0 s: average time to show the main content across five page types
- 51% fewer network requests per page (848 → 412 across the five pages)
- 0 layout shift on every page. The old home page scored 0.126, above Google's 0.1 limit for "good"
- 7.6 MB → 0.96 MB home page weight. The old figure is a lower bound: it excludes the HTML document itself

Largest contentful paint (time until the main image or heading is on screen), old WooCommerce store in September 2026 versus the new Medusa store in November 2026. Lower is better.
Largest contentful paint by page type
- Home: 2.74 s → 1.16 s, 58% faster; requests 201 → 82; layout shift 0.126 → 0
- Category: 3.02 s → 1.06 s, 65% faster; requests 148 → 90; layout shift 0.003 → 0
- Product: 3.34 s → 0.92 s, 72% faster; requests 220 → 87; layout shift 0.004 → 0
- Search results: 3.88 s → 1.06 s, 73% faster; requests 115 → 89; layout shift 0 → 0
- Cart: 2.22 s → 0.84 s, 62% faster; requests 164 → 64; layout shift 0 → 0
Lighthouse scores on the live store

Lighthouse, desktop, home page of the live store.
- Home: performance 97 on desktop and 75 on mobile; accessibility 100; best practices 100; SEO 100
- Category: performance 95 on desktop and 78 on mobile; accessibility 100; best practices 100; SEO 100
- Product: performance 82 on desktop and 70 on mobile; accessibility 98; best practices 100; SEO 100
What made it fast
Pages are rendered on the server and cached, and list pages ask the API only for the fields a product tile shows. Images come from the original files resized at the edge by Cloudflare. Nothing loads before the first paint unless it is visible: menu drawer photos, hover photos and video players wait, and analytics tags load on the shopper's first tap or click. Layout shift is zero because every image and widget reserves its space.
How we measured
Before and after: Chromium at 1440×900, cold cache, three runs per page, median, with ad trackers blocked on both sites so the comparison is fair. Lighthouse 12.6: desktop and mobile presets, mobile as the median of three runs. Mobile uses simulated slow 4G and was run from India against servers in the US, which costs it several points; Google PageSpeed Insights, which runs near the servers, gave the home page a median of 90 on mobile in October.
Results: a faster store the team runs itself
The outcome in three numbers
- 3× faster pages: the main content appears in 1.0 s on average, down from 3.0 s on the old store, with 97/100 on desktop Lighthouse and 100 for accessibility, best practices and SEO.
- 0 ranked URLs lost: each live product URL was taken from the old store's own permalink and checked by two automated gates before launch.
- 1 payment provider instead of four, one ERP integration that works in both directions, and one codebase instead of a dozen plugins to update.
Data moved without loss
Order totals were kept exactly as the payment gateway captured them, never recalculated, and verified to the cent. Discounts that the old store had stored as negative fees landed as real discounts. Customer addresses were rebuilt from each customer's most recent order, so the Brazilian fields a shipping label needs are present.
Imported customers sign in with a code sent to their e-mail. The first time they do, the code finds their existing account, so nobody ends up with a second, empty one.
The team runs the store
Menus, the home page, best-sellers, banners, countdowns, promotions, price lists, free-shipping rules, redirects, search synonyms and product order are all edited from the admin. Seasonal campaigns now mostly mean admin work: a banner with start and end dates, a menu entry and a price list.
Safety switches keep risky actions off until the business turns them on: e-mail sending, ERP writes and review-provider writes each have their own toggle.
Tech stack
- Medusa 2 (commerce engine) and Next.js 15 (storefront)
- React 19 and TypeScript
- PostgreSQL, Redis (events and workflows) and Meilisearch (search)
- Puck (visual editor)
- Railway (hosting) and Cloudflare R2, Pages and Images
- PagBank, Olist (Tiny) ERP and Postmark
- Google Tag Manager
- Turborepo and pnpm
What comes next
The platform is built to grow. These are the next steps we have recommended:
- AI shopping assistant. The store already speaks the protocols AI agents use to browse and buy. A chat assistant on top of the same API can answer sizing and product questions and build a cart.
- Subscriptions and refills. Incense, oils and wellness consumables suit recurring orders with PIX or saved cards.
- Loyalty and referrals. Points and referral rewards built on the existing promotions engine.
- B2B and wholesale. The business also sells through resellers. Customer-group price lists and a wholesale account area come almost free with Medusa.
- Horizontal scaling. Move card handling and page caching to shared storage, so the storefront and API can run several instances for peak days like Black Friday.
- Server-side analytics. Send purchase events server to server for more accurate ad attribution and fewer scripts in the shopper's browser.
Planning a replatform?
We migrate WooCommerce, Shopify and custom stores to headless commerce, with the data and SEO checks built in from day one. Read more about our e-commerce development work and our Medusa developers, compare engines in Shopify or Medusa.js, or see the summary on the Yogateria project page. Visit the live store at yogateria.com.br, then talk to us about moving your store without losing a customer, an order or a ranking.
