Medusa.js
An open-source commerce engine for stores whose rules don't fit a ready-made platform.
E-commerceUsing since 2025 · Featured project: CAS Marketplace (in the Code & Pepper team)
- Category
- E-commerce
- Using since
- 2025
- Featured project
- CAS Marketplacein the Code & Pepper team
In practice
I reach for Medusa when a store has logic a ready-made platform can't carry without workarounds: multiple sellers, B2B price lists or a custom cart. In CAS Marketplace it ran the whole marketplace, and the storefront itself was built separately, in Next.js.
What is Medusa.js?
Medusa.js is an open-source commerce engine in Node.js and TypeScript. It is headless: it provides APIs for products, cart, orders, payments and inventory, and the storefront is built separately, usually in Next.js.
Since version 2 it is built from modules. Each area, from price lists to fulfilment, is a module with its own PostgreSQL data model, which you can extend or replace without forking the core.
- License
- MIT
- Language
- TypeScript, Node.js
- Database
- PostgreSQL
- Model
- Headless, modular
How I work with Medusa.js
I start with the data model, not the store's look. The order matters: each of these decisions is cheapest before launch.
Data model
I decide what a standard Medusa module covers, what needs a custom one and what a module link can handle.
Workflows
I wrap business logic in workflows with compensating steps, so a failed Stripe payment never leaves an order half done.
Storefront and content
I build the store in Next.js. Marketing content lives outside the engine, usually in Payload CMS, joined on the server.
When it fits, and when it doesn't
Medusa pays off when you pay for flexibility you will actually use.
A good fit when
- A marketplace with many sellers and split payments.
- B2B with customer-specific price lists and invoice orders.
- A store that is part of a bigger product.
- A team that wants its code and data in-house.
Not a fit when
- A simple store with a few dozen products and standard shipping.
- Nobody on your side will maintain it after launch.
- Launch in two weeks on a small budget.
In those cases Shopify gets you there faster and cheaper.
Medusa or Shopify?
Both sell well. They differ in who owns the code and how much you can change.
| Criterion | Medusa.js | Shopify |
|---|---|---|
| Time to launch | Longer, depends on the scope | Short, live after setup |
| Running costs | Hosting and database, no platform fees | Subscription, plus fees on external gateways |
| Custom logic | Custom modules and workflows in code | Apps and functions within its limits |
| Checkout | Fully your own | Configurable, deeper changes on Shopify Plus |
| Multiple vendors | Mercur on top of Medusa | External marketplace apps |
| Maintenance | On your side or your contractor's | On Shopify's side |
| Code and data | Yours, under the MIT license | On the platform, via API |
Choose Medusa when
the store's rules are your edge: unusual price lists, many sellers, your own order process. You pay more up front, but skip plugin workarounds.
Choose Shopify when
you want to sell fast and your buying process is standard. If the platform starts to pinch, a later migration costs less than building an engine too early.
On CAS Marketplace I chose Mercur on top of Medusa because the project needed multiple vendors with commissions and split orders.
Pitfalls from real projects
Shipping rules are checked twice
From the CAS Marketplace project
Medusa v2 evaluates shipping-option rules in two separate workflows: once when it lists the options and again when the customer picks one. Custom rule context, such as the cart subtotal for free delivery, has to reach both, or an option shows up in checkout and then fails with a generic 400 when selected. I store thresholds as fixed-decimal strings like 60.00, because the comparator tries to read a bare 60 as a date first.
Workarounds outlive the bug
From the CAS Marketplace project
A subscriber added to work around a bug, for example a payment-capture issue, can keep running after Medusa fixes the problem upstream, and then it duplicates order.placed events, and with them the order confirmation emails. That is why every workaround gets a link to the issue, a version check or a flag, and a review on each upgrade. Minor v2 releases can carry breaking changes, so I pin versions and read the changelog before bumping.
Dev mode is not production
From the CAS Marketplace project
In development Medusa v2 runs its event bus, workflow engine and cache in memory, so async events and caching across several instances behave differently than in production. So I test those paths locally against Redis before they ship. After adding module links I run the migrations and link sync, because without them the links silently do nothing.
Frequently asked questions
Considering Medusa for your store?
Tell me what you sell and how you want to sell it. I'll tell you straight whether Medusa makes sense or Shopify gets you there faster.