Overview
Spree is built around a set of interconnected models that represent the core concepts of e-commerce: products, orders, payments, and shipments. Understanding how these pieces fit together is essential for customizing and extending Spree.
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:
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
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:
| 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.
Code Conventions
Spree is built on Ruby on Rails and follows Model-View-Controller (MVC) architecture. All Spree code is namespaced under Spree:: to avoid conflicts with your application code.
Example: Product
| Component | Location | Class Name |
|---|
| Model | core/app/models/spree/product.rb | Spree::Product |
| Admin Controller | admin/app/controllers/spree/admin/products_controller.rb | Spree::Admin::ProductsController |
| API Serializer | api/app/serializers/spree/v2/storefront/product_serializer.rb | Spree::V2::Storefront::ProductSerializer |
Packages
Spree is distributed as a set of Ruby gems (packages). Most users run Spree in headless mode with a custom frontend built using the Storefront API or Platform API.
Core packages (required):
| Package | Purpose |
|---|
spree_core | Models, services, and business logic |
spree_api | Storefront API, Platform API, and Webhooks |
| Package | Purpose |
|---|
spree_admin | Admin dashboard for managing your store |
spree_cli | CLI tool to interact with your Spree installation |
spree_storefront | Pre-built Rails storefront (not needed for headless setups) |
spree_emails | Transactional email templates (order confirmation, shipping, etc.) |
spree_page_builder | Visual page builder for the Rails storefront |
spree_sample | Sample data (products, categories, etc.) for development and testing |
spree_dev_tools | Development and testing utilities for Spree applications and extensions |
For headless commerce, you only need spree_core and spree_api. Build your customer-facing frontend with any technology (Next.js, Nuxt, mobile apps) using the Storefront API.
