Payload CMS Ecommerce Plugin vs Medusa.js: Which Should You Use?

The mistake most teams make here is treating this like a brand comparison.

It is not.

The real question is how much commerce engine your project actually needs.

You are already building in Next.js and TypeScript. You either know Payload well already or you are weighing Payload CMS pricing as part of your stack decision. Then you notice Payload now has an official ecommerce plugin. Suddenly the obvious follow-up is: do I still need Medusa, or can I keep everything inside Payload?

That is the right question. The expensive part is answering it badly.

Choose too much platform too early and you buy complexity you do not need. Choose too little and you end up rebuilding shipping, pricing, tax, payment, and order logic that a dedicated commerce engine already solved. Payload’s ecommerce plugin is now real, official, open source, and still in beta. Medusa is a separate commerce platform with a large open-source footprint, a mature module model, and a standard architecture built around a headless backend plus admin plus storefront. They overlap, but they are not interchangeable.

What the Payload ecommerce plugin actually is

Payload’s ecommerce plugin is an official package, @payloadcms/plugin-ecommerce, that plugs directly into a Payload project. Today it ships with products and variants, carts tracked in Payload, orders and transactions, customer-linked addresses, a payment adapter pattern with Stripe currently supported, multi-currency support, and React UI utilities for frontend commerce flows. It is also explicitly marked as beta, and the docs say breaking changes are possible in future releases.

That matters because the plugin is attractive for a very specific reason: it keeps your commerce model inside the same Payload app you are already using for content and admin operations. I wrote a complete guide to the Payload ecommerce plugin covering Stripe setup, cart flows, and order management if you want the full implementation walkthrough. In practice, that usually means one codebase, one admin surface, and one deployment path instead of standing up a dedicated commerce backend. That simplicity is the main selling point, not feature breadth. The plugin is configured directly in your Payload config, and its collections live in the same system as the rest of your project.

Just as important is what it does not do yet. Payload’s docs are direct here: the plugin does not handle shipping, taxes, or subscriptions natively, though you can implement those yourself with the provided collections and hooks. The RFC thread around the plugin reinforces that those areas are still active gaps the community is pushing on, especially shipping, taxes, discounting, subscriptions, and inventory-related concerns. Recent GitHub issues also show the kind of edge-case maturity work you should expect in beta software, including an open issue around order confirmation logic in the Stripe adapter and another around price rendering when a value is 0.

So the honest description is this: Payload ecommerce is a strong “keep it in one system” option for teams whose commerce requirements are still reasonably bounded. Install is straightforward:

npm install @payloadcms/plugin-ecommerce

But if your roadmap already includes shipping logic, tax rules, approvals, subscriptions, multiple payment methods, or complex operations, you should treat the missing pieces as implementation work you own from day one.

What Medusa actually is

Medusa is not a CMS plugin. It is a separate open-source commerce platform built around Node.js and TypeScript, released under MIT, with a large GitHub footprint. As of March 31, 2026, the main repo shows about 32.5k stars, and the docs are on v2.13.5. Its architecture is explicitly commerce-first: the standard Medusa application consists of a headless Node.js server and an admin dashboard, while the storefront is installed or built separately and talks to Medusa through API routes. ([GitHub][2])

The reason teams choose Medusa is scope. Medusa ships with commerce modules for cart, customer, order, payment, pricing, product, promotion, region, inventory, stock location, store, and tax, among others. The multi-region recipe shows how it handles region-specific tax settings, payment providers, fulfillment providers, prices per currency and region, and multi-warehouse inventory. It also has an integrations ecosystem for payment and fulfillment providers, plus an official B2B starter that already includes company management, quote management, approvals, spending limits, bulk add-to-cart, and a Next.js storefront. ([docs.medusajs.com][3])

There is one nuance worth stating clearly because it often gets flattened in comparisons: Medusa is much stronger than Payload for subscription-style commerce, but subscriptions are not a built-in checkbox in the same way products or orders are. The current docs frame subscriptions as a recipe built with Medusa’s framework, custom modules, API routes, and workflows. That is still a very different proposition from Payload, because Medusa gives you the right primitives and documented path for recurring commerce flows, but it is not honest to present it as zero-work native functionality. ([docs.medusajs.com][4])

So the honest description of Medusa is this: if Payload ecommerce is a lightweight way to add commerce to a CMS project, Medusa is a dedicated commerce backend that expects commerce to be a first-class concern. That extra capability is real, and so is the extra operational weight. ([docs.medusajs.com][5])

The key differences side by side

The biggest difference is architecture.

With the Payload plugin, commerce lives inside Payload. Your products, carts, orders, and payments become part of the same application model. That reduces mental overhead for smaller teams because content and commerce are administered together. With Medusa, commerce is its own backend with its own admin, and your Next.js storefront consumes its APIs. If you also use Payload for content, you are now running two backends on purpose: Payload for content, Medusa for commerce.

The second difference is commerce surface area.

Payload covers the basics well enough to ship a real store: products, variants, carts, orders, transactions, Stripe, customer addresses, and multiple currencies. But the docs explicitly call out no native shipping, taxes, or subscriptions. Medusa, by contrast, ships with modules for tax, fulfillment, pricing, inventory, promotions, regions, stock locations, and payments, and its multi-region docs show those pieces working together in a way Payload simply does not try to cover yet.

The third difference is maturity.

Payload’s plugin is beta, and the project openly says breaking changes are possible. The RFC is still actively surfacing missing capabilities, and recent issues show the plugin is still getting hardened through real-world usage. Medusa is also evolving quickly, but its commerce core is materially more battle-tested. The repo shows a much larger install base and activity footprint, and Medusa’s own materials point to hundreds of deployed customer applications, including complex B2B and ERP-linked implementations.

The fourth difference is customization model.

Both tools are TypeScript-friendly. Both are extensible. But they are extensible in different ways. In Payload, you customize by shaping collections, hooks, access rules, and admin behavior inside your Payload app. In Medusa, you customize by adding modules, workflows, subscribers, API routes, and provider integrations around the commerce engine. That means Payload customizations tend to feel like application-level CMS engineering, while Medusa customizations feel like commerce-backend engineering. Neither is inherently better. They fit different project shapes.

The fifth difference is operational complexity.

Payload ecommerce is attractive because it keeps your stack flatter — a significant simplifier if you are mid-way through a Payload CMS migration from a legacy system. Medusa increases capability by increasing moving parts. Standard Medusa means a separate backend and admin, and if you also need editorial content, localization, landing pages, or structured marketing content, you often add Payload or another CMS on top. Medusa itself clearly supports that model and even lists Payload as a content integration. That is powerful, but it is not simpler. ([docs.medusajs.com][5])

Decision framework: which one should you use?

Use the Payload ecommerce plugin when the commerce layer is important but not the hardest part of the project.

That usually means a DTC store or a relatively simple B2B build where products, cart, checkout, Stripe, and order capture are the core requirement, and the real value is elsewhere, such as content, product education, gated resources, quote lead-gen, custom fields, or operational workflows inside one admin. Payload is especially compelling when timeline and budget matter more than exhaustive commerce coverage, and when the team would benefit from one codebase rather than another service boundary. If shipping is simple, tax logic is minimal or externalized, and you are comfortable owning some beta risk, the Payload route is rational and often faster.

Use Medusa when the commerce layer is the hard part.

That includes cases where region-specific pricing, tax behavior, payment methods, fulfillment rules, inventory logic, stock locations, promotions, approvals, or deep ERP integration are already in scope, not “maybe later” items. Medusa gives you a much broader set of native commerce primitives, plus a more natural path for complex B2B requirements through its modules, workflows, integrations, and official B2B starter. Subscription-based purchasing also fits Medusa’s model far better than Payload’s, even though you still implement it via Medusa’s recipe and custom modules rather than flipping a built-in setting. ([docs.medusajs.com][3])

Use both together when content and commerce are independently serious.

That is the architecture I would choose for a project with significant editorial content, strong landing-page needs, rich product storytelling, or AI integration implementation for content workflows on one side, and serious B2B or mid-market commerce complexity on the other. In that setup, Payload owns content. Medusa owns commerce. Next.js composes both. Medusa’s integrations catalog explicitly supports Payload as a content integration ([see the official Payload + Medusa integration guide][8]), which tells you this is not a weird edge case, it is an expected architecture. The tradeoff is obvious: you get clear separation of concerns and a much stronger long-term fit, but you also accept more infrastructure, more synchronization points, and more engineering discipline. ([Medusa][6])

A simple way to decide is this:

If your current requirements fit on a product manager’s whiteboard in ten minutes, start with Payload.

If your current requirements already need a systems diagram, start with Medusa.

A representative project example

Say you are building for a B2B signage company.

They sell configurable signage kits across multiple regions. Some products are standard catalog items. Others are semi-custom and depend on dimensions, finish, mounting type, and compliance requirements. Customers might need quote requests before checkout. Internal teams need approval workflows. Pricing may vary by region and customer group. Inventory is not always straightforward because some parts are stocked, some are assembled on demand, and some ship from different locations.

I would not build that on the Payload ecommerce plugin as the main commerce engine.

Could I force it? Yes. Payload gives me the data model freedom to do it. But I would be re-creating too much core commerce behavior around pricing rules, fulfillment logic, region handling, and approvals while also carrying beta risk. That is exactly the point where “one codebase” stops being a simplifier and starts being a trap.

For that project, I would use Medusa for commerce and Payload for content. Medusa’s B2B starter already includes several patterns that look a lot like this problem space, including quote management, company management, company approvals, merchant approvals, and spending controls. Its region, pricing, tax, inventory, and fulfillment model is much closer to the shape of the business. Payload would still be valuable for editorial landing pages, case studies, installation guides, calculators, and content operations, but I would not ask it to be the main commerce brain. ([GitHub][7])

By contrast, if the same company only needed a straightforward catalog, a cart, Stripe checkout, order tracking, and a quote-request form layered onto mostly static pricing, I would seriously consider keeping it all inside Payload first. The right answer changes when the operational model changes.

What neither tool covers well

Neither of these should be treated as a drop-in Shopify replacement for high-volume consumer retail where the main problem is not developer control but retail operations at scale.

That is not a knock on either tool. It is just a category boundary. Payload ecommerce is still early and intentionally narrower. Medusa is much stronger operationally, but it still assumes you are comfortable owning architecture, integrations, and custom implementation. For many consumer-heavy DTC teams, headless Shopify is still the pragmatic answer because so much retail functionality and app ecosystem behavior is already packaged. The sweet spot for both Payload ecommerce and Medusa is developer-controlled B2B and mid-market commerce where flexibility matters more than marketplace convenience.

Conclusion

The honest answer is not “Payload or Medusa.” It is “how much commerce complexity do you need to own on purpose?”

Use Payload ecommerce when you want the shortest path to a content-led or moderately complex store inside one TypeScript application, and your missing features are genuinely manageable. Use Medusa when commerce itself is the product problem, not just a feature of the site. Use both when content and commerce are both serious enough to deserve their own systems.

If you are making that call on a real project and want a second opinion before you commit the architecture, book a discovery call.