Medusa.js 2.0 Migration Guide: What Changed and How to Upgrade Without Breaking Your Store

The core change in Medusa 2.0 is the shift from a service-based monolithic backend to a fully modular architecture. In v1, Medusa's commerce logic lived in tightly coupled services. In v2, each commerce domain, such as cart, product, order, payment, and inventory, is now a discrete module with its own data layer, events, and API surface.

This matters for migration because customisations you built against v1 services will not map directly to v2 modules. Custom service overrides, event subscribers, and direct entity manipulation all need to be reviewed and in many cases rewritten.

The teams that struggle most with Medusa 2.0 migrations are the ones that start refactoring code before they have a complete picture of what they have built. Before writing a single line of migration code, run a thorough audit of your existing installation.

Custom Services and Overrides

List every service you have extended or overridden. In Medusa v1, it was common to extend the ProductService, CartService, or OrderService to add custom business logic. In v2, this logic belongs inside custom modules. Identify what each override does and which v2 module or workflow is the appropriate home for it.

Subscribers and Event Listeners

If you built real-time integrations on top of Medusa's EventBus, check which events you are subscribed to and verify those events still exist in v2 or have been renamed. The event naming conventions changed in 2.0 and silent failures in subscriber registration are a common source of post-migration bugs.

API Route Customisations

Custom API endpoints built on top of Medusa's v1 route structure may need to be ported to the v2 API layer. Review each custom route and confirm whether it still functions as expected after the module architecture change.

Attempting a big-bang migration where you upgrade everything at once and then fix what breaks is the most common way teams end up with extended downtime and a frustrating debugging session. A phased approach takes more planning but produces far more predictable outcomes.

Phase 1: Upgrade in a Staging Environment

Never run a Medusa 2.0 migration on your production database first. Clone your production environment, including database and environment variables, and run the upgrade there. This gives you a safe space to identify breaking changes without customer impact.

The official Medusa.js migration documentation outlines the upgrade script and database migration steps. Run through these in staging at least twice before touching production.

Phase 2: Migrate Custom Modules Before Core Data

Port your custom service logic to v2 modules in staging first. Test each custom module independently before running the core data migration. This way, when you run the data migration script, you are applying it to a system where the application layer is already validated.

Phase 3: Run the Data Migration Script on a Database Snapshot

Medusa 2.0 includes a data migration script that transforms your v1 database schema to the v2 structure. Before running this on any live database, take a full snapshot. The migration script is not reversible in place, so your snapshot is your rollback plan.

Based on what engineering teams encounter most often when upgrading Medusa v1 stores, these are the areas that need the most attention.

• Custom payment provider implementations built against the v1 AbstractPaymentService interface need to be rewritten against the v2 payment module interface

• Direct database queries or TypeORM entity manipulation that bypasses the service layer will fail or produce unexpected results once the schema changes

• Frontend storefronts using undocumented internal API routes may break since the internal API structure changed significantly in v2

• Any plugin that has not been updated for Medusa 2.0 compatibility will need to be replaced or maintained as a custom module

If you are evaluating whether the migration effort is worth it for your current stack, the Askan Commerce team has documented their experience running Medusa.js in production across multiple architectures. You can explore their technical resources at ecom.askantech.com or read their broader engineering perspective at askantech.com/medusa-js-ecommerce-development-company.