docs: add documentation for v1.8 (#3669)
This commit is contained in:
Shahed Nasser
@@ -0,0 +1,87 @@
|
||||
---
|
||||
description: "In this document, you’ll learn how to install multi-warehouse related modules using NPM in the Medusa backend."
|
||||
---
|
||||
|
||||
# Install Multi-Warehouse Modules
|
||||
|
||||
In this document, you’ll learn how to install multi-warehouse related modules using NPM in the Medusa backend.
|
||||
|
||||
:::tip
|
||||
|
||||
You can also install these modules in any NPM project.
|
||||
|
||||
:::
|
||||
|
||||
## Inventory Module
|
||||
|
||||
### Step 1: Install Inventory Module
|
||||
|
||||
To install the Inventory Module, run the following command in the root directory of the Medusa backend:
|
||||
|
||||
```bash npm2yarn
|
||||
npm install @medusajs/inventory
|
||||
```
|
||||
|
||||
### Step 2: Add Inventory Module to Configurations
|
||||
|
||||
In `medusa-config.js`, add the inventory module to the exported object under the `modules` property:
|
||||
|
||||
```js
|
||||
module.exports = {
|
||||
// ...
|
||||
modules: {
|
||||
// ...
|
||||
inventoryService: {
|
||||
resolve: "@medusajs/inventory",
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### Step 3: Run Migrations of Inventory Module
|
||||
|
||||
Run the following command to reflect schema changes into your database:
|
||||
|
||||
```bash
|
||||
medusa migrations run
|
||||
```
|
||||
|
||||
You can now start the Medusa backend and use the inventory module in your commerce application.
|
||||
|
||||
---
|
||||
|
||||
## Stock Location Module
|
||||
|
||||
### Step 1: Install Stock Location Module
|
||||
|
||||
To install the Stock Location Module, run the following command in the root directory of the Medusa backend:
|
||||
|
||||
```bash npm2yarn
|
||||
npm install @medusajs/stock-location
|
||||
```
|
||||
|
||||
### Step 2: Add Stock Location Module to Configurations
|
||||
|
||||
In `medusa-config.js`, add the stock location module to the exported object under the `modules` property:
|
||||
|
||||
```js
|
||||
module.exports = {
|
||||
// ...
|
||||
modules: {
|
||||
// ...
|
||||
stockLocationService: {
|
||||
resolve: "@medusajs/stock-location",
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### Step 3: Run Migrations of Stock Location Module
|
||||
|
||||
Run the following command to reflect schema changes into your database:
|
||||
|
||||
```bash
|
||||
medusa migrations run
|
||||
```
|
||||
|
||||
You can now start the Medusa backend and use the stock location module in your commerce application.
|
||||
@@ -0,0 +1,102 @@
|
||||
---
|
||||
description: "In this document, you’ll learn about the inventory module, how it works, and its relation to other processes in your commerce application."
|
||||
---
|
||||
|
||||
# Inventory Module
|
||||
|
||||
In this document, you’ll learn about the inventory module and how it works.
|
||||
|
||||
## Overview
|
||||
|
||||
The inventory module includes all functionalities related to product inventory. It implements inventory management for a product, confirming whether a product is available across inventory levels, and updating the inventory availability of a product variant at different points in the order lifecycle.
|
||||
|
||||
Medusa's Inventory module is a standalone module that can be used in any commerce application, not just in a Medusa backend. This document gives a general overview of how the inventory module is designed, then explains how the Medusa core orchestrates relations and processes around this module when it's used with the Medusa backend.
|
||||
|
||||
---
|
||||
|
||||
## Entities Overview
|
||||
|
||||
|
||||
|
||||
### InventoryItem
|
||||
|
||||
The `InventoryItem` entity represents a stock-kept item. It holds inventory details, such as `origin_country` or `hs_code`. It's not associated with any entity that represents a stock-kept item, enabling you to choose how you integrate it with your existing commerce application.
|
||||
|
||||
The `InventoryItem` entity doesn’t hold data regarding where the item is stored or its available quantity. This data is stored in the `InventoryLevel` entity.
|
||||
|
||||
### InventoryLevel
|
||||
|
||||
The `InventoryLevel` entity represents the quantity of an inventory item in a stock location. This ensures that an inventory item can be located in multiple stock locations.
|
||||
|
||||
Among the `InventoryLevel` entity’s attributes, the following provide insights into the available quantity within that entity:
|
||||
|
||||
- `stocked_quantity`: a number indicating the available stock of that item in the associated location.
|
||||
- `reserved_quantity`: a number indicating the quantity that should be reserved from the available `stocked_quantity`. It can be used to indicate a quantity that is still not removed from stock, but should be considered as unavailable which confirming that an item is in stock.
|
||||
- `incoming_quantity`: a number indicating an incoming stock quantity of the item into the associated location. This attribute doesn't play into the `stocked_quantity` or when confirming whether a stock-kept item is in stock.
|
||||
|
||||
The `InventoryLevel` entity is associated with a location through the `location_id` attribute. The entity representing a location isn't implemented with this module, allowing for greater flexibility in how you choose to implement a location.
|
||||
|
||||
### ReservationItem
|
||||
|
||||
The `ReservationItem` entity represents a quantity of an inventory item that is reserved when an order is placed but not fulfilled yet. This indicates that the stock-kept item still hasn't been moved from stock, but should be considered as unavailable.
|
||||
|
||||
The `ReservationItem` entity has the following notable attributes, among others:
|
||||
|
||||
- `line_item_id`: The ID of the line item in the order that this reservation item refers to.
|
||||
- `inventory_item_id`: The ID of the inventory item this reservation item refers to.
|
||||
- `location_id`: The ID of the location that this item is reserved from.
|
||||
- `quantity`: A number indicating the quantity to be reserved.
|
||||
|
||||
---
|
||||
|
||||
## How the Module Integrates into Medusa
|
||||
|
||||
This section explains how the Medusa backend uses the inventory module along with its entities and other modules, and in its processes.
|
||||
|
||||
### Entities Relation Overview
|
||||
|
||||
The core Medusa package contains an entity `ProductVariantInventoryItem` that is used to establish a relation between a product variant and an inventory item. This enables you to use inventory management features on the product variant level, while maintaining the modularity that allows you to use Medusa's inventory module or implement your custom inventory module.
|
||||
|
||||
When you use Medusa's Inventory Module, the Medusa backend uses the `ProductVariantInventoryItem` entity as a bridge between the `InventoryItem` entity and the `ProductVariant` entity.
|
||||
|
||||
|
||||
|
||||
The Medusa backend also orchestrates between the installed inventory and stock location modules. The association between an Inventory Level and a location is handled by passing the ID of a location from the stock location module to the inventory module when an Inventory Level is being created. When using Medusa's [Stock Location module](./stock-location-module.md), the entity representing the location is `StockLocation`.
|
||||
|
||||
|
||||
|
||||
Similarly, the Medusa backend associates the `ReservationItem` entity with a line item and a location by passing the IDs of each to the inventory module when a reservation item is created.
|
||||
|
||||
### Product Variant Creation Process
|
||||
|
||||
In the Medusa backend, when a product variant that has an enabled `manage_inventory` attribute is created, the backend uses the inventory module to automatically create an inventory item along with the product variant. When the inventory item is created, the Medusa backend attaches it to the product variant using the `ProductVariantInventoryItem` entity as explained earlier.
|
||||
|
||||
The Medusa backend uses the inventory module to create Inventory Levels when the admin sets the available quantity of a product variant in a stock location.
|
||||
|
||||
### Cart and Checkout
|
||||
|
||||
During the cart and checkout workflow, for example when a product variant is added to the cart or during cart validation, the Medusa backend uses the inventory module to confirm that items in the cart have sufficient stock to be purchased in the desired quantity. If a product variant doesn't have an inventory item, which is the case when the `manage_inventory` attribute of the variant is disabled, the variant is assumed to be available in stock.
|
||||
|
||||
As an inventory item can exist in multiple locations, the inventory module checks across those locations. The Medusa backend retrieves the locations based on the sales channel of the cart, as each location is associated with a sales channel, and passes them along to the inventory module to perform the checking.
|
||||
|
||||
:::tip
|
||||
|
||||
You can learn more about the relation between Stock Locations and Sales Channels in the [Stock Location documentation](./stock-location-module.md).
|
||||
|
||||
:::
|
||||
|
||||
Then, the inventory module confirms that the product variant has sufficient quantity across these locations by summing all the `stocked_quantity` of the inventory levels associated with these locations. When retrieving the `stocked_quantity` of each of the inventory levels, the `reserved_quantity` is subtracted from it to ensure accurate availability.
|
||||
|
||||
### Order Placement
|
||||
|
||||
When an order is placed, the Medusa backend uses the inventory module to reserve the ordered quantity of line items that are associated with product variants having an enabled `manage_inventory` attribute. The reserved quantity is indicated by creating a reservation item for each line item, associating it with its inventory item and a stock location.
|
||||
|
||||
The Medusa backend chooses the stock location randomly from the available stock locations associated with the order’s sales channel. The admin can later change which stock location the item will be fulfilled from.
|
||||
|
||||
### Order Fulfillment
|
||||
|
||||
When an item in the order is fulfilled, and the item is associated with a product variant that has an enabled `manage_inventory`, the Medusa backend uses the inventory module to subtract the inventory level's `reserved_quantity` from the `stocked_quantity`. The inventory module also resets the `reserved_quantity` to `0`.
|
||||
|
||||
### Order Return
|
||||
|
||||
When an item in the order is returned, and the item is associated with a product variant that has an enabled `manage_inventory`, the Medusa backend uses the inventory module to increment the inventory level's `stocked_quantity` with the returned amount.
|
||||
@@ -0,0 +1,168 @@
|
||||
---
|
||||
description: "Multi-warehouse allows merchants to store a product in multiple locations with accurate and consistent inventory data within the commerce application."
|
||||
---
|
||||
|
||||
import DocCardList from '@theme/DocCardList';
|
||||
import DocCard from '@theme/DocCard';
|
||||
import Icons from '@theme/Icon';
|
||||
|
||||
# Multi-Warehouse
|
||||
|
||||
Multi-warehouse allows merchants to store a product in multiple locations with accurate and consistent inventory data within the commerce application.
|
||||
|
||||
Multi-warehouse in Medusa is composed of two modules: an inventory module - which is the NPM package `@medusajs/inventory` - and a stock location module - which is the NPM package `@medusajs/stock-location`.
|
||||
|
||||
<DocCard item={{
|
||||
type: 'link',
|
||||
href: '/modules/multiwarehouse/install-modules',
|
||||
label: 'Install Modules',
|
||||
customProps: {
|
||||
icon: Icons['academic-cap-solid'],
|
||||
description: 'Learn how to install the modules related to multi-warehouse',
|
||||
}
|
||||
}} />
|
||||
|
||||
---
|
||||
|
||||
## Features
|
||||
|
||||
### Multiple Stock Locations
|
||||
|
||||
Admins can manage the stock locations, which are the places they store their products. Stock locations are associated with different sales channels.
|
||||
|
||||
<DocCardList colSize={6} items={[
|
||||
{
|
||||
type: 'link',
|
||||
href: '/user-guide/multiwarehouse/locations',
|
||||
label: 'User Guide: Manage Stock Locations',
|
||||
customProps: {
|
||||
icon: Icons['users-solid'],
|
||||
description: 'Learn how to manage stock locations in Medusa admin.'
|
||||
}
|
||||
},
|
||||
{
|
||||
type: 'link',
|
||||
href: '#',
|
||||
label: 'Admin: Manage Stock Locations',
|
||||
customProps: {
|
||||
icon: Icons['academic-cap-solid'],
|
||||
description: 'Learn how to manage stock locations using admin APIs.',
|
||||
isSoon: true,
|
||||
}
|
||||
},
|
||||
]} />
|
||||
|
||||
### Inventory Management Across Locations
|
||||
|
||||
Admins can manage the inventory of product variants across the different stock locations.
|
||||
|
||||
<DocCardList colSize={6} items={[
|
||||
{
|
||||
type: 'link',
|
||||
href: '/user-guide/multiwarehouse/inventory',
|
||||
label: 'User Guide: Manage Inventory',
|
||||
customProps: {
|
||||
icon: Icons['users-solid'],
|
||||
description: 'Learn how to manage inventory using the Medusa admin.'
|
||||
}
|
||||
},
|
||||
{
|
||||
type: 'link',
|
||||
href: '#',
|
||||
label: 'Admin: Manage Inventory',
|
||||
customProps: {
|
||||
icon: Icons['academic-cap-solid'],
|
||||
description: 'Learn how to manage inventory using the admin APIs.',
|
||||
isSoon: true,
|
||||
}
|
||||
},
|
||||
]} />
|
||||
|
||||
### Manage Item Allocations in Orders
|
||||
|
||||
Admins can manage item allocations to choose which stock location to fulfill items from or return items to. Item quantities are reserved in a stock location until the item is fulfilled to ensure data consistency.
|
||||
|
||||
<DocCardList colSize={6} items={[
|
||||
{
|
||||
type: 'link',
|
||||
href: '/user-guide/orders/manage#manage-item-allocation',
|
||||
label: 'User Guide: Manage Allocations in Orders',
|
||||
customProps: {
|
||||
icon: Icons['users-solid'],
|
||||
description: 'Learn how to manage allocations of items in an order using the Medusa admin.'
|
||||
}
|
||||
},
|
||||
{
|
||||
type: 'link',
|
||||
href: '#',
|
||||
label: 'Admin: Manage Allocations in Orders',
|
||||
customProps: {
|
||||
icon: Icons['academic-cap-solid'],
|
||||
description: 'Learn how to manage allocations of items in an order using the admin APIs.',
|
||||
isSoon: true,
|
||||
}
|
||||
},
|
||||
]} />
|
||||
|
||||
---
|
||||
|
||||
## Understanding the Architecture
|
||||
|
||||
The commerce modules automatically detect whether a product variant is in stock, decrement the variant’s stock on fulfillment, and increment the variant’s stock on returns.
|
||||
|
||||
<DocCardList colSize={6} items={[
|
||||
{
|
||||
type: 'link',
|
||||
href: '/modules/multiwarehouse/inventory-module',
|
||||
label: 'Architecture: Inventory Module',
|
||||
customProps: {
|
||||
icon: Icons['circle-stack-solid'],
|
||||
description: 'Learn about the Inventory Module and how it works.'
|
||||
}
|
||||
},
|
||||
{
|
||||
type: 'link',
|
||||
href: '/modules/multiwarehouse/stock-location-module',
|
||||
label: 'Architecture: Stock Location Module',
|
||||
customProps: {
|
||||
icon: Icons['circle-stack-solid'],
|
||||
description: 'Learn about the Stock Location Module and how it works.'
|
||||
}
|
||||
},
|
||||
]} />
|
||||
|
||||
---
|
||||
|
||||
## Related Modules
|
||||
|
||||
Discover Multi-warehouse’s relation to other modules in Medusa.
|
||||
|
||||
<DocCardList colSize={4} items={[
|
||||
{
|
||||
type: 'link',
|
||||
href: '/modules/products/overview',
|
||||
label: 'Products',
|
||||
customProps: {
|
||||
icon: Icons['tag-solid'],
|
||||
description: 'Manage the inventory of product variants across locations.',
|
||||
}
|
||||
},
|
||||
{
|
||||
type: 'link',
|
||||
href: '/modules/sales-channels/overview',
|
||||
label: 'Sales Channels',
|
||||
customProps: {
|
||||
icon: Icons['channels-solid'],
|
||||
description: 'Stock locations are associated with sales channels.',
|
||||
}
|
||||
},
|
||||
{
|
||||
type: 'link',
|
||||
href: '/modules/orders/overview',
|
||||
label: 'Orders',
|
||||
customProps: {
|
||||
icon: Icons['check-circle-solid'],
|
||||
description: 'Change available stock based on returns and fulfillment.',
|
||||
}
|
||||
},
|
||||
]} />
|
||||
@@ -0,0 +1,63 @@
|
||||
---
|
||||
description: "In this document, you’ll learn about the inventory module, how it works, and its relation to other processes in your commerce application."
|
||||
---
|
||||
|
||||
# Stock Level Module
|
||||
|
||||
In this document, you’ll learn about the Stock Level module and how it works.
|
||||
|
||||
## Overview
|
||||
|
||||
A stock location indicates a physical address that stock-kept items can be stored in. The stock location module handles functionalities related to managing stock locations and their addresses.
|
||||
|
||||
Medusa's Stock Location module is a standalone module that can be used in any commerce application, not just in a Medusa backend. This document gives a general overview of how the stock location module is designed, and highlights how the Medusa core orchestrates relations around this module when it's used with the Medusa backend.
|
||||
|
||||
---
|
||||
|
||||
## StockLocation Entity
|
||||
|
||||
The `StockLocation` entity represents a stock location. It has minimal attributes including a `name` attribute. It’s associated with the `StockLocationAddress` entity.
|
||||
|
||||
---
|
||||
|
||||
## StockLocationAddress Entity
|
||||
|
||||
The `StockLocationAddress` is an entitiy that contains address-related fields, such as `city` or `country_code`.
|
||||
|
||||
The `StockLocationAddress` entity belongs to the `StockLocation` entity. It is used to store the address details of a stock location.
|
||||
|
||||
---
|
||||
|
||||
## How the Module Integrates into Medusa
|
||||
|
||||
This section explains how the Medusa backend uses the stock location module along with its entities and other modules.
|
||||
|
||||
### Entities Relation Overview
|
||||
|
||||
The following entities in the Medusa backend each have an attribute that is used to associate them with a stock location:
|
||||
|
||||
- `Fulfillment`: The `location_id` attribute within the `Fulfillment` entity is used to indicate from which stock location an order item is fulfilled.
|
||||
- `Return`: The `location_id` attribute within the `Return` entity is used to indicate to which stock location an order item is returned.
|
||||
- `Store`: The `default_location_id` attribute within the `Store` entity is used to indicate the default stock location to use in the ecommerce store.
|
||||
- `SalesChannelLocation`: This entity is used to attach a stock location to a `SalesChannel`. The relation between these two entities is explained further in the [Relation to Sales Channel section](#relation-to-saleschannel).
|
||||
|
||||
When the Medusa's Stock Location module is used with the Medusa backend, the ID that is associated with the attributes mentioned above is from the `StockLocation` module.
|
||||
|
||||
The Medusa backend also orchestrates between different modules. The [Inventory Module](./inventory-module.md)'s entities contain the following attributes to handle associations between them and a stock location:
|
||||
|
||||
- `InventoryLevel`: This entity is used to indicate the stocked quantity of an inventory item in a stock location. As explained in the [Inventory Module documentation](./inventory-module.md#inventorylevel), the `InventoryLevel` entity has an attribute `location_id`.
|
||||
- `ReservationItem`: This entity is used to indicate the reserved quantity of an inventory item in a stock location. As explained in the [Inventory Module documentation](./inventory-module.md#reservationitem), the `ReservationItem` entity has an attribute `location_id`.
|
||||
|
||||
When both modules are used within the Medusa backend, the Medusa backend bridges between these modules by passing the ID of a `StockLocation` from the stock location module to the inventory module, and the inventory module uses the ID in its entities.
|
||||
|
||||
### Relation to SalesChannel
|
||||
|
||||
A stock location can be associated with more than one sales channel. For example, a physical store and an online store can use the same stock location.
|
||||
|
||||
As the `StockLocation` and `SalesChannel` entities are available in separate modules, the Medusa backend handles attaching the stock location with the sales channel within the `SalesChannelLocation` entity.
|
||||
|
||||
This relation is used across the Medusa backend and within checkout and order workflows:
|
||||
|
||||
- When checking the availability of an inventory item during checkout, the Medusa backend retrieves the location IDs that are associated with the cart’s sales channel using the `SalesChannelLocation`, then passes it along to the inventory module to perform the quantity check.
|
||||
- When an order is placed, the Medusa backend retrieves the location IDs that are associated with the cart’s sales channel using the `SalesChannelLocation` entity, and passes it to the inventory module that reserves the ordered quantity of the inventory item from that location. The admin can later change the stock location if necessary.
|
||||
- When an item in an order is fulfilled, the admin chooses a stock location to fulfill the item from. Similarly, when an item in an order is returned, the admin can choose a stock location to return the item to. The Medusa backend then passes the ID of the location from the stock module to the inventory module to perform inventory management functionalities.
|
||||
Reference in New Issue
Block a user