nextlevels logo
DEEN

MedusaJS: what the headless commerce framework can really do in 2026

A neutral market overview: architecture, workflow engine, TCO and what Medusa is really suited to in 2026

Commerce & Shopware16 min read

In 2026, "headless" is no longer a selling point but the default. A different question is decisive: do you need a ready-made shop system or a commerce back end that you assemble yourself? It is exactly along this line that it is decided whether MedusaJS is the right tool for you or the most expensive misunderstanding in your stack.

Two real paths show how wide the range is. Makro PRO uses MedusaJS to orchestrate around 5,000 orders a day across a three-digit network of shops. Other companies evaluate Medusa and in the end deliberately decide against it, because a suite solution fits their set-up better. Both decisions can be right, and precisely this contrast shows what the framework is suitable for and what it is not.

MedusaJS is an open-source commerce framework written in TypeScript and based on Node.js. It provides a modular commerce back end with more than 20 commerce modules, a workflow engine, a React admin and a strict separation of storefront, admin and data storage. The core is under the MIT license: no license fee, no share of GMV. Since August 2026, however, this no longer applies to the entire repository — more on this below.

This article provides a neutral overview with the details that are typically missing from marketing overviews: what does the framework achieve technically, for which scenarios is it worthwhile, and when should you keep your hands off it?

What MedusaJS is and what it is not

Medusa started in 2020 as an open-source alternative to Shopify Plus and commercetools and was completely rebuilt with version 2.0 on 23 October 2024. With around 36,700 GitHub stars (as of October 2026) and around 747,000 npm downloads per month (as of October 2026), it is the open-source commerce project with the most GitHub stars — Bagisto is at around 28,200, Saleor at around 23,400.

Two classifications help to place the framework correctly.

Medusa is not a shop system in the classic sense. It is a commerce back end with a modular architecture. What you understand by a "shop" (storefront, product detail page, checkout UI) is not supplied by Medusa out of the box. Instead, there is an official Next.js starter, community starters for other frameworks and a REST/GraphQL API layer to which you connect your own front end. Anyone looking for a shop that can sell immediately, as with Shopify or Shopware, gets a framework here, not a platform.

Medusa is not a purely "headless" product. It comes with a complete admin panel written in React, which was fundamentally reworked with version 2.0. Order management, product maintenance, promotions, B2B accounts, multi-warehouse: everything is there, everything is extensible.

In practice, the framework does not compete with Shopify or WooCommerce but with commercetools, Saleor and tailor-made composable stacks. The comparison class is enterprise-oriented, but the entry point is open source.

MedusaJS architecture: modular back end with modules, module links, workflow engine and separate storefront

The architecture in detail

With version 2.0, the originally monolithic back end became a genuinely modular architecture. This is more than a marketing term: it has tangible consequences for maintenance and extensibility.

Commerce modules without hard database coupling

Medusa divides each business domain (products, carts, orders, payments, pricing, inventory, promotions, customers) into a separate module. Around 20 commerce modules are included in the core; in 2026, settings and translation (beta), among others, were added. RBAC, on the other hand, is not a freely usable module but is tied to the enterprise license — more on this below. What matters is that there are no foreign-key relationships between these modules at database level. Connections are mapped via so-called module links, which are resolved at runtime.

What sounds like architecture theory becomes tangible in comparison: in Shopware, the customer is hard-wired to the order, and both live in the same database with constraints. In Medusa, you can replace the customer module with a Salesforce connection without touching the order table. Two scenarios from practice:

  1. Selective adoption. A PIM-driven manufacturer adopts only the order and pricing modules and lets product data continue to flow from its existing PIM. A large data migration is not a prerequisite.
  2. Module replacement. If the supplied pricing module is not sufficient, for example because a complex tiered pricing model with individual contract terms is needed, you can swap it for your own implementation without touching the rest of the system.

For organically grown mid-sized stacks with an ERP, a PIM and their own OMS, this is a relevant property. Classic suites often require you either to commit fully to their data model or not at all.

In short: Medusa does not force you into a predefined data model. You take the modules that fit and replace those that do not. That is the real difference from a suite, not the buzzword "modular".

The workflow engine

The workflow engine gets too little attention in most Medusa discussions, even though it is one of the strongest arguments for the framework. Anyone who has ever searched the logs at three in the morning for a half-completed checkout knows the basic problem of multi-step commerce processes. Stock reserved, payment authorized, but the ERP posting fails. What now?

Medusa models such processes as workflows made up of atomic steps. The engine takes care of three things:

  • Compensation: if step 4 fails, steps 1 to 3 are cleanly rolled back, each with its own compensate function.
  • Retry logic: transient errors such as a payment provider timeout trigger automatic retries with configurable backoff.
  • Idempotency: the same workflow does not run twice if it is triggered several times; each step can provide a guarantee based on an idempotency key.

The engine itself is interchangeable: for development it runs in memory, in production via the Redis variant of the workflow engine module. Both are part of the infrastructure modules, i.e. the same swap logic as for cache, events and file storage.

A typical order placement workflow looks like this: validateCart → reserveInventory → authorizePayment → createOrder → triggerFulfillment. If triggerFulfillment fails because the interface to the WMS is not responding, the engine cancels the inventory reservation, releases the payment authorization and logs each step traceably in an audit trail. Anyone who wants this mechanism in a classic shop system builds it themselves or adds an external workflow tool such as Temporal.

Sequence diagram of a Medusa order placement workflow with compensation

Storefront, admin and hosting strictly separated

Architecturally, a Medusa installation breaks down into three components that can be deployed independently:

  • Medusa back end: a Node.js server with all modules.
  • Admin dashboard: a React SPA, hosted in the back end or separately.
  • Storefront: completely decoupled from the back end, usually Next.js, but any front end that speaks REST or GraphQL works.

This separation is not an end in itself. It ensures that the front-end team works at its own pace and the back end at its own, and that performance tuning for the storefront (edge caching, ISR, static pre-rendering) takes place independently of the commerce back end.

What MedusaJS is suitable for

Medusa is not a general-purpose tool. It plays to its strengths in certain constellations.

Most clearly in B2B with complex pricing and account models. Customer-specific price lists, approved ranges per account and multi-level order approvals can be mapped cleanly because the pricing and customer modules are designed for multi-dimensionality from the outset. Makro PRO shows how robust this is: the wholesaler orchestrates around 5,000 orders a day across a three-digit network of shops and distribution partners, with an annual GMV of more than 300 million US dollars.

It fits similarly well for marketplaces and multi-vendor set-ups. There is no built-in marketplace mode, but thanks to sales channels, stock locations and module links, multi-tenant and multi-vendor architectures can be created with manageable effort.

A field of its own is order orchestration beyond the classic web shop. Anyone who understands Medusa not as a front store but as an order backbone, for example for consolidating orders from several sales channels or as a hub between several ERPs, uses it precisely where the modular data model is superior. INSPIRED Pet Nutrition, for example, uses it as AI-supported order management between two separate ERPs, processing orders nine times faster as a result and cutting operating costs by 80 per cent.

The framework offers the greatest lead for custom workflows that standard suites cannot map: rental models, subscriptions with irregular delivery cycles, booking commerce or pay-per-use. Viessmann runs mobileheating.de on it, a B2B marketplace for renting mobile heating and cooling equipment; suppliers there save more than 60 per cent of the time spent on quotes and clarifying requirements, and bookings that used to take weeks now go through in minutes. Medusa does not force anything into a predefined order concept.

Finally, it covers internationalisation with real multi-region logic. Multiple currencies, region-specific tax rates, shipping zones and payment methods are part of the core and are not cobbled together via plugins.

Comparison of what MedusaJS fits and what it does not

What MedusaJS is less suited to

The other side is just as important. For quick out-of-the-box shops, Medusa is the wrong choice: anyone who wants to launch a B2C shop in four weeks and has no DevOps team within reach is better served by Shopify, Shopware or a cloud suite. Medusa presupposes that someone designs the front end, runs the hosting and writes the integrations.

Teams without JavaScript or TypeScript depth also quickly reach their limits. All customizing, from new modules and custom workflows to admin extensions, takes place in TypeScript. A PHP-heavy team can run the system but cannot extend it efficiently.

Marketing teams that expect a WYSIWYG front end will also be disappointed. Unlike Shopware or Shopify, there is no built-in "Shopping Experiences" tool; storefront editing runs via the front-end framework, not via the admin panel. This requires either code discipline or an upstream CMS such as Sanity, Strapi or Contentful, which in turn enlarges the stack.

And with very small product catalogs with classic B2C needs, the effort is not worthwhile: anyone selling 50 products and needing standard functionality pays a complexity tax that does not pay for itself.

What the 2026 MedusaJS license change means for you

Anyone who files Medusa away as "simply MIT, so free" has no longer been quite right since August 2026. The project has switched to an open-core model: the core remains MIT-licensed, but according to the ENTERPRISE-LICENSE.md in the repo, individual building blocks are excluded as Enterprise Materials and require a commercial contract with MedusaJS, Inc.

Two things that are regularly needed in mid-sized companies are affected: RBAC, i.e. fine-grained roles and permissions in the admin, and SSO/OIDC, i.e. the connection to corporate identity management via the OIDC auth provider. The license lists the affected repository paths individually — generic authentication as well as normal user and invitation management explicitly remain MIT.

For your calculation, this specifically means one thing: if your requirements specification states that accounting may not change prices and that the team logs in with a company login, the three self-service plans Develop, Launch and Scale, from $29, $99 and $299, are not enough. The cloud pricing overview lists RBAC, SSO and audit logs exclusively in the Enterprise plan (as of October 2026).

You end up in the Enterprise plan, whose price is given on request. That is no small matter in a build-vs-buy calculation in which Medusa is competing against a suite where roles and SSO are included in the standard package.

In fairness, there is also reassurance: the change explicitly only applies going forward and does not withdraw any rights to versions already published. The GMV share remains zero, and everything outside the excluded paths is still MIT. So anyone running a classic D2C shop without differentiated admin roles will notice practically nothing of the change.

The strategic reading is nevertheless the more interesting one. Medusa has not made any new funding public since its 2022 seed round; cloud and the enterprise edition are the visible monetization path.

This is not an alarm signal — it is the usual path of successful open-source companies. But if you are planning Medusa over five years, the question of which features might migrate from the MIT core into the commercial edition during this time belongs in the assessment. That is exactly the trade-off that also counts when comparing it with a suite such as Shopware.

Total cost of ownership: honestly calculated

Open source does not mean free of charge. Even though the MIT core costs no license fee, real costs arise in four areas — not yet including the enterprise building blocks from the previous section.

Hosting starts at a manageable level. Self-hosting on a platform such as Railway, Render or DigitalOcean realistically starts at €35–110 a month for a lean set-up with back end and database. With scaling, Redis, a caching layer and a CDN, this quickly grows to several hundred euros.

Anyone who opts for Medusa Cloud instead, available as self-service since October 2025, pays, as of October 2026, from $29 for the Develop plan, from $99 for the Launch plan and from $299 for the Scale plan per month. On top of this there is an Enterprise plan on request. All plans charge usage-based overages for compute, storage, preview environments and build minutes. Production shops with 50–150k sessions a month end up at $200–800 a month, depending on the load profile.

Development, maintenance and third-party systems

By far the biggest item is development and maintenance. A concrete example set-up: a storefront based on the Next.js starter, three custom workflows, a connection to SAP Business One, Algolia for search and Stripe for payments. This typically takes 60–120 days of implementation time and a budget of between €80,000 and €130,000. More complex B2B set-ups with their own pricing engines quickly reach six-figure sums, and ongoing development costs as much as with any other custom solution.

Then there are the third-party systems. Something shifted here in 2026: since version 2.19, the core has come with its own search module. In 2.20, the in-memory provider was dropped in favor of @medusajs/search-postgres, and the foundations for vector search were added. Transactional emails are included in Medusa Cloud on all plans, with quotas per day and month.

Still budget for this item. For facets, synonyms and merchandising rules, Algolia or Meilisearch remain the realistic choice, and Medusa still does not include a CMS. Sanity, Strapi or Contentful add up — and each of them is an interface that has to be built and maintained. That is not a disadvantage of the framework but a property of every composable set-up.

The often-quoted saving of 30–50 per cent in development time is only partly true. Anyone who would have to build a custom platform anyway reaches the goal faster with Medusa than with a fresh start. Compared with a suite solution with a ready-made front end, on the other hand, it is not a leap in efficiency but a deliberate investment in control and flexibility.

Total cost of ownership of MedusaJS: hosting, development, third-party systems and maintenance

Cloud or self-hosting?

This question divides the community, but for most mid-sized set-ups the answer is clear: Medusa Cloud, Launch plan. Anyone who needs time to value, does not maintain their own DevOps set-up and wants to focus their team on product development rather than infrastructure is best off with it.

Self-hosting is only worthwhile under one condition: an internal DevOps team that reliably runs Node.js services in production, including monitoring, backups, scaling and security updates. With moderate traffic it is cheaper on the pure hosting bill, but as soon as you weigh the euros saved against the engineering hours invested, the advantage usually collapses. Without this team, self-hosting is the more expensive option, just with a hidden price tag.

A hybrid of cloud for staging and self-hosting for production (or vice versa) is technically possible but organisationally more fragile than it looks on the whiteboard. We advise against it unless there is a compelling reason.

Decision matrix Medusa Cloud versus self-hosting by internal DevOps capacity

What a realistic start looks like

A Medusa evaluation usually goes through three phases. At the beginning is a technical proof of concept: four to eight weeks, a fixed scope with a standard storefront, one payment provider, one ERP connection and a clearly defined use case. The aim is not the finished shop but a reliable answer to the question of whether the framework works as promised under your actual requirements.

This is followed by an MVP with real traffic, i.e. expanding the PoC into a minimal but production-ready version with realistic data, real orders and measurable KPIs. Depending on the depth of integration, this takes two to four months.

Only then, with roll-out and expansion, are the demanding features added: AI-supported search, personalization, multi-region expansion, marketplace components or the connection to agentic commerce endpoints.

The most common misjudgement is skipping the proof of concept and starting directly with the MVP. Anyone who does so builds in architectural decisions that can later only be reversed with pain.

Conclusion: where Medusa stands today

With version 2.0 (2024), now the 2.21 release line, most recently 2.21.2 (as of October 2026), and the official cloud offering (2025), Medusa has made the leap out of the "interesting but risky" state. Enterprise implementations such as Viessmann, Makro PRO and INSPIRED Pet Nutrition prove that the framework holds up under real pressure.

The MCP server from 2025 has since become a whole agent toolset: a cloud CLI, a cloud development agent and official agent skills. Medusa now describes itself as a commerce platform for agents and developers — a path that most classic suites have so far not offered in comparable depth.

The pace belongs in the calculation. Between 2.18 in July and 2.21 in September 2026, four minor releases appeared, several of them with breaking changes: 2.20 brought a depth limit for relations in the Store API, 2.21 a strict allow-list for fields. Anyone running Medusa schedules upgrade windows firmly and reads the release notes in the GitHub repo.

Nevertheless, it is not a mass-market solution. Anyone looking for a flexible, permanently extensible commerce back end for complex requirements, and who has the technical team to use this freedom, gets one of the most mature open-source frameworks on the market. Anyone who wants to sell quickly and does not want to design the front end themselves is better off with a classic suite.

The right question is therefore rarely "Medusa or Shopware?" but: which problems do we want to solve, and which tool has the fewest breaking points for them? If the suitability scenarios in this article fit your business, Medusa belongs on the shortlist. If they do not, there are better-suited tools, and that too is a reliable finding.

Next step

Is MedusaJS the right backend for your shop?

In a free initial call, we compare MedusaJS and Shopware against your requirements and talk openly about total cost of ownership.