​
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:
AttributeDescriptionExample Value
nameThe public name of the stock location. This is used on Storefront and Storefront APIWarehouse 1
admin_nameThe name used internally for the stock location. This is not shown on the Storefront.WH1 Domestic
address1The primary address line for the stock location.5th avenue
address2The secondary address line for the stock location.Suite 100
cityThe city where the stock location is based.New York
state_idThe ID of the state where the stock location is based. This references the State model.1
country_idThe ID of the country where the stock location is based. This references the Country model.1
zipcodeThe postal code for the stock location.10001
phoneThe contact phone number for the stock location.555-1234
activeA 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
defaultA boolean indicating whether the stock location is the default one used for new inventory operations.false
backorderable_defaultA boolean indicating whether new stock items in this location are backorderable by default.false
propagate_all_variantsA 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.
AttributeDescriptionExample Value
stock_location_idReferences the stock location where the stock item belongs.1
variant_idReferences the variant associated with the stock item.32
count_on_handThe number of items available on hand.150
backorderableIndicates 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:
AttributeDescriptionExample Value
numberThe unique number identifier for the stock transfer, generated automatically.T123456789
referenceAn optional reference field for the stock transfer.Transfer for Event
source_location_idThe ID of the stock location where the stock is transferred from.2
destination_location_idThe 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:
AttributeDescriptionExample Value
stock_item_idReferences the stock item that the movement belongs to.45
quantityThe 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_typeThe type of the originator of the stock movement. This is a polymorphic association.Spree::Shipment
originator_idThe 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:
AttributeDescriptionExample Value
variant_idReferences the variant associated with the inventory unit.32
order_idReferences the order associated with the inventory unit.123
shipment_idReferences the shipment associated with the inventory unit.77
stateThe state of the inventory uniton_hand
Inventory Units states are:
  • on_hand - the inventory unit is on hand
  • backordered - the inventory unit is backordered
  • shipped - 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: 
Spree::Config[:track_inventory_levels] = false
You can also disable tracking inventory on a Variant level, by simply updating Variant track_inventory column to false, eg. 
variant.update(track_inventory: false)
This can also be done via the Admin Panel or Platform API.