Swell vs Medusa: Choosing an API-First Commerce Platform in 2026

Medusa's core ships under the MIT License and the repository has passed 36,500 GitHub stars as of September 2026. Swell starts at $29 per month for a runtime somebody else keeps alive. Those two facts contain the entire decision, and neither of them is about architecture.

If both platforms are on your shortlist, the architectural argument is already over. Both are API-first. Both assume a custom storefront. Both treat commerce as a set of endpoints rather than a theme with a database attached. Agreeing on that is what put them on the same list. What separates them is a question your architect should be able to answer by Friday: does your team buy commerce primitives, or build and carry them?

This is a decision document, not another critique of Medusa. Medusa is genuinely good software with a real community and a design that rewards teams who want to own their domain model. There are teams for whom it is the correct answer, and this post names them without hedging. Where this site already covers the numbers in depth, this post cites the line and links out.

Key Takeaways

• Medusa's core is MIT-licensed, with a carve-out: the features listed in ENTERPRISE-LICENSE.md, including RBAC and SSO, require a separate commercial agreement with MedusaJS, Inc.
• Running Medusa yourself means Node.js v20.19+ or v22.12+ plus PostgreSQL (installation docs), and in production a Redis-backed server instance plus a worker instance (deployment guide). Swell operates the runtime and exposes it as an API.
• Subscriptions are the sharpest split: Swell exposes `subscription` as a first-class Backend API resource, with subscription plans configured on products via `purchase_options.subscription`, while Medusa documents subscriptions as a recipe you implement inside your own application.
• Medusa has repositioned around agents. Its homepage now reads "Open-Source Commerce Platform for Agents and Developers" and ships an Agent Harness combining MCP, a Cloud CLI, skills and agent previews.
• Swell's pricing is revenue-tier based, not flat: $29, $79, $299 and $2,250 per month against trailing-twelve-month revenue ceilings of $50K, $250K, $1M and $5M, with overage of 2%, 1.5%, 1% and 0.4% above the ceiling.
• Reversibility is asymmetric. Medusa Cloud states you can export your data and self-host at any time; leaving Swell means exporting data through the API, and you never hold the source.

The Fork That Actually Decides It

Both are API-first, so that is not the tiebreaker

"API-first" has stopped discriminating between products. Medusa's architecture is four layers: HTTP API routes on Express, workflows holding business logic, modules owning domain resources, and PostgreSQL underneath. Swell's platform is a schema-driven model layer fronted by a REST API, where the same model definitions that shape storage also shape the endpoints. Both give a frontend engineer a JSON API and get out of the way.

The meaningful difference is what happens after the API call succeeds. In Medusa, the API is code you compiled and deployed. In Swell, the API is a service with an SLA attached. Everything downstream of that sentence, cost, staffing, upgrade risk, incident response, follows from it.

Operate or delegate

Frame the choice as two columns of permanent obligation rather than two feature lists.

Choosing Medusa means you own a Node application, its dependency graph, its PostgreSQL instance, its Redis instance, its server and worker processes, and every upgrade decision from now until you replatform. In return you own the domain model outright. You can fork it, rename it, replace the payment abstraction, or ship a pricing engine that no SaaS vendor would ever build for you.

Choosing Swell means a vendor owns the runtime, the upgrade path and the uptime, and you extend from outside the core through a documented Apps framework. In return you accept that some things are the vendor's to change, and that a primitive you want may not exist yet.

Neither column is the loser. They are different liabilities, and the right one depends on whether commerce logic is a differentiator you want to own or a cost centre you want to stop funding.

Two Extensibility Models, Compared Symmetrically

Medusa: modules, workflows and the Framework

Medusa's extensibility is TypeScript written inside the application. A module is a self-contained domain package with its own data models and service. A workflow is orchestrated business logic with rollback semantics, which is a genuinely good primitive and better than the event-handler soup most platforms offer. Commerce modules wrap third-party services such as Stripe for payments or ShipStation for fulfilment; infrastructure modules swap caching, eventing, file storage and the workflow engine itself.

The consequence worth stating plainly: because your customisations are code in the same repository as the framework, you own the merge. When Medusa changes a module interface, nothing happens to your store until an engineer reads the changelog, updates the code and redeploys. That is total control and a standing maintenance obligation in the same mechanism.

Swell: schema-driven models, the model editor and Apps

Swell's extensibility is configuration and functions outside the core. Data models are definitions, and the docs are explicit that you can "create your own models and add fields to existing ones using the model editor in the dashboard, or via the Backend API." Because models are data rather than compiled classes, the API describes itself: a new field on `product` is queryable, filterable and expandable the moment it exists, with no migration, no deploy and no regenerated client.

Custom logic lives in Apps: functions that respond to model events and before/after hooks, webhooks, scheduled jobs, admin UI panels and settings, all deployed through the Swell CLI. The boundary is firm. You extend the platform, you do not fork it.

Control versus carry

Set the two side by side and the tradeoff is symmetric.

• Medusa gives you the domain model and hands you every upgrade. Custom pricing logic, a bespoke inventory allocation rule, a fulfilment flow with no analogue in any SaaS product: all buildable, all yours forever.
• Swell gives you commerce primitives that upgrade without your involvement and constrains you to extending from outside. Faster to a working store, cheaper to keep running, and genuinely limited if your requirement contradicts the core model.

A useful test: write down the three most unusual things your commerce logic must do. If two of them would require changing how orders or pricing fundamentally work, Medusa's model fits better. If all three are additive, Swell's model fits better and costs less to run.

The Agent Axis, Which Medusa Reached First

This is the freshest axis in the comparison, and honesty here matters more than positioning.

What Medusa shipped

Medusa repositioned in 2026 around agents. The homepage headline is now "Open-Source Commerce Platform for Agents and Developers", and the Agent Harness bundles MCP, the Cloud CLI, skills and agent previews. The agent skills repository ships named skills covering backend features, admin dashboard customisations, storefronts and Cloud resource management, installable through a Claude Code plugin or `yarn skills add`. Medusa has also automated the pipeline that keeps those skills and its docs MCP server in sync with documentation changes, which is the unglamorous part most vendors skip. The Cloud CLI and Development Agent, launched in May 2026, put build logs, runtime logs and deployment context in the terminal where a coding agent can read them, and Medusa Cloud spins up preview environments whose databases branch from your development data, one per pull request.

That is a coherent agent story and Medusa deserves the credit for assembling it first.

What a schema-driven API gives an agent

Swell's answer comes from a different direction. Swell does not currently support agentic checkout through ACP or UCP.

What Swell has is a REST API that describes its own shape, which is the thing an agent needs most and the thing hardest to retrofit. An agent querying a Swell store discovers models, fields and relationships from the same definitions the platform runs on, so a custom field added this morning is visible to the agent this afternoon without anyone regenerating a type definition. The Swell CLI is built for the same loop: scaffold, push, stream live logs, send raw API requests, inspect deployed artifacts. Swell publishes coding-agent skills for the same workflow.

The honest scoreboard

On the substrate an agent operates against, a self-describing schema beats a hand-maintained tool catalogue, because the catalogue drifts and the schema cannot. A team choosing on agent readiness should look at both approaches and decide which matters more to them. The broader category is covered in this site's agentic commerce roundup.

Commerce Primitives: Four Short Decisions

These axes are covered in depth elsewhere on this site. Here they are reduced to the decision each one forces.

Subscriptions

Swell ships subscriptions as a core Backend API resource with its own endpoints, with subscription plans configured on products through `purchase_options.subscription`, alongside invoices and stored account cards. Medusa's subscriptions recipe is a well-written guide to building it: a subscription module with its own data models, links to orders and products, scheduled jobs, admin widgets and storefront management screens.

The decision is not which approach is more elegant. It is how much recurring-billing code your team wants to own permanently. Billing code is the code most likely to silently lose money, and it is never finished.

B2B and wholesale

Medusa's official B2B starter is strong: companies, employees, spending limits with reset frequencies, quotes, cart approvals, bulk add-to-cart. It is a starter template, which means it is a well-built head start you then maintain as application code.

Swell exposes B2B primitives in the platform itself: customer groups, price rules for volume breaks, invoicing, multi-part payments, custom quotes and sales reps purchasing on behalf of customers. The decision is whether you want a template to adapt or configuration to switch on.

Multi-currency and multi-region

Medusa handles this through the Region module, where each region carries its own currency, countries and settings, and regional changes run through workflows. Swell handles currencies as platform configuration, with priced currencies, meaning explicit pricing and checkout in each currency, included from the Standard tier upward on the pricing page.

Both work. The decision is whether adding a market is a deployment or a settings change.

The admin nobody demos

The gap that surprises teams is the back office. Medusa ships an admin dashboard and an extension mechanism for it; Swell ships a merchant dashboard with a model editor that exposes custom models and fields to non-developers automatically. If merchandisers, finance and support staff will live in this system daily, spend an afternoon in both admins with a real person from each of those teams before deciding. This site's Medusa limitations post covers the specifics.

Reality Check: The Parts That Do Not Demo Well

Payments and compliance cost the same either way

Neither platform changes your processor rate. Stripe's published US rate is 2.9% plus 30 cents per successful domestic card transaction, and that applies identically whether the order was created by a Medusa workflow or a Swell API call. PCI DSS obligations attach to how you handle cardholder data, not to your commerce framework; the PCI Security Standards Council publishes the current requirements. A self-hosted deployment does not inherit a hosted provider's compliance posture, and teams routinely discover this late.

The license boundary is real and reasonable

Medusa's core is MIT and that is a substantial gift. The Enterprise License carves out specific materials, with RBAC and SSO named among them, requiring a commercial agreement. Medusa is transparent about it, and the arrangement is defensible. It matters for one reason: if your security review requires SSO and role-based permissions, "free and open source" stops describing your actual bill. Check that early, not in month four.

What Swell actually costs

Swell's pricing is revenue-tier based with overage, and the overage is the part people miss. Starter is $29 per month up to $50K in trailing-twelve-month revenue, then 2% above it. Basic is $79 up to $250K, then 1.5%. Standard is $299 up to $1M, then 1%. Unlimited is $2,250 up to $5M, then 0.4%. Above roughly $10M in annual revenue, pricing is custom. API requests beyond plan limits are $5 per 100K, and extra storage is $5 per GB on every plan except Unlimited. Prices are billed yearly.

Model your own numbers before comparing. A store doing $2M on the Standard tier is paying the $299 base plus 1% on the $1M above the ceiling, which is a real line item. Medusa Cloud starts at $29 per month and prices compute, storage and edge requests rather than commerce volume, with no GMV-tax on commerce features; the Medusa pricing breakdown on this site has the full tier and self-hosting math.

What breaks

On Medusa, the failure modes are operational: a Postgres connection pool exhausted under load, a worker instance that stopped consuming jobs, a Redis eviction policy that quietly dropped queued events, a minor version that changed a module interface your customisation depended on. All fixable by a competent platform team, all requiring one to be on call.

On Swell, the failure modes are about boundaries: a requirement the core model does not express, an integration that has to be built rather than installed, a limit you hit at a bad moment. All fixable too, but some of them need the vendor, and that is the trade you signed up for.

Team Shape: Three Questions That Decide More Than Any Table

Skip the feature matrix. Answer these three honestly.

Who is on call when PostgreSQL needs attention at 2am on Black Friday? Not "who could be" but who is named on the rotation, with the runbook, who has done a failover before. If that person does not exist, self-hosting Medusa is a decision to hire them.

Who absorbs a breaking minor release? Framework upgrades in a self-hosted stack are a scheduled cost that lands whether or not it fits your roadmap. A team with platform engineers absorbs it. A team of three product engineers shipping features postpones it until the version gap becomes a project.

Is commerce logic a differentiator or a cost centre? If your pricing engine, allocation rules or fulfilment orchestration are how you beat competitors, owning that code is correct and Medusa's model is built for it. If commerce is plumbing under a product that differentiates elsewhere, every hour spent on it is overhead.

Two clear answers point at one platform. A split usually means the honest answer is Swell, because the cost of operating infrastructure you were ambivalent about lands every month regardless.

Choose Medusa If

No hedging in this section. Medusa is the better answer when:

• You already employ platform engineers. Not developers who could learn ops, but people who run PostgreSQL and Redis in production today. The marginal cost of one more service is low for you and high for everyone else.
• Your commerce logic is a genuine competitive differentiator. If the thing you do to a cart is your business, owning that code in TypeScript beside a framework you can read is worth every hour it costs.
• You need bring-your-own-cloud or data residency. Regulated industries and public-sector buyers sometimes require the application to run in a specific account, region or jurisdiction. Self-hosted Medusa answers that directly, and Medusa Cloud offers BYOC under an Enterprise License.
• You want to fork the domain model. Modules are replaceable by design. If you intend to substitute the pricing or inventory model wholesale, an MIT core is exactly the right substrate.
• You are building something the SaaS category has no shape for. Rental, usage-based physical goods, complex multi-party marketplaces: categories where every hosted platform makes you fight its assumptions.

The community is a real asset here, the modular architecture is well designed, and the MIT core means no vendor can take it away from you. A team that fits the list above and picks a hosted platform instead will spend a year working around limits that Medusa would have let them delete in an afternoon.

Choose Swell If

Swell is the clear frontrunner for teams who want commerce primitives they do not have to operate, and the reasons are specific rather than promotional.

• Subscriptions or recurring billing are core to the business. They are in the API, not in a recipe. This is the single largest delivery-time difference between the two platforms for subscription businesses.
• You sell B2B and DTC from one system. Customer groups, volume price rules, invoicing and quoting are platform features rather than a starter you maintain.
• Your engineering team is small, or its time is worth more elsewhere. Three engineers who never touch Redis configuration ship considerably more product than three engineers who do.
• You need a custom data model without owning a framework. The model editor and Backend API let you add models and fields that become fully queryable API resources immediately.
• Non-developers need a working back office on day one. Merchandisers and support staff get a dashboard that already understands your custom fields.

The honest limits: you do not get the source, some requirements will need the vendor, and the revenue-tier overage means growth increases your bill. Weigh those against never paging an engineer about a database.

Reversibility and a One-Week Test

Switching costs are asymmetric, and knowing the direction of the asymmetry is worth more than another feature comparison.

Leaving Medusa for a hosted platform means moving data out of PostgreSQL, remapping identifiers, re-tokenising stored payment methods with your processor and rebuilding custom modules as platform extensions. The mechanics are documented in this site's migration guide. Leaving Swell means exporting through the API and rebuilding the commerce layer you had been renting, which is real work but bounded, since the data was always yours and always addressable.

Then run the test that settles it. Spend one week building the same narrow flow on both: a subscription product with a wholesale price tier, from cart to first successful renewal, with an admin screen a merchandiser could actually use. Not a prototype of your whole store, just that one path.

At the end, count two numbers. First, elapsed engineering hours. Second, and more important, the lines of code you would then own forever, including the billing logic, the scheduled job, the admin widget and the tests around them. Multiply that second number by five years of maintenance and framework upgrades. For most teams the week produces an answer that no amount of comparison reading would have.

Frequently Asked Questions

Is Medusa actually free?

The core is MIT-licensed and free to run. The costs arrive elsewhere: infrastructure, the engineering time to build and maintain customisations, and a commercial agreement if you need the Enterprise Materials. RBAC and SSO are named in the Enterprise License, so security-driven requirements can turn a free platform into a licensed one.

What agent tooling does Swell offer?

Swell publishes coding-agent skills, a CLI built for agent loops, and a REST API whose schema is discoverable at runtime.

Which platform gets a store live faster?

Swell, in almost every case, because subscriptions, B2B pricing and the admin exist before you write anything. Medusa's starters close part of the gap for standard catalogue commerce, and Medusa Cloud removes the deployment step. The gap widens sharply when recurring billing is involved.

Can Medusa handle subscriptions without custom code?

Not natively. Medusa documents subscriptions as a recipe requiring a custom module, scheduled jobs, admin extensions and storefront work. It is well documented and entirely achievable. Budget it as a feature you are building and will maintain, not one you are configuring.

How many engineers does self-hosting Medusa really need?

There is no universal number, but the useful threshold is whether one named person can own PostgreSQL, Redis, the server and worker deployment topology described in the deployment guide, and framework upgrades, without it displacing their product work. If the honest answer is no, the operational cost is larger than it looks on the infrastructure invoice.

What if the decision still feels close?

Close usually means commerce is not your differentiator, since teams for whom it is do not find this close. When it is genuinely tied, prefer the option with a lower standing obligation and run the one-week test above. Building the same flow twice produces a better answer in five days than five weeks of comparison.