Start with two buckets
No migration is perfect, so the goal isn't zero problems. It's making sure the problems aren't disasters. Sort everything into two buckets and spend 70 to 80% of your effort on the first.
Bucket 1 (Critical): costs money by the minute
- Product pages
- Cart and checkout
- Payments
Bucket 2 (Survivable): annoying, but fixable
- About page layout
- An analytics plugin down for a day
- Minor content issues
The 14 mistakes, in order
Before the build
1. Bringing stakeholders in late
Customer service, operations and management use the platform daily and have requirements nobody wrote down. So do third parties like email marketing, analytics and SEO. Involve them all at the start.
2. A vague scope
Sit with each stakeholder, write their requirements down in detail, and use that to set realistic timelines.
3. One giant sprint
Split the scope into three or four phases with start and end dates, so you know early when you're off track.
4. No launch date
Set a hard launch date at the start. Without one, "we'll go live when it's ready" turns into months of delay.
During the build
5. No experienced Medusa developer
You need someone who knows the codebase to guide architecture, strategy and integrations, especially if you lean on AI agents. That's the work AI won't get right on its own.
6. Skipping an independent code review
After months on one project, teams stop seeing the obvious. A fresh review catches bugs and security holes.
7. Building until launch night
Set a feature cutoff one to two weeks before launch. Use that time to test end to end, on real devices, not just browser dev tools.
8. Leaving SEO until launch week
URLs, page structure, redirects, metadata and sitemaps all change. Give an SEO specialist ownership from the start.
Launch prep
9. No single game plan
One document with every person, their responsibility and one communication channel. Nobody should be waiting on an API key during the launch window.
10. Untested production keys
Write down every environment variable you'll switch over, and test them before launch day.
11. No dress rehearsal
Walk through the offline window, when the old store is down and the new one isn't live, in 10-minute blocks with an owner for each. Keep it short and boring.
Launch and after
12. No buffer
If you expect four hours offline, plan for six.
13. No rollback plan
Decide who's in charge and what triggers a rollback, such as checkout or cart failing, so customers can keep shopping while you fix it.
14. Walking away after launch
Run a hypercare period of about 10 days: check backend and storefront logs and error tracking every few hours, and watch checkout success rates.
What this looks like in practice
For Wipertech, we migrated their Australia and New Zealand stores to Medusa, order history included. The cutover took 3 to 4 hours offline.
Read the Wipertech case study ↗
Frequently asked questions
How long is a store offline during a Medusa migration?
It depends on data volume. Wipertech's cutover took 3 to 4 hours offline. Add a buffer of about 50% to your estimate.
Can you migrate orders and customers, not just products?
Yes. Products, customers and order history can all move to Medusa. Treat the data migration as a bucket 1 item and test it before launch.
Will we lose SEO rankings?
Not if redirects, URL structure, metadata and sitemaps are planned from the start, with an SEO specialist involved.
Which platforms can you migrate from?
We've moved stores to Medusa from Shopify, WooCommerce and Craft Commerce.
Official Medusa JS Experts