Migrating from Shopify to Medusa.js: Data, Redirects, and What to Test First

For most merchants, Shopify works well at the start. The setup is fast, themes are polished, and the app ecosystem covers most standard requirements. The friction appears later, usually when a business needs something that sits just outside what Shopify allows.

Transaction fees compound as volume grows. Custom checkout logic requires Shopify Plus, which adds significant cost. B2B pricing, multi-vendor support, and advanced inventory workflows either require expensive apps or awkward workarounds. And because Shopify is a closed platform, you have limited control over how the backend behaves.

Medusa.js addresses these limitations directly. It is open-source, self-hosted, and built around a modular architecture. You own the codebase, pay no transaction fees, and can extend or replace any part of the platform to fit your exact requirements.

A migration that is rushed tends to create problems that take longer to fix than the original move. Before touching any data or spinning up a Medusa instance, spend time on the planning phase. This is where the quality of your migration is actually decided.

Audit What You Have on Shopify

Start with a complete inventory of everything currently living in your Shopify store. This includes products and all their variants, options, and metadata. It includes customer records with addresses, order history, and account credentials. It includes active discount codes and gift cards. And critically, it includes your current URL structure, every product URL, collection URL, and page URL that has been indexed by search engines or shared in marketing materials.

Knowing exactly what exists is the only way to know what needs to move and what can be intentionally left behind. Old or discontinued products, expired promotions, and test customer accounts do not need to be migrated.

Map Shopify Concepts to Medusa Concepts

Shopify and Medusa use different terminology for similar ideas, and the data structures do not map one-to-one. A Shopify collection becomes a Medusa product collection. Shopify product options become Medusa product options and variants. Shopify customer addresses map to Medusa customer addresses but require attention to the required field structure. Shopify discount codes move into Medusa as promotions, but the configuration logic is different enough to require manual recreation rather than a direct import.

Spending time on this mapping before the migration saves you from discovering mismatches mid-import when data is partially loaded and harder to fix.

Products are usually the highest-volume part of any Shopify migration. Medusa provides an official source plugin called medusa-source-shopify that handles product and collection import directly. To use it, you create a private app in your Shopify store with read access to products, retrieve the API credentials, and configure the plugin in your Medusa backend.

Setting Up the Shopify Source Plugin

Install the plugin in your Medusa project and add the configuration to your medusa-config.js file. The plugin requires two environment variables: your Shopify store domain, which is the subdomain portion of your myshopify.com address, and your Shopify private app password. Once configured, the plugin runs automatically when the Medusa server starts and imports your products, variants, collections, and pricing into Medusa.

For stores with large catalogs, the plugin uses batch processing to handle imports in segments rather than trying to load everything in a single request. Each page of products retrieved from Shopify is queued as a batch job, which makes the process more reliable for stores with thousands of SKUs.

What the Plugin Imports and What It Does Not

The Shopify source plugin migrates products, product variants, product options, collection memberships, and basic pricing. It also handles product metadata through Shopify metafields, storing them in Medusa as product metadata. What it does not migrate includes order history, customer accounts, discount codes, gift cards, or payment records. Those require separate handling.

Customer data must be exported from Shopify and imported into Medusa through the customer API or a custom import script. Order history, if needed for reference, is typically kept accessible through a read-only Shopify connection or a data warehouse rather than being fully ported into Medusa, since historical orders from a different platform cannot be reconstructed with all their original payment and fulfillment details intact

This is the part that many technical teams underestimate, and it is where migrations most commonly damage organic search traffic. When you move from Shopify to a new storefront, your URL structure almost certainly changes. Shopify product URLs follow a fixed pattern. Your new Medusa storefront, built on Next.js, will have its own routing structure. Any URL that has changed needs a 301 redirect from the old address to the new one.

Building Your Redirect Map

Export your full URL list from Shopify using the sitemap or a crawl tool. Then map every old URL to its corresponding new URL on the Medusa storefront. Products that keep the same handle will often be straightforward to redirect. Collections that have been renamed or restructured need careful mapping. Blog posts and static pages need to be moved individually.

The redirect map should be completed and reviewed before the new storefront goes live. Implementing redirects after launch means a window of time where indexed URLs return 404 errors, which signals to search engines that content has been removed rather than moved.

Implementing Redirects in Next.js

In a Next.js storefront, you implement redirects in the next.config.js file using the redirects function. Each entry specifies a source path, a destination path, and the permanent flag set to true for 301 redirects. For stores with large numbers of URLs, you can load the redirect map from an external file and dynamically generate the redirects array at build time.

Preserve your canonical tags and metadata on the new storefront as well. The product and page metadata that existed on Shopify, including meta titles, meta descriptions, and Open Graph tags, should be recreated accurately on every corresponding page in Medusa.

For a detailed technical reference on managing redirects and preserving SEO equity during platform migrations, Google's official Search Central documentation on site moves covers the crawl and indexing behavior you should expect after implementing 301 redirects.

Customer passwords cannot be migrated from Shopify. Shopify uses its own hashing mechanism and does not expose password hashes through the API. This means that when you migrate customer records to Medusa, every customer will need to set a new password on their first login to the new store.

The standard approach is to send a reactivation email to all migrated customers before or shortly after launch, explaining the migration and prompting them to set a new password. The email should acknowledge that they are existing customers and make the password reset process simple and clear. Customers who do not respond to the reactivation email can still recover their account through the standard forgot password flow on the new storefront.

Customer order history from Shopify will not be visible in the Medusa customer account area by default, since those orders exist only in Shopify. If historical order visibility is important for your customers, one option is to display Shopify order history through a separate API call from within the Medusa storefront account page, keeping the Shopify store in read-only mode for a defined period after migration.

Testing before cutover is not optional. The sequence of what you test matters as much as the coverage. Start with the flows that directly affect revenue, then work outward to supporting functionality.

The Purchase Flow End to End

Test the complete purchase journey from landing on the homepage through product discovery, product selection, adding to cart, checkout, payment, and order confirmation. Do this with your actual production payment credentials in a staging environment that mirrors production. A checkout bug discovered after go-live will cost you real orders.

Test with different combinations: a single product, multiple products, products with variants, with a discount code applied, with shipping to different regions, and with both guest checkout and logged-in account checkout. Each combination exposes a different potential failure point.

Redirects and URL Validation

Crawl the old Shopify sitemap and verify that every URL in it either resolves correctly on the new storefront or returns a 301 redirect to the correct destination. A 404 from any previously indexed URL is a problem that needs to be fixed before launch. Tools like Screaming Frog or Ahrefs can automate this verification against your redirect map.

Product Data Accuracy

Spot check product records across different categories and catalog sections. Verify that variant options display correctly, prices reflect accurately by region and currency, product images loaded cleanly, and inventory levels imported without errors. Pay extra attention to products that had complex metafield configurations in Shopify, as these are most likely to have lost data during import.

Search and Filtering

If your Medusa storefront uses Algolia, MeiliSearch, or any other search provider, verify that the product index is current and that search returns accurate results. Test filter combinations that your customers use frequently: filtering by category, price range, availability, and any custom attributes your catalog uses.

Email and Notification Flows

Trigger test orders, returns, and account actions to confirm that transactional emails fire correctly. Order confirmation, shipping notification, return request acknowledgment, and password reset emails all need to send reliably from the new setup. If you are using a third-party email service like Postmark or SendGrid, verify that your Medusa backend is correctly connected and that the templates render as expected.

Teams at Askan Technologies run structured pre-launch QA across all these dimensions when delivering Medusa migrations for clients. For more detail on our Medusa development and migration capabilities, visit our Medusa.js development services page.

The actual cutover, the moment when live traffic moves from Shopify to the new Medusa storefront, is best done during a low-traffic window. For most businesses this means late evening or early morning on a weekday. Schedule the cutover in advance and communicate it to your team so that support, operations, and marketing are all aware and available.

Keep your Shopify store in read-only or password-protected mode for two to four weeks after migration rather than canceling the subscription immediately. This gives you a safety net to reference historical orders, recover any data that was missed during migration, and handle any customer queries that reference their old Shopify order history.

Monitor your Medusa backend error logs, your CDN and hosting metrics, and your checkout conversion rate closely in the first week after launch. Anomalies in any of these will surface issues that did not appear in testing. Respond quickly to anything that looks unusual, since a slow response to a checkout issue can turn a minor bug into a significant revenue impact.