Overview
Each Variant has a StockItem that tracks its inventory at a specific location. A variant can have multiple stock items if it’s available at multiple stock locations.
When products are sold or returned, individual InventoryUnit records track each unit through the fulfillment process.
Adding new inventory to an out-of-stock product that has backorders will first fill the backorders, then update the available count with the remainder.
Inventory Model Diagram
Key relationships:
- Stock Location → Contains Stock Items (inventory per variant) and is the source/destination for Stock Transfers
- Stock Item → Tracks quantity (
count_on_hand) for a specific Variant at a specific Stock Location
- Stock Movement → Records changes to Stock Item quantities (purchases, returns, transfers)
- Stock Transfer → Moves inventory between Stock Locations, creating Stock Movements at source and destination
- Inventory Unit → Represents individual units in Orders and Shipments
Inventory Management
Stock Locations
Stock Locations are the physical locations where your inventory is stored and shipped from.
Stock Locations can be created in the Admin Panel under Settings → Stock Locations, or via the Admin API.
Stock Locations have several attributes that define their properties and behavior within the Spree system. Below is a table outlining these attributes:
| Attribute | Description | Example Value |
|---|
name | The public name of the stock location. This is returned in Store API | Warehouse 1 |
admin_name | The name used internally for the stock location. This is only returned in Admin API. | WH1 Domestic |
address1 | The primary address line for the stock location. | 5th avenue |
address2 | The secondary address line for the stock location. | Suite 100 |
city | The city where the stock location is based. | New York |
state_id | The ID of the state where the stock location is based. This references the State model. | 1 |
country_id | The ID of the country where the stock location is based. This references the Country model. | 1 |
zipcode | The postal code for the stock location. | 10001 |
phone | The contact phone number for the stock location. | 555-1234 |
active | A boolean indicating whether the stock location is active. Inactive stock locations will not be used in stock calculations or be available for selection during checkout. | true |
default | A boolean indicating whether the stock location is the default one used for new inventory operations. | false |
backorderable_default | A boolean indicating whether new stock items in this location are backorderable by default. | false |
propagate_all_variants | A boolean indicating whether new stock items should be automatically created for all Store variants when a new stock location is added. | false |
Stock Items
Stock Items represent the inventory at a stock location for a specific variant. Stock item count on hand can be increased or decreased by creating stock movements.
| Attribute | Description | Example Value |
|---|
stock_location_id | References the stock location where the stock item belongs. | 1 |
variant_id | References the variant associated with the stock item. | 32 |
count_on_hand | The number of items available on hand. | 150 |
backorderable | Indicates whether the stock item can be backordered. | true |
Stock Transfers
Stock transfers allow you to move inventory in bulk from one stock location to another stock location. This is handy when you want to integrate with a POS system or other inventory management system. Or you can just rely on Spree being the source of truth for your inventory.
Stock Transfers can be created in the Admin dashboard or via the Admin API.
| Attribute | Description | Example Value |
|---|
number | The unique number identifier for the stock transfer, generated automatically. | T123456789 |
reference | An optional reference field for the stock transfer. | Transfer for Event |
source_location_id | The ID of the stock location where the stock is transferred from. | 2 |
destination_location_id | The ID of the stock location where the stock is transferred to. | 3 |
Stock Movements
Stock Movements track the movement of the inventory:
- when you move inventory between stock locations (via Stock Transfer)
- when you add inventory to a stock location
- when you remove inventory from a stock location
- when customers purchase products
- when customers return products
Here’s the list of attributes for the Stock Movement model:
| Attribute | Description | Example Value |
|---|
stock_item_id | References the stock item that the movement belongs to. | 45 |
quantity | The quantity by which the stock item’s count on hand is changed. Positive values indicate stock being added, while negative values indicate stock being removed. | -10 |
originator_type | The type of the originator of the stock movement. This is a polymorphic association. | Spree::Shipment |
originator_id | The ID of the originator of the stock movement. This is used in conjunction with originator_type. | 2 |
Inventory Units
As we mentioned above, back-ordered, sold, or shipped products are stored as individual InventoryUnit objects so they can have relevant information attached to them.
We create InventoryUnit objects when:
- a product is sold (they are added to the Shipment)
- a product is returned
Here’s a list of attributes for the Inventory Unit model:
| Attribute | Description | Example Value |
|---|
variant_id | References the variant associated with the inventory unit. | 32 |
order_id | References the order associated with the inventory unit. | 123 |
shipment_id | References the shipment associated with the inventory unit. | 77 |
state | The state of the inventory unit | on_hand |
on_hand - the inventory unit is on handbackordered - the inventory unit is backorderedshipped - the inventory unit is shipped
As we noted before, when you add new Stock Items to a Variant (eg. via Admin Panel or Admin API), the first Inventory Units to fulfill are the backordered ones.
Disabling Inventory Tracking
If you don’t need to track inventory, you can disable it:
- Per variant — set
track_inventory to false on a specific variant via the Admin Panel or Admin API
- Globally — disable inventory tracking for the entire store in your Spree configuration
- Products - Product and variant management
- Shipments - How inventory relates to shipments
- Orders - How inventory is allocated to orders
