Migrating away from Medusa to a custom Solidus store

What Medusa is, and why you already own more than most

Medusa is an open source commerce platform you run yourself. The core is a Node.js application written in TypeScript, organised as a monorepo of commerce and infrastructure modules and needing a current Node runtime to build and run.¹ It is licensed under the permissive MIT licence, with only the role based access control of its Enterprise Edition sitting behind a separate commercial agreement.² You install it, you deploy it, and it reads and writes to a PostgreSQL database that lives on infrastructure you control.³ That one fact changes the whole character of this article.

Most of the migration series is about getting data out of a platform that does not want to let go. Shopify hands you CSV files and keeps the rest. Wix barely exports at all. Medusa is the opposite case. You already have the database, you already have the admin, and nobody can switch your shop off or raise your rent. So I am not going to pretend you are trapped, because you are not. The honest question here is a different one: given that you own it, is Medusa still the right thing to own, or would your business be better served by a mature shop built on Ruby on Rails that one person can be accountable for end to end?

I build on Solidus, an open source Rails commerce framework, so you know where I stand. That is exactly why I am going to be careful to be fair. Medusa is a capable, modern, actively developed project, and plenty of businesses should stay on it. This article is for the ones that have looked at their stack and concluded the fit is wrong.

If you want the ownership principle in full, I set it out in who actually owns your business data, and the whole series starts from what moves and what does not when you migrate a shop.

Who should stay on Medusa

Let me put the fairness up front, because it is the credibility of everything after it.

Stay on Medusa if your team is genuinely happy writing Node.js and TypeScript, and you have the engineers to keep a framework current. Medusa 2, released in October 2024, was a complete architectural rewrite of the project, with breaking changes from the 1.x line.⁴ That rewrite produced a much stronger platform, but it also tells you something about the shape of the commitment: this is a young, fast moving framework, and owning it well means keeping a Node team who follow its releases and understand its model.

Stay if you like that model. Medusa 2 is built from isolated modules. Each module owns its own data and exposes a service, and modules are deliberately kept apart so that one cannot reach into another's tables with a direct foreign key. To connect a product to, say, a custom record, you define a module link, and Medusa stores the association in a dedicated link table rather than as an ordinary relation.⁵ This is a thoughtful design that keeps integrations clean. It is also a particular way of thinking about commerce data, and some teams love it while others find it more indirection than their shop needs.

Stay if headless is genuinely what you want. Medusa ships a backend and an admin, and your storefront is a separate application you build and run, usually in a JavaScript framework. If you want a single owned application that serves the storefront, the admin and the API together, that is a different architecture, and it is the one I build.

None of those reasons to stay is about lock in. You own your data either way. They are about fit. If three of them describe you, the honest advice is to close this article and keep improving the Medusa shop you already own.

The export and API reality: Postgres, the Admin API and CSV

Because you own the database and the API, data access on Medusa is as good as it gets. There is no rescue operation here, which is the nicest problem a migration can have.

You have three clean routes to your data, and a real move usually uses all three.

The first is the PostgreSQL database itself. It is yours, on your own infrastructure, and a standard dump gives you every table: products, variants, prices, customers, orders, line items, addresses and whatever your custom modules have stored.³ For the bulk of a catalogue and the full order history, reading the database directly is the most complete and the fastest path.

The second is the Admin API. Medusa exposes a REST Admin API under the /admin path, authenticated with a bearer token, an API key or a session, and it covers products, customers, orders and the rest of the admin surface.⁶ An API is the right tool when you want records in a shape the application understands, with its pricing and relationships resolved, rather than raw rows. It is also how you script a repeatable export that you can run again on cutover day.

The third is the built in CSV import and export for products. Each row represents a product variant, Medusa provides a template, and the same format round trips, so a product catalogue moves through a file you can read, check and diff.⁷ For products this is often the cleanest bridge into a new shop.

Passwords are the one thing that does not travel, and that is true everywhere, not a Medusa failing. They are stored as one way hashes, so they cannot be turned back into passwords and carried across. You either verify the old hash once at a customer's first sign in or, more simply, ask every customer to reset. I cover both approaches, and how to do the reset as a calm relaunch rather than a support fire, in migrating customer accounts and addresses.

So the move off Medusa is not a data extraction problem. It is a backend reimplementation: the same well structured data landing in a Rails application, with the business logic rewritten in Solidus and Ruby instead of Medusa modules and TypeScript.

The honest reason to move is fit, not lock in

If the data comes out cleanly, why move at all? Four honest reasons, none of which is Medusa being a poor platform.

The first is ecosystem and language. Ruby on Rails is twenty years old, and Solidus is a mature commerce framework built on it, under the BSD three clause licence.⁸ For a business that wants the Rails ecosystem, its conventions, its enormous pool of developers and its long record of running shops in production, moving from Node to Rails is a reasonable strategic choice. It is not that one language is better. It is that you want the one your business is going to hire for and build on for the next decade.

The second is one accountable builder. On Medusa, keeping a young framework current, watching its releases and carrying its architecture forward is ongoing work that usually wants a team who know Node well. Some businesses would rather have one person who designs, builds, tests and maintains the whole shop and answers for it, than a framework roadmap and the specialists to track it. That is the model I work in: I build the Solidus store, I run the move, and the bespoke code becomes yours on full payment.

The third is maturity and stability expectations. Medusa moves quickly, and the jump from 1.x to 2 was a rebuild. If you want a platform where a major version every couple of years is planned, incremental maintenance rather than a rewrite, Solidus follows strict semantic versioning with a slow, deprecation led upgrade path, and that predictability is worth a lot to an owner who signs the invoices.

The fourth is the surrounding services. A production Medusa deployment usually leans on more than Postgres: Redis for its event bus, caching, locking and workflow engine, a file provider such as S3, a notification provider for email, and a separately deployed storefront.³ That is a sensible architecture, and the managed Medusa Cloud exists precisely to run it for you. But if you would rather own a smaller operational surface, a single Rails application with PostgreSQL and a background job queue, deployed the way I deploy everything, that simplicity is a legitimate thing to want.

Notice what none of these are. None of them is "Medusa is locking you in" or "you cannot get your data". They are all fit. Be honest with yourself about which of them actually applies to your business, because if none does, you should stay.

Four things to settle before anything else

A Medusa move is mostly calm, but four areas carry the risk. Flag them in the first conversation, not the last week.

Payments and saved cards. Medusa handles payments through module providers, Stripe being the common one, and the sensitive card data lives with the gateway, never in your Medusa database. That is good news for a migration. If your new Solidus shop connects to the same Stripe account, the saved cards and their tokens stay exactly where they are and your customers notice nothing. If you are changing gateway, that is the hard case, and the rules are the same as for any platform. I set them out in migrating payment tokens and saved cards.

Subscriptions and recurring payments. Medusa core does not ship a subscription engine, so if you sell on a recurring basis you have built that logic yourself, in custom modules, workflows and a scheduled job, or bolted on a provider. That means there is real business logic to understand and re express, and there may be live mandates and tokens at a gateway that need care. The concepts, and what can and cannot move, are in migrating subscriptions and recurring payments.

Custom modules hold your logic. The strength of Medusa is that you have probably modelled your particular business in its modules and workflows. That same logic is the work of the move. Every custom module, every workflow, every bespoke rule has to be understood and rebuilt as Rails and Solidus code, with tests. The more you have built, the larger this part is, and it is the part to scope honestly rather than wave at.

SEO and the redirect map live in your storefront. Because Medusa is headless, your URLs belong to your storefront application, not to Medusa. The product, category and content paths that carry your search rankings are defined in that front end, so the redirect map is drawn from your storefront's routes. Getting every old URL mapped to a permanent redirect is the single most valuable day of the whole project, and I treat it the same way on every migration. The full method is in migrating products and catalogue data.

Here is the shape of it on one view.

Area	What moves cleanly	What needs care
Catalogue	Products, variants, prices, images via database, Admin API or CSV	Mapping to the Solidus model
Customers	Names, addresses, order links	Passwords never move, so reset or verify
Orders	Full history from the database	Decide how far back to carry
Payments	Tokens stay if you keep the same gateway	A gateway change is the hard case
Subscriptions	The records	Live mandates and your custom recurring logic
Storefront and SEO	Nothing automatic	Rebuild the front end, map every URL

A worked example: a Bristol brand moves off Medusa

Let me make it concrete with an invented business. None of this is a real client.

Marsh Lane Supply (marshlanesupply.example) is a Bristol brand selling outdoor and camping gear direct to consumers. Three years ago a capable contractor built them a Medusa backend with a Next.js storefront, and it has served them well: about 2,500 products with variants, a tidy admin, a custom module for a build your own kit bundle, and Stripe for payments. They own all of it, on their own servers.

So why are they talking to me? The contractor has moved on, the storefront and the backend are on a version of Medusa that is now a year behind, and every agency they ring quotes them as a Node project that needs a team. The founder wants two things: to stop depending on scarce framework specific knowledge, and to have one person accountable for the shop who will still be there in three years. They are a Rails leaning business already, because their warehouse tool is a small Rails application. The fit has drifted.

We start with the honest conversation, and I tell the founder plainly that nothing is forcing this move. The data is safe and the shop works. If they were happy on Node, I would tell them to stay. They are not, so we go on.

The payment question is settled in the first meeting, which is where it belongs. Marsh Lane keeps its own Stripe account, so the new Solidus shop connects to that same account and the saved cards simply carry over. No customer re enters a card.

The data itself is the easy part. I take a PostgreSQL dump for the full catalogue and order history, use the Admin API to pull resolved product and customer records for checking, and use the CSV export to diff the catalogue as I load it into Solidus.³⁶⁷ Passwords are hashed, so we plan a reset framed as a relaunch, with a service message before cutover.

The real work is the custom bundle module and the Next.js storefront. The build your own kit logic is re expressed as ordinary Solidus and Rails code, with a Cucumber test for every rule, so the founder can read what the shop promises. The storefront becomes part of the single Solidus application I build, and we draw the redirect map from the old Next.js routes so not one ranking is dropped on cutover. Within a planned window, Marsh Lane is on a shop they own just as fully as before, now in the ecosystem they were already leaning towards, with one person they can ring.

The move, mapped to the data guides

I do not re explain the deep mechanics in a platform article, because the data type guides own them. Here is the map for a Medusa move.

Products, variants, prices, categories, images and the all important redirect map: migrating products and catalogue data.
Customer accounts, addresses and the password reset done as a relaunch: migrating customer accounts and addresses.
Saved cards and vaulted tokens, and why keeping the same gateway is the quiet win: migrating payment tokens and saved cards.
Recurring plans, mandates and the logic behind them: migrating subscriptions and recurring payments.
The ownership principle under all of it: who actually owns your business data.

Two more pieces are worth reading next to this one. If you want the numbers, the five year total cost of ownership builds a full model for a move onto Solidus. If you are weighing Solidus against the rented platforms more broadly, the platform comparison is the piece to read. And because you are coming from a headless setup already, headless and API first Solidus explains how a Solidus store keeps the API you are used to.

If your reason for looking at Medusa alternatives is really a comparison of modern commerce frameworks, two other open source projects sit in the same space. Saleor is a Python and GraphQL platform, and commercetools is the licensed enterprise end of headless. I treat them fairly in their own pieces, migrating away from Saleor and migrating away from commercetools.

What you take with you

Ask the question I ask of every platform: if I want to move again in four years, what do I walk away with?

From Medusa, a lot, which is to its credit. You take your PostgreSQL database, your repository, and a shop you were already running on your own servers. From Solidus you take exactly the same kind of thing: a Ruby on Rails application and a PostgreSQL database that you own outright, on infrastructure you control, with the bespoke code yours on full payment. The difference between the two is not ownership, because both give you that. It is the ecosystem you are standing in, the maturity of the framework, and whether one accountable builder or a Node team is the right shape for your business.

That is the whole honest case. You are not escaping a trap. You are choosing a different, mature, equally owned foundation because it fits you better.

Who I would tell to move, and who to stay

Stay on Medusa if you have Node and TypeScript people who enjoy the work, you like the module and workflow model, and headless is the architecture you want. You already own your data and your deployment. Do not move for the sake of it.

Move to Solidus if you would rather build on Ruby on Rails, if you want one person accountable for the whole shop end to end rather than a framework to keep current, if you prefer a mature platform with a slow, predictable upgrade path, or if you want a single owned application instead of a backend, a storefront and a row of supporting services to run. The data will come across cleanly. The work, and the value, is in the rebuild of your logic and your storefront.

If you are not sure which of those is you, that is exactly what the workshop is for. Bring your Medusa setup, your custom modules and your honest frustrations, and I will tell you whether a move actually pays off for your business. Sometimes it does not, and I will say so.

Medusa, README and contribution guide, medusajs/medusa on GitHub (Node.js v22 or later, a Yarn workspaces monorepo, Commerce and Infrastructure modules), accessed 14 November 2026, https://github.com/medusajs/medusa ↩
Medusa, licence and README, medusajs/medusa on GitHub (MIT Licence, with the Enterprise Edition covered by a separate commercial agreement), accessed 14 November 2026, https://github.com/medusajs/medusa/blob/develop/LICENSE and https://github.com/medusajs/medusa ↩
Medusa Documentation, Architecture (Express based server, API routes to workflows to modules to PostgreSQL, PostgreSQL as the only natively supported database, Redis backed infrastructure modules and Medusa Cloud for managed hosting), accessed 14 November 2026, https://docs.medusajs.com/learn/introduction/architecture ↩ ↩² ↩³ ↩⁴
Medusa, Medusa 2.0 is now generally available, 23 October 2024 (a complete architectural rewrite with breaking changes from the 1.x line), https://medusajs.com/blog/v2-release/ ↩
Medusa Documentation, Module links (modules are isolated and cannot define a direct foreign key into another module's data, so associations are stored in a dedicated link table), accessed 14 November 2026, https://docs.medusajs.com/learn/fundamentals/module-links ↩
Medusa Documentation, Admin API reference (REST routes under the /admin prefix, authenticated with a bearer token, an API key or a session), accessed 14 November 2026, https://docs.medusajs.com/api/admin ↩ ↩²
Medusa Documentation, Import products via CSV (one row per product variant, with a downloadable template and the same format for export), accessed 14 November 2026, https://docs.medusajs.com/user-guide/products/import ↩ ↩²
Solidus, solidusio/solidus repository on GitHub (an open source commerce framework on Ruby on Rails, under the BSD three clause licence), accessed 14 November 2026, https://github.com/solidusio/solidus ↩