What Is Medusa? The Open-Source Commerce Platform, Explained

Most explanations of Medusa start with a feature list. That is the wrong end. What Medusa is, structurally, is a commerce framework you install into your own Node application — closer to Next.js than to Shopify. Everything else follows from that one fact.

The one-paragraph version

Medusa is an open-source commerce platform built in TypeScript. You install it as a Node application, point it at a Postgres database, and get a complete commerce backend: products, variants, inventory, carts, orders, customers, regions, pricing, promotions, fulfilment and payments — all exposed over REST APIs. You then build whatever storefront you want against those APIs, usually in Next.js. The admin dashboard ships with it.

The difference from a hosted platform is not features. It is who owns the runtime. Your Medusa app runs on your infrastructure, against your database, with your code in the request path.

How the architecture actually works

Medusa v2 restructured the platform around four ideas. If you understand these four, you understand the system.

Modules

A module is a self-contained commerce domain: its own data models, its own service, its own migrations. The Product module owns products. The Cart module owns carts. Your subscriptions module owns subscriptions. Modules do not import each other's internals — they are isolated by design, which is what makes replacing one viable.

import { Module } from "@medusajs/framework/utils"
import BlogModuleService from "./service"

export const BLOG_MODULE = "blog"

export default Module(BLOG_MODULE, {
  service: BlogModuleService,
})

Register it in config and it is resolvable everywhere:

module.exports = defineConfig({
  modules: [
    {
      resolve: "./src/modules/blog",
    },
  ],
})

Full detail in Medusa v2 modules explained.

Workflows

Business processes that span modules are written as workflows: a sequence of steps, each of which can define a compensation function that undoes it. If step four fails, steps three, two and one roll back. Placing an order — reserve inventory, authorise payment, create the order, send the confirmation — is a workflow, and so is anything custom you build. See workflows explained.

Module links

Because modules are isolated, you cannot add a foreign key from your module's table to the Product table. Links solve this: a defined relationship between records in two modules, resolved by the query layer without coupling the modules themselves. How module links work.

The container

Everything resolvable — services, the logger, the query layer, your modules — lives in a dependency container. Steps, API routes and subscribers receive it. The Medusa container.

What you get out of the box

That last pair is the trade. Medusa gives you the commerce engine and the admin; the storefront and the infrastructure are your responsibility.

Who Medusa is right for

We recommend it when at least two of these are true:

• +Your business logic does not fit a standard checkout. Subscriptions with unusual billing, B2B quoting and net terms, marketplaces with vendor payouts, regulated categories with per-jurisdiction rules.
• +You are in a category platforms avoid. Nicotine, firearms adjacent, CBD, supplements, adult. See the vape and Shopify problem.
• +Platform and app fees have become a real line item. Once you are past roughly $5M GMV, the percentage-of-revenue model starts to look like a tax on growth.
• +You have or can hire engineering. This is the hard requirement.

Who it is wrong for

Honestly: most small stores. If you sell 40 SKUs, do not need custom checkout logic, and have no developer, Shopify will serve you better and cost you less. Medusa's advantages are all advantages of control, and control has an operating cost. Paying that cost to avoid a $39/month subscription is a bad trade.

The other bad fit is teams who want open source for ideological reasons but plan to staff it with nobody. An unmaintained Medusa deployment is worse than a hosted platform in every measurable way.

What it costs to run

There is no licence fee. The costs are infrastructure and people:

Call it $100–500/month for a mid-size store, plus whatever your engineering time costs. Compare that against platform fees, transaction surcharges and the app stack it replaces — the honest comparison is in headless commerce TCO.

Getting started

npx create-medusa-app@latest my-store

That scaffolds the backend and optionally a Next.js storefront, runs migrations and seeds sample data. From there, installing Medusa v2 covers the setup properly, and the project structure guide explains what all the directories are for.

The five things people get wrong about Medusa

"It is a Shopify alternative." Only in the sense that a framework is an alternative to a product. Shopify is something you use; Medusa is something you build with. Teams that evaluate them as like-for-like consistently under-budget the storefront and the operations.

"Open source means free." The licence is free. The engineering is not, and it is the larger number. Price the retainer before the comparison, not after.

"Headless means faster." Headless makes fast possible by removing a themed rendering layer you do not control. It does not make it automatic — plenty of headless storefronts are slower than the Shopify theme they replaced, usually through over-fetching.

"We will migrate everything in a month." Catalog, yes. Subscriptions, ERP integrations and the one weird pricing rule, no. See migration planning.

"We need Medusa because we are growing." Growth alone is not a reason. A constraint is. If Shopify is not stopping you doing something specific, growth just means you will pay more for a thing that works.

A two-week evaluation that gives a real answer

Rather than reading comparisons, build the thing you are least sure about:

Two weeks of a developer's time answers the question better than any amount of evaluation, and the prototype is not wasted — it becomes the spike for the real build.

Medusa is the right answer when your commerce logic is a competitive advantage rather than a commodity. If you are weighing it against your current platform, we do this assessment — usually in a week.