Skip to main content

​
Overview

Spree is a commerce engine built around interconnected models that represent the core concepts of commerce: products, orders, payments, and shipments. It adapts to your stack — use it as a headless API for any frontend, embed it into an existing application, or scale it from a single storefront to a global multi-vendor marketplace.
Spree supports PostgreSQL, MySQL, and SQLite. PostgreSQL is recommended for production. Learn more about database configuration.

​
Core Commerce Flow

The following diagram shows how the main models interact during a typical customer purchase: How it works:
  1. Catalog — Products have Variants (SKUs) with prices and inventory tracked at Stock Locations
  2. Shopping — Customers add Variants to their cart, creating an Order with Line Items
  3. Checkout — The Order collects Addresses, calculates Shipping options, and processes Payments
  4. Fulfillment — Shipments are created from Stock Locations, tracking individual Inventory Units
  5. Pricing & Adjustments — Taxes and Promotions create Adjustments that modify order totals

​
Core Model Relationships

This diagram shows the key database relationships between Spree’s main models:

​
APIs

Spree exposes two REST APIs: Both APIs share the same list shapes, filtering, querying, and pagination, and offer fully typed TypeScript clients — @spree/sdk for the Store API and @spree/admin-sdk for the Admin API. Events from both APIs can trigger Webhooks to notify external systems in real time.

​
Multi-Store Architecture

Spree supports running multiple storefronts from a single installation. Each Store can have:
  • Its own domain and branding
  • Different currencies and locales
  • Separate product catalogs
  • Independent payment and shipping methods
  • Isolated orders and customers
This makes Spree suitable for multi-brand retailers, international expansion, or B2B/B2C hybrid setups.

​
Extension Points

Spree is designed to be customized without modifying core code. The main extension mechanisms are:
For most customizations, prefer Events and Dependencies over Decorators. They’re easier to maintain and won’t break during upgrades.

​
Packages

Spree is distributed as a set of packages: Core (required): Optional: TypeScript packages: