Spree Commerce

Spree Commerce is an API-first, open-source eCommerce platform built for fast-growing businesses and enterprises that need native support for complex commerce scenarios: B2B wholesale portals, multi-vendor marketplaces, and cross-border storefronts — all without vendor lock-in. Released under the permissive BSD 3-Clause license, you keep full ownership of your code, data, and infrastructure.

The platform ships as a complete Ruby on Rails backend with a production-grade REST API, an official TypeScript SDK with full type safety, and an open-source Next.js 16 storefront built with React 19 and Tailwind CSS 4. Bootstrapping takes five minutes via npx create-spree-app@latest, which sets up the backend, admin dashboard, and storefront together with Docker. A dedicated Spree CLI lets you manage projects from the terminal, run generators, and call the Admin API directly — with zero-config credentials in local development for AI coding agents.

Spree’s modular Rails core handles multi-currency pricing, per-country markets, customer segmentation via price lists and customer groups, promotions, gift cards, digital product fulfillment, and webhooks out of the box. Native integrations include Stripe, Adyen, PayPal, Klaviyo, Google Analytics 4, Google Tag Manager, and MeiliSearch for typo-tolerant product search. The platform is actively maintained by a funded team with 238+ releases, over 27,000 commits, and a release cadence of roughly twice per month.

For organizations requiring more, a paid Enterprise Edition adds multi-vendor marketplace automation (Shopify/WooCommerce vendor sync, Stripe Connect payouts), multi-tenant SaaS infrastructure, advanced B2B buyer organizations with approval workflows and ERP integrations, and SSO (SAML/OIDC) with PCI-compliant architecture and SLA-backed support — all built on the same open-source REST API core.

What You Get

• Production-grade REST API & TypeScript SDK - A fully documented REST API with publishable keys, rate limiting, and an OpenAPI 3.0 spec, paired with an official TypeScript SDK (@spree/sdk) that adds autocomplete and type safety for storefront and mobile integrations.
• Next.js Storefront - An open-source, production-ready storefront built with Next.js 16, React 19, Tailwind CSS 4, and TypeScript — includes multi-region URL routing, Stripe payments (Apple Pay, Google Pay, Klarna, Affirm), customer accounts, and SEO built in.
• Spree CLI - A terminal tool (spree dev, spree generate, spree api get/post/...) that boots the stack, runs generators and migrations, and calls the Admin API directly with zero-config credentials in local dev — built for scripts and AI coding agents.
• Cross-Border Markets - Bundles currency, language, payment methods, and shipping rules per country. Includes a Translations Center for bulk product localization and EU Omnibus Directive compliance with automatic 30-day price history tracking.
• B2B & Wholesale Pricing - Native Price Lists for regional, B2B, and wholesale pricing per customer segment; Customer Groups for segmentation; gated storefronts via publishable keys; and Catalogs for curated per-segment product assortments.
• Promotions, Gift Cards & Digital Products - Rules-based promotions engine, native gift card support with store credits, and automated digital product delivery with per-customer download limits and license key generation.
• MeiliSearch Integration - Typo-tolerant product search and faceted filtering powered by MeiliSearch, configurable directly from the admin dashboard without additional glue code.
• Webhooks 2.0 with Admin UI - Configure, manage, and test webhooks from the admin panel to trigger external systems (ERP, CRM, fulfillment) on order, product, customer, or inventory events.
• Admin Dashboard with Tailwind CSS - A modern, fully customizable admin interface with role-based permissions, staff management, bulk product operations, CSV import/export, and a declarative Tables DSL for custom data views.
• Agentic Development Support - Ships with 25 agent skills (npx skills add spree/agent-skills), a docs MCP server, LLM-ready documentation (llms.txt, per-page Markdown), and auto-generated AGENTS.md/CLAUDE.md in every scaffolded project.

Common Use Cases

• Building a cross-border direct-to-consumer storefront - A fashion brand deploys Spree with the Next.js storefront and configures Markets per country, each with local currency, language, tax rules, and payment methods — all from one backend without a third-party internationalization plugin.
• Running a B2B wholesale portal - A distributor uses Price Lists and Customer Groups to show segment-specific pricing to verified resellers, enforces net-30 payment terms, and gates catalog access behind publishable API keys without a separate B2B platform.
• Launching a headless mobile commerce app - A team builds a React Native app backed by the Spree REST API and TypeScript SDK, using the Admin Dashboard to manage products, orders, and inventory while the storefront is custom-built for native mobile UX.
• Selling digital products and software licenses - An indie software publisher uses Spree’s digital product fulfillment to automatically deliver downloads with per-customer click and day limits upon payment completion, with no additional fulfillment service required.
• Operating a multi-channel sales operation - A company runs a consumer storefront, a B2B panel, and a mobile app from a single Spree backend, each as a separate Sales Channel with its own products, pricing, payment methods, and shipping rules.
• Self-hosting a privacy-first commerce backend - A company with strict data residency requirements deploys Spree on their own infrastructure via Docker Compose, maintaining full ownership of customer data, transaction logs, and product catalog without SaaS platform dependency.

Under The Hood

Architecture Spree organizes its Rails codebase into bounded contexts through discrete gems — core domain logic, REST API layer, admin dashboard, and email subsystem — each independently testable and deployable as a Ruby gem. Service objects follow a consistent ServiceModule::Base pattern with an explicit call interface and run pipeline, cleanly separating business logic from controllers and serializers. The order checkout uses a configurable state machine defined declaratively via checkout_flow blocks, allowing customization of the fulfillment pipeline without modifying core files. Concerns and mixins — Spree::Metafields, Spree::TranslatableResource, Spree::Webhooks, Spree::VendorConcern — are conditionally included using defined? guards, so Enterprise Edition modules layer on top of Core without core code changes. An ActiveSupport::Notifications-backed event bus lets subscribers react asynchronously to lifecycle events across the platform, and a lefthook pre-commit hook automatically regenerates TypeScript types and Zod schemas from Ruby serializers to keep the API contract in sync.

Tech Stack The backend is Ruby on Rails 8 with Ruby 3.2+ minimum, using ActiveRecord with PostgreSQL, state_machines-activerecord for the order workflow, ransack for filterable admin queries, mobility for translatable model fields, and friendly_id for human-readable slugs. Redis handles background jobs via ActiveJob. The TypeScript side is a pnpm monorepo orchestrated with Turborepo: @spree/sdk (ESM + CJS builds via tsup) provides the Store API client; @spree/cli (Commander-based) wraps Docker and the Admin API; and the React admin dashboard uses Vite, TanStack Router (routeTree.gen.ts), and Base UI components. Biome replaces ESLint + Prettier for TypeScript linting and formatting. MeiliSearch powers product search with typo tolerance and faceting. Docker Compose with health checks defines the full local and CI environment, and npx create-spree-app bootstraps the entire stack in one command.

Code Quality The Ruby codebase has extensive RSpec coverage organized by domain — models, services, controllers, serializers, subscribers, and presenters each have dedicated spec directories. The core Order model spec alone runs nearly 2,900 lines. Service objects use ApplicationRecord.transaction with failure/success result types, giving clear, typed error paths rather than exception-driven control flow. The TypeScript packages use Vitest with a test suite per package, and Biome CI runs on every push with --changed --since=main to enforce consistency across the branch diff. The pre-commit hook’s automatic type regeneration from serializers means the TypeScript contract can never silently drift from the Ruby API response. Codecov integration tracks coverage across both Ruby and TypeScript.

What Makes It Unique Spree’s most distinctive technical choice is the serializer-driven type generation pipeline: Ruby API serializers are the single source of truth, and Zod schemas plus TypeScript types in @spree/sdk are regenerated automatically on every serializer change via a lefthook hook. This eliminates the category of bugs where frontend types diverge from backend responses. The platform also ships first-class agentic development infrastructure — a docs MCP server, 25 installable agent skills teaching coding agents Spree’s conventions, and auto-generated AGENTS.md/CLAUDE.md — treating AI-assisted development as a core product feature rather than an afterthought. The configurable order state machine with checkout_flow block DSL lets non-framework developers define custom fulfillment pipelines declaratively, and the defined?(SpreeEnterprise) conditional-inclusion pattern allows Enterprise Edition modules to extend Core without a single line of monkey-patching.

Self-Hosting

Spree Commerce is released under the BSD 3-Clause license, one of the most permissive open-source licenses available. You are free to use, modify, and distribute Spree for any purpose — commercial or otherwise — without paying royalties or releasing your own application code under the same terms. The only obligations are retaining the copyright notice and license text in redistributions and not using the Spree name to endorse derived products without permission. This means you can build a fully proprietary storefront, marketplace, or SaaS product on top of Spree Core without any copyleft implications for your own code.

Running Spree yourself requires meaningful infrastructure: a Ruby on Rails application server (Puma), PostgreSQL, Redis for background jobs, and optionally MeiliSearch for product search — all orchestrated via Docker Compose in the standard setup. The npx create-spree-app scaffold and Spree CLI reduce day-zero friction considerably, but ongoing operations mean your team is responsible for database backups, SSL termination, zero-downtime deploys, scaling worker processes under load, and applying security patches. Render’s one-click deploy and Heroku are documented options for small stores; larger deployments typically run on Kubernetes or managed container platforms. The codebase is actively maintained with security advisories and patches issued for all supported minor versions, so staying current on patches is realistic but not automatic.

The open-source Core covers the REST API, TypeScript SDK, Next.js storefront, cross-border Markets, B2B price lists, promotions, digital products, webhooks, and native payment integrations with Stripe, Adyen, and PayPal. The paid Enterprise Edition, offered by Vendo (the company behind Spree), layers on multi-tenant SaaS infrastructure, advanced multi-vendor marketplace automation (Shopify/WooCommerce sync, Stripe Connect automated payouts), B2B buyer organizations with ERP connectors and approval workflows, SSO (SAML/OIDC), encryption at rest, audit logging, and PCI-compliant architecture. Enterprise also provides a dedicated success manager, guaranteed response-time SLAs, long-term support releases, and 24/7 monitoring — operational assurances you must build yourself on the open-source edition.