docs/developer/core-concepts/architecture.mdx
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.
<Info> Spree supports PostgreSQL, MySQL, and SQLite. PostgreSQL is recommended for production. [Learn more about database configuration](/developer/deployment/database). </Info>The following diagram shows how the main models interact during a typical customer purchase:
flowchart TB
subgraph Catalog["Catalog"]
Product --> Variant
Variant --> Price
Variant --> StockItem
StockItem --> StockLocation
end
subgraph Shopping["Shopping"]
User --> Order
Order --> LineItem
LineItem --> Variant
end
subgraph Checkout["Checkout"]
Order --> Address
Order --> Shipment
Order --> Payment
Shipment --> ShippingMethod
Payment --> PaymentMethod
end
subgraph Fulfillment["Fulfillment"]
Shipment --> InventoryUnit
InventoryUnit --> Variant
StockLocation --> Shipment
end
subgraph Pricing["Pricing & Adjustments"]
Order --> Adjustment
LineItem --> Adjustment
Shipment --> Adjustment
TaxRate --> Adjustment
Promotion --> Adjustment
end
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
This diagram shows the key database relationships between Spree's main models:
erDiagram
Store ||--o{ Order : "has many"
Store ||--o{ Product : "has many"
Product ||--o{ Variant : "has many"
Product }o--|| TaxCategory : "belongs to"
Product }o--|| ShippingCategory : "belongs to"
Product }o--o{ Taxon : "categorized by"
Variant ||--o{ Price : "has many"
Variant ||--o{ StockItem : "has many"
Variant ||--o{ LineItem : "has many"
Order ||--o{ LineItem : "has many"
Order ||--o{ Shipment : "has many"
Order ||--o{ Payment : "has many"
Order ||--o{ Adjustment : "has many"
Order }o--|| User : "belongs to"
Order }o--|| Address : "ship address"
Order }o--|| Address : "bill address"
Shipment ||--o{ InventoryUnit : "has many"
Shipment }o--|| StockLocation : "ships from"
Shipment }o--|| ShippingMethod : "via"
Payment }o--|| PaymentMethod : "via"
StockLocation ||--o{ StockItem : "has many"
TaxRate }o--|| TaxCategory : "belongs to"
TaxRate }o--|| Zone : "applies to"
TaxRate ||--o{ Adjustment : "creates"
Promotion ||--o{ Adjustment : "creates"
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 |
Both APIs use prefixed IDs (e.g., 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.
Spree supports multiple stores from a single installation. Each Store can have:
This makes Spree suitable for multi-brand retailers, international expansion, or B2B/B2C hybrid setups.
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 |
Spree is distributed as a set of packages:
Core (required):
| Package | Purpose |
|---|---|
spree | Models, services, business logic, Store API, Admin API, and Webhooks |
Optional:
| Package | Purpose |
|---|---|
spree_admin | Admin dashboard for managing your store |
spree_emails | Transactional email templates (order confirmation, shipping, etc.) |
TypeScript packages:
| Package | Purpose |
|---|---|
@spree/sdk | TypeScript SDK for Store API and Admin API |