asyavee/medusa-store
1
0
Fork 0
Code Issues Pull Requests Actions 3 Packages Projects Releases Wiki Activity

docs: general improvements (#13530)

Browse Source
This commit is contained in:
Shahed Nasser
2025-09-17 08:48:18 +03:00
committed by GitHub
parent 1c4f7bd53a
commit ba9a30757b
7 changed files with 140 additions and 110 deletions
Download Patch File Download Diff File Expand all files Collapse all files
www/apps/book/app/learn/fundamentals/workflows/workflow-hooks/page.mdx
+21 -23
View File
@@ -4,11 +4,11 @@ export const metadata = {
# {metadata.title}
In this chapter, you'll learn what a workflow hook is and how to consume them.
In this chapter, you'll learn what workflow hooks are and how to use them.
## What is a Workflow Hook?
A workflow hook is a point in a workflow where you can inject custom functionality as a step function, called a hook handler.
A workflow hook is a specific point in a workflow where you can inject custom functionality. This custom functionality is called a hook handler.
Medusa exposes hooks in many of its workflows that are used in its API routes. You can consume those hooks to add your custom logic.
@@ -28,13 +28,13 @@ You want to perform a custom action during a workflow's execution, such as when
## How to Consume a Hook?
A workflow has a special `hooks` property which is an object that holds its hooks.
A workflow has a special `hooks` property. This property is an object that contains all available hooks.
So, in a TypeScript or JavaScript file created under the `src/workflows/hooks` directory:
- Import the workflow.
- Access its hook using the `hooks` property.
- Pass the hook a step function as a parameter to consume it.
1. Import the workflow.
2. Access the hook using the `hooks` property.
3. Pass a step function as a parameter to the hook.
For example, to consume the `productsCreated` hook of Medusa's `createProductsWorkflow`, create the file `src/workflows/hooks/product-created.ts` with the following content:
@@ -52,15 +52,15 @@ createProductsWorkflow.hooks.productsCreated(
)
```
The `productsCreated` hook is available on the workflow's `hooks` property by its name.
The `productsCreated` hook is available in the workflow's `hooks` property.
You invoke the hook, passing a step function (the hook handler) as a parameter.
You call the hook and pass a step function (the hook handler) as a parameter.
Now, when a product is created using the [Create Product API route](!api!/admin#products_postproducts), your hook handler is executed after the product is created.
Now, when a product is created using the [Create Product API route](!api!/admin#products_postproducts), your hook handler runs after the product is created.
<Note>
A hook can have only one handler.
A hook can have only one handler. So, you can't consume the same hook multiple times.
</Note>
@@ -74,7 +74,9 @@ Refer to the [createProductsWorkflow reference](!resources!/references/medusa-wo
Since a hook handler is essentially a step function, it receives the hook's input as a first parameter, and an object holding a `container` property as a second parameter.
Each hook has different input. For example, the `productsCreated` hook receives an object having a `products` property holding the created product.
Each hook has different input. For example, the `productsCreated` hook receives an object with a `products` property that contains the created product.
You can find the input for each workflow's hooks in the [Core Workflows Reference](!resources!/medusa-workflows-reference).
### Hook Handler Compensation
@@ -97,15 +99,15 @@ createProductsWorkflow.hooks.productsCreated(
)
```
The compensation function is executed if an error occurs in the workflow to undo the actions performed by the hook handler.
The compensation function runs if an error occurs in the workflow. It undoes the actions performed by the hook handler.
The compensation function receives as an input the second parameter passed to the `StepResponse` returned by the step function.
The compensation function receives the second parameter passed to the `StepResponse` returned by the step function as input.
It also accepts as a second parameter an object holding a `container` property to resolve resources from the Medusa container.
It also accepts an object with a `container` property as a second parameter. This allows you to resolve resources from the Medusa container.
### Additional Data Property
Medusa's workflows pass in the hook's input an `additional_data` property:
Medusa's workflows include an `additional_data` property in the hook's input:
```ts title="src/workflows/hooks/product-created.ts" highlights={[["4", "additional_data"]]}
import { createProductsWorkflow } from "@medusajs/medusa/core-flows"
@@ -117,17 +119,13 @@ createProductsWorkflow.hooks.productsCreated(
)
```
This property is an object that holds additional data passed to the workflow through the request sent to the API route using the workflow.
This property is an object that contains additional data passed to the workflow through the request sent to the API route.
<Note>
Learn how to pass `additional_data` in requests to API routes in [this chapter](../../api-routes/additional-data/page.mdx).
</Note>
Learn how to pass `additional_data` in requests to API routes in the [Additional Data](../../api-routes/additional-data/page.mdx) chapter.
### Pass Additional Data to Workflow
You can also pass that additional data when executing the workflow. Pass it as a parameter to the `.run` method of the workflow:
You can also pass additional data when running the workflow. Pass it as a parameter to the workflow's `.run` method:
```ts title="src/workflows/hooks/product-created.ts" highlights={[["10", "additional_data"]]}
import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
@@ -147,4 +145,4 @@ export async function POST(req: MedusaRequest, res: MedusaResponse) {
}
```
Your hook handler then receives that passed data in the `additional_data` object.
Your hook handler then receives the passed data in the `additional_data` object.
www/apps/book/app/learn/storefront-development/page.mdx
+12 -6
View File
@@ -6,9 +6,15 @@ export const metadata = {
# {metadata.title}
The Medusa application is made up of a Node.js server and an admin dashboard. Storefronts are installed, built, and hosted separately from the Medusa application, giving you the flexibility to choose the frontend tech stack that you and your team are proficient in, and implement unique design systems and user experience.
In this chapter, you'll learn about storefronts and how to build one.
You can build your storefront from scratch with your preferred tech stack, or start with our Next.js Starter storefront. The Next.js Starter storefront provides rich commerce features and a sleek design. Developers and businesses can use it as-is or build on top of it to tailor it for the business's unique use case, design, and customer experience.
## Storefronts in Medusa
The Medusa application includes a Node.js server and an admin dashboard. Storefronts are separate applications that you install, build, and host independently from Medusa. This gives you the flexibility to choose your preferred frontend tech stack and implement unique designs and user experiences.
In your storefront, you can retrieve data and perform commerce operations by sending requests to the Medusa application's [Store API routes](!api!/store) and your custom API routes.
You can build your storefront from scratch with your preferred tech stack, or start with our Next.js Starter storefront. The Next.js Starter storefront provides rich commerce features and a modern design. You can use it as-is or customize it to match your business needs, design requirements, and customer experience goals.
<CardList
items={[
@@ -25,12 +31,12 @@ You can build your storefront from scratch with your preferred tech stack, or st
---
## Passing a Publishable API Key in Storefront Requests
## Using a Publishable API Key in Storefront Requests
When sending a request to an API route starting with `/store`, you must include a publishable API key in the header of your request.
When sending requests to API routes that start with `/store`, you must include a publishable API key in the request header.
A publishable API key sets the scope of your request to one or more sales channels.
Then, when you retrieve products, only products of those sales channels are retrieved. This also ensures you retrieve correct inventory data, and associate created orders with the scoped sales channel.
When you retrieve products, only products from those sales channels are returned. This also ensures you get correct inventory data and associate created orders with the right sales channel.
Learn more about passing the publishable API key in [this storefront development guide](!resources!/storefront-development/publishable-api-keys).
Learn more about using the publishable API key in the [Storefront Development guide](!resources!/storefront-development/publishable-api-keys).
www/apps/book/generated/edit-dates.mjs
+2 -2
View File
@@ -5,9 +5,9 @@ export const generatedEditDates = {
"app/learn/page.mdx": "2025-06-27T11:39:15.941Z",
"app/learn/fundamentals/modules/commerce-modules/page.mdx": "2025-04-17T08:51:32.723Z",
"app/learn/fundamentals/workflows/retry-failed-steps/page.mdx": "2025-09-15T09:38:18.299Z",
"app/learn/fundamentals/workflows/workflow-hooks/page.mdx": "2024-12-09T10:44:33.781Z",
"app/learn/fundamentals/workflows/workflow-hooks/page.mdx": "2025-09-16T15:52:33.602Z",
"app/learn/debugging-and-testing/logging/page.mdx": "2025-08-28T15:31:57.879Z",
"app/learn/storefront-development/page.mdx": "2024-12-10T09:11:04.993Z",
"app/learn/storefront-development/page.mdx": "2025-09-16T15:57:42.189Z",
"app/learn/fundamentals/page.mdx": "2024-07-04T17:26:03+03:00",
"app/learn/fundamentals/admin-customizations/page.mdx": "2024-10-07T12:41:39.218Z",
"app/learn/fundamentals/workflows/workflow-timeout/page.mdx": "2025-04-24T13:15:14.472Z",
www/apps/book/public/llms-full.txt
+68 -51
View File
@@ -21077,11 +21077,11 @@ const myWorkflow = createWorkflow(
# Workflow Hooks
In this chapter, you'll learn what a workflow hook is and how to consume them.
In this chapter, you'll learn what workflow hooks are and how to use them.
## What is a Workflow Hook?
A workflow hook is a point in a workflow where you can inject custom functionality as a step function, called a hook handler.
A workflow hook is a specific point in a workflow where you can inject custom functionality. This custom functionality is called a hook handler.
Medusa exposes hooks in many of its workflows that are used in its API routes. You can consume those hooks to add your custom logic.
@@ -21093,13 +21093,13 @@ You want to perform a custom action during a workflow's execution, such as when
## How to Consume a Hook?
A workflow has a special `hooks` property which is an object that holds its hooks.
A workflow has a special `hooks` property. This property is an object that contains all available hooks.
So, in a TypeScript or JavaScript file created under the `src/workflows/hooks` directory:
- Import the workflow.
- Access its hook using the `hooks` property.
- Pass the hook a step function as a parameter to consume it.
1. Import the workflow.
2. Access the hook using the `hooks` property.
3. Pass a step function as a parameter to the hook.
For example, to consume the `productsCreated` hook of Medusa's `createProductsWorkflow`, create the file `src/workflows/hooks/product-created.ts` with the following content:
@@ -21113,13 +21113,13 @@ createProductsWorkflow.hooks.productsCreated(
)
```
The `productsCreated` hook is available on the workflow's `hooks` property by its name.
The `productsCreated` hook is available in the workflow's `hooks` property.
You invoke the hook, passing a step function (the hook handler) as a parameter.
You call the hook and pass a step function (the hook handler) as a parameter.
Now, when a product is created using the [Create Product API route](https://docs.medusajs.com/api/admin#products_postproducts), your hook handler is executed after the product is created.
Now, when a product is created using the [Create Product API route](https://docs.medusajs.com/api/admin#products_postproducts), your hook handler runs after the product is created.
A hook can have only one handler.
A hook can have only one handler. So, you can't consume the same hook multiple times.
Refer to the [createProductsWorkflow reference](https://docs.medusajs.com/resources/references/medusa-workflows/createProductsWorkflow/index.html.md) to see at which point the hook handler is executed.
@@ -21127,7 +21127,9 @@ Refer to the [createProductsWorkflow reference](https://docs.medusajs.com/resour
Since a hook handler is essentially a step function, it receives the hook's input as a first parameter, and an object holding a `container` property as a second parameter.
Each hook has different input. For example, the `productsCreated` hook receives an object having a `products` property holding the created product.
Each hook has different input. For example, the `productsCreated` hook receives an object with a `products` property that contains the created product.
You can find the input for each workflow's hooks in the [Core Workflows Reference](https://docs.medusajs.com/resources/medusa-workflows-reference/index.html.md).
### Hook Handler Compensation
@@ -21150,15 +21152,15 @@ createProductsWorkflow.hooks.productsCreated(
)
```
The compensation function is executed if an error occurs in the workflow to undo the actions performed by the hook handler.
The compensation function runs if an error occurs in the workflow. It undoes the actions performed by the hook handler.
The compensation function receives as an input the second parameter passed to the `StepResponse` returned by the step function.
The compensation function receives the second parameter passed to the `StepResponse` returned by the step function as input.
It also accepts as a second parameter an object holding a `container` property to resolve resources from the Medusa container.
It also accepts an object with a `container` property as a second parameter. This allows you to resolve resources from the Medusa container.
### Additional Data Property
Medusa's workflows pass in the hook's input an `additional_data` property:
Medusa's workflows include an `additional_data` property in the hook's input:
```ts title="src/workflows/hooks/product-created.ts" highlights={[["4", "additional_data"]]}
import { createProductsWorkflow } from "@medusajs/medusa/core-flows"
@@ -21170,13 +21172,13 @@ createProductsWorkflow.hooks.productsCreated(
)
```
This property is an object that holds additional data passed to the workflow through the request sent to the API route using the workflow.
This property is an object that contains additional data passed to the workflow through the request sent to the API route.
Learn how to pass `additional_data` in requests to API routes in [this chapter](https://docs.medusajs.com/learn/fundamentals/api-routes/additional-data/index.html.md).
Learn how to pass `additional_data` in requests to API routes in the [Additional Data](https://docs.medusajs.com/learn/fundamentals/api-routes/additional-data/index.html.md) chapter.
### Pass Additional Data to Workflow
You can also pass that additional data when executing the workflow. Pass it as a parameter to the `.run` method of the workflow:
You can also pass additional data when running the workflow. Pass it as a parameter to the workflow's `.run` method:
```ts title="src/workflows/hooks/product-created.ts" highlights={[["10", "additional_data"]]}
import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
@@ -21196,7 +21198,7 @@ export async function POST(req: MedusaRequest, res: MedusaResponse) {
}
```
Your hook handler then receives that passed data in the `additional_data` object.
Your hook handler then receives the passed data in the `additional_data` object.
# Workflow Timeout
@@ -23986,24 +23988,30 @@ MEDUSA_FF_ANALYTICS=false
# Storefront Development
The Medusa application is made up of a Node.js server and an admin dashboard. Storefronts are installed, built, and hosted separately from the Medusa application, giving you the flexibility to choose the frontend tech stack that you and your team are proficient in, and implement unique design systems and user experience.
In this chapter, you'll learn about storefronts and how to build one.
You can build your storefront from scratch with your preferred tech stack, or start with our Next.js Starter storefront. The Next.js Starter storefront provides rich commerce features and a sleek design. Developers and businesses can use it as-is or build on top of it to tailor it for the business's unique use case, design, and customer experience.
## Storefronts in Medusa
The Medusa application includes a Node.js server and an admin dashboard. Storefronts are separate applications that you install, build, and host independently from Medusa. This gives you the flexibility to choose your preferred frontend tech stack and implement unique designs and user experiences.
In your storefront, you can retrieve data and perform commerce operations by sending requests to the Medusa application's [Store API routes](https://docs.medusajs.com/api/store) and your custom API routes.
You can build your storefront from scratch with your preferred tech stack, or start with our Next.js Starter storefront. The Next.js Starter storefront provides rich commerce features and a modern design. You can use it as-is or customize it to match your business needs, design requirements, and customer experience goals.
- [Install Next.js Starter Storefront](https://docs.medusajs.com/resources/nextjs-starter/index.html.md)
- [Build Custom Storefront](https://docs.medusajs.com/resources/storefront-development/index.html.md)
***
## Passing a Publishable API Key in Storefront Requests
## Using a Publishable API Key in Storefront Requests
When sending a request to an API route starting with `/store`, you must include a publishable API key in the header of your request.
When sending requests to API routes that start with `/store`, you must include a publishable API key in the request header.
A publishable API key sets the scope of your request to one or more sales channels.
Then, when you retrieve products, only products of those sales channels are retrieved. This also ensures you retrieve correct inventory data, and associate created orders with the scoped sales channel.
When you retrieve products, only products from those sales channels are returned. This also ensures you get correct inventory data and associate created orders with the right sales channel.
Learn more about passing the publishable API key in [this storefront development guide](https://docs.medusajs.com/resources/storefront-development/publishable-api-keys/index.html.md).
Learn more about using the publishable API key in the [Storefront Development guide](https://docs.medusajs.com/resources/storefront-development/publishable-api-keys/index.html.md).
# Updating Medusa
@@ -29055,45 +29063,52 @@ The `ShippingOption` data model has a `data` property. It's an object that store
# Inventory Concepts
In this document, you’ll learn about the main concepts in the Inventory Module, and how data is stored and related.
In this guide, you'll learn about the main concepts in the Inventory Module and how data is stored and connected.
## InventoryItem
An inventory item, represented by the [InventoryItem data model](https://docs.medusajs.com/references/inventory-next/models/InventoryItem/index.html.md), is a stock-kept item, such as a product, whose inventory can be managed.
An inventory item, represented by the [InventoryItem data model](https://docs.medusajs.com/references/inventory-next/models/InventoryItem/index.html.md), is a stock-kept item whose inventory can be managed. For example, a product.
The `InventoryItem` data model mainly holds details related to the underlying stock item, but has relations to other data models that include its inventory details.
The `InventoryItem` data model holds details about the stock item. It connects to other data models like `InventoryLevel` that store stock and quantity details.
![A diagram showcasing the relation between data models in the Inventory Module](https://res.cloudinary.com/dza7lstvk/image/upload/v1709658103/Medusa%20Resources/inventory-architecture_kxr2ql.png)
### Inventory Shipping Requirement
An inventory item has a `requires_shipping` field (enabled by default) that indicates whether the item requires shipping. For example, if you're selling a digital license that has limited stock quantity but doesn't require shipping.
An inventory item has a `requires_shipping` field that indicates whether the item needs shipping. This field is enabled by default.
When a product variant is purchased in the Medusa application, this field is used to determine whether the item requires shipping. Learn more in [this documentation](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/product/selling-products/index.html.md).
For example, if you're selling a digital license with limited stock that doesn't need shipping, you can set this field to `false`.
When a customer buys a product variant in the Medusa application, this field determines whether the item needs shipping. Learn more in the [Configure Selling Products](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/product/selling-products/index.html.md) guide.
***
## InventoryLevel
An inventory level, represented by the [InventoryLevel data model](https://docs.medusajs.com/references/inventory-next/models/InventoryLevel/index.html.md), holds the inventory and quantity details of an inventory item in a specific location.
An inventory level, represented by the [InventoryLevel data model](https://docs.medusajs.com/references/inventory-next/models/InventoryLevel/index.html.md), stores the inventory and quantity details of an inventory item in a specific location.
It has three quantity-related properties:
It has three quantity properties:
- `stocked_quantity`: The available stock quantity of an item in the associated location.
- `reserved_quantity`: The quantity reserved from the available `stocked_quantity`. It indicates the quantity that's still not removed from stock, but considered as unavailable when checking whether an item is in stock.
- `incoming_quantity`: The incoming stock quantity of an item into the associated location. This property doesn't play into the `stocked_quantity` or when checking whether an item is in stock.
- `reserved_quantity`: The quantity reserved from the available `stocked_quantity`. This quantity is still in stock but unavailable when checking if an item is available.
- For example, when an order is placed but not yet fulfilled, the ordered quantity is reserved from available stock.
- `incoming_quantity`: The incoming stock quantity of an item into the associated location. This property doesn't affect the `stocked_quantity` or availability checks.
### Associated Location
The inventory level's location is determined by the `location_id` property. Medusa links the `InventoryLevel` data model with the `StockLocation` data model from the Stock Location Module.
The inventory level's location is set in the `location_id` property. Medusa links the `InventoryLevel` data model with the `StockLocation` data model from the [Stock Location Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/stock-location/index.html.md).
***
## ReservationItem
A reservation item, represented by the [ReservationItem](https://docs.medusajs.com/references/inventory-next/models/ReservationItem/index.html.md) data model, represents unavailable quantity of an inventory item in a location. It's used when an order is placed but not fulfilled yet.
A reservation item, represented by the [ReservationItem](https://docs.medusajs.com/references/inventory-next/models/ReservationItem/index.html.md) data model, represents unavailable quantity of an inventory item in a location.
The reserved quantity is associated with a location, so it has a similar relation to that of the `InventoryLevel` with the Stock Location Module.
When an order is placed, Medusa creates a reservation item for each inventory item in the order. The reservation item stores the reserved quantity of the inventory item in the location associated with the order's sales channel.
You can also use reservation items for custom use cases. For example, if you're selling event tickets, you can create a reservation item when a customer selects a ticket. Then, you can remove the reservation item if the customer doesn't complete the purchase within a specific time.
The reserved quantity is linked to a location, so it has a similar relationship to the `InventoryLevel` with the [Stock Location Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/stock-location/index.html.md).
# Inventory Module in Medusa Flows
@@ -29834,56 +29849,58 @@ Learn more about workflows in [this documentation](https://docs.medusajs.com/doc
# Order Claim
In this document, you’ll learn about order claims.
In this guide, you'll learn about order claims.
Refer to this [Medusa Admin User Guide](https://docs.medusajs.com/user-guide/orders/claims/index.html.md) to learn how to manage an order's claims using the dashboard.
## What is a Claim?
When a customer receives a defective or incorrect item, the merchant can create a claim to refund or replace the item.
When a customer receives a defective or incorrect item, the merchant can create a claim to refund or replace that item.
The [OrderClaim data model](https://docs.medusajs.com/references/order/models/OrderClaim/index.html.md) represents a claim.
A claim is represented by the [OrderClaim data model](https://docs.medusajs.com/references/order/models/OrderClaim/index.html.md).
***
## Claim Type
The `Claim` data model has a `type` property whose value indicates the type of the claim:
The `Claim` data model has a `type` property that indicates the type of claim:
- `refund`: the items are returned, and the customer is refunded.
- `replace`: the items are returned, and the customer receives new items.
- `refund`: The items are returned and the customer receives a refund.
- `replace`: The items are returned and the customer receives new items.
***
## Old and Replacement Items
When the claim is created, a return, represented by the [Return data model](https://docs.medusajs.com/references/order/models/Return/index.html.md), is also created to handle receiving the old items from the customer.
When you create a claim, a return is also created to handle receiving the old items from the customer. The return is represented by the [Return data model](https://docs.medusajs.com/references/order/models/Return/index.html.md).
Learn more about returns in [this guide](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/order/return/index.html.md).
Refer to the [Returns](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/order/return/index.html.md) guide to learn more about returns.
If the claim’s type is `replace`, replacement items are represented by the [ClaimItem data model](https://docs.medusajs.com/references/order/models/OrderClaimItem/index.html.md).
If the claim's type is `replace`, the replacement items are represented by the [ClaimItem data model](https://docs.medusajs.com/references/order/models/OrderClaimItem/index.html.md).
***
## Claim Shipping Methods
A claim uses shipping methods to send the replacement items to the customer. These methods are represented by the [OrderShippingMethod data model](https://docs.medusajs.com/references/order/models/OrderShippingMethod/index.html.md).
A claim uses shipping methods to send replacement items to the customer. These methods are represented by the [OrderShippingMethod data model](https://docs.medusajs.com/references/order/models/OrderShippingMethod/index.html.md).
The shipping methods for the returned items are associated with the claim's return, as explained in [this guide](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/order/return#return-shipping-methods/index.html.md).
The shipping methods for returned items are linked to the claim's return, as explained in the [Returns](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/order/return#return-shipping-methods/index.html.md) guide.
***
## Claim Refund
If the claim’s type is `refund`, the amount to be refunded is stored in the `refund_amount` property.
If the claim's type is `refund`, the refund amount is stored in the `refund_amount` property.
The [Transaction data model](https://docs.medusajs.com/references/order/models/OrderTransaction/index.html.md) represents the refunds made for the claim.
***
## How Claims Impact an Order’s Version
## How Claims Impact an Order's Version
When a claim is confirmed, the order’s version is incremented.
When you confirm a claim, the order's version increases.
Learn more about order versions in the [Order Versioning](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/order/order-versioning/index.html.md) guide.
# Order Concepts
www/apps/resources/app/commerce-modules/inventory/concepts/page.mdx
+19 -12
View File
@@ -4,42 +4,49 @@ export const metadata = {
# {metadata.title}
In this document, you’ll learn about the main concepts in the Inventory Module, and how data is stored and related.
In this guide, you'll learn about the main concepts in the Inventory Module and how data is stored and connected.
## InventoryItem
An inventory item, represented by the [InventoryItem data model](/references/inventory-next/models/InventoryItem), is a stock-kept item, such as a product, whose inventory can be managed.
An inventory item, represented by the [InventoryItem data model](/references/inventory-next/models/InventoryItem), is a stock-kept item whose inventory can be managed. For example, a product.
The `InventoryItem` data model mainly holds details related to the underlying stock item, but has relations to other data models that include its inventory details.
The `InventoryItem` data model holds details about the stock item. It connects to other data models like `InventoryLevel` that store stock and quantity details.
![A diagram showcasing the relation between data models in the Inventory Module](https://res.cloudinary.com/dza7lstvk/image/upload/v1709658103/Medusa%20Resources/inventory-architecture_kxr2ql.png)
### Inventory Shipping Requirement
An inventory item has a `requires_shipping` field (enabled by default) that indicates whether the item requires shipping. For example, if you're selling a digital license that has limited stock quantity but doesn't require shipping.
An inventory item has a `requires_shipping` field that indicates whether the item needs shipping. This field is enabled by default.
When a product variant is purchased in the Medusa application, this field is used to determine whether the item requires shipping. Learn more in [this documentation](../../product/selling-products/page.mdx).
For example, if you're selling a digital license with limited stock that doesn't need shipping, you can set this field to `false`.
When a customer buys a product variant in the Medusa application, this field determines whether the item needs shipping. Learn more in the [Configure Selling Products](../../product/selling-products/page.mdx) guide.
---
## InventoryLevel
An inventory level, represented by the [InventoryLevel data model](/references/inventory-next/models/InventoryLevel), holds the inventory and quantity details of an inventory item in a specific location.
An inventory level, represented by the [InventoryLevel data model](/references/inventory-next/models/InventoryLevel), stores the inventory and quantity details of an inventory item in a specific location.
It has three quantity-related properties:
It has three quantity properties:
- `stocked_quantity`: The available stock quantity of an item in the associated location.
- `reserved_quantity`: The quantity reserved from the available `stocked_quantity`. It indicates the quantity that's still not removed from stock, but considered as unavailable when checking whether an item is in stock.
- `incoming_quantity`: The incoming stock quantity of an item into the associated location. This property doesn't play into the `stocked_quantity` or when checking whether an item is in stock.
- `reserved_quantity`: The quantity reserved from the available `stocked_quantity`. This quantity is still in stock but unavailable when checking if an item is available.
- For example, when an order is placed but not yet fulfilled, the ordered quantity is reserved from available stock.
- `incoming_quantity`: The incoming stock quantity of an item into the associated location. This property doesn't affect the `stocked_quantity` or availability checks.
### Associated Location
The inventory level's location is determined by the `location_id` property. Medusa links the `InventoryLevel` data model with the `StockLocation` data model from the Stock Location Module.
The inventory level's location is set in the `location_id` property. Medusa links the `InventoryLevel` data model with the `StockLocation` data model from the [Stock Location Module](../../stock-location/page.mdx).
---
## ReservationItem
A reservation item, represented by the [ReservationItem](/references/inventory-next/models/ReservationItem) data model, represents unavailable quantity of an inventory item in a location. It's used when an order is placed but not fulfilled yet.
A reservation item, represented by the [ReservationItem](/references/inventory-next/models/ReservationItem) data model, represents unavailable quantity of an inventory item in a location.
The reserved quantity is associated with a location, so it has a similar relation to that of the `InventoryLevel` with the Stock Location Module.
When an order is placed, Medusa creates a reservation item for each inventory item in the order. The reservation item stores the reserved quantity of the inventory item in the location associated with the order's sales channel.
You can also use reservation items for custom use cases. For example, if you're selling event tickets, you can create a reservation item when a customer selects a ticket. Then, you can remove the reservation item if the customer doesn't complete the purchase within a specific time.
The reserved quantity is linked to a location, so it has a similar relationship to the `InventoryLevel` with the [Stock Location Module](../../stock-location/page.mdx).
www/apps/resources/app/commerce-modules/order/claim/page.mdx
+16 -14
View File
@@ -4,7 +4,7 @@ export const metadata = {
# {metadata.title}
In this document, you’ll learn about order claims.
In this guide, you'll learn about order claims.
<Note title="Looking for no-code docs?">
@@ -14,51 +14,53 @@ Refer to this [Medusa Admin User Guide](!user-guide!/orders/claims) to learn how
## What is a Claim?
When a customer receives a defective or incorrect item, the merchant can create a claim to refund or replace the item.
When a customer receives a defective or incorrect item, the merchant can create a claim to refund or replace that item.
The [OrderClaim data model](/references/order/models/OrderClaim) represents a claim.
A claim is represented by the [OrderClaim data model](/references/order/models/OrderClaim).
---
## Claim Type
The `Claim` data model has a `type` property whose value indicates the type of the claim:
The `Claim` data model has a `type` property that indicates the type of claim:
- `refund`: the items are returned, and the customer is refunded.
- `replace`: the items are returned, and the customer receives new items.
- `refund`: The items are returned and the customer receives a refund.
- `replace`: The items are returned and the customer receives new items.
---
## Old and Replacement Items
When the claim is created, a return, represented by the [Return data model](/references/order/models/Return), is also created to handle receiving the old items from the customer.
When you create a claim, a return is also created to handle receiving the old items from the customer. The return is represented by the [Return data model](/references/order/models/Return).
<Note>
Learn more about returns in [this guide](../return/page.mdx).
Refer to the [Returns](../return/page.mdx) guide to learn more about returns.
</Note>
If the claim’s type is `replace`, replacement items are represented by the [ClaimItem data model](/references/order/models/OrderClaimItem).
If the claim's type is `replace`, the replacement items are represented by the [ClaimItem data model](/references/order/models/OrderClaimItem).
---
## Claim Shipping Methods
A claim uses shipping methods to send the replacement items to the customer. These methods are represented by the [OrderShippingMethod data model](/references/order/models/OrderShippingMethod).
A claim uses shipping methods to send replacement items to the customer. These methods are represented by the [OrderShippingMethod data model](/references/order/models/OrderShippingMethod).
The shipping methods for the returned items are associated with the claim's return, as explained in [this guide](../return/page.mdx#return-shipping-methods).
The shipping methods for returned items are linked to the claim's return, as explained in the [Returns](../return/page.mdx#return-shipping-methods) guide.
---
## Claim Refund
If the claim’s type is `refund`, the amount to be refunded is stored in the `refund_amount` property.
If the claim's type is `refund`, the refund amount is stored in the `refund_amount` property.
The [Transaction data model](/references/order/models/OrderTransaction) represents the refunds made for the claim.
---
## How Claims Impact an Order’s Version
## How Claims Impact an Order's Version
When a claim is confirmed, the order’s version is incremented.
When you confirm a claim, the order's version increases.
Learn more about order versions in the [Order Versioning](../order-versioning/page.mdx) guide.
www/apps/resources/generated/edit-dates.mjs
+2 -2
View File
@@ -28,12 +28,12 @@ export const generatedEditDates = {
"app/commerce-modules/fulfillment/page.mdx": "2025-05-20T07:51:40.707Z",
"app/commerce-modules/inventory/_events/_events-table/page.mdx": "2024-07-03T19:27:13+03:00",
"app/commerce-modules/inventory/_events/page.mdx": "2024-07-03T19:27:13+03:00",
"app/commerce-modules/inventory/concepts/page.mdx": "2025-02-13T12:37:28.918Z",
"app/commerce-modules/inventory/concepts/page.mdx": "2025-09-16T16:03:29.634Z",
"app/commerce-modules/inventory/inventory-in-flows/page.mdx": "2025-01-08T12:21:12.157Z",
"app/commerce-modules/inventory/page.mdx": "2025-04-17T08:48:24.991Z",
"app/commerce-modules/order/_events/_events-table/page.mdx": "2024-07-03T19:27:13+03:00",
"app/commerce-modules/order/_events/page.mdx": "2024-07-03T19:27:13+03:00",
"app/commerce-modules/order/claim/page.mdx": "2025-02-26T11:23:55.003Z",
"app/commerce-modules/order/claim/page.mdx": "2025-09-16T16:07:25.033Z",
"app/commerce-modules/order/concepts/page.mdx": "2025-08-21T15:05:58.124Z",
"app/commerce-modules/order/exchange/page.mdx": "2025-02-26T11:23:29.845Z",
"app/commerce-modules/order/order-versioning/page.mdx": "2025-08-21T15:31:58.563Z",