first draft

Author: Jo

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/managing-inventory.mdx

@@ -0,0 +1,12 @@
+Managing inventory involves a variety of tasks aimed at 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/multi-location.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, distribution center. You may want a virtual inventory location, for example, for promotions. You may want to collect all the products in the promotion virtually in one place within your system, to ensure that promotional stock is reserved and accurately tracked.
+
+In the Inventories API, you can create an inventory location. You can create individual inventory locations, either for a single physical site or for multiple distinct locations.
+
+When creating an inventory location, there are several details, you need to consider the location's details, 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.
+
+In addition, you can import your locations from another company system. See Importing locations.
+
+
+

docs/partials/inventory/multi-location/creating-locations.mdx

@@ -1,6 +1,11 @@
-The Inventory API allows you to manage stock for products at both organization and store levels.
+Using Inventories allows you to track stock inventory for products in Elastic Path Composable Commerce at both organization and store levels.
 
-Inventory is the quantity of each product that you have in stock. The inventory service allows you and your business to keep track of inventory, optionally at different locations, and including a transactional historic log.
+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 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?
 

docs/partials/inventory/multi-location/managing-locations.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 in Inventories.
+
+## Types of Transactions
+
+In Inventories, 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 when you want to set stock in Elastic Path Composable Commerce from an external warehousing system.

docs/partials/inventory/multi-location/overview.mdx

@@ -0,0 +1,36 @@
+### Order flow
+
+There are three mandatory steps to complete an order in relation to inventory:
+
+1. Added to a cart
+2. Checked out
+3. Paid
+4. Shipped (optional)
+
+#### Unpaid order flow
+
+The following flowchart depicts the process of an unpaid order.
+
+![The order is created from the cart during the checkout process.](/assets/order-flow.png)
+
+#### Payment flow
+
+The following flowchart depicts the process of paying for an order.
+
+![The payment workflow.](/assets/payment-workflow-1.png)
+
+### How stock is managed
+
+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.
+
+If the payment fails, the temporary stock allocation is removed, and the stock becomes available again for anyone to buy.
+
+If 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.
+5. 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.
+
+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.