Medusa’s documentation explains modules well, for developers. It tells you how to define a data model, write a service, and register the module in your config. All of that is useful if you are the person writing the code, and none of it answers the question a CTO is actually asking: do Medusa v2 modules reduce my risk, or add to it?
This is that explanation, without code. The short version: Medusa v2 modules split commerce into independent parts you can replace one at a time. That is genuinely valuable, and it is not free. What follows is what modularity buys, what it costs, and the one question that decides whether the trade is worth it for your business.
What Medusa v2 modules actually replaced
Start with what came before. In most commerce platforms, including Medusa v1, the commerce logic is one interconnected system. Products, carts, orders, pricing and inventory share a database and know about each other directly. Change how pricing works and you are reaching into code the order system depends on.
That coupling is the problem Medusa v2 modules were designed around, and it is why customising a traditional commerce platform gets more expensive over time rather than cheaper. Every change has to be checked against everything it might touch.
Medusa v2 broke that apart. Commerce logic now lives in roughly two dozen independent modules: Cart, Product, Order, Payment, Pricing, Inventory, Fulfillment, Promotion, Tax, Customer, Region, Sales Channel, Stock Location, Currency, User, Auth, API Keys, and more added since, including Loyalty, Store Credit and Translation. The full list sits on Medusa’s commerce modules page.
The architecturally important part is not the count. It is that the modules have no database-level dependencies on each other. The Order module has no foreign key into the Pricing module’s tables. They are connected instead through a lightweight links system that describes relationships without fusing the two together, a change Medusa set out in its v2 release notes.
Two consequences follow from the way Medusa v2 modules are separated, and both matter at decision level.
A change is contained. Replacing how pricing works does not require understanding the order system, because the order system does not reach into pricing’s data. The blast radius of a change is one module plus the workflows that call it.
Business logic moved somewhere visible. Anything spanning modules, such as add to cart, complete order or process a return, is written as a workflow: a named sequence of steps, each with rollback logic if a later step fails. In v1 that logic was scattered through service methods. In v2 it is a defined object with a name.
That is a governance improvement as much as a technical one. When someone asks what exactly happens when an order is placed, there is now a specific answer rather than an archaeology exercise. Medusa’s modules documentation covers the mechanics for the team who will build it.
What you can actually swap
Replaceable modules appears on every headless commerce site, and Medusa v2 modules are no exception. Here is what it means concretely.
Each of the Medusa v2 modules can be replaced with your own implementation or with a third-party service, because Medusa defines an interface for each one. In practice, teams do this in three situations.
Connecting to a system that already owns the data. The most common real case. A distributor whose stock levels live in an ERP or warehouse management system does not want a second inventory system in the commerce platform disagreeing with the first. Replacing the Inventory module with one that reads the ERP removes the sync problem rather than managing it.
Pricing that does not fit a pricing engine. Contract pricing negotiated per customer, volume breaks that depend on annual commitments, rules that live in a spreadsheet somebody maintains. Every hosted platform has a pricing model, and yours either fits it or you spend years working around it.
Regional payment and fulfilment. Where a local method has no ready integration, and outside the US and Western Europe that is common, you build the module rather than wait for a plugin.
Two clarifications are worth having before this feature gets oversold.
Swapping is building, not configuring. Replacing one of the Medusa v2 modules means writing and then maintaining that module. The architecture makes it possible and contained; it does not make it quick. The honest framing is that Medusa removes the platform’s permission problem, not the engineering work.
You can adopt selectively. Because the modules are not coupled at the database level, it is possible to use a few of them rather than all: Medusa as a component in a wider system rather than the system itself. That is a real option for a business that already has order management or inventory it is not replacing.
Upgrade safety, the part to plan for
This is the section a CTO should read twice, because it is where the published material is thinnest and the planning impact is largest.
The good part. Because Medusa v2 modules do not share database dependencies, an upgrade touches less than it would in a monolithic platform. Custom work lives in your own modules and in workflow extensions rather than in patched core files, so upgrading no longer means re-applying your changes on top of someone else’s new version. Compared with v1, where teams customised by extending core services, that is a substantial reduction in upgrade pain.
The part to plan for. Medusa releases frequently, and minor releases have carried breaking changes that require code or configuration updates. Two concrete examples: v2.13 changed how a core dependency is imported, and v2.14 moved that dependency to a new major version with its own breaking API changes. Medusa ships codemods, scripts that rewrite your code automatically, for some of these, which genuinely helps.
The part worth knowing before you commit. A request in Medusa’s own issue tracker asking for a documented backward-compatibility policy was closed without one being published. There is still no public promise about what a minor version bump may or may not break. That is not an accusation, and it is normal for a platform at this stage of maturity. It does mean you cannot plan upgrades on the assumption that minor versions are safe by definition.
In practice, for a build on Medusa v2 modules: pin your version deliberately rather than tracking latest, read release notes before upgrading rather than after, and budget upgrade work as recurring maintenance. Teams that treat we will upgrade when there is a gap as a plan are the ones who end up four minor versions behind, facing a compound migration.
What Medusa v2 modules ask of your team
Medusa v2 modules moved the difficulty rather than removing it. In v1, customising Medusa was hard because you were patching core logic. In v2, customising is maintainable, but you have to understand the architecture before you can be productive in it.
Strong TypeScript. Not we have someone who knows JavaScript. The data modelling language, the service layer and the type generation all assume genuine TypeScript fluency.
Comfort with an architecture, not just a framework. Modules, workflows, links and the container are concepts a developer has to hold in their head before the first useful commit. A capable developer who has never seen this shape will spend real time getting oriented, and much of the community content written before late 2024 describes v1 and will actively mislead them.
Someone who owns infrastructure. Production Medusa needs Postgres, Redis, and separate server and worker processes. That is a standing responsibility, not a launch task.
Continuity. The one most often missed. Modular architecture pays off across years, and the second and third change are where the investment returns. A team that builds and then disperses leaves behind a system whose main advantage nobody is present to use.
When modularity is overkill
Every point above is manageable, and none of it argues against Medusa v2 modules on its own. But the architecture makes a specific bet, and it is worth being clear about when that bet does not pay.
Modular architecture is, in economic terms, an option. You pay a premium upfront, in more concepts, more setup and more senior engineering, in exchange for the right to change one part of the system later without disturbing the rest. Like any option, it is worth buying only if there is a reasonable chance you exercise it.
| What Medusa v2 modules buy you | What the option costs |
|---|---|
| The right to replace one part without touching the rest | More concepts to learn before the first useful commit |
| Custom work that survives an upgrade | Breaking changes in minor releases you have to read for |
| Business logic named and visible in workflows | Senior engineering rather than configuration |
| Adopting a few modules instead of a whole platform | A standing infrastructure and continuity commitment |
So the question is not whether modular beats monolithic. It is this: which module do you expect to replace, and when?
A business that can name it has already identified the option it is buying. Our pricing is contract-based and no platform will model it. Inventory lives in our ERP and always will. We need a payment method with no integration in this market. For that business the premium is rational, and usually cheap relative to the alternative.
A business that cannot name one is buying an option it may never exercise. Where requirements are conventional retail, with a standard catalogue, standard checkout and standard promotions, the flexibility is real but unused, while the complexity is real and permanent. The ability to replace one of the Medusa v2 modules also means nothing without somebody available to replace it.
There is a middle case worth naming, because it is common and gets missed. Businesses whose requirements are conventional today but whose direction is not: entering a market with different payment rails, moving from single-seller to marketplace, adding B2B alongside B2C. The option has value there even though the module to be replaced is not yet obvious. Our note on Medusa marketplace architecture walks through one version of that shift.
The question to answer before you commit
Strip away the architecture discussion and the decision reduces to four questions.
- Which part of a standard commerce platform does your business not fit? If you can name it specifically, that is the module you are buying the right to replace.
- Who owns this in eighteen months? Modular architecture rewards continuity. Name the team.
- What is your upgrade cadence, and is it budgeted? Not whether you will upgrade, but how often and out of whose time.
- Is the complexity proportionate to the business? Two dozen modules is the right answer to a complicated business and an expensive answer to a simple one.
Answer those honestly and the architecture question mostly settles itself. The value of Medusa v2 modules is not that they are modern; it is that they let you name, contain and price a change you already know is coming.
Frequently asked questions
What are Medusa v2 modules?
They are the independent packages that hold Medusa’s commerce logic: Cart, Product, Order, Payment, Pricing, Inventory and roughly twenty more. Each owns its own data and exposes an interface, so one can be replaced without rewriting the others.
Can I replace just one module?
Yes, and that is the point of the design. Because the modules have no database-level dependencies on each other, replacing Inventory or Pricing touches that module plus the workflows that call it, rather than the whole platform.
Do Medusa v2 modules make upgrades safer?
Safer than v1, yes, because your custom work lives in your own modules rather than in patched core files. Minor releases have still carried breaking changes, so pin your version, read release notes before upgrading, and budget upgrade work as recurring maintenance.
How many modules does Medusa v2 have?
Medusa v2 modules number roughly two dozen, with more added over time, including Loyalty, Store Credit and Translation. The count matters less than the fact that they are not coupled at the database level.
Is the modular architecture worth it for a simple catalogue?
Often not. If your requirements are standard catalogue, standard checkout and standard promotions, and you cannot name a module you expect to replace, you are paying for flexibility you will not use.
We build and maintain production Medusa systems, including the custom Medusa v2 modules and workflow extensions described above. If you are assessing whether this architecture fits what you are building, or whether it is more than your case needs, we are glad to go through it with you and give you a straight read. See our Medusa.js development services, or request a technical review.