Inventory
Overview
In Spree each Variant has a StockItem. This is the place where the inventory for that variant is stored. Variant can have multiple StockItems if they are available in multiple StockLocations.
Back-ordered, sold, or shipped products are stored as individual InventoryUnit objects so they can have relevant information attached to them.
New products created in the system can be given a starting “on hand” inventory level. You can subsequently set new inventory levels and the correct things will happen, e.g. adding new on-hand inventory to an out-of-stock product that has some backorders will first fill the backorders then update the product with the remaining inventory count.
Inventory Management
Stock Locations
Stock Locations are the locations where your inventory is shipped from. Each StockLocation has many stock_items and stock_movements.
Stock Locations can be created in the admin panel Configuration → Stock Locations or via Platform 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 used on Storefront and Storefront API | Warehouse 1 |
admin_name | The name used internally for the stock location. This is not shown on the Storefront. | 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 Locations can be easily used for tracking warehouses and other physical locations. They can be used to track separate sections of a warehouse (e.g. aisles, shelves, etc.) or to track different warehouses.
You can easily use them with your Point of Sale (POS) system to track inventory at different locations.
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 Platform API.
Here’s the list of attributes for the Stock Transfer model:
| 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 transfers are crucial for managing inventory across multiple locations, ensuring that stock levels are accurate and up-to-date.
Each Stock Transfer will hold a list of Stock Movements.
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 |
Stock Movements are crucial for maintaining accurate inventory levels and for historical tracking of inventory adjustments.
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 |
Inventory Units states are:
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 Platform API), the first Inventory Units to fulfill are the backordered ones.
Disabling inventory tracking
What if you don’t need to track inventory? You can disable it for the entire application in config/initializers/spree.rb file which was generated during installation. Add the following line:
You can also disable tracking inventory on a Variant level, by simply updating Variant track_inventory column to false, eg.
This can also be done via the Admin Panel or Platform API.