DB-1138 - Inventory key concepts

docs/partials/inventory/characteristics.mdx

@@ -0,0 +1,7 @@
+Inventories has the following characteristics:
+
+- It is possible for more products to be in carts than there are in stock if the add to cart request quantity is less than available stocks. For example, when available stocks are 100, a user can add 60 to cart 1 and then 50 to cart 1, or user A can add 80 to cart 1, while user B can add 30 to cart 2.
+- It is possible for more products to be checked out than there are in stock if the add to cart request quantity is less than the available stocks.
+- It is not possible for more stock to be paid for than is in stock.
+- It is a race for your customers to pay for an order, and whoever does not pay fast enough, is left disappointed.
+

docs/partials/inventory/managinginventory.mdx

@@ -0,0 +1,12 @@
+Managing inventory involves ensuring that stock levels are optimized, products are stored correctly, and supply meets demand, efficiently.
+
+Using Inventories, you can:
+
+- identify the source of a stock position.
+- explicitly set stock for your locations.
+- change stock.
+- move stock between locations automatically. Stock positions can be updated in near real-time using batch updates.
+- see if there are failures when updating stock positions.
+- disable or enable locations.
+
+

docs/partials/inventory/multilocation.mdx

@@ -0,0 +1,14 @@
+Inventories allows you to optionally manage stock across multiple locations, giving you better control over your inventory and improving stock accuracy.
+
+By offering localized stock information and flexible order fulfilment options, you can enhance your customer's shopping experience. For example, you can use multi-location inventory to support the **Buy Online, Pick Up In-Store** process. Tagging inventory with specific locations, allows you to select a designated location for dispatch when adding stock to a product, ensuring that inventory is accurately tracked and readily available for in-store pickup orders. Multi-location inventory optimizes your fulfillment process by aligning stock with the most appropriate physical locations, improving efficiency and boosting customer satisfaction.
+
+An inventory location is a specific physical or virtual place where stock or inventory is stored, tracked, and managed. Your inventory locations could refer to a warehouse, retail store, or distribution center. You may want a virtual inventory location, for example, for promotions. You may want to collect all the products in a promotion virtually in one place within your system, to ensure that promotional stock is reserved and accurately tracked.
+
+When creating an inventory location, there are several details you need to consider including name, description, and GPS location. In addition, you can specify an `external_ref` which is a unique attribute that you could use to contain information from an external warehouse system, for example.
+
+You can create individual inventory locations, either for a single physical site or for multiple distinct locations.
+
+In addition, you can import your locations from another company system. See Importing locations.
+
+
+

docs/partials/inventory/overview.mdx

@@ -0,0 +1,18 @@
+Using Inventories allows you to track stock inventory for products in Elastic Path Composable Commerce at both organization and store level.
+
+Inventory is the quantity of each product that you have in stock. The inventory service allows you and your business to track inventory, with a transactional historic log, and optionally, manage stock across multiple locations.
+
+You can manage inventory using both:
+
+- the [Inventories API](/docs/api/pxm/inventory)
+- [Commerce Manager](/docs/commerce-manager/product-experience-manager/Products/manage-product-inventory)
+
+### What is Inventory?
+
+Inventory for each product is tracked using the following values:
+
+- **Total**: The amount of product in stock. This can be expressed by the following equation: Total = Available + Allocated
+- **Available**: The amount of product available in stock minus allocated products. This can be expressed by the following equation: Available = Total - Allocated.
+- **Allocated**: The amount of reserved product in stock.
+- **Location**: The location of the stock. For each location, this can be expressed by the following equation: Total = Available + Allocated. One or more locations contributes to an aggregated stock total.
+

docs/partials/inventory/paidorder.mdx

@@ -0,0 +1,16 @@
+The following flowchart shows the process for paying for an order.
+
+![The payment workflow.](/assets/payment-workflow-1.png)
+
+Stock is managed as follows:
+
+1. When a customer attempts to add products to a cart, the inventory service checks if there is enough available stock. If there is not enough stock available, you receive a 400 HTTP response with a warning. The response does not describe what products cannot be added, nor does it return how many products are in stock.
+2. If a customer successfully adds products to a cart, the customer can checkout to create an unpaid order.
+3. A final check on the available stock is performed.
+4. After creating the unpaid order, the payment for an order can be taken. When a customer attempts to pay for an order, the inventory service reserves the stock before the payment is processed internally. At any time before the point of payment, a customer might lose their order, if the customer is slower than everyone else.
+5. When the payment succeeds, that stock is still allocated, and the items belong to the customer, unless for any reason they are reallocated before shipment. For example, if the customer cancels, or you realize the order is fraudulent, then you can reallocate the inventory.
+
+    During split payments, stocks are allocated only if the first transaction for an order is complete. If the transaction fails, the stocks are deallocated. Once the first transaction is complete, the stocks are not allocated for the subsequent transactions as they are already reserved for the order. The stocks are deallocated and return to available when the the order is canceled.
+
+6. Finally, when the order is marked as shipped, that stock is fully decremented. This means the allocation number is reduced, and therefore the total, and the products are no longer in the warehouse.
+

docs/partials/inventory/transactions.mdx

@@ -0,0 +1,13 @@
+The way you track stock levels in Inventories is through transactions. Inventories maintains a transactional historic log. This is a detailed, chronological record of all transactions that have affected inventory levels within a system over time. It serves as an audit trail, ensuring transparency and accountability.
+
+## Types of Transactions
+
+Stock levels are adjusted or updated through transactions. In other words, you manage stock levels by recording transactions that increase or decrease inventory. For example, increase this stock level by 10 units using the **increment** transaction.
+
+Inventories has the following transaction types:
+
+- **increment** - use this when you want to make products available for purchase, for example, when you have received stock from a supplier.
+- **decrement** - use this when you want to remove stock from product inventory.
+- **allocate** - use this when you want to allocate stock, normally to a reseller who sells on the stock.
+- **deallocate** - use this when you want to deallocate any previously allocated stock.
+- **set** - use this to explicitly set your stock.

docs/partials/inventory/unpaidorder.mdx

@@ -0,0 +1,15 @@
+
+The following flowchart shows the process for an unpaid order.
+
+![The order is created from the cart during the checkout process.](/assets/unpaidorder.png)
+
+Stock is managed as follows:
+
+1. When a customer attempts to add products to a cart, the inventory service checks if there is enough available stock. If there is not enough stock available, you receive a 400 HTTP response with a warning. The response does not describe what products cannot be added, nor does it return how many products are in stock.
+1. If a customer successfully adds products to a cart, the customer can optionally choose the location of the stock (if this order is for collection).
+1. The inventory service checks if there is enough available stock at the location.
+1. If there is enough stock available at the location, then the customer can checkout to create an unpaid order.
+1. A final check on the available stock is performed.
+1. After creating the unpaid order, the payment for an order can be taken. When a customer attempts to pay for an order, the inventory service reserves the stock before the payment is processed internally. At any time before the point of payment, a customer might lose their order, if the customer is slower than everyone else.
+1. If the payment fails, the temporary stock allocation is removed, and the stock becomes available again for anyone to buy.
+

docs/partials/inventory/workflow.mdx

@@ -0,0 +1,9 @@
+Inventory transactions refer to the various actions that take place to adjust stock levels, such as receiving, storing, or shipping goods. Inventory transactions are tied to orders as each step of an order triggers changes in inventory levels.
+
+When processing an order, there are three mandatory inventory-related steps that must be completed.
+
+1. Adding a product to a cart.
+1. (*Optional*) Choosing a location
+1. Checking out a cart.
+1. Paying for an order.
+1. (*Optional*) Shipping an order.

guides/key-concepts/inventory/_category_.json

@@ -0,0 +1,5 @@
+{
+  "position": 3,
+  "label": "Inventory",
+  "collapsible": true
+}

guides/key-concepts/inventory/characteristcs.mdx

@@ -0,0 +1,9 @@
+---
+title: Inventory Characteristics
+nav_label: Inventory Characteristics
+sidebar_position: 30
+---
+
+import CharacteristicsOverview from "/docs/partials/inventory/characteristics.mdx";
+
+<CharacteristicsOverview></CharacteristicsOverview>

guides/key-concepts/inventory/managinginventory.mdx

@@ -0,0 +1,9 @@
+---
+title: Managing Inventory
+nav_label: Managing Inventory
+sidebar_position: 15
+---
+
+import ManagingInventory from "/docs/partials/inventory/managinginventory.mdx";
+
+<ManagingInventory></ManagingInventory>

guides/key-concepts/inventory/multilocation.mdx

@@ -0,0 +1,9 @@
+---
+title: Multi-Location Inventory
+nav_label: Overview
+sidebar_position: 10
+---
+
+import LocationOverview from "/docs/partials/inventory/multilocation.mdx";
+
+<LocationOverview></LocationOverview>

guides/key-concepts/inventory/overview.mdx

@@ -0,0 +1,9 @@
+---
+title: Overview
+nav_label: Overview
+sidebar_position: 5
+---
+
+import InventoryOverview from "/docs/partials/inventory/overview.mdx";
+
+<InventoryOverview></InventoryOverview>

guides/key-concepts/inventory/transactions.mdx

@@ -0,0 +1,9 @@
+---
+title: Inventory Transactions
+nav_label: Inventory Transactions
+sidebar_position: 20
+---
+
+import TransactionsOverview from "/docs/partials/inventory/transactions.mdx";
+
+<TransactionsOverview></TransactionsOverview>

guides/key-concepts/inventory/workflow/_category_.json

@@ -0,0 +1,5 @@
+{
+  "position": 25,
+  "label": "Inventory Workflow",
+  "collapsible": true
+}

guides/key-concepts/inventory/workflow/paidorder.mdx

@@ -0,0 +1,9 @@
+---
+title: Paid Order Flow
+nav_label: Paid Order Flow
+sidebar_position: 15
+---
+
+import PaidOrder from "/docs/partials/inventory/paidorder.mdx";
+
+<PaidOrder></PaidOrder>

guides/key-concepts/inventory/workflow/unpaidorder.mdx

@@ -0,0 +1,11 @@
+---
+title: Unpaid Order Flow
+nav_label: Unpaid Order Flow
+sidebar_position: 10
+---
+
+import UnpaidOrder from "/docs/partials/inventory/unpaidorder.mdx";
+
+<UnpaidOrder></UnpaidOrder>
+
+Once payment is completed, the order transitions to a [paid order](/guides/key-concepts/inventory/workflow/paidorder), allowing further processing, such as fulfillment or shipping.

guides/key-concepts/inventory/workflow/workflow.mdx

@@ -0,0 +1,11 @@
+---
+title: Inventory Workflow
+nav_label: Inventory Workflow
+sidebar_position: 5
+---
+
+import InventoryWorkflow from "/docs/partials/inventory/workflow.mdx";
+
+<InventoryWorkflow></InventoryWorkflow>
+
+The order service first creates an [unpaid order](/guides/key-concepts/inventory/workflow/unpaidorder), which records the order details and holds the items. Once payment is completed, the order transitions to a [paid order](/guides/key-concepts/inventory/workflow/paidorder), allowing further processing, such as fulfillment or shipping.