Spree Commerce: a BSD-licensed Ruby commerce backend you host yourself

What Spree actually replaces in a commerce stack

Spree is a Ruby application that owns the commerce primitives: products, variants, price lists, customer groups, companies, catalogs, channels, markets, orders, payments and fulfillment. The README frames it as one core serving several business shapes, and the use-case list is specific about which primitives each one leans on. A marketplace needs seller onboarding with requirement checklists, order splitting per seller at completion, a commission engine and a payout ledger with Stripe Connect. A B2B channel needs price lists with volume tiers, customer groups, companies with locations and tax exemptions, and catalogs scoped per segment. Cross-border selling needs markets that bundle currency, language, payment methods and shipping per region.

The audience is a team with Ruby or Rails capacity that wants to own the data layer and the deployment. It is not aimed at someone who wants a checkout button on a static site with no server to run. The README is explicit that this is self-hosted software with no platform fees and no vendor lock-in, which is a description of an operating model, not a feature: you get the code and you get the pager.

How the API, channels and markets fit together

The architecture the README describes is a single backend with several front ends attached through a REST API. The admin side is a React dashboard, and the storefront side is a separate Next.js application in the spree/storefront repository, built with Next.js 16, React 19, Tailwind CSS 4 and TypeScript. The backend does not render the customer-facing pages in that setup; it answers API calls.

Channels are the mechanism that keeps multiple surfaces apart. According to the README, each channel gets its own catalog, pricing, payment methods and order attribution, so a web storefront, a mobile app, a point of sale and a B2B panel can all read from one backend without sharing configuration. Markets operate on a different axis: they bundle currency, language, payment methods and shipping per region, and the README notes translations for product content, EU Omnibus price history and customs duties are built in. If you have sold into the EU, you know that price history requirement is not decoration; it is a legal obligation that usually gets bolted on late. Having it named in the core documentation is a meaningful signal about who the project is written for.

The repository layout reflects the split. There is a spree/ directory for the Ruby side and a packages/ directory for the JavaScript packages, with pnpm workspaces and turbo wired through the root package.json. The root package.json also carries scripts that clone spree/spree-starter into a server/ directory and generate a SECRET_KEY_BASE with openssl rand -hex 64, which tells you the intended local topology: a Rails server plus a database plus a worker, driven through Docker Compose files under scripts/.

Installing Spree and running a first store

The README gives one command for local setup and states it takes about five minutes. It requires Node.js 24 or later and Docker running on the machine. The command scaffolds the backend, the React admin dashboard and, optionally, the Next.js storefront into a single project directory.

npx create-spree-app@latest my-store

After the scaffold finishes you have a project directory named my-store. The README does not spell out the prompts in the text shown here, so expect to be asked whether you want the storefront included. Once the stack is up, the README points at the live demo at demo.spreecommerce.org if you want to see the Next.js storefront before building your own.

The project also ships a CLI package, @spree/cli, which the README describes as managing the project from the terminal: booting the stack, running generators and migrations, tailing logs, and calling the Admin API directly with get, post, patch and delete commands. In local development it uses zero-config credentials. Two examples from the README:

spree dev
spree generate api_resource Brand name:string description

The first boots web, worker and database together. The second generates an API resource for a Brand model with a name and a description field. If you are coming from a Rails background, that generator will feel familiar; if you are not, it is the fastest way to see how Spree expects custom resources to be shaped. The README does not document a rollback for the generator, so treat generated files as something you review in version control rather than something you undo with a flag.

If you are building with an AI coding agent, the README points at a separate repository, spree/agent-skills, installed with npx skills add spree/agent-skills, which teaches tools such as Claude Code, Cursor and Copilot the project's conventions and upgrade flows. There is also a docs MCP server referenced in the agentic development documentation.

The parts the README leaves thin

The quickstart is the strongest part of the documentation and also the narrowest. It covers local development on a machine with Docker. It does not describe a production deployment path in the README text: no mention of how the web and worker processes should be supervised, how the database is backed up, or how the storefront and backend are wired in a real environment. Those answers may exist in the linked documentation site, but the README itself stops at local setup. Anyone planning a launch should treat the quickstart as a starting point and go read the installation docs before sizing infrastructure.

The multi-tenant story is the clearest boundary. The README lists multi-tenant SaaS as an Enterprise use case and states plainly that it requires the Enterprise Edition, with a link to a pricing page. Each tenant gets an isolated store with its own catalog, orders, customers, payment methods and branding, and staff can manage several tenants. That capability is not in the open source core. If your product idea is selling stores to merchants as a service, the free path does not include the isolation model you need.

The release cadence is also worth reading carefully. The most recent release listed is v6.0.0.beta2, dated 2026-09-17, which is a beta. The last stable line shown is v5.6.1 from 2026-07-28. A beta on the main branch means the 6.x line is in motion; extensions and custom code written against 5.x may need work. The README does not document a migration path between major versions in the text available here, so verify that before you start building on 6.x.

Spree against Shopify and Medusa

The honest comparison is not feature-by-feature, because the projects are sold on different terms. Shopify is a hosted platform: you do not run the Ruby, you do not own the database, and you pay platform fees on transactions. Spree's pitch is the inverse. The README describes BSD 3-Clause licensing, self-hosting, full ownership of code, data and infrastructure, and zero platform fees. The trade is operational: with Shopify, someone else handles uptime, upgrades and PCI scope around checkout; with Spree, that work lands on your team.

Medusa is the closer alternative, and the difference is the language and the shape of the core. Medusa is a Node and TypeScript commerce backend, which means a JavaScript-heavy team can run the backend and the storefront in one language and share types across the boundary. Spree is Ruby, with TypeScript SDKs and a Next.js storefront layered on top through the REST API. If your team already writes Rails, Spree fits without a second runtime in the backend. If nobody on the team wants to operate a Ruby application, Medusa removes that requirement. Spree's answer to the JavaScript side is the SDK and the storefront repository, not a JavaScript core.

WooCommerce is the other common starting point, and it is a different bet again: it is a plugin on WordPress, so the commerce model is shaped by the CMS rather than the other way around. Spree treats commerce as the primary domain and lets you attach whatever front end you want, which is why the README talks about channels and markets rather than themes.

Licence, upgrades and what maintenance costs you

The repository is BSD 3-Clause licensed, and the README states that you keep full ownership of your code, data and infrastructure. BSD 3-Clause is permissive: it allows commercial use and modification, and it does not require you to publish your changes the way a copyleft licence would. It does carry the standard clause restricting use of the project's name to endorse derivative work, which matters if you plan to market a product built on it. This is a description of the licence text, not legal advice; if you are building a commercial product on top, have counsel read the LICENSE file in the repository.

The Enterprise Edition is the commercial boundary. Multi-tenant SaaS is listed under it, and the README links to a pricing page rather than describing terms. That is the one place where the no-platform-fees claim has a caveat, and it is worth understanding before you design a product around tenant isolation.

On maintenance: the repository is not archived, and the last push was on 2026-09-21. The release history shows a stable 5.6.1 in July 2026 and a 6.0.0 beta in September 2026, alongside a TypeScript SDK release, @spree/[email protected], in July 2026. That is a project moving on two tracks at once, which is good for longevity and inconvenient for anyone who needs a frozen target. The upgrade cost is the real line item: a Rails application you host means you own Ruby version bumps, database migrations, dependency updates and the Docker Compose topology the root package.json scripts assume. Budget for that as ongoing work, not a one-time setup.

Editorial conclusion

Adopt Spree if you want a Ruby commerce core with an open REST API and you are willing to run Ruby, PostgreSQL and a worker yourself; the README's own quickstart assumes Node.js 24+ and Docker. Skip it if you need multi-tenant SaaS isolation on the free tier, since that is documented as Enterprise Edition, or if you want a hosted checkout with no infrastructure. Before committing, read the installation docs at spreecommerce.org, check the v6.0.0.beta2 release notes, and confirm whether the extensions you need are compatible with the 6.x line rather than only 5.6.1.

Frequently asked questions

Official sources

1. License: BSD-3-Clause
2. Project website
3. README
4. Releases
5. spree/spree on GitHub