Help

2.3.2. Migrate from Shopify to Medusa

In this chapter, you'll learn how to use the Medusa MCP server to migrate your store's data from Shopify into Medusa.

What is the Migration Tool?#

The Medusa MCP server exposes a get_import_data_from_shopify_or_other_platform_guide tool that returns a complete, step-by-step implementation guide for importing or migrating existing store data into Medusa from Shopify, including Shopify Plus.

You tell your AI agent that you're coming from Shopify and what you want to bring over, and it produces a working import: your store's data lands in Medusa with Shopify's model mapped onto Medusa's, and, depending on the approach you choose, the import can be re-run whenever you need it.

The tool can produce a migration for any of the following data types:

Products, variants, prices, and images
Inventory levels
Collections and categories

The migration can also support other types like orders and customers, but it's mainly catered toward catalog data.

Note: The same tool also has curated guides for WooCommerce and Magento / Adobe Commerce. It's platform agnostic beyond those: for any other source, it returns a generic migration guide, so you can use it to migrate from platforms like BigCommerce and commercetools. Always tell your AI agent the actual platform you're migrating from, since knowing the real platform helps your agent map its data model correctly.

Who is this Useful for?#

This tool is useful for:

Merchants and teams migrating an existing store from Shopify to Medusa.
Agencies and solution partners performing repeated Shopify migrations for clients.
Teams running Medusa alongside a Shopify store that needs continuous data synchronization.
Developers who need to seed a Medusa development environment with real catalog data.

Why Use This Tool?#

A migration is the one task where a plausible-looking result is the most dangerous. The import runs, rows appear in the database, and the problems only surface later: products that aren't purchasable, images that break when the Shopify store is switched off, and records that can't be matched back to Shopify when you need to re-sync.

Compared to reading the documentation yourself or asking a Medusa question, this tool gives you:

A migration plan rather than an accumulation of answers. Your agent gets the ordered approach for moving data from Shopify into Medusa, instead of assembling one from separate answers about importers, workflows, and file providers.
Source-platform quirks accounted for. The curated Shopify guide carries the specifics of how Shopify models and exports its data, which is knowledge that lives in Shopify's ecosystem rather than in Medusa's documentation.
Imports that can be run again. When you choose the API-based approach, the result is built to be idempotent and resumable, so a migration becomes ongoing synchronization rather than a one-time event you can't repeat.

Your agent still calls ask_medusa_question while it works, for the exact Medusa APIs and workflows involved. The guide decides the approach; the documentation supplies the details.

Migration Approaches#

The tool supports two migration approaches, and the guide it returns differs based on the approach you choose:

Approach	How it works	When to use it
Custom (default)	Builds a custom module and workflows in your Medusa application that pull data from Shopify's API. The import is idempotent, resumable, and re-runnable, and it can be triggered from an admin widget, a scheduled job, a CLI command, or a webhook.	You need to migrate inventory levels or re-host images in Medusa's file provider, or you want ongoing synchronization rather than a one-time cutover.
CSV	Builds a transform from Shopify's CSV export into the CSV format that Medusa's built-in product importer accepts. You then import the resulting file from the Medusa Admin.	You can't create an API app or credentials on Shopify, or you want a single minimum-effort cutover and will handle stock quantities and images yourself.

The CSV approach is much faster to build, but it's lossy: inventory quantities aren't migrated, images stay as URLs pointing to Shopify's CDN, collections usually aren't part of the export, and most exports have no ID column, so records can't be keyed back to the source for later re-syncs.

Warning: Don't mix the two approaches on the same store. The CSV path can't key records to source IDs, so running the API-based importer afterwards treats every record as new and fails on duplicate product handles.

How to Use the Migration Tool#

Medusa MCP server connected to your AI tool or IDE↗

After connecting to the Medusa MCP server, ask your AI agent to migrate your data. Your agent detects the intent, calls the migration tool with Shopify as the source platform, along with the data type and approach, then follows the returned guide.

For example:

Example prompt
❯Migrate my Shopify store's products to Medusa.

Other prompts that trigger the tool:

Example prompts
❯Import our Shopify catalog into Medusa.

Example prompts
❯We're switching from Shopify. Move our products and customers over to Medusa.

What to Expect#

Your AI agent asks which approach you want, if you haven't specified one, and explains the trade-offs.
It calls the migration tool for Shopify, along with the data type and approach.
It scaffolds the module, workflows, and any triggers or transforms the guide specifies.
It guides you through running the import and verifying the migrated data.

Tip: If you're migrating multiple data types, ask your agent to start with products. Other entities, such as orders and inventory, reference products, so migrating products first avoids unresolved references.

Not an MCP server user?#

If you don't use the Medusa MCP server but need help migrating your store's data to Medusa, contact our team for other options:

Was this chapter helpful?