Inventory

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

erDiagram
    StockLocation {
        string name
        string admin_name
        boolean active
        boolean default
        boolean backorderable_default
        boolean propagate_all_variants
    }

    StockItem {
        integer count_on_hand
        boolean backorderable
        integer stock_location_id
        integer variant_id
    }

    StockMovement {
        integer quantity
        string originator_type
        integer originator_id
        integer stock_item_id
    }

    StockTransfer {
        string number
        string reference
        integer source_location_id
        integer destination_location_id
    }

    InventoryUnit {
        string state
        integer variant_id
        integer order_id
        integer shipment_id
    }

    StockLocation ||--o{ StockItem : "has many"
    StockLocation ||--o{ StockTransfer : "source"
    StockLocation ||--o{ StockTransfer : "destination"
    Variant ||--o{ StockItem : "has many"
    Variant ||--o{ InventoryUnit : "has many"
    StockItem ||--o{ StockMovement : "has many"
    StockTransfer ||--o{ StockMovement : "has many"
    Order ||--o{ InventoryUnit : "has many"
    Shipment ||--o{ InventoryUnit : "has many"

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:

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.

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.

Here's the list of attributes for the Stock Transfer model:

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:

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:

Inventory Units states are:

• on_hand - the inventory unit is on hand
• backordered - the inventory unit is backordered
• shipped - the inventory unit is shipped

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

Related Documentation

• Products - Product and variant management
• Shipments - How inventory relates to shipments
• Orders - How inventory is allocated to orders