Migrating away from Swell to a custom Solidus store

The email that starts a Swell migration

The message usually comes from a founder who already knows how their shop works. They chose Swell on purpose, built a custom storefront against its API, and have run on it for a couple of years. The complaint is rarely that Swell is bad. It is that the shop has become two systems held together by a contract: a storefront the business owns and a commerce backend it rents, each with its own bill, its own roadmap and its own people who understand it. The question in the email is whether all of that could live in one application the business owns outright, built on the same web framework the storefront team already likes.

That is a fair question, and the honest answer is not always yes. Swell is a capable modern platform, and plenty of shops are right to stay on it. This article is for the business that has outgrown the arrangement and wants a single owned Rails application instead, and it tries to be precise about what leaving actually involves. For the concepts that are true of any migration, I link out to the deep guides rather than repeat them. The one to read first is what moves and what does not.

What Swell is, and who should stay on it

Swell is a headless commerce platform. It gives you a hosted database with the standard ecommerce models already built, an admin dashboard, and an API, and it leaves the customer facing storefront to you.¹ You build that storefront yourself, usually as a separate front end application that talks to Swell over its API, and Swell runs the commerce backend on its own infrastructure so you never operate a database or a server for it.¹ That is a real and sensible model. It suits a team that wants the control of custom code at the front without the work of running the commerce engine at the back.

So before any of the migration detail, here is who should not move. If you are happy running a bought storefront against a hosted backend, if your catalogue and your rules fit Swell's data model without a fight, and if the monthly bill is comfortable at your current size, Swell is doing its job and a migration would be effort spent to reach the same place. The headless split is a feature for you, not a tax.

The business this article is written for is the one for which that split has turned into a cost. It wants one application, one deployment, one codebase and one person accountable for the whole of it, rather than a storefront in one place and a commerce platform it cannot see inside in another. Often it already runs the storefront in Ruby on Rails or wants to, and Solidus, an open source commerce framework on Rails,² lets the catalogue, the checkout, the admin and the storefront be one owned thing. The wedge here is fit and ownership, not a rescue. You can get your data out of Swell. The question is whether owning the whole stack is worth the build.

What you own and what sits on Swell's infrastructure

Draw the line clearly before you plan anything.

You own your storefront code, because you wrote it. You own your domain, your design and your content. You own your data in the practical sense that the API will hand it back to you in full. What you do not own is the place it lives. The database, the commerce logic, the admin, the card vault and the API that serves all of it run on Swell's infrastructure, and your storefront depends on that infrastructure being up and answering every time a customer loads a page.¹ That dependence is the thing a move changes. After it, the data lives in your own Postgres database, inside your own application, on hosting you control.

What you take with you	How it leaves Swell	Where it lands in Solidus
Products, variants, categories, attributes, images	Backend API read of each model	Products, variants, option types, taxons
Customer accounts and addresses	Backend API read of the accounts model	Users and addresses, passwords excluded
Order and purchase history	Backend API read of the orders model	Orders as read only history
Subscriptions	Backend API read plus gateway cooperation	Solidus subscription setup, re anchored to your gateway
Saved cards	Live in Swell's vault, gateway to gateway move	Your own gateway's vault
The storefront	You already own the code	Rebuilt or reused against Solidus

Each row that involves moving data has a deep guide behind it: customer accounts and addresses, products and catalogue data, order and purchase history, payment tokens and saved cards and subscriptions and recurring payments. I will not re explain those mechanics here. The point of this article is the part that is specific to Swell.

The export and API reality

Swell does not lock your data away, and it is worth saying so plainly because the honest wedge is not a data hostage situation. The way out is the Backend API. It gives full access to every model in the store, it is a plain REST interface that accepts and returns JSON at the base URL https://api.swell.store, and there are official Node and PHP libraries for it.³ The standard models cover the commerce objects you would expect, products and orders among them, and any custom models you added appear through the same interface because Swell generates endpoints from the model definitions.⁴ You can also read the schema itself, model by model, so a migration script can discover every field you ever added rather than guessing.⁴

That last point matters more on Swell than on a rigid platform. Swell lets you extend the data model: you can add fields to the standard models or define new ones in the dashboard under Developer and then Models, and apps you installed may have added their own.⁴ A product on your Swell store is therefore not a generic product. It may carry fields that exist only in your store, and the migration has to find them, understand what each one means, and decide where it goes in the Solidus model. Reading the schema is how you avoid silently dropping a field that the business depends on.

There are two limits to plan around. The first is that the export is an API read, not a single download button, so the migration is a set of scripts that page through each model, not an afternoon with a spreadsheet. The second is the rate limit. Backend API usage is limited per store and separately per environment, across both throughput and concurrency, and requests are weighted rather than counted one for one, so an aggregate or a heavily expanded query costs more than a plain read.⁵ When you go over, requests are queued rather than refused, and only a request that waits more than sixty seconds is dropped with an HTTP 429.⁵ In practice that means the full export runs as a paced, resumable job that reads in batches and does not try to pull a large catalogue in one burst. Light reads of products, variants, categories, attributes, accounts, carts and content draw from a separate pool, which helps, but the sensible plan is still to rehearse the export on a copy and let it take the time it takes.⁵

The pricing that scales with you

The clearest ownership argument for a growing Swell shop is on the pricing page. Swell's plans run from Starter at USD 29 a month to Unlimited at USD 2,250 a month, and each plan has two things a rented backend tends to have: an annual sales ceiling and a meter.⁶

The ceiling is a figure of annual sales, from USD 50,000 on the entry plan up to USD 5 million on Unlimited, and sales above your plan's ceiling are charged a percentage, from 2% on the smallest plan down to 0.4% on the largest.⁶ That is not a per order transaction fee, and Swell is clear that it does not take a cut of payments through an outside gateway, but it means the platform's cost is tied to how much you sell, which is exactly the line a shop hopes to grow. The meter is on the API itself: each plan includes a monthly allowance of API requests, from 100,000 up to 2 million, and requests beyond the allowance cost USD 5 per additional 100,000, with similar overage on function calls and storage.⁶ For a headless shop that is a live number, because your own storefront is the thing making those requests on every page view and every search.

None of this is hidden or unfair, and at a small size it is inexpensive. The point is only that it scales with your success rather than with your costs. A custom Solidus store inverts that shape: a larger build cost at the start, then hosting and maintenance that track the work, not the turnover, with no licence and no percentage above a ceiling.² The full five year arithmetic, with worked figures, is in the total cost of ownership article, and the platform by platform comparison is in the comparison article.

The card vault is the hard part, as it always is

Swell runs its own card vault. When a customer saves a card, Swell tokenises it and stores the encrypted details in that vault, and the token is held against the customer account.⁷ This is a genuinely good design while you are on Swell, because it means you can change payment gateway without customers entering their cards again, and it is what lets Swell run subscriptions against any gateway that supports vaulted cards.⁷ It is also the single thing that most needs planning before you leave.

The nuance is worth getting right, because this is where fairness and precision matter most. The vault is portable between gateways inside Swell, but it is Swell's vault. Moving fully off Swell means getting those saved cards into a vault you control, and raw card numbers never travel in a migration script. If your Swell store already charges through your own gateway account, the saved cards may already live in that gateway's vault, in which case the Solidus store connects to the same account and the cards stay exactly where they are. If they live in Swell's vault, you are into a gateway to gateway transfer, which the receiving processor will only accept from one certified at PCI DSS Level 1, and which does not carry subscriptions or payment history with it.⁸ The deep version of this, with the questions to ask your gateway first, is in the payment tokens guide. Flag it in week one, not week ten.

Subscriptions sit right next to this, because Swell's recurring billing depends on the vaulted card.⁷ A subscription is not just a row that says monthly. It is a live billing agreement with a next charge date, a schedule and a saved payment method behind it, and it keeps taking money while you move. You carry the schedules and the customer intent across, you re anchor each subscription to the gateway the Solidus store will bill through, and you pick a cutover that does not land in the middle of a billing run. The subscriptions guide covers the mechanics. If your shop is subscription led, this is the part that decides the timeline.

The storefront, SEO and redirects

Here is where a Swell move is lighter than leaving a closed builder, and I should say so. Because Swell is headless, you already own the storefront and you already own the URLs. There is no theme locked inside a platform language to unpick, and your front end code can often be reused against Solidus with the data layer swapped underneath, rather than rebuilt from nothing. That is a real saving, and it is one of the reasons a Swell to Solidus move can be cleaner than it sounds.

The flip side is that SEO was always your job on Swell and stays your job on Solidus. The platform did not own your URL structure, so there is no vendor specific path scheme to translate, but every address your storefront publishes still has to resolve after the move. Map every old URL to its new one, use permanent server side redirects straight to the destination rather than through a chain, and keep them for at least a year.⁹ On a headless build the redirect map is usually smaller and cleaner than on a templated platform, because you chose the URLs in the first place, but a missing row is still a page that returns a 404 the day you cut over. Product URLs and canonical handling carry the detail in the products guide.

One more line belongs here. Moving customer records does not need fresh consent from every customer, but the shop stays the controller of that data and each processor, the old platform, the new host and the developer, needs a written processing contract under Article 28.¹⁰ Carry marketing consents across with their timestamp and wording rather than a bare yes or no flag, and after the final export ask Swell in writing to delete the old copy. Who holds what, and why owning the stack changes the answer, is the subject of who actually owns your business data.

A worked example: a Brighton coffee subscription moving to Solidus

Ridgeway Coffee Roasters (ridgewaycoffee.example) is an invented Brighton business that roasts and ships coffee on subscription. It turns over about £1.2 million a year, has around 400 products once grinds and bag sizes are counted as variants, and runs roughly 3,000 active subscriptions on weekly, fortnightly and monthly schedules. Two years ago the founder built a fast custom storefront and put Swell behind it, which was the right call then. Today the business wants its roastery software, its wholesale ordering and its subscription shop to be one Rails application its own developer owns, and it is tired of reasoning about a backend it cannot read the source of.

The move starts with the questions that are expensive to get wrong, and on this shop they are all about money in flight. In week one I establish where the saved cards actually live. Ridgeway charges through its own gateway account, so the cards are in the gateway's vault, not stranded in Swell's, which turns the hardest problem into a connection rather than a transfer.⁷⁸ Then the subscriptions: I read every subscription through the Backend API with its schedule, next charge date and the customer it belongs to, and I plan the cutover for the quietest window in the billing calendar so that no customer is charged twice and none is missed.⁵

The catalogue and customers are the calm part. A paced set of scripts reads products, variants, categories and the custom fields Ridgeway added for roast date and origin, discovered by reading the schema so none is dropped, and writes them into Solidus as products, variants and option types.⁴ Customer accounts and addresses come across the same way, without passwords, so every customer sets a password or signs in afresh on their first visit after launch. Three years of orders move as read only history so support and customers can look back, while the full export is archived for the accountant. The storefront, already the business's own code, is pointed at Solidus with the data layer rewritten, which is the reason this build is weeks rather than months.

Cutover is a quiet Tuesday morning outside a billing run. The domain moves to the new application, the redirect map is checked by hand against the top pages, a real subscription renewal and a real one off order are run and refunded on each payment method, and the old Swell store is kept live and paid for thirty days as the way back. A month later, after one clean billing cycle and one clean month end on Solidus, the Swell plan is cancelled and its deletion requested in writing. Ridgeway now runs one application: roastery, wholesale, subscriptions and shop, owned, on hosting it controls, with no sales ceiling and no API meter.

The honest move plan

Stripped to its shape, the plan is the same discipline every migration needs, with the Swell specifics slotted in.

Decide the payments and subscriptions question first, because it sets the timeline and it is the only part that can go wrong with customers' money. Read the schema before you write an import, so the custom fields that make your store yours are not silently lost. Run the export as a paced, resumable job that respects the rate limit rather than fighting it. Reuse the storefront where you can, since you own it, and swap the data layer underneath. Build the redirect map even though it is smaller than usual, and test it. Keep three years of orders, not everything. Run both systems in parallel with the catalogue frozen, rehearse the final import twice, cut over on a quiet morning outside any billing run, and keep Swell alive for thirty days as the fallback before you cancel.

None of that is unique to Swell except the schema read, the rate limited export and the vault question. The rest is the craft in the pillar guide, and if your plan does not have an owner inside the business who understands the data, the custom fields and the subscriptions, it is not a plan yet.

When staying on Swell is the right call

I would rather lose this work than sell it to the wrong shop, so here is the counsel to stay.

Stay if the headless split is helping you, not costing you, which is true for most shops at most sizes. Stay if your sales sit comfortably under your plan's ceiling and the API meter is a rounding error, because then the pricing that looks like a tax at scale is simply a fair bill. Stay if your team is small and the idea of owning hosting, upgrades and security for the whole stack is a burden rather than a relief. Stay if what you really want is a storefront change, because you can do that on Swell without touching the backend at all. A migration is worth it when owning one application end to end is worth more to you than the build costs, and when you can name the person who will own it. If you cannot, the move will hand you a beautiful new shop full of data nobody vouched for.

The workshop

If you are weighing this up, I run a free workshop and the first two weeks of work are on me. Bring your Swell plan and its current bill, a note of the custom fields and apps you have added, and whether your saved cards live in your own gateway or in Swell's vault, and I will work through with you whether owning the whole stack pays off for your shop. Sometimes it does not, and I will tell you so.

Swell, Platform overview (a headless commerce platform with managed infrastructure, a hosted database of standard ecommerce models per store, an admin dashboard, and storefronts that the merchant builds and serves), developers.swell.is, checked 14 November 2026, https://developers.swell.is/guides/core-concepts/platform-overview ↩ ↩² ↩³
Solidus, solidusio/solidus repository on GitHub (an open source commerce framework on Ruby on Rails under the BSD 3 clause licence), https://github.com/solidusio/solidus ↩ ↩²
Swell, Backend API introduction (REST interface that accepts and returns JSON at the base URL https://api.swell.store, with official Node and PHP libraries), checked 14 November 2026, https://developers.swell.is/backend-api/introduction ↩
Swell, Backend API data models (full access to every model in the store, standard models such as products and orders, custom models created under Developer then Models, models that extend a parent, and the schema readable as a meta model), checked 14 November 2026, https://developers.swell.is/backend-api/data-models ↩ ↩² ↩³ ↩⁴
Swell, Backend API rate limits (limited per store and per environment across throughput and concurrency, weighted requests, excess queued and dropped after sixty seconds with HTTP 429, and a separate pool for light reads of products, variants, categories, attributes, accounts, carts, purchase links and content pages), checked 14 November 2026, https://developers.swell.is/backend-api/rate-limits ↩ ↩² ↩³ ↩⁴
Swell, Pricing (plans from USD 29 to USD 2,250 a month, each with an annual sales ceiling from USD 50,000 to USD 5 million and a percentage from 2% to 0.4% on sales above it, monthly API request allowances from 100,000 to 2 million, and overage of USD 5 per additional 100,000 API requests), checked 14 November 2026, https://www.swell.is/pricing ↩ ↩² ↩³
Swell, Payments core concept (a vault for storing encrypted card information, cards tokenised and stored in Swell's vault with the token held on the customer account, the ability to change gateways without customers entering details again, and recurring billing with any gateway that supports vaulted cards), checked 14 November 2026, https://developers.swell.is/guides/core-concepts/payments ↩ ↩² ↩³ ↩⁴
Stripe, Request a payment data export (saved card data exported only to a processor certified at PCI DSS Level 1, and the export does not include subscriptions or payment history), checked 14 November 2026, https://docs.stripe.com/get-started/data-migrations/pan-export ↩ ↩²
Google Search Central, Site moves with URL changes (map every old URL, use permanent redirects straight to the destination rather than a chain, and keep them at least a year), https://developers.google.com/search/docs/crawling-indexing/site-move-with-url-changes ↩
UK GDPR, Article 28 (Processor), legislation.gov.uk, https://www.legislation.gov.uk/eur/2016/679/article/28 ↩