Migrate from Shopify Plus to Medusa

Staging should mirror the production topology closely enough that a failed migration, a missing secret or a worker that never picks up jobs shows up before go-live. A self-hosted Medusa deployment needs a PostgreSQL database and a Redis database, plus two Medusa instances: one in server mode for the API and admin dashboard, and one in worker mode for background tasks. Staging is also the place to confirm that the production modules replace the development defaults, so the team sees Redis-based caching, the event bus, the workflow engine and locking, and S3 file storage working before real orders depend on them.

• Full topology: Run one server-mode instance and one worker-mode instance against separate processes, not a single combined instance, so background jobs behave as they will in production.
• Production modules: Confirm that Redis backs caching, the event bus, the workflow engine and locking, and that uploads go to S3 rather than local disk.
• Migration step: Check that the predeploy script runs database migrations before each startup and that a failed migration blocks the rollout.
• Secrets: Set distinct COOKIE_SECRET and JWT_SECRET values for the server and worker, and keep them out of source control.
• Health checks: Call the /health endpoint on each instance and confirm the result before you run test orders.

Confirm the exact environment variable names and module configuration for your Medusa version with the deployment documentation before you copy any example into your pipeline.

Production is where the topology carries real customer, payment and order data, so the configuration should be reviewed as a controlled change. Keep the server and worker instances separate so that heavy background work, such as scheduled or event-driven jobs, does not slow the storefront API or the admin dashboard. Run database migrations through the predeploy step rather than by hand, so every startup applies the same schema changes in the same order.

• Separate roles: Run the server instance for the API and admin dashboard, and the worker instance for background tasks, each with its own process and scaling settings.
• Managed or self-managed data stores: Decide whether PostgreSQL and Redis run on your own servers or on a managed service in your cloud account, and document backups and failover for each.
• File storage: Store product images and uploads in S3 or an S3-compatible store, with access policies that limit who can write to the bucket.
• Access to secrets: Load COOKIE_SECRET, JWT_SECRET and database credentials from a secrets manager or the platform's secret store, and rotate them on a schedule your security team sets.
• Health and monitoring: Use the /health endpoint in load balancer checks and alert on failed health checks and stalled worker queues.

Before launch, ask your partner or internal team to document who can deploy, who can rotate secrets and how a failed release is rolled back.

A disaster recovery environment has to restore more than the application code. Recovery depends on a current PostgreSQL backup, a Redis state that the team understands, S3 objects that are still reachable, and the same secret values that signed existing sessions and tokens. Plan the recovery as a rehearsed procedure, because a restored database with the wrong secrets or a missing file bucket can look healthy in part and still fail for customers.

• Database restore: Test restoring PostgreSQL from backup into an isolated environment, then run the predeploy migration step against the restored schema before starting any instance.
• Redis expectations: Decide which Redis data must survive a failover, such as workflow state and locks, and which can be rebuilt. Confirm this with your Medusa version's documentation.
• Secrets continuity: Keep a protected copy of the COOKIE_SECRET and JWT_SECRET values so that restored instances can validate existing sessions, and record where that copy is stored.
• Object storage replication: Replicate the S3 bucket to a second location or region in your own account, and test that restored product images resolve from the storefront.
• Recovery checks: Start the server and worker instances in the recovery environment, call /health on each, and place a test order before you redirect traffic.

Ask for a written recovery runbook with recovery time and recovery point targets that your business owners have approved, and rehearse it at least once before you rely on it.

A brand with a modest product range and a storefront it already designed for headless delivery usually has the smallest data job. The product, customer and order exports are short, and the main work sits in the Medusa side: modeling products and prices, wiring checkout and payment providers, and connecting the existing frontend to the Store API. Because the storefront may be custom already, the rebuild is often a connection exercise rather than a redesign.

• Data scope: Export products, customers and orders from the admin, then check which images and metafields the CSVs leave out.
• Storefront work: Confirm how much of the current frontend calls Shopify APIs directly and what would need to change to call Medusa.
• Checkout: Map the payment gateways and shipping rules you use today to Medusa payment and fulfillment providers.
• Operations: Even a small store needs a server instance, a worker instance, PostgreSQL and Redis running and patched.
• Redirects: Plan URL redirects for every product and collection page that changes path.

Before you commit, ask your partner to confirm the storefront effort in writing, since it is the largest variable in this case.

A B2B merchant depends on company accounts, buyer-specific prices, catalogs and payment terms. These rules often live in Shopify Plus B2B features or in apps layered on top, so the migration is mostly a modeling exercise. Medusa supports B2B stores through its modules, but the account structures, approval flows and negotiated price lists must be designed and built rather than copied across.

• Account model: Document companies, locations, buyers and roles before mapping them to Medusa customer groups and access rules.
• Price logic: Export every price list and volume tier, then confirm how Medusa pricing modules will apply them per customer group.
• Access rules: Role-based access control in the admin is part of Medusa Enterprise Edition, which requires a commercial agreement with MedusaJS, Inc., so confirm whether you need it.
• Order history: Plan how open invoices and past orders for each company will be imported and linked to the right account.
• Testing: Build test accounts for each pricing and approval scenario and run them against the new store before cutover.

Ask whether the B2B rules will be built as custom modules or workflows, and what sign-off the business expects for pricing parity.

A merchant with many Shopify apps and custom Shopify Functions has the largest rebuild. Each app supplies a feature, such as reviews, loyalty, subscriptions, discounts or shipping rules, and each Function runs logic at checkout or on carts. None of these transfer to Medusa. Each one must be retired, replaced with an existing integration, or rebuilt as a Medusa module, subscriber or workflow step, and the checkout logic needs particular attention.

• App inventory: List every installed app, what it does, and which data it stores, since some data will not come through a CSV export.
• Function logic: Document each Shopify Function's inputs and outputs, then decide whether it becomes a pricing rule, a promotion or custom workflow code.
• Metafields and automatic discounts: Confirm how metafield values and automatic discounts will be recreated, because the CSV exports do not carry them.
• Background jobs: Move scheduled and event-driven tasks to the worker instance and test retries.
• Scope control: Agree in writing which apps are replaced in phase one and which are dropped.

Ask for a feature-by-feature mapping before any build estimate is accepted, because that list defines the true scope of this case.