ENATIV Logo
ENATIV
Back
© 2026 ENATIV
ProjectsServicesKnowledge hubContact
contact@enativ.pl
  1. Knowledge hub
  2. ›
  3. E-commerce
  4. ›
  5. Medusa.js

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.

  1. Data model

    I decide what a standard Medusa module covers, what needs a custom one and what a module link can handle.

  2. Workflows

    I wrap business logic in workflows with compensating steps, so a failed Stripe payment never leaves an order half done.

  3. 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.

Medusa.js and Shopify compared
CriterionMedusa.jsShopify
Time to launchLonger, depends on the scopeShort, live after setup
Running costsHosting and database, no platform feesSubscription, plus fees on external gateways
Custom logicCustom modules and workflows in codeApps and functions within its limits
CheckoutFully your ownConfigurable, deeper changes on Shopify Plus
Multiple vendorsMercur on top of MedusaExternal marketplace apps
MaintenanceOn your side or your contractor'sOn Shopify's side
Code and dataYours, under the MIT licenseOn 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

Yes, the code is MIT-licensed, with no licence fee or cut of your sales. You pay for hosting, the database, and the build and upkeep work.
Medusa is a Node.js app with a PostgreSQL database, so I run it on a server or cloud you choose. The code and customer data stay with you.
Yes. Medusa ships an admin panel for products, orders, customers and promotions that needs no code. When a team needs its own views, I add admin extensions.
Yes. I build customer groups, company price lists and custom order rules with modules and workflows. When a project outgrows the standard modules, I write my own rather than fork the core.

On this page

  • In practice
  • What is Medusa.js?
  • How I work with Medusa.js
  • When it fits, and when it doesn't
  • Medusa or Shopify?
  • Pitfalls from real projects
  • Frequently asked questions

Related topics

  • Medusa.js
  • Next.js
  • Shopify
  • Stripe
  • PostgreSQL
  • Headless commerce
  • Payload CMS

Related services

  • E-CommerceHeadless Shopify, Medusa.js, and custom storefronts with Stripe.

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.

Describe your projectSee CAS Marketplace