From 6b01a6800a68645f7928b3f087f29117c9750ebe Mon Sep 17 00:00:00 2001 From: Benjamin Willems Date: Tue, 30 Jan 2018 01:49:05 -0800 Subject: [PATCH 1/2] Add documentation for stock items and movements This commit adds two articles: "Stock items" and "Stock movements". Stock locations documentation will be merged as part of another pull request (in the inventory overview article). --- guides/inventory/stock-items.md | 48 ++++++++++++++++++++++++ guides/inventory/stock-movements.md | 58 +++++++++++++++++++++++++++++ 2 files changed, 106 insertions(+) create mode 100644 guides/inventory/stock-items.md create mode 100644 guides/inventory/stock-movements.md diff --git a/guides/inventory/stock-items.md b/guides/inventory/stock-items.md new file mode 100644 index 00000000000..c6c185d24af --- /dev/null +++ b/guides/inventory/stock-items.md @@ -0,0 +1,48 @@ +# Stock items + +On-hand inventory is tracked using the `Spree::StockItem` model. Each +`Spree::Variant` in a store has a corresponding `Spree::StockItem` object with a +`count_on_hand` value that represents the number of items you have in stock. + +`Spree::StockItem` objects have the following attributes: + +- `stock_location_id`: The ID for the `Spree::StockLocation` where the stock + item is located. +- `variant_id`: The ID for the `Spree::Variant` that this stock item represents. +- `count_on_hand`: The number of units currently in inventory. See [Count on + hand](#count-on-hand) for more information. +- `backorderable`: Sets whether the stock item should be + [backorderable](#backorderable-stock-items). +- `deleted_at`: A timestamp that logs when this stock item was deleted from + inventory. Otherwise, the value is `nil`. + +## Count on hand + +When administrators create a new product using the `solidus_backend`, they can +set an initial inventory "Count On Hand" value for the new product. + +The `count_on_hand` value changes whenever a [stock movement][stock-movements] +occurs. For example, if one unit of a product is sold the `count_on_hand` would +decrease by one. + +### Changing the count on hand value + +While a `Spree::StockMovement` object logs the increase or decrease of the +`count_on_hand` value, administrators can also edit the count on hand from the +`solidus_backend`. + +Whenever an administrator updates the count on hand, they are discarding the old +value completely. So, if a stock item is +[backorderable](#backorderable-stock-items) and its `count_on_hand` is `-5`, +when the administrator changes the value to `20`, they are creating a +`Spree::StockMovement` with a value of `25`. + +See the [Stock movements][stock-movements] article for more information. + +[stock-movements]: stock-movements.md + +## Backorderable stock items + +If a `Spree::StockItem` is `backorderable`, then customers can continue to order +it after the product is sold out. When a sold out product continues to sell, the +`count_on_hand` would become a negative integer. diff --git a/guides/inventory/stock-movements.md b/guides/inventory/stock-movements.md new file mode 100644 index 00000000000..bb6def1a648 --- /dev/null +++ b/guides/inventory/stock-movements.md @@ -0,0 +1,58 @@ +# Stock movements + +A `Spree::StockMovement` object is created every time that a stock item moves in +or out of a stock location. This objects documents how many items were added or +removed. + +The `Spree::StockMovement` model has the following attributes: + +- `stock_item_id`: The ID of the `Spree::StockItem` the movement is related to. +- `quantity`: The amount of stock items added or removed from the + `Spree::StockItem`'s `count_on_hand` value. +- `originator_type` and `originator_id`: The model and ID of an object that + initiated the creation of the current stock movement. For example, an + originator could be an administrator (a `Spree::User`) adding new stock or a + `Spree::Shipment` being created after an order is placed. + + + +## Usage example + +A typical example of a stock movement would be when a customer buys an item from +your store: + +1. A stock item has a `count_on_hand` value of `20`. +2. A customer buys one unit of its associated variant. +3. A new `Spree::StockMovement` object is created. + - It has a `quantity` of `-1`. + - It has a `originator_type` of `Spree::Shipment` because a new shipment + triggered the movement. +4. The stock item's `count_on_hand` value is updated to `19`. + +## Administrating inventory + +Administrators can generate stock movements by changing the "Count On Hand" +value for a stock item in the `solidus_backend` (on the **Stock** page). +However, they cannot create a stock movement directly. + +Because of this, Solidus has no concept of *adding to* existing inventory. For +example: + +- A stock item has a `count_on_hand` value of `7`. +- A store administrator receives 25 new items to add to inventory. +- They log into the backend and change the count on hand from `7` to `33`. +- This creates a new `Spree::StockMovement` with a quantity of `25`. (`7 + 25 = + 33`.) + +If an administrator does not account for the units already in stock, they may +enter the wrong value into the "Count On Hand" field for an item. + +For example, if the administrator changes the value from `7` to `25`, then the +stock movement only documents that `18` units were added to inventory. (`7 + 18 += 25`.) From 9bc381152d201df16169edfe1e1509335fc5da42 Mon Sep 17 00:00:00 2001 From: Benjamin Willems Date: Wed, 14 Feb 2018 13:33:36 -0800 Subject: [PATCH 2/2] Update stock items article after PR review This clarifies some information about `Spree::StockItem`s after a review by kennyadsl. Specifically, it confirms how many `StockItem`s should exist if there are multiple `StockLocation`s, and it details how backorderable stock items are handled. --- guides/inventory/stock-items.md | 34 +++++++++++++++++++++++++-------- 1 file changed, 26 insertions(+), 8 deletions(-) diff --git a/guides/inventory/stock-items.md b/guides/inventory/stock-items.md index c6c185d24af..b544d5349c1 100644 --- a/guides/inventory/stock-items.md +++ b/guides/inventory/stock-items.md @@ -1,8 +1,15 @@ # Stock items -On-hand inventory is tracked using the `Spree::StockItem` model. Each -`Spree::Variant` in a store has a corresponding `Spree::StockItem` object with a -`count_on_hand` value that represents the number of items you have in stock. +On-hand inventory is tracked using the `Spree::StockItem` model. A stock item +tracks stock at a single `Spree::StockLocation`. + +If you only track stock at one stock location, then every `Spree::Variant` in +your store has one corresponding `Spree::StockItem` object. If you track stock +at two stock locations, then every `Spree::Variant` in your store has *two* +corresponding `Spree::StockItem`s: one for each `Spree::StockLocation`. + +The `Spree::StockItem`'s `count_on_hand` value that represents the number of +items you have in stock. `Spree::StockItem` objects have the following attributes: @@ -32,10 +39,9 @@ While a `Spree::StockMovement` object logs the increase or decrease of the `solidus_backend`. Whenever an administrator updates the count on hand, they are discarding the old -value completely. So, if a stock item is -[backorderable](#backorderable-stock-items) and its `count_on_hand` is `-5`, -when the administrator changes the value to `20`, they are creating a -`Spree::StockMovement` with a value of `25`. +value completely. So, if a stock item's `count_on_hand` is `5`, when the +administrator changes the value to `20`, they are creating a +`Spree::StockMovement` with a value of `15`. See the [Stock movements][stock-movements] article for more information. @@ -45,4 +51,16 @@ See the [Stock movements][stock-movements] article for more information. If a `Spree::StockItem` is `backorderable`, then customers can continue to order it after the product is sold out. When a sold out product continues to sell, the -`count_on_hand` would become a negative integer. +`count_on_hand` becomes a negative integer. + +For example, if a customer orders five backorderable items and its +`count_on_hand` becomes `-5`, the customer can still check out successfully. +[Inventory units][inventory-units] with the `state` value of `backordered` are +created for the five items. + +The `Spree::Shipment`(s) associated with the backordered items cannot be shipped +until the stock has been replenished. Once the item is in stock again, each +backordered inventory unit's `state` value is changed from `backordered` to +`on_hand` and the shipment becomes shippable. + +[inventory-units]: inventory-units.md