Guides

Chapters

1. Overview
2. Design and functionality
   • Relevant settings
   • What the customer sees
   • What the orders administrator sees
3. Site Customizations
   • Programming interface
   • More sophisticated inventory management
   • Useful extensions

1 Overview

Inventory is being modeled in a fairly new and innovative way. This approach was suggested by some of the commerce gurus at End Point. Since the goal was for Spree to be suitable for simple and sophisticated applications alike, the real challenge was implementing these ideas in a way that was as transparent as possible to the user (should the user choose not to use this level of sophistication.)

Basically the idea is to have one record per unit of inventory that you have available for sale. Each Inventory item has one of these possible states: on hand, sold, shipped or back-ordered. The inventory state changes through out the process in the way you would probably expect.

Why do we bother with all of these records in our database? Won’t that mean millions of records in the database if we have millions of items in our inventory? The answer is yes. But if you think about it, if you have that much inventory, your application needs go way beyond a simple quantity field in a database. You’ll need something more powerful.

There are several advantages to this approach. The first is that it allows you very fine grained control over inventory. You can easily expand upon this model to track the location of items in a warehouse, or even which warehouse the item is located in. You can also track serial number information or other information (perhaps RFID) that is unit specific.

What if you don’t need to track inventory? We have come up with a design that basically shields the simple store user from much of this complexity. Simply leave the inventory fields blank and you never have to worry about it. You can also create new products in the system and give them a starting “on hand” inventory level which will create the necessary records. You can subsequently adjust the inventory levels by positive or negative integers and the appropriate number of records will be created or destroyed.

We’ve also done a great deal of improvement with variants. Every line item in an order tracks the exact variant of the product sold. Things work fine even if the product has no meaningful variant information (say you are just selling CD’s and you don’t need to worry about “size”, “color”, etc.) A “master” variant is created behind the scenes and your inventory and SKU information will be associated with this variant. If you do end up using variants though, you now have fine grained control over the SKU and inventory information.

2 Design and functionality

2.1 Relevant settings

Behaviour of the inventory system is governed by these settings:

• show_zero_stock_products – usually, Spree shows products in listings if it has some stock (which means at least one of its variants has stock), and this setting disregards the result of that test and so allows such products’ details to be viewed.

• allow_backorders – similarly, Spree usually only accepts orders for a variant if there is some stock, and this setting overrides that condition. The default behaviour, when the setting is false and there is no stock in any variant, is to show an “Out of stock” message; or when just some of the variants are unavailable, to disable the relevant radio buttons.

One other flag is relevant:

• allow_backorder_shipping – allows inventory in the backorder state to be marked as shipped. You may need to do this in certain cases, eg if your backorders are handled by a 3rd party fulfilment house and they have agreed to ship an item once stock is available again.

2.2 What the customer sees

Generally, the settings above are the most significant. Customizations can also access details of stock levels for each variant via the on_hand method, e.g. to show the current level on the cart page.

2.3 What the orders administrator sees

As mentioned above, the admin interface hides some of the complexity of the full system. When adding or editing a variants of a product, the merchant can set or alter the stock level for that variant through a single number. If the product has no variants (rather, it has an “empty” variant which Spree doesn’t show explicitly), then this stock level can be set on the product details page.

3 Site Customizations

3.1 Programming interface

Here’s a summary of methods you might use in a customization (v is a variant, p is a product):

• v.on_hand – returns how many inventory items a variant has with the “on_hand” state

• v.in_stock? – returns true if at least one item is “on_hand”

• p.has_stock? – returns true if any variant of the product is “on_hand”

3.2 More sophisticated inventory management

It’s straightforward to add new fields to inventory units, eg to record a unit’s location or some tracking information

3.3 Useful extensions

There are a few Spree extensions which provide XYZ

See the Spree Extension Registry for the latest information.