Documentation Index
Fetch the complete documentation index at: https://spreecommerce.org/docs/llms.txt
Use this file to discover all available pages before exploring further.
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:- Catalog — Products have Variants (SKUs) with prices and inventory tracked at Stock Locations
- Shopping — Customers add Variants to their cart, creating an Order with Line Items
- Checkout — The Order collects Addresses, calculates Shipping options, and processes Payments
- Fulfillment — Shipments are created from Stock Locations, tracking individual Inventory Units
- 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 under API v3:| API | Purpose | Authentication |
|---|---|---|
| Store API | Customer-facing — cart, checkout, products, account | Publishable API key + JWT |
| Admin API | Operational — manage products, orders, customers, settings | Secret API key |
prod_86Rf07xd4z, or_m3Rp9wXz), flat JSON request/response structures, and full TypeScript types via the @spree/sdk.
Events from both APIs can trigger Webhooks to notify external systems in real time.
Multi-Store Architecture
Spree supports multiple stores 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
Extension Points
Spree is designed to be customized without modifying core code. The main extension mechanisms are:| Mechanism | Use Case | Documentation |
|---|---|---|
| Events & Subscribers | React to order completion, payment, shipment events | Events Guide |
| Webhooks | Notify external systems of changes | Webhooks Guide |
| Dependencies | Swap out services (tax calculation, shipping estimation) | Dependencies Guide |
| Decorators | Modify existing model/controller behavior (use sparingly) | Decorators Guide |
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):| Package | Purpose |
|---|---|
spree | Models, services, business logic, Store API, Admin API, and Webhooks |
| Package | Purpose |
|---|---|
spree_admin | Admin dashboard for managing your store |
spree_emails | Transactional email templates (order confirmation, shipping, etc.) |
| Package | Purpose |
|---|---|
@spree/sdk | TypeScript SDK for Store API and Admin API |
For headless commerce, you only need the
spree package. Build your customer-facing frontend with any technology (Next.js, Nuxt, mobile apps) using the Store API and SDK.Related Documentation
- Products — Product catalog and variants
- Orders — Order lifecycle and state machine
- Payments — Payment processing
- Shipments — Shipping and fulfillment
- Customization Quickstart — How to extend Spree