diff --git a/www/apps/book/app/learn/fundamentals/api-routes/middlewares/page.mdx b/www/apps/book/app/learn/fundamentals/api-routes/middlewares/page.mdx
index a8c9f8b371..68a0d068ba 100644
--- a/www/apps/book/app/learn/fundamentals/api-routes/middlewares/page.mdx
+++ b/www/apps/book/app/learn/fundamentals/api-routes/middlewares/page.mdx
@@ -1,3 +1,5 @@
+import { Table, CodeTabs, CodeTab } from "docs-ui"
+
export const metadata = {
title: `${pageNumber} Middlewares`,
}
@@ -12,6 +14,8 @@ A middleware is a function executed when a request is sent to an API Route. It's
Middlewares are used to guard API routes, parse request content types other than `application/json`, manipulate request data, and more.
+
+
As Medusa's server is based on Express, you can use any [Express middleware](https://expressjs.com/en/resources/middleware.html).
@@ -22,19 +26,59 @@ As Medusa's server is based on Express, you can use any [Express middleware](htt
There are two types of middlewares:
-1. Global Middleware: A middleware that applies to all routes matching a specified pattern.
-2. Route Middleware: A middleware that applies to routes matching a specified pattern and HTTP method(s).
+
+
+
+
+ Type
+
+
+ Description
+
+
+ Example
+
+
+
+
+
+
+ Global Middleware
+
+
+ A middleware that applies to all routes matching a specified pattern.
+
+
+ `/custom*` applies to all routes starting with `/custom`
+
+
+
+
+ Route Middleware
+
+
+ A middleware that applies to routes matching a specified pattern and HTTP method(s).
+
+
+ A middleware that applies to all `POST` requests to routes starting with `/custom`.
+
+
+
+
These middlewares generally have the same definition and usage, but they differ in the routes they apply to. You'll learn how to create both types in the following sections.
---
-## How to Create a Global Middleware?
+## How to Create a Middleware?
Middlewares of all types are defined in the special file `src/api/middlewares.ts`. Use the `defineMiddlewares` function from the Medusa Framework to define the middlewares, and export its value.
For example:
+
+
+
```ts title="src/api/middlewares.ts"
import {
defineMiddlewares,
@@ -63,46 +107,17 @@ export default defineMiddlewares({
})
```
-The `defineMiddlewares` function accepts a middleware configurations object that has the property `routes`. `routes`'s value is an array of middleware route objects, each having the following properties:
-
-- `matcher`: a string or regular expression indicating the API route path to apply the middleware on. The regular expression must be compatible with [path-to-regexp](https://github.com/pillarjs/path-to-regexp).
-- `middlewares`: An array of global and route middleware functions.
-
-In the example above, you define a global middleware that logs the message `Received a request!` whenever a request is sent to an API route path starting with `/custom`.
-
-### Test the Global Middleware
-
-To test the middleware:
-
-1. Start the application:
-
-```bash npm2yarn
-npm run dev
-```
-
-2. Send a request to any API route starting with `/custom`.
-3. See the following message in the terminal:
-
-```bash
-Received a request!
-```
-
----
-
-## How to Create a Route Middleware?
-
-In the previous section, you learned how to create a global middleware. You define the route middleware in the same way in `src/api/middlewares.ts`, but you specify an additional property `method` in the middleware route object. Its value is one or more HTTP methods to apply the middleware to.
-
-For example:
+
+
export const highlights = [["12", "method", "Apply the middleware only on `POST` requests"]]
-```ts title="src/api/middlewares.ts" highlights={highlights} collapsibleLines="1-7" expandButtonLabel="Show Imports"
+```ts title="src/api/middlewares.ts" highlights={highlights}
import {
+ defineMiddlewares,
MedusaNextFunction,
MedusaRequest,
MedusaResponse,
- defineMiddlewares,
} from "@medusajs/framework/http"
export default defineMiddlewares({
@@ -126,9 +141,16 @@ export default defineMiddlewares({
})
```
-This example applies the middleware only when a `POST` or `PUT` request is sent to an API route path starting with `/custom`, changing the middleware from a global middleware to a route middleware.
+
+
-### Test the Route Middleware
+The `defineMiddlewares` function accepts a middleware configurations object that has the property `routes`. `routes`'s value is an array of middleware route objects, each having the following properties:
+
+- `matcher`: a string or regular expression indicating the API route path to apply the middleware on. The regular expression must be compatible with [path-to-regexp](https://github.com/pillarjs/path-to-regexp).
+- `middlewares`: An array of global and route middleware functions.
+- `method`: (optional) By default, a middleware is applied on all HTTP methods for a route. You can specify one or more HTTP methods to apply the middleware to in this option, making it a route middleware.
+
+### Test the Middleware
To test the middleware:
@@ -138,7 +160,7 @@ To test the middleware:
npm run dev
```
-2. Send a `POST` request to any API route starting with `/custom`.
+2. Send a request to any API route starting with `/custom`. If you specified an HTTP method in the `method` property, make sure to use that method.
3. See the following message in the terminal:
```bash
@@ -149,12 +171,12 @@ Received a request!
## When to Use Middlewares
-
+Middlewares are useful for:
-- You want to protect API routes by a custom condition.
-- You're modifying the request body.
-
-
+- [Protecting API routes](../protected-routes/page.mdx) to ensure that only authenticated users can access them.
+- [Validating](../validation/page.mdx) request query and body parameters.
+- [Parsing](../parse-body/page.mdx) request content types other than `application/json`.
+- [Applying CORS](../cors/page.mdx) configurations to custom API routes.
---
@@ -172,12 +194,50 @@ You must call the `next` function in the middleware. Otherwise, other middleware
+For example:
+
+```ts title="src/api/middlewares.ts"
+import {
+ MedusaNextFunction,
+ MedusaRequest,
+ MedusaResponse,
+ defineMiddlewares,
+} from "@medusajs/framework/http"
+
+export default defineMiddlewares({
+ routes: [
+ {
+ matcher: "/custom*",
+ middlewares: [
+ (
+ req: MedusaRequest,
+ res: MedusaResponse,
+ next: MedusaNextFunction
+ ) => {
+ console.log("Received a request!", req.body)
+
+ next()
+ },
+ ],
+ },
+ ],
+})
+```
+
+This middleware logs the request body to the terminal, then calls the `next` function to execute the next middleware in the stack.
+
---
## Middleware for Routes with Path Parameters
To indicate a path parameter in a middleware's `matcher` pattern, use the format `:{param-name}`.
+
+
+A middleware applied on a route with path parameters is a route middleware.
+
+
+
For example:
export const pathParamHighlights = [["11", ":id", "Indicates that the API route accepts an `id` path parameter."]]
@@ -248,15 +308,19 @@ In general, avoid adding trailing backslashes when sending requests to API route
---
-## Middlewares and Route Ordering
+## How Are Middlewares Ordered and Applied?
-The ordering explained in this section was added in [Medusa v2.6](https://github.com/medusajs/medusa/releases/tag/v2.6)
+The information explained in this section is applicable starting from [Medusa v2.6](https://github.com/medusajs/medusa/releases/tag/v2.6).
-The Medusa application registers middlewares and API route handlers in the following order:
+### Middleware and Routes Execution Order
+
+The Medusa application registers middlewares and API route handlers in the following order, stacking them on top of each other:
+
+
1. Global middlewares in the following order:
1. Global middleware defined in the Medusa's core.
@@ -271,6 +335,48 @@ The Medusa application registers middlewares and API route handlers in the follo
2. API routes defined in the plugins (in the order the plugins are registered in).
3. API routes you define in the application.
+Then, when a request is sent to an API route, the stack is executed in order: global middlewares are executed first, then the route middlewares, and finally the route handlers.
+
+
+
+For example, consider you have the following middlewares:
+
+```ts title="src/api/middlewares.ts"
+export default defineMiddlewares({
+ routes: [
+ {
+ matcher: "/custom",
+ middlewares: [
+ (req, res, next) => {
+ console.log("Global middleware")
+ next()
+ },
+ ],
+ },
+ {
+ matcher: "/custom",
+ method: ["GET"],
+ middlewares: [
+ (req, res, next) => {
+ console.log("Route middleware")
+ next()
+ },
+ ],
+ },
+ ],
+})
+```
+
+When you send a request to `/custom` route, the following messages are logged in the terminal:
+
+```bash
+Global middleware
+Route middleware
+Hello from custom! # message logged from API route handler
+```
+
+The global middleware runs first, then the route middleware, and finally the route handler, assuming that it logs the message `Hello from custom!`.
+
### Middlewares Sorting
On top of the previous ordering, Medusa sorts global and route middlewares based on their matcher pattern in the following order:
@@ -317,50 +423,10 @@ And the route middlewares are sorted into the following order before they're reg
1. Route middleware `/custom*`.
2. Route middleware `/custom/:id`.
+
+
Then, the middlwares are registered in the order mentioned earlier, with global middlewares first, then the route middlewares.
-### Middlewares and Route Execution Order
-
-When a request is sent to an API route, the global middlewares are executed first, then the route middlewares, and finally the route handler.
-
-For example, consider you have the following middlewares:
-
-```ts title="src/api/middlewares.ts"
-export default defineMiddlewares({
- routes: [
- {
- matcher: "/custom",
- middlewares: [
- (req, res, next) => {
- console.log("Global middleware")
- next()
- },
- ],
- },
- {
- matcher: "/custom",
- method: ["GET"],
- middlewares: [
- (req, res, next) => {
- console.log("Route middleware")
- next()
- },
- ],
- },
- ],
-})
-```
-
-When you send a request to `/custom` route, the following messages are logged in the terminal:
-
-```bash
-Global middleware
-Route middleware
-Hello from custom! # message logged from API route handler
-```
-
-The global middleware runs first, then the route middleware, and finally the route handler, assuming that it logs the message `Hello from custom!`.
-
---
## Overriding Middlewares
@@ -368,3 +434,11 @@ The global middleware runs first, then the route middleware, and finally the rou
A middleware can not override an existing middleware. Instead, middlewares are added to the end of the middleware stack.
For example, if you define a custom validation middleware, such as `validateAndTransformBody`, on an existing route, then both the original and the custom validation middleware will run.
+
+Similarly, if you add an [authenticate](../protected-routes/page.mdx#protect-custom-api-routes) middleware to an existing route, both the original and the custom authentication middleware will run. So, you can't override the original authentication middleware.
+
+### Alternative Solution to Overriding Middlewares
+
+If you need to change the middlewares applied to a route, you can create a custom [API route](../page.mdx) that executes the same functionality as the original route, but with the middlewares you want.
+
+Learn more in the [Override API Routes](../override/page.mdx) chapter.
\ No newline at end of file
diff --git a/www/apps/book/app/learn/fundamentals/api-routes/override/page.mdx b/www/apps/book/app/learn/fundamentals/api-routes/override/page.mdx
new file mode 100644
index 0000000000..f01291e220
--- /dev/null
+++ b/www/apps/book/app/learn/fundamentals/api-routes/override/page.mdx
@@ -0,0 +1,135 @@
+import { Table } from "docs-ui"
+
+export const metadata = {
+ title: `${pageNumber} Override API Routes`,
+}
+
+# {metadata.title}
+
+In this chapter, you'll learn the approach recommended when you need to override an existing API route in Medusa.
+
+## Approaches to Consider Before Overriding API Routes
+
+While building customizations in your Medusa application, you may need to make changes to existing API routes for your business use case.
+
+Medusa provides the following approaches to customize API routes:
+
+
+
+
+
+ Approach
+
+
+ Description
+
+
+
+
+
+
+ [Pass Additional Data](../additional-data/page.mdx)
+
+
+ Pass custom data to the API route with custom validation.
+
+
+
+
+ [Perform Custom Logic within an Existing Flows](../../workflows/workflow-hooks/page.mdx)
+
+
+ API routes execute workflows to perform business logic, which may have hooks that allow you to perform custom logic.
+
+
+
+
+ [Use Custom Middlewares](../middlewares/page.mdx)
+
+
+ Use custom middlewares to perform custom logic before the API route is executed. However, you cannot remove or replace middlewares applied to existing API routes.
+
+
+
+
+ [Listen to Events in Subscribers](../../events-and-subscribers/page.mdx)
+
+
+ Functionalities in API routes may trigger events that you can handle in subscribers. This is useful if you're performing an action that isn't integral to the API route's core functionality or response.
+
+
+
+
+
+If the above approaches do not meet your needs, you can consider the approaches mentioned in the rest of this chapter.
+
+---
+
+## Replicate, Don't Override API Routes
+
+If the approaches mentioned in the [section above](#approaches-to-consider-before-overriding-api-routes) do not meet your needs, you can replicate an existing API route and modify it to suit your requirements.
+
+By replicating instead of overriding, the original API route remains intact, allowing you to easily revert to the original functionality if needed. You can also update your Medusa version without worrying about breaking changes in the original API route.
+
+---
+
+## How to Replicate an API Route?
+
+Medusa's API routes are generally slim and use logic contained in [workflows](../../workflows/page.mdx). So, creating a custom route based on the original route is straightforward.
+
+You can view the source code for Medusa's API routes in the [Medusa GitHub repository](https://github.com/medusajs/medusa/tree/develop/packages/medusa/src/api).
+
+For example, if you need to allow vendors to access the `POST /admin/products` API route, you can create an API route in your Medusa project at `src/api/vendor/products/route.ts` with the [same code as the original route](https://github.com/medusajs/medusa/blob/develop/packages/medusa/src/api/admin/products/route.ts#L88). Then, you can make changes to it or its middlewares.
+
+---
+
+## When to Replicate an API Route?
+
+Some examples of when you might want to replicate an API route include:
+
+
+
+
+
+ Use Case
+
+
+ Description
+
+
+
+
+
+
+ Custom Validation
+
+
+ You want to change the validation logic for a specific API route, and the [Additional Data](../additional-data/page.mdx) isn't sufficient or applicable.
+
+
+
+
+ Change Authentication
+
+
+ You want to remove required authentication for a specific API route, or you want to allow custom [actor types](!resources!/commerce-modules/auth/auth-identity-and-actor-types) to access existing protected API routes.
+
+
+
+
+ Custom Response
+
+
+ You want to change the response format of an existing API route.
+
+
+
+
+ Override Middleware
+
+
+ You want to override the middleware applied on existing API routes. Because of [how middlewares are ordered and applied](../middlewares/page.mdx#how-are-middlewares-ordered-and-applied), you can't remove or replace middlewares applied to existing API routes.
+
+
+
+
diff --git a/www/apps/book/app/learn/fundamentals/api-routes/protected-routes/page.mdx b/www/apps/book/app/learn/fundamentals/api-routes/protected-routes/page.mdx
index 16d5e11e31..18d5e5dbea 100644
--- a/www/apps/book/app/learn/fundamentals/api-routes/protected-routes/page.mdx
+++ b/www/apps/book/app/learn/fundamentals/api-routes/protected-routes/page.mdx
@@ -1,36 +1,102 @@
+import { Table } from "docs-ui"
+
export const metadata = {
- title: `${pageNumber} Protected Routes`,
+ title: `${pageNumber} Protected API Routes`,
}
# {metadata.title}
-In this chapter, you’ll learn how to create protected routes.
+In this chapter, you’ll learn how to create protected API routes.
-## What is a Protected Route?
+## What is a Protected API Route?
-A protected route is a route that requires requests to be user-authenticated before performing the route's functionality. Otherwise, the request fails, and the user is prevented access.
+By default, an API route is publicly accessible, meaning that any user can access it without authentication. This is useful for public API routes that allow users to browse products, view collections, and so on.
----
+A protected API route is an API route that requires requests to be user-authenticated before performing the route's functionality. Otherwise, the request fails, and the user is prevented access.
-## Default Protected Routes
-
-Medusa applies an authentication guard on routes starting with `/admin`, including custom API routes.
-
-Requests to `/admin` must be user-authenticated to access the route.
+Protected API routes are useful for routes that require user authentication, such as creating a product or managing an order. These routes must only be accessed by authenticated admin users.
-Refer to the API Reference for [Admin](!api!/admin#authentication) and [Store](!api!/store#authentication) authentication methods.
+Refer to the API Reference for [Admin](!api!/admin#authentication) and [Store](!api!/store#authentication) to learn how to send authenticated requests.
---
+## Default Protected Routes
+
+Any API route, including your custom API routes, are protected if they start with the following prefixes:
+
+
+
+Refer to the API Reference for [Admin](!api!/admin#authentication) and [Store](!api!/store#authentication) to learn how to send authenticated requests.
+
+### Opt-Out of Default Authentication Requirement
+
+If you create a custom API route under a prefix that is protected by default, you can opt-out of the authentication requirement by exporting an `AUTHENTICATE` variable in the route file with its value set to `false`.
+
+For example, to disable authentication requirement for a custom API route created at `/admin/custom`, you can export an `AUTHENTICATE` variable in the route file:
+
+```ts title="src/api/admin/custom/route.ts" highlights={[["15"]]}
+import type {
+ AuthenticatedMedusaRequest,
+ MedusaResponse,
+} from "@medusajs/framework/http"
+
+export const GET = async (
+ req: AuthenticatedMedusaRequest,
+ res: MedusaResponse
+) => {
+ res.json({
+ message: "Hello",
+ })
+}
+
+export const AUTHENTICATE = false
+```
+
+Now, any request sent to the `/admin/custom` API route is allowed, regardless if the admin user is authenticated.
+
+---
+
## Protect Custom API Routes
-To protect custom API Routes to only allow authenticated customer or admin users, use the `authenticate` middleware from the Medusa Framework.
+You can protect API routes using the `authenticate` [middleware](../middlewares/page.mdx) from the Medusa Framework. When applied to a route, the middleware checks that:
-For example:
+- The correct actor type (for example, `user`, `customer`, or a custom actor type) is authenticated.
+- The correct authentication method is used (for example, `session`, `bearer`, or `api-key`).
+
+For example, you can add the `authenticate` middleware in the `src/api/middlewares.ts` file to protect a custom API route:
export const highlights = [
[
@@ -119,111 +185,148 @@ export default defineMiddlewares({
})
```
+### Override Authentication for Medusa's API Routes
+
+In some cases, you may want to override the authentication requirement for Medusa's API routes. For example, you may want to allow custom actor types to access existing protected API routes.
+
+It's not possible to change the [authentication middleware](../middlewares/page.mdx) applied to an existing API route. Instead, you need to replicate the API route and apply the authentication middleware to it.
+
+Learn more in the [Override API Routes](../override/page.mdx) chapter.
+
---
-## Authentication Opt-Out
+## Access Authentication Details in API Routes
-To disable the authentication guard on custom routes under the `/admin` path prefix, export an `AUTHENTICATE` variable in the route file with its value set to `false`.
+To access the authentication details in an API route, such as the logged-in user's ID, set the type of the first request parameter to `AuthenticatedMedusaRequest`. It extends `MedusaRequest`:
-For example:
-
-```ts title="src/api/admin/custom/route.ts" highlights={[["15"]]}
-import type {
- AuthenticatedMedusaRequest,
+```ts highlights={[["7", "AuthenticatedMedusaRequest"]]}
+import type {
+ AuthenticatedMedusaRequest,
MedusaResponse,
} from "@medusajs/framework/http"
export const GET = async (
- req: AuthenticatedMedusaRequest,
+ req: AuthenticatedMedusaRequest,
res: MedusaResponse
) => {
- res.json({
- message: "Hello",
- })
+ // ...
}
-
-export const AUTHENTICATE = false
```
-Now, any request sent to the `/admin/custom` API route is allowed, regardless if the admin user is authenticated.
-
----
-
-## Authenticated Request Type
-
-To access the authentication details in an API route, such as the logged-in user's ID, set the type of the first request parameter to `AuthenticatedMedusaRequest`. It extends `MedusaRequest`.
-
The `auth_context.actor_id` property of `AuthenticatedMedusaRequest` holds the ID of the authenticated user or customer. If there isn't any authenticated user or customer, `auth_context` is `undefined`.
+For example:
+
+```ts title="src/api/store/custom/route.ts" highlights={[["10", "actor_id"]]}
+import type {
+ AuthenticatedMedusaRequest,
+ MedusaResponse,
+} from "@medusajs/framework/http"
+
+export const GET = async (
+ req: AuthenticatedMedusaRequest,
+ res: MedusaResponse
+) => {
+ const id = req.auth_context?.actor_id
+
+ // ...
+}
+```
+
+In this example, you retrieve the ID of the authenticated user, customer, or custom actor type from the `auth_context` property of the `AuthenticatedMedusaRequest` object.
+
-If you opt-out of authentication in a route as mentioned in the [previous section](#authentication-opt-out), you can't access the authenticated user or customer anymore. Use the [authenticate middleware](#protect-custom-api-routes) instead.
+If you opt-out of authentication in a route as mentioned in the [Opt-Out section](#opt-out-of-default-authentication-requirement), you can't access the authenticated user or customer anymore. Use the [authenticate middleware](#protect-custom-api-routes) instead to protect the route.
### Retrieve Logged-In Customer's Details
-You can access the logged-in customer’s ID in all API routes starting with `/store` using the `auth_context.actor_id` property of the `AuthenticatedMedusaRequest` object.
+You can access the logged-in customer’s ID in all API routes starting with `/store` using the `auth_context.actor_id` property of the `AuthenticatedMedusaRequest` object. You can then use [Query](../../module-links/query/page.mdx) to retrieve the customer details, or pass the ID to a [workflow](../../workflows/page.mdx) that performs business logic.
For example:
-```ts title="src/api/store/custom/route.ts" highlights={[["19", "req.auth_context.actor_id", "Access the logged-in customer's ID."]]} collapsibleLines="1-7" expandButtonLabel="Show Imports"
+export const customerHighlights = [
+ ["10", "customerId", "Retrieve the logged-in customer's ID."],
+ ["13", "query", "Retrieve the customer details."],
+ ["20", "throwIfKeyNotFound", "Throw an error if the customer with\nthe specified ID is not found."],
+]
+
+```ts title="src/api/store/custom/route.ts" highlights={customerHighlights}
import type {
AuthenticatedMedusaRequest,
MedusaResponse,
} from "@medusajs/framework/http"
-import { Modules } from "@medusajs/framework/utils"
-import { ICustomerModuleService } from "@medusajs/framework/types"
export const GET = async (
req: AuthenticatedMedusaRequest,
res: MedusaResponse
) => {
- if (req.auth_context?.actor_id) {
- // retrieve customer
- const customerModuleService: ICustomerModuleService = req.scope.resolve(
- Modules.CUSTOMER
- )
+ const customerId = req.auth_context?.actor_id
+ const query = req.scope.resolve("query")
- const customer = await customerModuleService.retrieveCustomer(
- req.auth_context.actor_id
- )
- }
+ const { data: [customer] } = await query.graph({
+ entity: "customer",
+ fields: ["*"],
+ filters: {
+ id: customerId,
+ },
+ }, {
+ throwIfKeyNotFound: true,
+ })
- // ...
+ // do something with the customer data...
}
```
-In this example, you resolve the Customer Module's main service, then use it to retrieve the logged-in customer, if available.
+In this example, you retrieve the customer's ID and resolve Query from the [Medusa container](../../medusa-container/page.mdx).
+
+Then, you use Query to retrieve the customer details. The `throwIfKeyNotFound` option throws an error if the customer with the specified ID is not found.
+
+After that, you can use the customer's details in your API route.
### Retrieve Logged-In Admin User's Details
-You can access the logged-in admin user’s ID in all API Routes starting with `/admin` using the `auth_context.actor_id` property of the `AuthenticatedMedusaRequest` object.
+You can access the logged-in admin user’s ID in all API routes starting with `/admin` using the `auth_context.actor_id` property of the `AuthenticatedMedusaRequest` object. You can then use [Query](../../module-links/query/page.mdx) to retrieve the user details, or pass the ID to a [workflow](../../workflows/page.mdx) that performs business logic.
For example:
-```ts title="src/api/admin/custom/route.ts" highlights={[["17", "req.auth_context.actor_id", "Access the logged-in admin user's ID."]]} collapsibleLines="1-7" expandButtonLabel="Show Imports"
+export const adminHighlights = [
+ ["10", "userId", "Retrieve the logged-in admin user's ID."],
+ ["13", "query", "Retrieve the user details."],
+ ["20", "throwIfKeyNotFound", "Throw an error if the user with\nthe specified ID is not found."],
+]
+
+```ts title="src/api/admin/custom/route.ts" highlights={adminHighlights}
import type {
AuthenticatedMedusaRequest,
MedusaResponse,
} from "@medusajs/framework/http"
-import { Modules } from "@medusajs/framework/utils"
-import { IUserModuleService } from "@medusajs/framework/types"
export const GET = async (
req: AuthenticatedMedusaRequest,
res: MedusaResponse
) => {
- const userModuleService: IUserModuleService = req.scope.resolve(
- Modules.USER
- )
+ const userId = req.auth_context?.actor_id
+ const query = req.scope.resolve("query")
- const user = await userModuleService.retrieveUser(
- req.auth_context.actor_id
- )
+ const { data: [user] } = await query.graph({
+ entity: "user",
+ fields: ["*"],
+ filters: {
+ id: userId,
+ },
+ }, {
+ throwIfKeyNotFound: true,
+ })
- // ...
+ // do something with the user data...
}
```
-In the route handler, you resolve the User Module's main service, then use it to retrieve the logged-in admin user.
+In this example, you retrieve the admin user's ID and resolve Query from the [Medusa container](../../medusa-container/page.mdx).
+
+Then, you use Query to retrieve the user details. The `throwIfKeyNotFound` option throws an error if the user with the specified ID is not found.
+
+After that, you can use the user's details in your API route.
diff --git a/www/apps/book/generated/edit-dates.mjs b/www/apps/book/generated/edit-dates.mjs
index 13dcc4b39a..b7f6040a21 100644
--- a/www/apps/book/generated/edit-dates.mjs
+++ b/www/apps/book/generated/edit-dates.mjs
@@ -22,7 +22,7 @@ export const generatedEditDates = {
"app/learn/fundamentals/admin/widgets/page.mdx": "2024-12-09T16:43:24.260Z",
"app/learn/fundamentals/data-models/page.mdx": "2025-03-18T07:55:56.252Z",
"app/learn/fundamentals/modules/remote-link/page.mdx": "2024-09-30T08:43:53.127Z",
- "app/learn/fundamentals/api-routes/protected-routes/page.mdx": "2025-03-17T11:47:10.101Z",
+ "app/learn/fundamentals/api-routes/protected-routes/page.mdx": "2025-05-09T07:57:32.929Z",
"app/learn/fundamentals/workflows/add-workflow-hook/page.mdx": "2024-12-09T14:42:39.693Z",
"app/learn/fundamentals/events-and-subscribers/data-payload/page.mdx": "2025-05-01T15:30:08.421Z",
"app/learn/fundamentals/workflows/advanced-example/page.mdx": "2024-09-11T10:46:59.975Z",
@@ -46,7 +46,7 @@ export const generatedEditDates = {
"app/learn/fundamentals/admin/tips/page.mdx": "2025-03-11T08:54:12.028Z",
"app/learn/fundamentals/api-routes/cors/page.mdx": "2025-03-11T08:54:26.281Z",
"app/learn/fundamentals/admin/ui-routes/page.mdx": "2025-02-24T09:35:11.752Z",
- "app/learn/fundamentals/api-routes/middlewares/page.mdx": "2025-03-24T06:43:02.362Z",
+ "app/learn/fundamentals/api-routes/middlewares/page.mdx": "2025-05-09T07:56:04.125Z",
"app/learn/fundamentals/modules/isolation/page.mdx": "2024-12-09T11:02:38.087Z",
"app/learn/fundamentals/data-models/index/page.mdx": "2025-03-18T07:59:07.798Z",
"app/learn/fundamentals/custom-cli-scripts/page.mdx": "2024-10-23T07:08:55.898Z",
@@ -119,5 +119,6 @@ export const generatedEditDates = {
"app/learn/fundamentals/data-models/properties/page.mdx": "2025-03-18T07:57:17.826Z",
"app/learn/fundamentals/framework/page.mdx": "2025-04-25T14:26:25.000Z",
"app/learn/fundamentals/api-routes/retrieve-custom-links/page.mdx": "2025-04-25T14:26:25.000Z",
- "app/learn/fundamentals/workflows/errors/page.mdx": "2025-04-25T14:26:25.000Z"
+ "app/learn/fundamentals/workflows/errors/page.mdx": "2025-04-25T14:26:25.000Z",
+ "app/learn/fundamentals/api-routes/override/page.mdx": "2025-05-09T08:01:24.493Z"
}
\ No newline at end of file
diff --git a/www/apps/book/generated/sidebar.mjs b/www/apps/book/generated/sidebar.mjs
index 32c777edd8..63108bfcf1 100644
--- a/www/apps/book/generated/sidebar.mjs
+++ b/www/apps/book/generated/sidebar.mjs
@@ -642,6 +642,16 @@ export const generatedSidebars = [
"children": [],
"chapterTitle": "3.6.11. Retrieve Custom Links",
"number": "3.6.11."
+ },
+ {
+ "loaded": true,
+ "isPathHref": true,
+ "type": "link",
+ "path": "/learn/fundamentals/api-routes/override",
+ "title": "Override API Routes",
+ "children": [],
+ "chapterTitle": "3.6.12. Override API Routes",
+ "number": "3.6.12."
}
],
"chapterTitle": "3.6. API Routes",
diff --git a/www/apps/book/public/llms-full.txt b/www/apps/book/public/llms-full.txt
index 5c737d99dc..92cd5a5e97 100644
--- a/www/apps/book/public/llms-full.txt
+++ b/www/apps/book/public/llms-full.txt
@@ -141,6 +141,76 @@ The next chapter covers how you generally deploy the production build.
You can also refer to the [deployment how-to guides](https://docs.medusajs.com/resources/deployment/index.html.md) for platform-specific how-to guides.
+# Medusa Deployment Overview
+
+In this chapter, you’ll learn the general approach to deploying the Medusa application.
+
+## Medusa Project Components
+
+A standard Medusa project is made up of:
+
+- Medusa application: The Medusa server and the Medusa Admin.
+- One or more storefronts
+
+
+
+You deploy the Medusa application, with the server and admin, separately from the storefront.
+
+***
+
+## Deploying the Medusa Application
+
+You must deploy the Medusa application before the storefront, as it connects to the server and won’t work without a deployed Medusa server URL.
+
+The Medusa application must be deployed to a hosting provider supporting Node.js server deployments, such as Railway, DigitalOcean, AWS, Heroku, etc…
+
+
+
+Your server connects to a PostgreSQL database, Redis, and other services relevant for your setup. Most hosting providers support deploying and managing these databases along with your Medusa server (such as Railway and DigitalOcean).
+
+When you deploy your Medusa application, you also deploy the Medusa Admin. For optimal experience, your hosting provider and plan must offer at least 2GB of RAM.
+
+### Deploy Server and Worker Instances
+
+By default, Medusa runs all processes in a single instance. This includes the server that handles incoming requests and the worker that processes background tasks. While this works for development, it’s not optimal for production environments as many background tasks can be long-running or resource-heavy.
+
+Instead, you should deploy two instances:
+
+- A server instance, which handles incoming requests to the application’s API routes.
+- A worker instance, which processes background tasks, including scheduled jobs and subscribers.
+
+You don’t need to set up different projects for each instance. Instead, you can configure the Medusa application to run in different modes based on environment variables.
+
+Learn more about worker modes and how to configure them in the [Worker Mode chapter](https://docs.medusajs.com/learn/production/worker-mode/index.html.md).
+
+### How to Deploy Medusa?
+
+Medusa Cloud is our managed services offering that makes deploying and operating Medusa applications possible without having to worry about configuring, scaling, and maintaining infrastructure. Medusa Cloud hosts your server, Admin dashboard, database, and Redis instance.
+
+With Medusa Cloud, you maintain full customization control as you deploy your own modules and customizations directly from GitHub:
+
+- Push to deploy.
+- Multiple testing environments.
+- Preview environments for new PRs.
+- Test on production-like data.
+
+[Sign up and learn more about Medusa Cloud](https://medusajs.com/pricing)
+
+To self-host Medusa, the [next chapter](https://docs.medusajs.com/learn/deployment/general/index.html.md) explains the general steps to deploy your Medusa application. Refer to [this reference](https://docs.medusajs.com/resources/deployment/index.html.md) to find how-to deployment guides for general and specific hosting providers.
+
+***
+
+## Deploying the Storefront
+
+The storefront is deployed separately from the Medusa application, and the hosting options depend on the tools and frameworks you use to create the storefront.
+
+If you’re using the Next.js Starter storefront, you may deploy the storefront to any hosting provider that supports frontend frameworks, such as Vercel.
+
+Per Vercel’s [license and plans](https://vercel.com/pricing), their free plan can only be used for personal, non-commercial projects. So, you can deploy the storefront on the free plan for development purposes, but for commercial projects, you must update your Vercel plan.
+
+Refer to [this reference](https://docs.medusajs.com/resources/deployment/index.html.md) to find how-to deployment guides for specific hosting providers.
+
+
# Install Medusa
In this chapter, you'll learn how to install and run a Medusa application.
@@ -275,76 +345,6 @@ Refer to [this documentation](https://docs.medusajs.com/learn/update/index.html.
In the next chapters, you'll learn about the architecture of your Medusa application, then learn how to customize your application to build custom features.
-# Medusa Deployment Overview
-
-In this chapter, you’ll learn the general approach to deploying the Medusa application.
-
-## Medusa Project Components
-
-A standard Medusa project is made up of:
-
-- Medusa application: The Medusa server and the Medusa Admin.
-- One or more storefronts
-
-
-
-You deploy the Medusa application, with the server and admin, separately from the storefront.
-
-***
-
-## Deploying the Medusa Application
-
-You must deploy the Medusa application before the storefront, as it connects to the server and won’t work without a deployed Medusa server URL.
-
-The Medusa application must be deployed to a hosting provider supporting Node.js server deployments, such as Railway, DigitalOcean, AWS, Heroku, etc…
-
-
-
-Your server connects to a PostgreSQL database, Redis, and other services relevant for your setup. Most hosting providers support deploying and managing these databases along with your Medusa server (such as Railway and DigitalOcean).
-
-When you deploy your Medusa application, you also deploy the Medusa Admin. For optimal experience, your hosting provider and plan must offer at least 2GB of RAM.
-
-### Deploy Server and Worker Instances
-
-By default, Medusa runs all processes in a single instance. This includes the server that handles incoming requests and the worker that processes background tasks. While this works for development, it’s not optimal for production environments as many background tasks can be long-running or resource-heavy.
-
-Instead, you should deploy two instances:
-
-- A server instance, which handles incoming requests to the application’s API routes.
-- A worker instance, which processes background tasks, including scheduled jobs and subscribers.
-
-You don’t need to set up different projects for each instance. Instead, you can configure the Medusa application to run in different modes based on environment variables.
-
-Learn more about worker modes and how to configure them in the [Worker Mode chapter](https://docs.medusajs.com/learn/production/worker-mode/index.html.md).
-
-### How to Deploy Medusa?
-
-Medusa Cloud is our managed services offering that makes deploying and operating Medusa applications possible without having to worry about configuring, scaling, and maintaining infrastructure. Medusa Cloud hosts your server, Admin dashboard, database, and Redis instance.
-
-With Medusa Cloud, you maintain full customization control as you deploy your own modules and customizations directly from GitHub:
-
-- Push to deploy.
-- Multiple testing environments.
-- Preview environments for new PRs.
-- Test on production-like data.
-
-[Sign up and learn more about Medusa Cloud](https://medusajs.com/pricing)
-
-To self-host Medusa, the [next chapter](https://docs.medusajs.com/learn/deployment/general/index.html.md) explains the general steps to deploy your Medusa application. Refer to [this reference](https://docs.medusajs.com/resources/deployment/index.html.md) to find how-to deployment guides for general and specific hosting providers.
-
-***
-
-## Deploying the Storefront
-
-The storefront is deployed separately from the Medusa application, and the hosting options depend on the tools and frameworks you use to create the storefront.
-
-If you’re using the Next.js Starter storefront, you may deploy the storefront to any hosting provider that supports frontend frameworks, such as Vercel.
-
-Per Vercel’s [license and plans](https://vercel.com/pricing), their free plan can only be used for personal, non-commercial projects. So, you can deploy the storefront on the free plan for development purposes, but for commercial projects, you must update your Vercel plan.
-
-Refer to [this reference](https://docs.medusajs.com/resources/deployment/index.html.md) to find how-to deployment guides for specific hosting providers.
-
-
# 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.
@@ -473,133 +473,951 @@ npm install
```
-# Customize Medusa Admin Dashboard
+# Medusa Application Configuration
-In the previous chapters, you've customized your Medusa application to [add brands](https://docs.medusajs.com/learn/customization/custom-features/module/index.html.md), [expose an API route to create brands](https://docs.medusajs.com/learn/customization/custom-features/api-route/index.html.md), and [linked brands to products](https://docs.medusajs.com/learn/customization/extend-features/define-link/index.html.md).
+In this chapter, you'll learn available configurations in the Medusa application. You can change the application's configurations to customize the behavior of the application, its integrated modules and plugins, and more.
-After customizing and extending your application with new features, you may need to provide an interface for admin users to utilize these features. The Medusa Admin dashboard is extendable, allowing you to:
+## Configuration File
-- Insert components, called [widgets](https://docs.medusajs.com/learn/fundamentals/admin/widgets/index.html.md), on existing pages.
-- Add new pages, called [UI Routes](https://docs.medusajs.com/learn/fundamentals/admin/ui-routes/index.html.md).
+All configurations of the Medusa application are stored in the `medusa.config.ts` file. The file exports an object created using the `defineConfig` utility. For example:
-From these customizations, you can send requests to custom API routes, allowing admin users to manage custom resources on the dashboard
+```ts title="medusa.config.ts"
+import { loadEnv, defineConfig } from "@medusajs/framework/utils"
+
+loadEnv(process.env.NODE_ENV || "development", process.cwd())
+
+module.exports = defineConfig({
+ projectConfig: {
+ databaseUrl: process.env.DATABASE_URL,
+ http: {
+ storeCors: process.env.STORE_CORS!,
+ adminCors: process.env.ADMIN_CORS!,
+ authCors: process.env.AUTH_CORS!,
+ jwtSecret: process.env.JWT_SECRET || "supersecret",
+ cookieSecret: process.env.COOKIE_SECRET || "supersecret",
+ },
+ },
+})
+
+```
+
+The `defineConfig` utility accepts an object having the following properties:
+
+- [projectConfig](#project-configurations-projectConfig): Essential configurations related to the Medusa application, such as database and CORS configurations.
+- [admin](#admin-configurations-admin): Configurations related to the Medusa Admin.
+- [modules](#module-configurations-modules): Configurations related to registered modules.
+- [plugins](#plugin-configurations-plugins): Configurations related to registered plugins.
+- [featureFlags](#feature-flags-featureFlags): Configurations to manage enabled beta features in the Medusa application.
+
+### Using Environment Variables
+
+Notice that you use the `loadEnv` utility to load environment variables. Learn more about it in the [Environment Variables chapter](https://docs.medusajs.com/learn/fundamentals/environment-variables/index.html.md).
+
+By using this utility, you can use environment variables as the values of your configurations. It's highly recommended that you use environment variables for secret values, such as API keys and database credentials, or for values that change based on the environment, such as the application's Cross Origin Resource Sharing (CORS) configurations.
+
+For example, you can set the `DATABASE_URL` environment variable in your `.env` file:
+
+```bash
+DATABASE_URL=postgres://postgres@localhost/medusa-store
+```
+
+Then, use the value in `medusa-config.ts`:
+
+```ts title="medusa-config.ts"
+module.exports = defineConfig({
+ projectConfig: {
+ databaseUrl: process.env.DATABASE_URL,
+ // ...
+ },
+ // ...
+})
+```
***
-## Next Chapters: View Brands in Dashboard
+## Project Configurations (`projectConfig`)
-In the next chapters, you'll continue with the brands example to:
+The `projectConfig` object contains essential configurations related to the Medusa application, such as database and CORS configurations.
-- Add a new section to the product details page that shows the product's brand.
-- Add a new page in the dashboard that shows all brands in the store.
+### databaseDriverOptions
+The `projectConfig.databaseDriverOptions` configuration is an object of additional options used to configure the PostgreSQL connection. For example, you can support TLS/SSL connection using this configuration's `ssl` property.
-# Extend Core Commerce Features
+This configuration is useful for production databases, which can be supported by setting the `rejectUnauthorized` attribute of `ssl` object to `false`. During development, it's recommended not to pass the `ssl.rejectUnauthorized` option.
-In the upcoming chapters, you'll learn about the concepts and tools to extend Medusa's core commerce features.
+#### Example
-In other commerce platforms, you extend core features and models through hacky workarounds that can introduce unexpected issues and side effects across the platform. It also makes your application difficult to maintain and upgrade in the long run.
+```ts title="medusa-config.ts"
+module.exports = defineConfig({
+ projectConfig: {
+ databaseDriverOptions: process.env.NODE_ENV !== "development" ?
+ { connection: { ssl: { rejectUnauthorized: false } } } : {},
+ // ...
+ },
+ // ...
+})
+```
-The Medusa Framework and orchestration tools mitigate these issues while supporting all your customization needs:
+When you disable `rejectUnauthorized`, make sure to also add `?ssl_mode=disable` to the end of the [databaseUrl](#databaseUrl) as well.
-- [Module Links](https://docs.medusajs.com/learn/fundamentals/module-links/index.html.md): Link data models of different modules without building direct dependencies, ensuring that the Medusa application integrates your modules without side effects.
-- [Workflow Hooks](https://docs.medusajs.com/learn/fundamentals/workflows/workflow-hooks/index.html.md): inject custom functionalities into a workflow at predefined points, called hooks. This allows you to perform custom actions as a part of a core workflow without hacky workarounds.
-- [Additional Data in API Routes](https://docs.medusajs.com/learn/fundamentals/api-routes/additional-data/index.html.md): Configure core API routes to accept request parameters relevant to your customizations. These parameters are passed to the underlying workflow's hooks, where you can manage your custom data as part of an existing flow.
+#### Properties
+
+- connection: (\`object\`)
+
+ - ssl: (\`object\` | \`boolean\`)
+
+ - pool: (\`object\`)
+
+ - min: (\`number\`)
+
+ - max: (\`number\`)
+
+ - idleTimeoutMillis: (\`number\`)
+
+ - reapIntervalMillis: (\`number\`)
+
+ - createRetryIntervalMillis: (\`number\`)
+- idle\_in\_transaction\_session\_timeout: (\`number\`)
+
+### databaseLogging
+
+The `projectConfig.databaseLogging` configuration specifies whether database messages should be logged to the console. It is `false` by default.
+
+#### Example
+
+```ts title="medusa-config.ts"
+module.exports = defineConfig({
+ projectConfig: {
+ databaseLogging: true,
+ // ...
+ },
+ // ...
+})
+```
+
+### databaseName
+
+The `projectConfig.databaseName` configuration determines the name of the database to connect to. If the name is specified in the [databaseUrl](#databaseUrl) configuration, you don't have to use this configuration.
+
+After setting the database credentials, you can create and setup the database using the [db:setup](https://docs.medusajs.com/resources/medusa-cli/commands/db#dbsetup/index.html.md) command of the Medusa CLI.
+
+#### Example
+
+```ts title="medusa-config.ts"
+module.exports = defineConfig({
+ projectConfig: {
+ databaseName: process.env.DATABASE_NAME ||
+ "medusa-store",
+ // ...
+ },
+ // ...
+})
+```
+
+### databaseSchema
+
+The `projectConfig.databaseSchema` configuration specifies the PostgreSQL database schema to connect to, which is `public` by default. Use this configuration only if you want to connect to a different schema.
+
+#### Example
+
+```ts title="medusa-config.ts"
+module.exports = defineConfig({
+ projectConfig: {
+ databaseSchema: process.env.DATABASE_SCHEMA ||
+ "custom",
+ // ...
+ },
+ // ...
+})
+```
+
+### databaseUrl
+
+The `projectConfig.databaseUrl` configuration specifies the PostgreSQL connection URL of the database to connect to. Its format is:
+
+```bash
+postgres://[user][:password]@[host][:port]/[dbname]
+```
+
+Where:
+
+- `[user]`: (required) your PostgreSQL username. If not specified, the system's username is used by default. The database user that you use must have create privileges. If you're using the `postgres` superuser, then it should have these privileges by default. Otherwise, make sure to grant your user create privileges. You can learn how to do that in [PostgreSQL's documentation](https://www.postgresql.org/docs/current/ddl-priv.html).
+- `[:password]`: an optional password for the user. When provided, make sure to put `:` before the password.
+- `[host]`: (required) your PostgreSQL host. When run locally, it should be `localhost`.
+- `[:port]`: an optional port that the PostgreSQL server is listening on. By default, it's `5432`. When provided, make sure to put `:` before the port.
+- `[dbname]`: the name of the database. If not set, then you must provide the database name in the [databaseName](#databasename) configuration.
+
+You can learn more about the connection URL format in [PostgreSQL’s documentation](https://www.postgresql.org/docs/current/libpq-connect.html).
+
+After setting the database URL, you can create and setup the database using the [db:setup](https://docs.medusajs.com/resources/medusa-cli/commands/db#dbsetup/index.html.md) command of the Medusa CLI.
+
+#### Example
+
+For example, set the following database URL in your environment variables:
+
+```bash
+DATABASE_URL=postgres://postgres@localhost/medusa-store
+```
+
+Then, use the value in `medusa-config.ts`:
+
+```ts title="medusa-config.ts"
+module.exports = defineConfig({
+ projectConfig: {
+ databaseUrl: process.env.DATABASE_URL,
+ // ...
+ },
+ // ...
+})
+```
+
+### http
+
+The `http` configures the application's http-specific settings, such as the JWT secret, CORS configurations, and more.
+
+#### http.jwtSecret
+
+The `projectConfig.http.jwtSecret` configuration is a random string used to create authentication tokens in the HTTP layer. This configuration is not required in development, but must be set in production.
+
+In a development environment, if this option is not set the default value is `supersecret`. However, in production, if this configuration is not set, an error is thrown and the application crashes. This is to ensure that you set a secure value for the JWT secret in production.
+
+#### Example
+
+```ts title="medusa-config.ts"
+module.exports = defineConfig({
+ projectConfig: {
+ http: {
+ jwtSecret: process.env.JWT_SECRET || "supersecret",
+ },
+ // ...
+ },
+ // ...
+})
+```
+
+#### http.jwtExpiresIn
+
+The `projectConfig.http.jwtExpiresIn` configuration specifies the expiration time for the JWT token. Its value format is based off the [ms package](https://github.com/vercel/ms).
+
+If not provided, the default value is `1d`.
+
+#### Example
+
+```ts title="medusa-config.ts"
+module.exports = defineConfig({
+ projectConfig: {
+ http: {
+ jwtExpiresIn: process.env.JWT_EXPIRES_IN || "2d",
+ },
+ // ...
+ },
+ // ...
+})
+```
+
+#### http.cookieSecret
+
+The `projectConfig.http.cookieSecret` configuration is a random string used to sign cookies in the HTTP layer. This configuration is not required in development, but must be set in production.
+
+In a development environment, if this option is not set the default value is `supersecret`. However, in production, if this configuration is not set, an error is thrown and the application crashes. This is to ensure that you set a secure value for the cookie secret in production.
+
+#### Example
+
+```ts title="medusa-config.ts"
+module.exports = defineConfig({
+ projectConfig: {
+ http: {
+ cookieSecret: process.env.COOKIE_SECRET || "supersecret",
+ },
+ // ...
+ },
+ // ...
+})
+```
+
+#### http.authCors
+
+The `projectConfig.http.authCors` configuration specifies the accepted URLs or patterns for API routes starting with `/auth`. It can either be one accepted origin, or a comma-separated list of accepted origins.
+
+Every origin in that list must either be:
+
+- A full URL. For example, `http://localhost:7001`. The URL must not end with a backslash;
+- Or a regular expression pattern that can match more than one origin. For example, `.example.com`. The regex pattern that Medusa tests for is `^([\/~@;%#'])(.*?)\1([gimsuy]*)$`.
+
+Since the `/auth` routes are used for authentication for both store and admin routes, it's recommended to set this configuration's value to a combination of the [storeCors](#httpstoreCors) and [adminCors](#httpadminCors) configurations.
+
+Some example values of common use cases:
+
+```bash
+# Allow different ports locally starting with 700
+AUTH_CORS=/http:\/\/localhost:700\d+$/
+
+# Allow any origin ending with vercel.app. For example, admin.vercel.app
+AUTH_CORS=/vercel\.app$/
+
+# Allow all HTTP requests
+AUTH_CORS=/http:\/\/.+/
+```
+
+Then, set the configuration in `medusa-config.ts`:
+
+```ts title="medusa-config.ts"
+module.exports = defineConfig({
+ projectConfig: {
+ http: {
+ authCors: process.env.AUTH_CORS,
+ },
+ // ...
+ },
+ // ...
+})
+```
+
+If you’re adding the value directly within `medusa-config.ts`, make sure to add an extra escaping `/` for every backslash in the pattern. For example:
+
+```ts title="medusa-config.ts"
+module.exports = defineConfig({
+ projectConfig: {
+ http: {
+ authCors: "/http:\\/\\/localhost:700\\d+$/",
+ },
+ // ...
+ },
+ // ...
+})
+```
+
+#### http.storeCors
+
+The `projectConfig.http.storeCors` configuration specifies the accepted URLs or patterns for API routes starting with `/store`. It can either be one accepted origin, or a comma-separated list of accepted origins.
+
+Every origin in that list must either be:
+
+- A full URL. For example, `http://localhost:7001`. The URL must not end with a backslash;
+- Or a regular expression pattern that can match more than one origin. For example, `.example.com`. The regex pattern that Medusa tests for is `^([\/~@;%#'])(.*?)\1([gimsuy]*)$`.
+
+Some example values of common use cases:
+
+```bash
+# Allow different ports locally starting with 800
+STORE_CORS=/http:\/\/localhost:800\d+$/
+
+# Allow any origin ending with vercel.app. For example, storefront.vercel.app
+STORE_CORS=/vercel\.app$/
+
+# Allow all HTTP requests
+STORE_CORS=/http:\/\/.+/
+```
+
+Then, set the configuration in `medusa-config.ts`:
+
+```ts title="medusa-config.ts"
+module.exports = defineConfig({
+ projectConfig: {
+ http: {
+ storeCors: process.env.STORE_CORS,
+ },
+ // ...
+ },
+ // ...
+})
+```
+
+If you’re adding the value directly within `medusa-config.ts`, make sure to add an extra escaping `/` for every backslash in the pattern. For example:
+
+```ts title="medusa-config.ts"
+module.exports = defineConfig({
+ projectConfig: {
+ http: {
+ storeCors: "/vercel\\.app$/",
+ },
+ // ...
+ },
+ // ...
+})
+```
+
+#### http.adminCors
+
+The `projectConfig.http.adminCors` configuration specifies the accepted URLs or patterns for API routes starting with `/admin`. It can either be one accepted origin, or a comma-separated list of accepted origins.
+
+Every origin in that list must either be:
+
+- A full URL. For example, `http://localhost:7001`. The URL must not end with a backslash;
+- Or a regular expression pattern that can match more than one origin. For example, `.example.com`. The regex pattern that Medusa tests for is `^([\/~@;%#'])(.*?)\1([gimsuy]*)$`.
+
+Some example values of common use cases:
+
+```bash
+# Allow different ports locally starting with 700
+ADMIN_CORS=/http:\/\/localhost:700\d+$/
+
+# Allow any origin ending with vercel.app. For example, admin.vercel.app
+ADMIN_CORS=/vercel\.app$/
+
+# Allow all HTTP requests
+ADMIN_CORS=/http:\/\/.+/
+```
+
+Then, set the configuration in `medusa-config.ts`:
+
+```ts title="medusa-config.ts"
+module.exports = defineConfig({
+ projectConfig: {
+ http: {
+ adminCors: process.env.ADMIN_CORS,
+ },
+ // ...
+ },
+ // ...
+})
+```
+
+If you’re adding the value directly within `medusa-config.ts`, make sure to add an extra escaping `/` for every backslash in the pattern. For example:
+
+```ts title="medusa-config.ts"
+module.exports = defineConfig({
+ projectConfig: {
+ http: {
+ adminCors: "/vercel\\.app$/",
+ },
+ // ...
+ },
+ // ...
+})
+```
+
+#### http.compression
+
+The `projectConfig.http.compression` configuration modifies the HTTP compression settings at the application layer. If you have access to the HTTP server, the recommended approach would be to enable it there. However, some platforms don't offer access to the HTTP layer and in those cases, this is a good alternative.
+
+If you enable HTTP compression and you want to disable it for specific API Routes, you can pass in the request header `"x-no-compression": true`. Learn more in the [API Reference](https://docs.medusajs.com/api/store#http-compression).
+
+For example:
+
+```ts title="medusa-config.ts"
+module.exports = defineConfig({
+ projectConfig: {
+ http: {
+ compression: {
+ enabled: true,
+ level: 6,
+ memLevel: 8,
+ threshold: 1024,
+ },
+ },
+ // ...
+ },
+ // ...
+})
+```
+
+This configuation is an object that accepts the following properties:
+
+- enabled: (\`boolean\`)
+- level: (\`number\`) The level of zlib compression to apply to responses. A higher level will result in better compression but will take longer to complete. A lower level will result in less compression but will be much faster.
+- memLevel: (\`number\`) How much memory should be allocated to the internal compression state. It value is between \`1\` (minimum level) and \`9\` (maximum level).
+- threshold: (\`number\` | \`string\`) The minimum response body size that compression is applied on. Its value can be the number of bytes or any string accepted by the \[bytes]\(https://www.npmjs.com/package/bytes) package.
+
+#### http.authMethodsPerActor
+
+The `projectConfig.http.authMethodsPerActor` configuration specifies the supported authentication providers per actor type (such as `user`, `customer`, or any custom actor).
+
+For example, you can allow Google login for `customers`, and allow email/password logins for `users` in the admin.
+
+`authMethodsPerActor` is a an object whose key is the actor type (for example, `user`), and the value is an array of supported auth provider IDs (for example, `emailpass`).
+
+Learn more about actor types in the [Auth Identity and Actor Type documentation](https://docs.medusajs.com/resources/commerce-modules/auth/auth-identity-and-actor-types/index.html.md).
+
+For example:
+
+```ts title="medusa-config.ts"
+module.exports = defineConfig({
+ projectConfig: {
+ http: {
+ authMethodsPerActor: {
+ user: ["emailpass"],
+ customer: ["emailpass", "google"],
+ },
+ },
+ // ...
+ },
+ // ...
+})
+```
+
+The above configurations allow admin users to login using email/password, and customers to login using email/password and Google.
+
+#### http.restrictedFields
+
+The `projectConfig.http.restrictedFields` configuration specifies the fields that can't be selected in API routes (using the `fields` query parameter) unless they're allowed in the [request's Query configurations](https://docs.medusajs.com/learn/fundamentals/module-links/query#request-query-configurations/index.html.md). This is useful to restrict sensitive fields from being exposed in the API.
+
+For example, you can restrict selecting customers in store API routes:
+
+```ts title="medusa-config.ts"
+module.exports = defineConfig({
+ projectConfig: {
+ http: {
+ restrictedFields: {
+ store: ["customer", "customers"],
+ },
+ },
+ // ...
+ },
+ // ...
+})
+```
+
+The `restrictedFields` configuration accepts the following properties:
+
+- store: (\`string\[]\`)
+
+### redisOptions
+
+The `projectConfig.redisOptions` configuration defines options to pass to `ioredis`, which creates the Redis connection used to store the Medusa server session. Refer to [ioredis’s RedisOptions documentation](https://redis.github.io/ioredis/index.html#RedisOptions)
+for the list of available options.
+
+#### Example
+
+```ts title="medusa-config.ts"
+module.exports = defineConfig({
+ projectConfig: {
+ redisOptions: {
+ connectionName: process.env.REDIS_CONNECTION_NAME ||
+ "medusa",
+ },
+ // ...
+ },
+ // ...
+})
+```
+
+### redisPrefix
+
+The `projectConfig.redisPrefix` configuration defines a prefix on all keys stored in Redis for the Medusa server session. The default value is `sess:`.
+
+The value of this configuration is prepended to `sess:`. For example, if you set it to `medusa:`, then a key stored in Redis is prefixed by `medusa:sess`.
+
+This configuration is not used for modules that also connect to Redis, such as the [Redis Cache Module](https://docs.medusajs.com/resources/infrastructure-modules/cache/redis/index.html.md).
+
+#### Example
+
+```ts title="medusa-config.ts"
+module.exports = defineConfig({
+ projectConfig: {
+ redisPrefix: process.env.REDIS_URL || "medusa:",
+ // ...
+ },
+ // ...
+})
+```
+
+### redisUrl
+
+The `projectConfig.redisUrl` configuration specifies the connection URL to Redis to store the Medusa server session. When specified, the Medusa server uses Redis to store the session data. Otherwie, the session data is stored in-memory.
+
+This configuration is not used for modules that also connect to Redis, such as the [Redis Cache Module](https://docs.medusajs.com/resources/infrastructure-modules/cache/redis/index.html.md). You'll have to configure the Redis connection for those modules separately.
+
+You must first have Redis installed. You can refer to [Redis's installation guide](https://redis.io/docs/getting-started/installation/).
+
+The Redis connection URL has the following format:
+
+```bash
+redis[s]://[[username][:password]@][host][:port][/db-number]
+```
+
+Where:
+
+- `redis[s]`: the protocol used to connect to Redis. Use `rediss` for a secure connection.
+- `[[username][:password]@]`: an optional username and password for the Redis server.
+- `[host]`: the host of the Redis server. When run locally, it should be `localhost`.
+- `[:port]`: an optional port that the Redis server is listening on. By default, it's `6379`.
+- `[/db-number]`: an optional database number to connect to. By default, it's `0`.
+
+For a local Redis installation, the connection URL should be `redis://localhost:6379` unless you’ve made any changes to the Redis configuration during installation.
+
+#### Example
+
+```ts title="medusa-config.ts"
+module.exports = defineConfig({
+ projectConfig: {
+ redisUrl: process.env.REDIS_URL ||
+ "redis://localhost:6379",
+ // ...
+ },
+ // ...
+})
+```
+
+### sessionOptions
+
+The `projectConfig.sessionOptions` configuration defines additional options to pass to [express-session](https://www.npmjs.com/package/express-session), which is used to store the Medusa server session.
+
+This configuration is not used for modules that also connect to Redis, such as the [Redis Cache Module](https://docs.medusajs.com/resources/infrastructure-modules/cache/redis/index.html.md).
+
+#### Example
+
+```ts title="medusa-config.ts"
+module.exports = defineConfig({
+ projectConfig: {
+ sessionOptions: {
+ name: process.env.SESSION_NAME || "custom",
+ },
+ // ...
+ },
+ // ...
+})
+```
+
+#### Properties
+
+- name: (\`string\`)
+- resave: (\`boolean\`)
+- rolling: (\`boolean\`)
+- saveUninitialized: (\`boolean\`)
+- secret: (\`string\`) The secret to sign the session ID cookie. By default, the value of \[http.cookieSecret]\(#httpcookieSecret) is used. Refer to \[express-session’s documentation]\(https://www.npmjs.com/package/express-session#secret) for details.
+- ttl: (\`number\`) The time-to-live (TTL) of the session ID cookie in milliseconds. It is used when calculating the \`Expires\` \`Set-Cookie\` attribute of cookies. Refer to \[express-session’s documentation]\(https://www.npmjs.com/package/express-session#cookie) for more details.
+
+### workerMode
+
+The `projectConfig.workerMode` configuration specifies the worker mode of the Medusa application. You can learn more about it in the [Worker Mode chapter](https://docs.medusajs.com/learn/production/worker-mode/index.html.md).
+
+The value for this configuration can be one of the following:
+
+- `shared`: run the application in a single process, meaning the worker and server run in the same process.
+- `worker`: run the a worker process only.
+- `server`: run the application server only.
+
+#### Example
+
+```ts title="medusa-config.ts"
+module.exports = defineConfig({
+ projectConfig: {
+ workerMode: process.env.WORKER_MODE || "shared",
+ // ...
+ },
+ // ...
+})
+```
***
-## Next Chapters: Link Brands to Products Example
+## Admin Configurations (`admin`)
-The next chapters explain how to use the tools mentioned above with step-by-step guides. You'll continue with the [brands example from the previous chapters](https://docs.medusajs.com/learn/customization/custom-features/index.html.md) to:
+The `admin` object contains configurations related to the Medusa Admin.
-- Link brands from the custom [Brand Module](https://docs.medusajs.com/learn/customization/custom-features/module/index.html.md) to products from Medusa's [Product Module](https://docs.medusajs.com/resources/commerce-modules/product/index.html.md).
-- Extend the core product-creation workflow and the API route that uses it to allow setting the brand of a newly created product.
-- Retrieve a product's associated brand's details.
+### backendUrl
+The `admin.backendUrl` configuration specifies the URL of the Medusa application. Its default value is the browser origin. This is useful to set when running the admin on a separate domain.
-# Build Custom Features
+#### Example
-In the upcoming chapters, you'll follow step-by-step guides to build custom features in Medusa. These guides gradually introduce Medusa's concepts to help you understand what they are and how to use them.
+```ts title="medusa-config.ts"
+module.exports = defineConfig({
+ admin: {
+ backendUrl: process.env.MEDUSA_BACKEND_URL ||
+ "http://localhost:9000",
+ },
+ // ...
+})
+```
-By following these guides, you'll add brands to the Medusa application that you can associate with products.
+### disable
-To build a custom feature in Medusa, you need three main tools:
+The `admin.disable` configuration specifies whether to disable the Medusa Admin. If disabled, the Medusa Admin will not be compiled and you can't access it at `/app` path of your application. The default value is `false`.
-- [Module](https://docs.medusajs.com/learn/fundamentals/modules/index.html.md): a package with commerce logic for a single domain. It defines new tables to add to the database, and a class of methods to manage these tables.
-- [Workflow](https://docs.medusajs.com/learn/fundamentals/workflows/index.html.md): a tool to perform an operation comprising multiple steps with built-in rollback and retry mechanisms.
-- [API route](https://docs.medusajs.com/learn/fundamentals/api-routes/index.html.md): a REST endpoint that exposes commerce features to clients, such as the admin dashboard or a storefront. The API route executes a workflow that implements the commerce feature using modules.
+#### Example
-
+```ts title="medusa-config.ts"
+module.exports = defineConfig({
+ admin: {
+ disable: process.env.ADMIN_DISABLED === "true" ||
+ false,
+ },
+ // ...
+})
+```
+
+### path
+
+The `admin.path` configuration indicates the path to the admin dashboard, which is `/app` by default. The value must start with `/` and can't end with a `/`.
+
+The value cannot be one of the reserved paths:
+
+- `/admin`
+- `/store`
+- `/auth`
+- `/`
+
+When using Docker, make sure that the root path of the Docker image isn't the same as the admin's path. For example, if the Docker image's root path is `/app`, change
+the value of the `admin.path` configuration, since it's `/app` by default.
+
+#### Example
+
+```ts title="medusa-config.ts"
+module.exports = defineConfig({
+ admin: {
+ path: process.env.ADMIN_PATH || `/app`,
+ },
+ // ...
+})
+```
+
+### storefrontUrl
+
+The `admin.storefrontUrl` configuration specifies the URL of the Medusa storefront application. This URL is used as a prefix to some links in the admin that require performing actions in the storefront.
+
+For example, this URL is used as a prefix to shareable payment links for orders with outstanding amounts.
+
+#### Example
+
+```js title="medusa-config.js"
+module.exports = defineConfig({
+ admin: {
+ storefrontUrl: process.env.MEDUSA_STOREFRONT_URL ||
+ "http://localhost:8000",
+ },
+ // ...
+})
+```
+
+### vite
+
+The `admin.vite` configration specifies Vite configurations for the Medusa Admin. Its value is a function that receives the default Vite configuration and returns the modified configuration. The default value is `undefined`.
+
+Learn about configurations you can pass to Vite in [Vite's documentation](https://vite.dev/config/).
+
+#### Example
+
+For example, if you're using a third-party library that isn't ESM-compatible, add it to Vite's `optimizeDeps` configuration:
+
+```ts title="medusa-config.ts"
+module.exports = defineConfig({
+ admin: {
+ vite: () => {
+ return {
+ optimizeDeps: {
+ include: ["qs"],
+ },
+ }
+ },
+ },
+ // ...
+})
+```
***
-## Next Chapters: Brand Module Example
+## Module Configurations (`modules`)
-The next chapters will guide you to:
+The `modules` configuration allows you to register and configure the [modules](https://docs.medusajs.com/learn/fundamentals/modules/index.html.md) registered in the Medusa application. Medusa's commerce and Infrastructure Modules are configured by default. So, you only need to pass your custom modules, or override the default configurations of the existing modules.
-1. Build a Brand Module that creates a `Brand` data model and provides data-management features.
-2. Add a workflow to create a brand.
-3. Expose an API route that allows admin users to create a brand using the workflow.
+`modules` is an array of objects for the modules to register. Each object has the following properties:
+1. `resolve`: a string indicating the path to the module, or the module's NPM package name. For example, `./src/modules/my-module`.
+2. `options`: (optional) an object indicating the [options to pass to the module](https://docs.medusajs.com/learn/fundamentals/modules/options/index.html.md). This object is specific to the module and its configurations. For example, your module may require an API key option, which you can pass in this object.
-# Customizations Next Steps: Learn the Fundamentals
+For modules that are part of a plugin, learn about registering them in the [Register Modules in Plugins](#register-modules-in-plugins) section.
-The previous guides introduced Medusa's different concepts and how you can use them to customize Medusa for a realistic use case, You added brands to your application, linked them to products, customized the admin dashboard, and integrated a third-party CMS.
+### Example
-The next chapters will cover each of these concepts in depth, with the different ways you can use them, their options or configurations, and more advanced features that weren't covered in the previous guides. While you can start building with Medusa, it's highly recommended to follow the next chapters for a better understanding of Medusa's fundamentals.
+To register a custom module:
-## Useful Guides
+```ts title="medusa-config.ts"
+module.exports = defineConfig({
+ modules: [
+ {
+ resolve: "./src/modules/cms",
+ options: {
+ apiKey: process.env.CMS_API_KEY,
+ },
+ },
+ ],
+ // ...
+})
+```
-The following guides and references are useful for your development journey:
+You can also override the default configurations of Medusa's modules. For example, to add a Notification Module Provider to the Notification Module:
-3. [Commerce Modules](https://docs.medusajs.com/resources/commerce-modules/index.html.md): Browse the list of Commerce Modules in Medusa and their references to learn how to use them.
-4. [Service Factory Reference](https://docs.medusajs.com/resources/service-factory-reference/index.html.md): Learn about the methods generated by `MedusaService` with examples.
-5. [Workflows Reference](https://docs.medusajs.com/resources/medusa-workflows-reference/index.html.md): Browse the list of core workflows and their hooks that are useful for your customizations.
-6. [Admin Injection Zones](https://docs.medusajs.com/resources/admin-widget-injection-zones/index.html.md): Browse the injection zones in the Medusa Admin to learn where you can inject widgets.
+```ts title="medusa-config.ts"
+module.exports = defineConfig({
+ modules: [
+ {
+ resolve: "@medusajs/medusa/notification",
+ options: {
+ providers: [
+ // default provider
+ {
+ resolve: "@medusajs/medusa/notification-local",
+ id: "local",
+ options: {
+ name: "Local Notification Provider",
+ channels: ["feed"],
+ },
+ },
+ // custom provider
+ {
+ resolve: "./src/modules/my-notification",
+ id: "my-notification",
+ options: {
+ channels: ["email"],
+ // provider options...
+ },
+ },
+ ],
+ },
+ },
+ ],
+ // ...
+})
+```
***
-## More Examples in Recipes
+## Plugin Configurations (`plugins`)
-In the [Recipes](https://docs.medusajs.com/resources/recipes/index.html.md) documentation, you'll also find step-by-step guides for different use cases, such as building a marketplace, digital products, and more.
+The `plugins` configuration allows you to register and configure the [plugins](https://docs.medusajs.com/learn/fundamentals/plugins/index.html.md) registered in the Medusa application. Plugins include re-usable Medusa customizations, such as modules, workflows, API routes, and more.
+Aside from installing the plugin with NPM, you must also register it in the `medusa.config.ts` file.
-# Integrate Third-Party Systems
+The `plugins` configuration is an array of objects for the plugins to register. Each object has the following properties:
-Commerce applications often connect to third-party systems that provide additional or specialized features. For example, you may integrate a Content-Management System (CMS) for rich content features, a payment provider to process credit-card payments, and a notification service to send emails.
+- A string, which is the name of the plugin's package as specified in the plugin's `package.json` file. This is useful if the plugin doesn't require any options.
+- An object having the following properties:
+ - `resolve`: The name of the plugin's package as specified in the plugin's `package.json` file.
+ - `options`: An object that includes [options to be passed to the modules](https://docs.medusajs.com/learn/fundamentals/modules/options#pass-options-to-a-module-in-a-plugin/index.html.md) within the plugin.
-The Medusa Framework facilitates integrating these systems and orchestrating operations across them, saving you the effort of managing them yourself. You won't find those capabilities in other commerce platforms that in these scenarios become a bottleneck to building customizations and iterating quickly.
+### Example
-In Medusa, you integrate a third-party system by:
+```ts title="medusa-config.ts"
+module.exports = {
+ plugins: [
+ `medusa-my-plugin-1`,
+ {
+ resolve: `medusa-my-plugin`,
+ options: {
+ apiKey: process.env.MY_API_KEY ||
+ `test`,
+ },
+ },
+ // ...
+ ],
+ // ...
+}
+```
-1. Creating a module whose service provides the methods to connect to and perform operations in the third-party system.
-2. Building workflows that complete tasks spanning across systems. You use the module that integrates a third-party system in the workflow's steps.
-3. Executing the workflows you built in an [API route](https://docs.medusajs.com/learn/fundamentals/api-routes/index.html.md), at a scheduled time, or when an event is emitted.
+The above configuration registers two plugins: `medusa-my-plugin-1` and `medusa-my-plugin`. The latter plugin requires an API key option, which is passed in the `options` object.
+
+### Register Modules in Plugins
+
+When you register a plugin, its modules are automatically registered in the Medusa application. You don't have to register them manually in the `modules` configuration.
+
+However, this isn't the case for module providers. If your plugin includes a module provider, you must register it in the `modules` configuration, referencing the module provider's path.
+
+For example:
+
+```ts title="medusa-config.ts"
+module.exports = {
+ plugins: [
+ `medusa-my-plugin`,
+ ],
+ modules: [
+ {
+ resolve: "@medusajs/medusa/notification",
+ options: {
+ providers: [
+ // ...
+ {
+ resolve: "medusa-my-plugin/providers/my-notification",
+ id: "my-notification",
+ options: {
+ channels: ["email"],
+ // provider options...
+ },
+ },
+ ],
+ },
+ },
+ ],
+ // ...
+}
+```
***
-## Next Chapters: Sync Brands Example
+## Feature Flags (`featureFlags`)
-In the previous chapters, you've [added brands](https://docs.medusajs.com/learn/customization/custom-features/module/index.html.md) to your Medusa application. In the next chapters, you will:
+The `featureFlags` configuration allows you to manage enabled beta features in the Medusa application.
-1. Integrate a dummy third-party CMS in the Brand Module.
-2. Sync brands to the CMS when a brand is created.
-3. Sync brands from the CMS at a daily schedule.
+Some features in the Medusa application are guarded by a feature flag. This ensures constant shipping of new features while maintaining the engine’s stability. You can enable or disable these features using the `featureFlags` configuration.
+
+The `featureFlags`'s value is an object whose keys are the names of the feature flags, and their values a boolean indicating whether the feature flag is enabled.
+
+Only enable feature flags in testing or development environments. Enabling a feature flag may introduce breaking changes or unexpected behavior.
+
+You can find available feature flags and their key name [here](https://github.com/medusajs/medusa/tree/develop/packages/medusa/src/loaders/feature-flags).
+
+### Example
+
+```ts title="medusa-config.ts"
+module.exports = defineConfig({
+ featureFlags: {
+ index_engine: true,
+ // ...
+ },
+ // ...
+})
+```
+
+After enabling a feature flag, make sure to run migrations, as the feature may introduce database changes:
+
+```bash
+npx medusa db:migrate
+```
-# Re-Use Customizations with Plugins
+# Using TypeScript Aliases
-In the previous chapters, you've learned important concepts related to creating modules, implementing commerce features in workflows, exposing those features in API routes, customizing the Medusa Admin dashboard with Admin Extensions, and integrating third-party systems.
+By default, Medusa doesn't support TypeScript aliases in production.
-You've implemented the brands example within a single Medusa application. However, this approach is not scalable when you want to reuse your customizations across multiple projects.
+If you prefer using TypeScript aliases, install following development dependencies:
-To reuse your customizations across multiple Medusa applications, such as implementing brands in different projects, you can create a plugin. A plugin is an NPM package that encapsulates your customizations and can be installed in any Medusa application. Plugins can include modules, workflows, API routes, Admin Extensions, and more.
+```bash npm2yarn
+npm install --save-dev tsc-alias rimraf
+```
-
+Where `tsc-alias` is a package that resolves TypeScript aliases, and `rimraf` is a package that removes files and directories.
-Medusa provides the tooling to create a plugin package, test it in a local Medusa application, and publish it to NPM.
+Then, add a new `resolve:aliases` script to your `package.json` and update the `build` script:
-To learn more about plugins and how to create them, refer to [this chapter](https://docs.medusajs.com/learn/fundamentals/plugins/index.html.md).
+```json title="package.json"
+{
+ "scripts": {
+ // other scripts...
+ "resolve:aliases": "tsc --showConfig -p tsconfig.json > tsconfig.resolved.json && tsc-alias -p tsconfig.resolved.json && rimraf tsconfig.resolved.json",
+ "build": "medusa build && npm run resolve:aliases"
+ }
+}
+```
+
+You can now use TypeScript aliases in your Medusa application. For example, add the following in `tsconfig.json`:
+
+```json title="tsconfig.json"
+{
+ "compilerOptions": {
+ // ...
+ "paths": {
+ "@/*": ["./src/*"]
+ }
+ }
+}
+```
+
+Now, you can import modules, for example, using TypeScript aliases:
+
+```ts
+import { BrandModuleService } from "@/modules/brand/service"
+```
# Configure Instrumentation
@@ -948,6 +1766,443 @@ Medusa's Testing Framework works for integration tests only. You can write unit
The next chapters explain how to use the testing tools provided by `@medusajs/test-utils` to write tests.
+# Build Custom Features
+
+In the upcoming chapters, you'll follow step-by-step guides to build custom features in Medusa. These guides gradually introduce Medusa's concepts to help you understand what they are and how to use them.
+
+By following these guides, you'll add brands to the Medusa application that you can associate with products.
+
+To build a custom feature in Medusa, you need three main tools:
+
+- [Module](https://docs.medusajs.com/learn/fundamentals/modules/index.html.md): a package with commerce logic for a single domain. It defines new tables to add to the database, and a class of methods to manage these tables.
+- [Workflow](https://docs.medusajs.com/learn/fundamentals/workflows/index.html.md): a tool to perform an operation comprising multiple steps with built-in rollback and retry mechanisms.
+- [API route](https://docs.medusajs.com/learn/fundamentals/api-routes/index.html.md): a REST endpoint that exposes commerce features to clients, such as the admin dashboard or a storefront. The API route executes a workflow that implements the commerce feature using modules.
+
+
+
+***
+
+## Next Chapters: Brand Module Example
+
+The next chapters will guide you to:
+
+1. Build a Brand Module that creates a `Brand` data model and provides data-management features.
+2. Add a workflow to create a brand.
+3. Expose an API route that allows admin users to create a brand using the workflow.
+
+
+# Customize Medusa Admin Dashboard
+
+In the previous chapters, you've customized your Medusa application to [add brands](https://docs.medusajs.com/learn/customization/custom-features/module/index.html.md), [expose an API route to create brands](https://docs.medusajs.com/learn/customization/custom-features/api-route/index.html.md), and [linked brands to products](https://docs.medusajs.com/learn/customization/extend-features/define-link/index.html.md).
+
+After customizing and extending your application with new features, you may need to provide an interface for admin users to utilize these features. The Medusa Admin dashboard is extendable, allowing you to:
+
+- Insert components, called [widgets](https://docs.medusajs.com/learn/fundamentals/admin/widgets/index.html.md), on existing pages.
+- Add new pages, called [UI Routes](https://docs.medusajs.com/learn/fundamentals/admin/ui-routes/index.html.md).
+
+From these customizations, you can send requests to custom API routes, allowing admin users to manage custom resources on the dashboard
+
+***
+
+## Next Chapters: View Brands in Dashboard
+
+In the next chapters, you'll continue with the brands example to:
+
+- Add a new section to the product details page that shows the product's brand.
+- Add a new page in the dashboard that shows all brands in the store.
+
+
+# Extend Core Commerce Features
+
+In the upcoming chapters, you'll learn about the concepts and tools to extend Medusa's core commerce features.
+
+In other commerce platforms, you extend core features and models through hacky workarounds that can introduce unexpected issues and side effects across the platform. It also makes your application difficult to maintain and upgrade in the long run.
+
+The Medusa Framework and orchestration tools mitigate these issues while supporting all your customization needs:
+
+- [Module Links](https://docs.medusajs.com/learn/fundamentals/module-links/index.html.md): Link data models of different modules without building direct dependencies, ensuring that the Medusa application integrates your modules without side effects.
+- [Workflow Hooks](https://docs.medusajs.com/learn/fundamentals/workflows/workflow-hooks/index.html.md): inject custom functionalities into a workflow at predefined points, called hooks. This allows you to perform custom actions as a part of a core workflow without hacky workarounds.
+- [Additional Data in API Routes](https://docs.medusajs.com/learn/fundamentals/api-routes/additional-data/index.html.md): Configure core API routes to accept request parameters relevant to your customizations. These parameters are passed to the underlying workflow's hooks, where you can manage your custom data as part of an existing flow.
+
+***
+
+## Next Chapters: Link Brands to Products Example
+
+The next chapters explain how to use the tools mentioned above with step-by-step guides. You'll continue with the [brands example from the previous chapters](https://docs.medusajs.com/learn/customization/custom-features/index.html.md) to:
+
+- Link brands from the custom [Brand Module](https://docs.medusajs.com/learn/customization/custom-features/module/index.html.md) to products from Medusa's [Product Module](https://docs.medusajs.com/resources/commerce-modules/product/index.html.md).
+- Extend the core product-creation workflow and the API route that uses it to allow setting the brand of a newly created product.
+- Retrieve a product's associated brand's details.
+
+
+# General Medusa Application Deployment Guide
+
+In this document, you'll learn the general steps to deploy your Medusa application. How you apply these steps depend on your chosen hosting provider or platform.
+
+Find how-to guides for specific platforms in [this documentation](https://docs.medusajs.com/resources/deployment/index.html.md).
+
+Want Medusa to manage and maintain your infrastructure? [Sign up and learn more about Medusa Cloud](https://medusajs.com/pricing)
+
+Medusa Cloud is our managed services offering that makes deploying and operating Medusa applications possible without having to worry about configuring, scaling, and maintaining infrastructure. Medusa Cloud hosts your server, Admin dashboard, database, and Redis instance.
+
+With Medusa Cloud, you maintain full customization control as you deploy your own modules and customizations directly from GitHub:
+
+- Push to deploy.
+- Multiple testing environments.
+- Preview environments for new PRs.
+- Test on production-like data.
+
+### Prerequisites
+
+- [Medusa application’s codebase hosted on GitHub repository.](https://docs.medusajs.com/learn/index.html.md)
+
+## What You'll Deploy
+
+When you deploy the Medusa application, you need to deploy the following resources:
+
+1. PostgreSQL database: This is the database that will hold your Medusa application's details.
+2. Redis database: This is the database that will store the Medusa server's session.
+3. Medusa application in [server and worker mode](https://docs.medusajs.com/learn/production/worker-mode/index.html.md), where:
+ - The server mode handles incoming API requests and serving the Medusa Admin dashboard.
+ - The worker mode handles background tasks, such as scheduled jobs and subscribers.
+
+So, when choosing a hosting provider, make sure it supports deploying these resources. Also, for optimal experience, the hosting provider and plan must offer at least 2GB of RAM.
+
+***
+
+## 1. Configure Medusa Application
+
+### Worker Mode
+
+The `workerMode` configuration determines which mode the Medusa application runs in. When you deploy the Medusa application, you deploy two instances: one in server mode, and one in worker mode.
+
+Learn more about worker mode in the [Worker Module chapter](https://docs.medusajs.com/learn/production/worker-mode/index.html.md).
+
+So, add the following configuration in `medusa-config.ts`:
+
+```ts title="medusa-config.ts"
+module.exports = defineConfig({
+ projectConfig: {
+ // ...
+ workerMode: process.env.MEDUSA_WORKER_MODE as "shared" | "worker" | "server",
+ },
+})
+```
+
+Later, you’ll set different values of the `MEDUSA_WORKER_MODE` environment variable for each Medusa application deployment or instance.
+
+### Configure Medusa Admin
+
+The Medusa Admin is served by the Medusa server application. So, you need to disable it in the worker Medusa application only.
+
+To disable the Medusa Admin in the worker Medusa application while keeping it enabled in the server Medusa application, add the following configuration in `medusa-config.ts`:
+
+```ts title="medusa-config.ts"
+module.exports = defineConfig({
+ // ...
+ admin: {
+ disable: process.env.DISABLE_MEDUSA_ADMIN === "true",
+ },
+})
+```
+
+Later, you’ll set different values of the `DISABLE_MEDUSA_ADMIN` environment variable for each Medusa application instance.
+
+### Configure Redis URL
+
+The `redisUrl` configuration specifies the connection URL to Redis to store the Medusa server's session.
+
+Learn more in the [Medusa Configuration documentation](https://docs.medusajs.com/learn/configurations/medusa-config#redisurl/index.html.md).
+
+So, add the following configuration in `medusa-config.ts` :
+
+```ts title="medusa-config.ts"
+module.exports = defineConfig({
+ projectConfig: {
+ // ...
+ redisUrl: process.env.REDIS_URL,
+ },
+})
+```
+
+***
+
+## 2. Add predeploy Script
+
+Before you start the Medusa application in production, you should always run migrations and sync links.
+
+So, add the following script in `package.json`:
+
+```json
+"scripts": {
+ // ...
+ "predeploy": "medusa db:migrate"
+},
+```
+
+***
+
+## 3. Install Production Modules and Providers
+
+By default, your Medusa application uses modules and providers useful for development, such as the In-Memory Cache Module or the Local File Module Provider.
+
+It’s highly recommended to instead use modules and providers suitable for production, including:
+
+- [Redis Cache Module](https://docs.medusajs.com/resources/infrastructure-modules/cache/redis/index.html.md)
+- [Redis Event Bus Module](https://docs.medusajs.com/resources/infrastructure-modules/event/redis/index.html.md)
+- [Workflow Engine Redis Module](https://docs.medusajs.com/resources/infrastructure-modules/workflow-engine/redis/index.html.md)
+- [S3 File Module Provider](https://docs.medusajs.com/resources/infrastructure-modules/file/s3/index.html.md) (or other file module providers production-ready).
+- [SendGrid Notification Module Provider](https://docs.medusajs.com/resources/infrastructure-modules/notification/sendgrid/index.html.md) (or other notification module providers production-ready).
+
+Then, add these modules in `medusa-config.ts`:
+
+```ts title="medusa-config.ts"
+import { Modules } from "@medusajs/framework/utils"
+
+module.exports = defineConfig({
+ // ...
+ modules: [
+ {
+ resolve: "@medusajs/medusa/cache-redis",
+ options: {
+ redisUrl: process.env.REDIS_URL,
+ },
+ },
+ {
+ resolve: "@medusajs/medusa/event-bus-redis",
+ options: {
+ redisUrl: process.env.REDIS_URL,
+ },
+ },
+ {
+ resolve: "@medusajs/medusa/workflow-engine-redis",
+ options: {
+ redis: {
+ url: process.env.REDIS_URL,
+ },
+ },
+ },
+ ],
+})
+```
+
+Check out the [Integrations](https://docs.medusajs.com/resources/integrations/index.html.md) and [Infrastructure Modules](https://docs.medusajs.com/resources/infrastructure-modules/index.html.md) documentation for other modules and providers to use.
+
+***
+
+## 4. Create PostgreSQL and Redis Databases
+
+Your Medusa application must connect to PostgreSQL and Redis databases. So, before you deploy it, create production PostgreSQL and Redis databases.
+
+If your hosting provider doesn't support databases, you can use [Neon for PostgreSQL database hosting](https://neon.tech/), and [Redis Cloud for the Redis database hosting](https://redis.io/cloud/).
+
+After hosting both databases, keep their connection URLs for the next steps.
+
+***
+
+## 5. Deploy Medusa Application in Server Mode
+
+As mentioned earlier, you'll deploy two instances or create two deployments of your Medusa application: one in server mode, and the other in worker mode.
+
+The deployment steps depend on your hosting provider. This section provides the general steps to perform during the deployment.
+
+### Set Environment Variables
+
+When setting the environment variables of the Medusa application, set the following variables:
+
+```bash
+COOKIE_SECRET=supersecret # TODO GENERATE SECURE SECRET
+JWT_SECRET=supersecret # TODO GENERATE SECURE SECRET
+STORE_CORS= # STOREFRONT URL
+ADMIN_CORS= # ADMIN URL
+AUTH_CORS= # STOREFRONT AND ADMIN URLS, SEPARATED BY COMMAS
+DISABLE_MEDUSA_ADMIN=false
+MEDUSA_WORKER_MODE=server
+PORT=9000
+DATABASE_URL # POSTGRES DATABASE URL
+REDIS_URL= # REDIS DATABASE URL
+```
+
+Where:
+
+- The value of `COOKIE_SECRET` and `JWT_SECRET` must be a randomly generated secret.
+- `STORE_CORS`'s value is the URL of your storefront. If you don’t have it yet, you can skip adding it for now.
+- `ADMIN_CORS`'s value is the URL of the admin dashboard, which is the same as the server Medusa application. You can add it later if you don't currently have it.
+- `AUTH_CORS`'s value is the URLs of any application authenticating users, customers, or other actor types, such as the storefront and admin URLs. The URLs are separated by commas. If you don’t have the URLs yet, you can set its value later.
+- Set `DISABLE_MEDUSA_ADMIN`'s value to `false` so that the admin is built with the server application.
+- Set the PostgreSQL database's connection URL as the value of `DATABASE_URL`
+- Set the Redis database's connection URL as the value of `REDIS_URL`.
+
+Feel free to add any other relevant environment variables, such as for integrations and Infrastructure Modules. If you're using environment variables in your admin customizations, make sure to set them as well, as they're inlined during the build process.
+
+### Set Start Command
+
+The Medusa application's production build, which is created using the `build` command, outputs the Medusa application to `.medusa/server`. So, you must install the dependencies in the `.medusa/server` directory, then run the `start` command in it.
+
+If your hosting provider doesn't support setting a current-working directory, set the start command to the following:
+
+```bash npm2yarn
+cd .medusa/server && npm install && npm run predeploy && npm run start
+```
+
+Notice that you run the `predeploy` command before starting the Medusa application to run migrations and sync links whenever there's an update.
+
+### Set Backend URL in Admin Configuration
+
+The Medusa Admin is built and hosted statically. To send requests to the Medusa server application, you must set the backend URL in the Medusa Admin's configuration.
+
+After you’ve obtained the Medusa application’s URL, add the following configuration to `medusa-config.ts`:
+
+```ts title="medusa-config.ts"
+module.exports = defineConfig({
+ // ...
+ admin: {
+ // ...
+ backendUrl: process.env.MEDUSA_BACKEND_URL,
+ },
+})
+```
+
+Then, push the changes to the GitHub repository or deployed application.
+
+In your hosting provider, add or modify the following environment variables for the Medusa application in server mode:
+
+```bash
+ADMIN_CORS= # MEDUSA APPLICATION URL
+AUTH_CORS= # ADD MEDUSA APPLICATION URL
+MEDUSA_BACKEND_URL= # URL TO DEPLOYED MEDUSA APPLICATION
+```
+
+Where you set the value of `ADMIN_CORS` and `MEDUSA_BACKEND_URL` to the Medusa application’s URL, and you add the URL to `AUTH_CORS`.
+
+After setting the environment variables, make sure to restart the deployment for the changes to take effect.
+
+Remember to separate URLs in `AUTH_CORS` by commas.
+
+***
+
+## 6. Deploy Medusa Application in Worker Mode
+
+Next, you'll deploy the Medusa application in worker mode.
+
+As explained in the previous section, the deployment steps depend on your hosting provider. This section provides the general steps to perform during the deployment.
+
+### Set Environment Variables
+
+When setting the environment variables of the Medusa application, set the following variables:
+
+```bash
+COOKIE_SECRET=supersecret # TODO GENERATE SECURE SECRET
+JWT_SECRET=supersecret # TODO GENERATE SECURE SECRET
+DISABLE_MEDUSA_ADMIN=true
+MEDUSA_WORKER_MODE=worker
+PORT=9000
+DATABASE_URL # POSTGRES DATABASE URL
+REDIS_URL= # REDIS DATABASE URL
+```
+
+Where:
+
+- The value of `COOKIE_SECRET` and `JWT_SECRET` must be a randomly generated secret.
+- Set `DISABLE_MEDUSA_ADMIN`'s value to `true` so that the admin isn't built with the worker application.
+- Set the PostgreSQL database's connection URL as the value of `DATABASE_URL`
+- Set the Redis database's connection URL as the value of `REDIS_URL`.
+
+Feel free to add any other relevant environment variables, such as for integrations and Infrastructure Modules.
+
+### Set Start Command
+
+The Medusa application's production build, which is created using the `build` command, outputs the Medusa application to `.medusa/server`. So, you must install the dependencies in the `.medusa/server` directory, then run the `start` command in it.
+
+If your hosting provider doesn't support setting a current-working directory, set the start command to the following:
+
+```bash npm2yarn
+cd .medusa/server && npm run install && npm run start
+```
+
+***
+
+## 7. Test Deployed Application
+
+Once the application is deployed and live, go to `/health`, where `` is the URL of the Medusa application in server mode. If the deployment was successful, you’ll see the `OK` response.
+
+The Medusa Admin is also available at `/app`.
+
+***
+
+## Create Admin User
+
+If your hosting provider supports running commands in your Medusa application's directory, run the following command to create an admin user:
+
+```bash
+npx medusa user -e admin-medusa@test.com -p supersecret
+```
+
+Replace the email `admin-medusa@test.com` and password `supersecret` with the credentials you want.
+
+You can use these credentials to log into the Medusa Admin dashboard.
+
+
+# Re-Use Customizations with Plugins
+
+In the previous chapters, you've learned important concepts related to creating modules, implementing commerce features in workflows, exposing those features in API routes, customizing the Medusa Admin dashboard with Admin Extensions, and integrating third-party systems.
+
+You've implemented the brands example within a single Medusa application. However, this approach is not scalable when you want to reuse your customizations across multiple projects.
+
+To reuse your customizations across multiple Medusa applications, such as implementing brands in different projects, you can create a plugin. A plugin is an NPM package that encapsulates your customizations and can be installed in any Medusa application. Plugins can include modules, workflows, API routes, Admin Extensions, and more.
+
+
+
+Medusa provides the tooling to create a plugin package, test it in a local Medusa application, and publish it to NPM.
+
+To learn more about plugins and how to create them, refer to [this chapter](https://docs.medusajs.com/learn/fundamentals/plugins/index.html.md).
+
+
+# Customizations Next Steps: Learn the Fundamentals
+
+The previous guides introduced Medusa's different concepts and how you can use them to customize Medusa for a realistic use case, You added brands to your application, linked them to products, customized the admin dashboard, and integrated a third-party CMS.
+
+The next chapters will cover each of these concepts in depth, with the different ways you can use them, their options or configurations, and more advanced features that weren't covered in the previous guides. While you can start building with Medusa, it's highly recommended to follow the next chapters for a better understanding of Medusa's fundamentals.
+
+## Useful Guides
+
+The following guides and references are useful for your development journey:
+
+3. [Commerce Modules](https://docs.medusajs.com/resources/commerce-modules/index.html.md): Browse the list of Commerce Modules in Medusa and their references to learn how to use them.
+4. [Service Factory Reference](https://docs.medusajs.com/resources/service-factory-reference/index.html.md): Learn about the methods generated by `MedusaService` with examples.
+5. [Workflows Reference](https://docs.medusajs.com/resources/medusa-workflows-reference/index.html.md): Browse the list of core workflows and their hooks that are useful for your customizations.
+6. [Admin Injection Zones](https://docs.medusajs.com/resources/admin-widget-injection-zones/index.html.md): Browse the injection zones in the Medusa Admin to learn where you can inject widgets.
+
+***
+
+## More Examples in Recipes
+
+In the [Recipes](https://docs.medusajs.com/resources/recipes/index.html.md) documentation, you'll also find step-by-step guides for different use cases, such as building a marketplace, digital products, and more.
+
+
+# Integrate Third-Party Systems
+
+Commerce applications often connect to third-party systems that provide additional or specialized features. For example, you may integrate a Content-Management System (CMS) for rich content features, a payment provider to process credit-card payments, and a notification service to send emails.
+
+The Medusa Framework facilitates integrating these systems and orchestrating operations across them, saving you the effort of managing them yourself. You won't find those capabilities in other commerce platforms that in these scenarios become a bottleneck to building customizations and iterating quickly.
+
+In Medusa, you integrate a third-party system by:
+
+1. Creating a module whose service provides the methods to connect to and perform operations in the third-party system.
+2. Building workflows that complete tasks spanning across systems. You use the module that integrates a third-party system in the workflow's steps.
+3. Executing the workflows you built in an [API route](https://docs.medusajs.com/learn/fundamentals/api-routes/index.html.md), at a scheduled time, or when an event is emitted.
+
+***
+
+## Next Chapters: Sync Brands Example
+
+In the previous chapters, you've [added brands](https://docs.medusajs.com/learn/customization/custom-features/module/index.html.md) to your Medusa application. In the next chapters, you will:
+
+1. Integrate a dummy third-party CMS in the Brand Module.
+2. Sync brands to the CMS when a brand is created.
+3. Sync brands from the CMS at a daily schedule.
+
+
# Admin Development
In this chapter, you'll learn about th Medusa Admin dashboard and the possible ways to customize it.
@@ -994,65 +2249,6 @@ Refer to the [Medusa UI documentation](https://docs.medusajs.com/ui/index.html.m
To build admin customizations that match the Medusa Admin's designs and layouts, refer to [this guide](https://docs.medusajs.com/resources/admin-components/index.html.md) to find common components.
-# API Routes
-
-In this chapter, you’ll learn what API Routes are and how to create them.
-
-## What is an API Route?
-
-An API Route is an endpoint. It exposes commerce features to external applications, such as storefronts, the admin dashboard, or third-party systems.
-
-The Medusa core application provides a set of admin and store API routes out-of-the-box. You can also create custom API routes to expose your custom functionalities.
-
-***
-
-## How to Create an API Route?
-
-An API Route is created in a TypeScript or JavaScript file under the `src/api` directory of your Medusa application. The file’s name must be `route.ts` or `route.js`.
-
-
-
-Each file exports API Route handler functions for at least one HTTP method (`GET`, `POST`, `DELETE`, etc…).
-
-For example, to create a `GET` API Route at `/hello-world`, create the file `src/api/hello-world/route.ts` with the following content:
-
-```ts title="src/api/hello-world/route.ts"
-import type {
- MedusaRequest,
- MedusaResponse,
-} from "@medusajs/framework/http"
-
-export const GET = (
- req: MedusaRequest,
- res: MedusaResponse
-) => {
- res.json({
- message: "[GET] Hello world!",
- })
-}
-```
-
-### Test API Route
-
-To test the API route above, start the Medusa application:
-
-```bash npm2yarn
-npm run dev
-```
-
-Then, send a `GET` request to the `/hello-world` API Route:
-
-```bash
-curl http://localhost:9000/hello-world
-```
-
-***
-
-## When to Use API Routes
-
-You're exposing custom functionality to be used by a storefront, admin dashboard, or any external application.
-
-
# Custom CLI Scripts
In this chapter, you'll learn how to create and execute custom scripts from Medusa's CLI tool.
@@ -1227,6 +2423,65 @@ For example, the Blog Module's service would have methods like `retrievePost` an
Refer to the [Service Factory](https://docs.medusajs.com/learn/fundamentals/modules/service-factory/index.html.md) chapter to learn more about how to extend the service factory and manage data models, and refer to the [Service Factory Reference](https://docs.medusajs.com/resources/service-factory-reference/index.html.md) for the full list of generated methods and how to use them.
+# API Routes
+
+In this chapter, you’ll learn what API Routes are and how to create them.
+
+## What is an API Route?
+
+An API Route is an endpoint. It exposes commerce features to external applications, such as storefronts, the admin dashboard, or third-party systems.
+
+The Medusa core application provides a set of admin and store API routes out-of-the-box. You can also create custom API routes to expose your custom functionalities.
+
+***
+
+## How to Create an API Route?
+
+An API Route is created in a TypeScript or JavaScript file under the `src/api` directory of your Medusa application. The file’s name must be `route.ts` or `route.js`.
+
+
+
+Each file exports API Route handler functions for at least one HTTP method (`GET`, `POST`, `DELETE`, etc…).
+
+For example, to create a `GET` API Route at `/hello-world`, create the file `src/api/hello-world/route.ts` with the following content:
+
+```ts title="src/api/hello-world/route.ts"
+import type {
+ MedusaRequest,
+ MedusaResponse,
+} from "@medusajs/framework/http"
+
+export const GET = (
+ req: MedusaRequest,
+ res: MedusaResponse
+) => {
+ res.json({
+ message: "[GET] Hello world!",
+ })
+}
+```
+
+### Test API Route
+
+To test the API route above, start the Medusa application:
+
+```bash npm2yarn
+npm run dev
+```
+
+Then, send a `GET` request to the `/hello-world` API Route:
+
+```bash
+curl http://localhost:9000/hello-world
+```
+
+***
+
+## When to Use API Routes
+
+You're exposing custom functionality to be used by a storefront, admin dashboard, or any external application.
+
+
# Environment Variables
In this chapter, you'll learn how environment variables are loaded in Medusa.
@@ -2328,6 +3583,426 @@ A [module](https://docs.medusajs.com/learn/fundamentals/modules/index.html.md),
Learn more about the module's container in [this chapter](https://docs.medusajs.com/learn/fundamentals/modules/container/index.html.md).
+# Plugins
+
+In this chapter, you'll learn what a plugin is in Medusa.
+
+Plugins are available starting from [Medusa v2.3.0](https://github.com/medusajs/medusa/releases/tag/v2.3.0).
+
+## What is a Plugin?
+
+A plugin is a package of reusable Medusa customizations that you can install in any Medusa application. The supported customizations are [Modules](https://docs.medusajs.com/learn/fundamentals/modules/index.html.md), [API Routes](https://docs.medusajs.com/learn/fundamentals/api-routes/index.html.md), [Workflows](https://docs.medusajs.com/learn/fundamentals/workflows/index.html.md), [Workflow Hooks](https://docs.medusajs.com/learn/fundamentals/workflows/workflow-hooks/index.html.md), [Links](https://docs.medusajs.com/learn/fundamentals/module-links/index.html.md), [Subscribers](https://docs.medusajs.com/learn/fundamentals/events-and-subscribers/index.html.md), [Scheduled Jobs](https://docs.medusajs.com/learn/fundamentals/scheduled-jobs/index.html.md), and [Admin Extensions](https://docs.medusajs.com/learn/fundamentals/admin/index.html.md).
+
+Plugins allow you to reuse your Medusa customizations across multiple projects or share them with the community. They can be published to npm and installed in any Medusa project.
+
+
+
+Learn how to create a wishlist plugin in [this guide](https://docs.medusajs.com/resources/plugins/guides/wishlist/index.html.md).
+
+***
+
+## Plugin vs Module
+
+A [module](https://docs.medusajs.com/learn/fundamentals/modules/index.html.md) is an isolated package related to a single domain or functionality, such as product reviews or integrating a Content Management System. A module can't access any resources in the Medusa application that are outside its codebase.
+
+A plugin, on the other hand, can contain multiple Medusa customizations, including modules. Your plugin can define a module, then build flows around it.
+
+For example, in a plugin, you can define a module that integrates a third-party service, then add a workflow that uses the module when a certain event occurs to sync data to that service.
+
+- You want to reuse your Medusa customizations across multiple projects.
+- You want to share your Medusa customizations with the community.
+
+- You want to build a custom feature related to a single domain or integrate a third-party service. Instead, use a [module](https://docs.medusajs.com/learn/fundamentals/modules/index.html.md). You can wrap that module in a plugin if it's used in other customizations, such as if it has a module link or it's used in a workflow.
+
+***
+
+## How to Create a Plugin?
+
+The next chapter explains how you can create and publish a plugin.
+
+
+# Scheduled Jobs
+
+In this chapter, you’ll learn about scheduled jobs and how to use them.
+
+## What is a Scheduled Job?
+
+When building your commerce application, you may need to automate tasks and run them repeatedly at a specific schedule. For example, you need to automatically sync products to a third-party service once a day.
+
+In other commerce platforms, this feature isn't natively supported. Instead, you have to setup a separate application to execute cron jobs, which adds complexity as to how you expose this task to be executed in a cron job, or how do you debug it when it's not running within the platform's tooling.
+
+Medusa removes this overhead by supporting this feature natively with scheduled jobs. A scheduled job is an asynchronous function that the Medusa application runs at the interval you specify during the Medusa application's runtime. Your efforts are only spent on implementing the functionality performed by the job, such as syncing products to an ERP.
+
+- You want the action to execute at a specified schedule while the Medusa application **isn't** running. Instead, use the operating system's equivalent of a cron job.
+- You want to execute the action once when the application loads. Use [loaders](https://docs.medusajs.com/learn/fundamentals/modules/loaders/index.html.md) instead.
+- You want to execute the action if an event occurs. Use [subscribers](https://docs.medusajs.com/learn/fundamentals/events-and-subscribers/index.html.md) instead.
+
+***
+
+## How to Create a Scheduled Job?
+
+You create a scheduled job in a TypeScript or JavaScript file under the `src/jobs` directory. The file exports the asynchronous function to run, and the configurations indicating the schedule to run the function.
+
+For example, create the file `src/jobs/hello-world.ts` with the following content:
+
+
+
+```ts title="src/jobs/hello-world.ts" highlights={highlights}
+import { MedusaContainer } from "@medusajs/framework/types"
+
+export default async function greetingJob(container: MedusaContainer) {
+ const logger = container.resolve("logger")
+
+ logger.info("Greeting!")
+}
+
+export const config = {
+ name: "greeting-every-minute",
+ schedule: "* * * * *",
+}
+```
+
+You export an asynchronous function that receives the [Medusa container](https://docs.medusajs.com/learn/fundamentals/medusa-container/index.html.md) as a parameter. In the function, you resolve the [Logger utility](https://docs.medusajs.com/learn/debugging-and-testing/logging/index.html.md) from the Medusa container and log a message.
+
+You also export a `config` object that has the following properties:
+
+- `name`: A unique name for the job.
+- `schedule`: A string that holds a [cron expression](https://crontab.guru/) indicating the schedule to run the job.
+
+This scheduled job executes every minute and logs into the terminal `Greeting!`.
+
+### Test the Scheduled Job
+
+To test out your scheduled job, start the Medusa application:
+
+```bash npm2yarn
+npm run dev
+```
+
+After a minute, the following message will be logged to the terminal:
+
+```bash
+info: Greeting!
+```
+
+***
+
+## Example: Sync Products Once a Day
+
+In this section, you'll find a brief example of how you use a scheduled job to sync products to a third-party service.
+
+When implementing flows spanning across systems or [modules](https://docs.medusajs.com/learn/fundamentals/modules/index.html.md), you use [workflows](https://docs.medusajs.com/learn/fundamentals/workflows/index.html.md). A workflow is a task made up of a series of steps, and you construct it like you would a regular function, but it's a special function that supports rollback mechanism in case of errors, background execution, and more.
+
+You can learn how to create a workflow in [this chapter](https://docs.medusajs.com/learn/fundamentals/workflows/index.html.md), but this example assumes you already have a `syncProductToErpWorkflow` implemented. To execute this workflow once a day, create a scheduled job at `src/jobs/sync-products.ts` with the following content:
+
+```ts title="src/jobs/sync-products.ts"
+import { MedusaContainer } from "@medusajs/framework/types"
+import { syncProductToErpWorkflow } from "../workflows/sync-products-to-erp"
+
+export default async function syncProductsJob(container: MedusaContainer) {
+ await syncProductToErpWorkflow(container)
+ .run()
+}
+
+export const config = {
+ name: "sync-products-job",
+ schedule: "0 0 * * *",
+}
+```
+
+In the scheduled job function, you execute the `syncProductToErpWorkflow` by invoking it and passing it the container, then invoking the `run` method. You also specify in the exported configurations the schedule `0 0 * * *` which indicates midnight time of every day.
+
+The next time you start the Medusa application, it will run this job every day at midnight.
+
+
+# Define Module Link
+
+In this chapter, you’ll learn what a module link is and how to define one.
+
+## What is a Module Link?
+
+Medusa's modular architecture isolates modules from one another to ensure they can be integrated into your application without side effects. Module isolation has other benefits, which you can learn about in the [Module Isolation chapter](https://docs.medusajs.com/learn/fundamentals/modules/isolation/index.html.md). Since modules are isolated, you can't access another module's data models to add a relation to it or extend it. Instead, you use a module link.
+
+A module link forms an association between two data models of different modules while maintaining module isolation. Using module links, you can build virtual relations between your custom data models and data models in the Commerce Modules, which is useful as you extend the features provided by the Commerce Modules. Then, Medusa creates a link table in the database to store the IDs of the linked records. You'll learn more about link tables later in this chapter.
+
+For example, the [Brand Customizations Tutorial](https://docs.medusajs.com/learn/customization/extend-features/index.html.md) shows how to create a Brand Module that adds the concept of brands to your application, then link those brands to a product.
+
+***
+
+## How to Define a Module Link?
+
+### 1. Create Link File
+
+Module links are defined in a TypeScript or JavaScript file under the `src/links` directory. The file defines the link using `defineLink` from the Modules SDK and exports it.
+
+For example:
+
+```ts title="src/links/blog-product.ts" highlights={highlights}
+import BlogModule from "../modules/blog"
+import ProductModule from "@medusajs/medusa/product"
+import { defineLink } from "@medusajs/framework/utils"
+
+export default defineLink(
+ ProductModule.linkable.product,
+ BlogModule.linkable.post
+)
+```
+
+The `defineLink` function accepts as parameters the link configurations of each module's data model. A module has a special `linkable` property that holds these configurations for its data models.
+
+In this example, you define a module link between the `blog` module's `post` data model and the Product Module's `Product` data model.
+
+### 2. Sync Links
+
+After defining the link, run the `db:sync-links` command:
+
+```bash
+npx medusa db:sync-links
+```
+
+The Medusa application creates a new table for your module link to store the IDs of linked records.
+
+You can also use the `db:migrate` command, which runs both the migrations and syncs the links.
+
+Use either of these commands whenever you make changes to your link definitions. For example, run this command if you remove your link definition file.
+
+***
+
+### Module Link's Database Table
+
+When you define a module link, the Medusa application creates a table in the database for that module link. The table's name is a combination of the names of the two data models linked in the format `module1_table1_module2_table2`, where:
+
+- `module1` and `module2` are the names of the modules.
+- `table1` and `table2` are the table names of the data models.
+
+For example, if you define a link between the `Product` data model from the [Product Module](https://docs.medusajs.com/resources/commerce-modules/product/index.html.md) and a `Post` data model from a Blog Module, the table name would be `product_product_blog_post`.
+
+The table has two columns, each storing the ID of a record from the linked data models. For example, the `product_product_blog_post` table would have columns `product_id` and `post_id`. These columns store only the IDs of the linked records and do not hold a foreign key constraint.
+
+Then, when you create links between records of the data models, the IDs of these data models are stored as a new record in the link's table.
+
+You can also add custom columns in the link table as explained in the [Add Columns to Link Table chapter](https://docs.medusajs.com/learn/fundamentals/module-links/custom-columns/index.html.md).
+
+
+
+***
+
+## When to Use Module Links
+
+- You want to create a relation between data models from different modules.
+- You want to extend the data model of another module.
+
+You want to create a relationship between data models in the same module. Use data model relationships instead.
+
+***
+
+## Define a List Module Link
+
+By default, a module link establishes a one-to-one relation: a record of a data model is linked to one record of the other data model.
+
+To specify that a data model can have multiple of its records linked to the other data model's record, use the `isList` option.
+
+For example:
+
+```ts
+import BlogModule from "../modules/blog"
+import ProductModule from "@medusajs/medusa/product"
+import { defineLink } from "@medusajs/framework/utils"
+
+export default defineLink(
+ ProductModule.linkable.product,
+ {
+ linkable: BlogModule.linkable.post,
+ isList: true,
+ }
+)
+```
+
+In this case, you pass an object of configuration as a parameter instead. The object accepts the following properties:
+
+- `linkable`: The data model's link configuration.
+- `isList`: Whether multiple records can be linked to one record of the other data model.
+
+In this example, a record of `product` can be linked to more than one record of `post`.
+
+### Many-to-Many Module Link
+
+Your module link can also establish a many-to-many relation between the linked data models. To do this, enable `isList` on both sides of the link.
+
+For example:
+
+```ts
+import BlogModule from "../modules/blog"
+import ProductModule from "@medusajs/medusa/product"
+import { defineLink } from "@medusajs/framework/utils"
+
+export default defineLink(
+ {
+ linkable: ProductModule.linkable.product,
+ isList: true,
+ },
+ {
+ linkable: BlogModule.linkable.post,
+ isList: true,
+ }
+)
+```
+
+***
+
+## Set Delete Cascades on Link
+
+To enable delete cascade on a link so that when a record is deleted, its linked records are also deleted, pass the `deleteCascade` property in the object passed to `defineLink`.
+
+For example:
+
+```ts
+import BlogModule from "../modules/blog"
+import ProductModule from "@medusajs/medusa/product"
+import { defineLink } from "@medusajs/framework/utils"
+
+export default defineLink(
+ ProductModule.linkable.product,
+ {
+ linkable: BlogModule.linkable.post,
+ deleteCascade: true,
+ }
+)
+```
+
+In this example, when a product is deleted, its linked `post` record is also deleted.
+
+***
+
+## Renaming Participants in a Module Link
+
+As mentioned in the [Module Link's Database Table](#module-links-database-table) section, the name of a link's table consists of the names of the modules and the data models' table names.
+
+So, if you rename a module or a data model's table, then run the `db:sync-links` or `db:migrate` commands, you'll be asked to delete the old link table and create a new one.
+
+A data model's table name is passed in the first parameter of `model.define`, and a module's name is passed in the first parameter of `Module` in the module's `index.ts` file.
+
+For example, if you have the link table `product_product_blog_post` and you rename the Blog Module from `blog` to `article`, Medusa considers the old link definition deleted. Then, when you run the `db:sync-links` or `db:migrate` command, Medusa will ask if you want to delete the old link table, and will create a new one with the new name `product_product_article_post`.
+
+To resolve this, you can rename the link table in the link definition.
+
+### Rename Link Table
+
+If you need to rename a module or its data model's table, you can persist the old name by passing a third parameter to `defineLink`. This parameter is an object of additional configurations. It accepts a `database` property that allows you to configure the link's table name.
+
+For example, after renaming the Blog Module to `article`, you can persist the old name `blog` in the link table name:
+
+```ts highlights={renameHighlights}
+import ArticleModule from "../modules/article"
+import ProductModule from "@medusajs/medusa/product"
+import { defineLink } from "@medusajs/framework/utils"
+
+export default defineLink(
+ ProductModule.linkable.product,
+ {
+ linkable: ArticleModule.linkable.post,
+ isList: true,
+ },
+ {
+ database: {
+ table: "product_product_blog_post",
+ },
+ }
+)
+```
+
+In this example, you set the `table` property in the `database` object to the old link table name `product_product_blog_post`, ensuring that the old link table is not deleted.
+
+This is enough to rename the link table when you rename a module. If you renamed a data model's table, you need to also run the `db:sync-links` or `db:migrate` commands, which will update the column names in the link table automatically:
+
+```bash
+npx medusa db:migrate
+```
+
+***
+
+## Delete Module Link Definition
+
+To delete a module link definition, remove the link file from the `src/links` directory. Then, run the `db:sync-links` or `db:migrate` command to delete the link table from the database:
+
+```bash
+npx medusa db:migrate
+```
+
+
+# Medusa's Architecture
+
+In this chapter, you'll learn about the architectural layers in Medusa.
+
+Find the full architectural diagram at the [end of this chapter](#full-diagram-of-medusas-architecture).
+
+## HTTP, Workflow, and Module Layers
+
+Medusa is a headless commerce platform. So, storefronts, admin dashboards, and other clients consume Medusa's functionalities through its API routes.
+
+In a common Medusa application, requests go through four layers in the stack. In order of entry, those are:
+
+1. API Routes (HTTP): Our API Routes are the typical entry point. The Medusa server is based on Express.js, which handles incoming requests. It can also connect to a Redis database that stores the server session data.
+2. Workflows: API Routes consume workflows that hold the opinionated business logic of your application.
+3. Modules: Workflows use domain-specific modules for resource management.
+4. Data store: Modules query the underlying datastore, which is a PostgreSQL database in common cases.
+
+These layers of stack can be implemented within [plugins](https://docs.medusajs.com/learn/fundamentals/plugins/index.html.md).
+
+
+
+***
+
+## Database Layer
+
+The Medusa application injects into each module, including your [custom modules](https://docs.medusajs.com/learn/fundamentals/modules/index.html.md), a connection to the configured PostgreSQL database. Modules use that connection to read and write data to the database.
+
+Modules can be implemented within [plugins](https://docs.medusajs.com/learn/fundamentals/plugins/index.html.md).
+
+
+
+***
+
+## Third-Party Integrations Layer
+
+Third-party services and systems are integrated through Medusa's Commerce and Infrastructure Modules. You also create custom third-party integrations through a [custom module](https://docs.medusajs.com/learn/fundamentals/modules/index.html.md).
+
+Modules can be implemented within [plugins](https://docs.medusajs.com/learn/fundamentals/plugins/index.html.md).
+
+### Commerce Modules
+
+[Commerce Modules](https://docs.medusajs.com/resources/commerce-modules/index.html.md) integrate third-party services relevant for commerce or user-facing features. For example, you can integrate [Stripe](https://docs.medusajs.com/resources/commerce-modules/payment/payment-provider/stripe/index.html.md) through a Payment Module Provider, or [ShipStation](https://docs.medusajs.com/resources/integrations/guides/shipstation/index.html.md) through a Fulfillment Module Provider.
+
+You can also integrate third-party services for custom functionalities. For example, you can integrate [Sanity](https://docs.medusajs.com/resources/integrations/guides/sanity/index.html.md) for rich CMS capabilities, or [Odoo](https://docs.medusajs.com/resources/recipes/erp/odoo/index.html.md) to sync your Medusa application with your ERP system.
+
+You can replace any of the third-party services mentioned above to build your preferred commerce ecosystem.
+
+
+
+### Infrastructure Modules
+
+[Infrastructure Modules](https://docs.medusajs.com/resources/infrastructure-modules/index.html.md) integrate third-party services and systems that customize Medusa's infrastructure. Medusa has the following Infrastructure Modules:
+
+- [Cache Module](https://docs.medusajs.com/resources/infrastructure-modules/cache/index.html.md): Caches data that require heavy computation. You can integrate a custom module to handle the caching with services like Memcached, or use the existing [Redis Cache Module](https://docs.medusajs.com/resources/infrastructure-modules/cache/redis/index.html.md).
+- [Event Module](https://docs.medusajs.com/resources/infrastructure-modules/event/index.html.md): A pub/sub system that allows you to subscribe to events and trigger them. You can integrate [Redis](https://docs.medusajs.com/resources/infrastructure-modules/event/redis/index.html.md) as the pub/sub system.
+- [File Module](https://docs.medusajs.com/resources/infrastructure-modules/file/index.html.md): Manages file uploads and storage, such as upload of product images. You can integrate [AWS S3](https://docs.medusajs.com/resources/infrastructure-modules/file/s3/index.html.md) for file storage.
+- [Locking Module](https://docs.medusajs.com/resources/infrastructure-modules/locking/index.html.md): Manages access to shared resources by multiple processes or threads, preventing conflict between processes and ensuring data consistency. You can integrate [Redis](https://docs.medusajs.com/resources/infrastructure-modules/locking/redis/index.html.md) for locking.
+- [Notification Module](https://docs.medusajs.com/resources/infrastructure-modules/notification/index.html.md): Sends notifications to customers and users, such as for order updates or newsletters. You can integrate [SendGrid](https://docs.medusajs.com/resources/infrastructure-modules/notification/sendgrid/index.html.md) for sending emails.
+- [Workflow Engine Module](https://docs.medusajs.com/resources/infrastructure-modules/workflow-engine/index.html.md): Orchestrates workflows that hold the business logic of your application. You can integrate [Redis](https://docs.medusajs.com/resources/infrastructure-modules/workflow-engine/redis/index.html.md) to orchestrate workflows.
+
+All of the third-party services mentioned above can be replaced to help you build your preferred architecture and ecosystem.
+
+
+
+***
+
+## Full Diagram of Medusa's Architecture
+
+The following diagram illustrates Medusa's architecture including all its layers.
+
+
+
+
# Modules
In this chapter, you’ll learn about modules and how to create them.
@@ -2628,259 +4303,6 @@ This will create a post and return it in the response:
You can also execute the workflow from a [subscriber](https://docs.medusajs.com/learn/fundamentals/events-and-subscribers/index.html.md) when an event occurs, or from a [scheduled job](https://docs.medusajs.com/learn/fundamentals/scheduled-jobs/index.html.md) to run it at a specified interval.
-# Plugins
-
-In this chapter, you'll learn what a plugin is in Medusa.
-
-Plugins are available starting from [Medusa v2.3.0](https://github.com/medusajs/medusa/releases/tag/v2.3.0).
-
-## What is a Plugin?
-
-A plugin is a package of reusable Medusa customizations that you can install in any Medusa application. The supported customizations are [Modules](https://docs.medusajs.com/learn/fundamentals/modules/index.html.md), [API Routes](https://docs.medusajs.com/learn/fundamentals/api-routes/index.html.md), [Workflows](https://docs.medusajs.com/learn/fundamentals/workflows/index.html.md), [Workflow Hooks](https://docs.medusajs.com/learn/fundamentals/workflows/workflow-hooks/index.html.md), [Links](https://docs.medusajs.com/learn/fundamentals/module-links/index.html.md), [Subscribers](https://docs.medusajs.com/learn/fundamentals/events-and-subscribers/index.html.md), [Scheduled Jobs](https://docs.medusajs.com/learn/fundamentals/scheduled-jobs/index.html.md), and [Admin Extensions](https://docs.medusajs.com/learn/fundamentals/admin/index.html.md).
-
-Plugins allow you to reuse your Medusa customizations across multiple projects or share them with the community. They can be published to npm and installed in any Medusa project.
-
-
-
-Learn how to create a wishlist plugin in [this guide](https://docs.medusajs.com/resources/plugins/guides/wishlist/index.html.md).
-
-***
-
-## Plugin vs Module
-
-A [module](https://docs.medusajs.com/learn/fundamentals/modules/index.html.md) is an isolated package related to a single domain or functionality, such as product reviews or integrating a Content Management System. A module can't access any resources in the Medusa application that are outside its codebase.
-
-A plugin, on the other hand, can contain multiple Medusa customizations, including modules. Your plugin can define a module, then build flows around it.
-
-For example, in a plugin, you can define a module that integrates a third-party service, then add a workflow that uses the module when a certain event occurs to sync data to that service.
-
-- You want to reuse your Medusa customizations across multiple projects.
-- You want to share your Medusa customizations with the community.
-
-- You want to build a custom feature related to a single domain or integrate a third-party service. Instead, use a [module](https://docs.medusajs.com/learn/fundamentals/modules/index.html.md). You can wrap that module in a plugin if it's used in other customizations, such as if it has a module link or it's used in a workflow.
-
-***
-
-## How to Create a Plugin?
-
-The next chapter explains how you can create and publish a plugin.
-
-
-# Define Module Link
-
-In this chapter, you’ll learn what a module link is and how to define one.
-
-## What is a Module Link?
-
-Medusa's modular architecture isolates modules from one another to ensure they can be integrated into your application without side effects. Module isolation has other benefits, which you can learn about in the [Module Isolation chapter](https://docs.medusajs.com/learn/fundamentals/modules/isolation/index.html.md). Since modules are isolated, you can't access another module's data models to add a relation to it or extend it. Instead, you use a module link.
-
-A module link forms an association between two data models of different modules while maintaining module isolation. Using module links, you can build virtual relations between your custom data models and data models in the Commerce Modules, which is useful as you extend the features provided by the Commerce Modules. Then, Medusa creates a link table in the database to store the IDs of the linked records. You'll learn more about link tables later in this chapter.
-
-For example, the [Brand Customizations Tutorial](https://docs.medusajs.com/learn/customization/extend-features/index.html.md) shows how to create a Brand Module that adds the concept of brands to your application, then link those brands to a product.
-
-***
-
-## How to Define a Module Link?
-
-### 1. Create Link File
-
-Module links are defined in a TypeScript or JavaScript file under the `src/links` directory. The file defines the link using `defineLink` from the Modules SDK and exports it.
-
-For example:
-
-```ts title="src/links/blog-product.ts" highlights={highlights}
-import BlogModule from "../modules/blog"
-import ProductModule from "@medusajs/medusa/product"
-import { defineLink } from "@medusajs/framework/utils"
-
-export default defineLink(
- ProductModule.linkable.product,
- BlogModule.linkable.post
-)
-```
-
-The `defineLink` function accepts as parameters the link configurations of each module's data model. A module has a special `linkable` property that holds these configurations for its data models.
-
-In this example, you define a module link between the `blog` module's `post` data model and the Product Module's `Product` data model.
-
-### 2. Sync Links
-
-After defining the link, run the `db:sync-links` command:
-
-```bash
-npx medusa db:sync-links
-```
-
-The Medusa application creates a new table for your module link to store the IDs of linked records.
-
-You can also use the `db:migrate` command, which runs both the migrations and syncs the links.
-
-Use either of these commands whenever you make changes to your link definitions. For example, run this command if you remove your link definition file.
-
-***
-
-### Module Link's Database Table
-
-When you define a module link, the Medusa application creates a table in the database for that module link. The table's name is a combination of the names of the two data models linked in the format `module1_table1_module2_table2`, where:
-
-- `module1` and `module2` are the names of the modules.
-- `table1` and `table2` are the table names of the data models.
-
-For example, if you define a link between the `Product` data model from the [Product Module](https://docs.medusajs.com/resources/commerce-modules/product/index.html.md) and a `Post` data model from a Blog Module, the table name would be `product_product_blog_post`.
-
-The table has two columns, each storing the ID of a record from the linked data models. For example, the `product_product_blog_post` table would have columns `product_id` and `post_id`. These columns store only the IDs of the linked records and do not hold a foreign key constraint.
-
-Then, when you create links between records of the data models, the IDs of these data models are stored as a new record in the link's table.
-
-You can also add custom columns in the link table as explained in the [Add Columns to Link Table chapter](https://docs.medusajs.com/learn/fundamentals/module-links/custom-columns/index.html.md).
-
-
-
-***
-
-## When to Use Module Links
-
-- You want to create a relation between data models from different modules.
-- You want to extend the data model of another module.
-
-You want to create a relationship between data models in the same module. Use data model relationships instead.
-
-***
-
-## Define a List Module Link
-
-By default, a module link establishes a one-to-one relation: a record of a data model is linked to one record of the other data model.
-
-To specify that a data model can have multiple of its records linked to the other data model's record, use the `isList` option.
-
-For example:
-
-```ts
-import BlogModule from "../modules/blog"
-import ProductModule from "@medusajs/medusa/product"
-import { defineLink } from "@medusajs/framework/utils"
-
-export default defineLink(
- ProductModule.linkable.product,
- {
- linkable: BlogModule.linkable.post,
- isList: true,
- }
-)
-```
-
-In this case, you pass an object of configuration as a parameter instead. The object accepts the following properties:
-
-- `linkable`: The data model's link configuration.
-- `isList`: Whether multiple records can be linked to one record of the other data model.
-
-In this example, a record of `product` can be linked to more than one record of `post`.
-
-### Many-to-Many Module Link
-
-Your module link can also establish a many-to-many relation between the linked data models. To do this, enable `isList` on both sides of the link.
-
-For example:
-
-```ts
-import BlogModule from "../modules/blog"
-import ProductModule from "@medusajs/medusa/product"
-import { defineLink } from "@medusajs/framework/utils"
-
-export default defineLink(
- {
- linkable: ProductModule.linkable.product,
- isList: true,
- },
- {
- linkable: BlogModule.linkable.post,
- isList: true,
- }
-)
-```
-
-***
-
-## Set Delete Cascades on Link
-
-To enable delete cascade on a link so that when a record is deleted, its linked records are also deleted, pass the `deleteCascade` property in the object passed to `defineLink`.
-
-For example:
-
-```ts
-import BlogModule from "../modules/blog"
-import ProductModule from "@medusajs/medusa/product"
-import { defineLink } from "@medusajs/framework/utils"
-
-export default defineLink(
- ProductModule.linkable.product,
- {
- linkable: BlogModule.linkable.post,
- deleteCascade: true,
- }
-)
-```
-
-In this example, when a product is deleted, its linked `post` record is also deleted.
-
-***
-
-## Renaming Participants in a Module Link
-
-As mentioned in the [Module Link's Database Table](#module-links-database-table) section, the name of a link's table consists of the names of the modules and the data models' table names.
-
-So, if you rename a module or a data model's table, then run the `db:sync-links` or `db:migrate` commands, you'll be asked to delete the old link table and create a new one.
-
-A data model's table name is passed in the first parameter of `model.define`, and a module's name is passed in the first parameter of `Module` in the module's `index.ts` file.
-
-For example, if you have the link table `product_product_blog_post` and you rename the Blog Module from `blog` to `article`, Medusa considers the old link definition deleted. Then, when you run the `db:sync-links` or `db:migrate` command, Medusa will ask if you want to delete the old link table, and will create a new one with the new name `product_product_article_post`.
-
-To resolve this, you can rename the link table in the link definition.
-
-### Rename Link Table
-
-If you need to rename a module or its data model's table, you can persist the old name by passing a third parameter to `defineLink`. This parameter is an object of additional configurations. It accepts a `database` property that allows you to configure the link's table name.
-
-For example, after renaming the Blog Module to `article`, you can persist the old name `blog` in the link table name:
-
-```ts highlights={renameHighlights}
-import ArticleModule from "../modules/article"
-import ProductModule from "@medusajs/medusa/product"
-import { defineLink } from "@medusajs/framework/utils"
-
-export default defineLink(
- ProductModule.linkable.product,
- {
- linkable: ArticleModule.linkable.post,
- isList: true,
- },
- {
- database: {
- table: "product_product_blog_post",
- },
- }
-)
-```
-
-In this example, you set the `table` property in the `database` object to the old link table name `product_product_blog_post`, ensuring that the old link table is not deleted.
-
-This is enough to rename the link table when you rename a module. If you renamed a data model's table, you need to also run the `db:sync-links` or `db:migrate` commands, which will update the column names in the link table automatically:
-
-```bash
-npx medusa db:migrate
-```
-
-***
-
-## Delete Module Link Definition
-
-To delete a module link definition, remove the link file from the `src/links` directory. Then, run the `db:sync-links` or `db:migrate` command to delete the link table from the database:
-
-```bash
-npx medusa db:migrate
-```
-
-
# Workflows
In this chapter, you’ll learn about workflows and how to define and execute them.
@@ -3135,1426 +4557,205 @@ You can now execute this workflow in a custom API route, scheduled job, or subsc
Find a full list of the registered resources in the Medusa container and their registration key in [this reference](https://docs.medusajs.com/resources/medusa-container-resources/index.html.md). You can use these resources in your custom workflows.
-# Medusa Application Configuration
+# Write Tests for Modules
-In this chapter, you'll learn available configurations in the Medusa application. You can change the application's configurations to customize the behavior of the application, its integrated modules and plugins, and more.
-
-## Configuration File
-
-All configurations of the Medusa application are stored in the `medusa.config.ts` file. The file exports an object created using the `defineConfig` utility. For example:
-
-```ts title="medusa.config.ts"
-import { loadEnv, defineConfig } from "@medusajs/framework/utils"
-
-loadEnv(process.env.NODE_ENV || "development", process.cwd())
-
-module.exports = defineConfig({
- projectConfig: {
- databaseUrl: process.env.DATABASE_URL,
- http: {
- storeCors: process.env.STORE_CORS!,
- adminCors: process.env.ADMIN_CORS!,
- authCors: process.env.AUTH_CORS!,
- jwtSecret: process.env.JWT_SECRET || "supersecret",
- cookieSecret: process.env.COOKIE_SECRET || "supersecret",
- },
- },
-})
-
-```
-
-The `defineConfig` utility accepts an object having the following properties:
-
-- [projectConfig](#project-configurations-projectConfig): Essential configurations related to the Medusa application, such as database and CORS configurations.
-- [admin](#admin-configurations-admin): Configurations related to the Medusa Admin.
-- [modules](#module-configurations-modules): Configurations related to registered modules.
-- [plugins](#plugin-configurations-plugins): Configurations related to registered plugins.
-- [featureFlags](#feature-flags-featureFlags): Configurations to manage enabled beta features in the Medusa application.
-
-### Using Environment Variables
-
-Notice that you use the `loadEnv` utility to load environment variables. Learn more about it in the [Environment Variables chapter](https://docs.medusajs.com/learn/fundamentals/environment-variables/index.html.md).
-
-By using this utility, you can use environment variables as the values of your configurations. It's highly recommended that you use environment variables for secret values, such as API keys and database credentials, or for values that change based on the environment, such as the application's Cross Origin Resource Sharing (CORS) configurations.
-
-For example, you can set the `DATABASE_URL` environment variable in your `.env` file:
-
-```bash
-DATABASE_URL=postgres://postgres@localhost/medusa-store
-```
-
-Then, use the value in `medusa-config.ts`:
-
-```ts title="medusa-config.ts"
-module.exports = defineConfig({
- projectConfig: {
- databaseUrl: process.env.DATABASE_URL,
- // ...
- },
- // ...
-})
-```
-
-***
-
-## Project Configurations (`projectConfig`)
-
-The `projectConfig` object contains essential configurations related to the Medusa application, such as database and CORS configurations.
-
-### databaseDriverOptions
-
-The `projectConfig.databaseDriverOptions` configuration is an object of additional options used to configure the PostgreSQL connection. For example, you can support TLS/SSL connection using this configuration's `ssl` property.
-
-This configuration is useful for production databases, which can be supported by setting the `rejectUnauthorized` attribute of `ssl` object to `false`. During development, it's recommended not to pass the `ssl.rejectUnauthorized` option.
-
-#### Example
-
-```ts title="medusa-config.ts"
-module.exports = defineConfig({
- projectConfig: {
- databaseDriverOptions: process.env.NODE_ENV !== "development" ?
- { connection: { ssl: { rejectUnauthorized: false } } } : {},
- // ...
- },
- // ...
-})
-```
-
-When you disable `rejectUnauthorized`, make sure to also add `?ssl_mode=disable` to the end of the [databaseUrl](#databaseUrl) as well.
-
-#### Properties
-
-- connection: (\`object\`)
-
- - ssl: (\`object\` | \`boolean\`)
-
- - pool: (\`object\`)
-
- - min: (\`number\`)
-
- - max: (\`number\`)
-
- - idleTimeoutMillis: (\`number\`)
-
- - reapIntervalMillis: (\`number\`)
-
- - createRetryIntervalMillis: (\`number\`)
-- idle\_in\_transaction\_session\_timeout: (\`number\`)
-
-### databaseLogging
-
-The `projectConfig.databaseLogging` configuration specifies whether database messages should be logged to the console. It is `false` by default.
-
-#### Example
-
-```ts title="medusa-config.ts"
-module.exports = defineConfig({
- projectConfig: {
- databaseLogging: true,
- // ...
- },
- // ...
-})
-```
-
-### databaseName
-
-The `projectConfig.databaseName` configuration determines the name of the database to connect to. If the name is specified in the [databaseUrl](#databaseUrl) configuration, you don't have to use this configuration.
-
-After setting the database credentials, you can create and setup the database using the [db:setup](https://docs.medusajs.com/resources/medusa-cli/commands/db#dbsetup/index.html.md) command of the Medusa CLI.
-
-#### Example
-
-```ts title="medusa-config.ts"
-module.exports = defineConfig({
- projectConfig: {
- databaseName: process.env.DATABASE_NAME ||
- "medusa-store",
- // ...
- },
- // ...
-})
-```
-
-### databaseSchema
-
-The `projectConfig.databaseSchema` configuration specifies the PostgreSQL database schema to connect to, which is `public` by default. Use this configuration only if you want to connect to a different schema.
-
-#### Example
-
-```ts title="medusa-config.ts"
-module.exports = defineConfig({
- projectConfig: {
- databaseSchema: process.env.DATABASE_SCHEMA ||
- "custom",
- // ...
- },
- // ...
-})
-```
-
-### databaseUrl
-
-The `projectConfig.databaseUrl` configuration specifies the PostgreSQL connection URL of the database to connect to. Its format is:
-
-```bash
-postgres://[user][:password]@[host][:port]/[dbname]
-```
-
-Where:
-
-- `[user]`: (required) your PostgreSQL username. If not specified, the system's username is used by default. The database user that you use must have create privileges. If you're using the `postgres` superuser, then it should have these privileges by default. Otherwise, make sure to grant your user create privileges. You can learn how to do that in [PostgreSQL's documentation](https://www.postgresql.org/docs/current/ddl-priv.html).
-- `[:password]`: an optional password for the user. When provided, make sure to put `:` before the password.
-- `[host]`: (required) your PostgreSQL host. When run locally, it should be `localhost`.
-- `[:port]`: an optional port that the PostgreSQL server is listening on. By default, it's `5432`. When provided, make sure to put `:` before the port.
-- `[dbname]`: the name of the database. If not set, then you must provide the database name in the [databaseName](#databasename) configuration.
-
-You can learn more about the connection URL format in [PostgreSQL’s documentation](https://www.postgresql.org/docs/current/libpq-connect.html).
-
-After setting the database URL, you can create and setup the database using the [db:setup](https://docs.medusajs.com/resources/medusa-cli/commands/db#dbsetup/index.html.md) command of the Medusa CLI.
-
-#### Example
-
-For example, set the following database URL in your environment variables:
-
-```bash
-DATABASE_URL=postgres://postgres@localhost/medusa-store
-```
-
-Then, use the value in `medusa-config.ts`:
-
-```ts title="medusa-config.ts"
-module.exports = defineConfig({
- projectConfig: {
- databaseUrl: process.env.DATABASE_URL,
- // ...
- },
- // ...
-})
-```
-
-### http
-
-The `http` configures the application's http-specific settings, such as the JWT secret, CORS configurations, and more.
-
-#### http.jwtSecret
-
-The `projectConfig.http.jwtSecret` configuration is a random string used to create authentication tokens in the HTTP layer. This configuration is not required in development, but must be set in production.
-
-In a development environment, if this option is not set the default value is `supersecret`. However, in production, if this configuration is not set, an error is thrown and the application crashes. This is to ensure that you set a secure value for the JWT secret in production.
-
-#### Example
-
-```ts title="medusa-config.ts"
-module.exports = defineConfig({
- projectConfig: {
- http: {
- jwtSecret: process.env.JWT_SECRET || "supersecret",
- },
- // ...
- },
- // ...
-})
-```
-
-#### http.jwtExpiresIn
-
-The `projectConfig.http.jwtExpiresIn` configuration specifies the expiration time for the JWT token. Its value format is based off the [ms package](https://github.com/vercel/ms).
-
-If not provided, the default value is `1d`.
-
-#### Example
-
-```ts title="medusa-config.ts"
-module.exports = defineConfig({
- projectConfig: {
- http: {
- jwtExpiresIn: process.env.JWT_EXPIRES_IN || "2d",
- },
- // ...
- },
- // ...
-})
-```
-
-#### http.cookieSecret
-
-The `projectConfig.http.cookieSecret` configuration is a random string used to sign cookies in the HTTP layer. This configuration is not required in development, but must be set in production.
-
-In a development environment, if this option is not set the default value is `supersecret`. However, in production, if this configuration is not set, an error is thrown and the application crashes. This is to ensure that you set a secure value for the cookie secret in production.
-
-#### Example
-
-```ts title="medusa-config.ts"
-module.exports = defineConfig({
- projectConfig: {
- http: {
- cookieSecret: process.env.COOKIE_SECRET || "supersecret",
- },
- // ...
- },
- // ...
-})
-```
-
-#### http.authCors
-
-The `projectConfig.http.authCors` configuration specifies the accepted URLs or patterns for API routes starting with `/auth`. It can either be one accepted origin, or a comma-separated list of accepted origins.
-
-Every origin in that list must either be:
-
-- A full URL. For example, `http://localhost:7001`. The URL must not end with a backslash;
-- Or a regular expression pattern that can match more than one origin. For example, `.example.com`. The regex pattern that Medusa tests for is `^([\/~@;%#'])(.*?)\1([gimsuy]*)$`.
-
-Since the `/auth` routes are used for authentication for both store and admin routes, it's recommended to set this configuration's value to a combination of the [storeCors](#httpstoreCors) and [adminCors](#httpadminCors) configurations.
-
-Some example values of common use cases:
-
-```bash
-# Allow different ports locally starting with 700
-AUTH_CORS=/http:\/\/localhost:700\d+$/
-
-# Allow any origin ending with vercel.app. For example, admin.vercel.app
-AUTH_CORS=/vercel\.app$/
-
-# Allow all HTTP requests
-AUTH_CORS=/http:\/\/.+/
-```
-
-Then, set the configuration in `medusa-config.ts`:
-
-```ts title="medusa-config.ts"
-module.exports = defineConfig({
- projectConfig: {
- http: {
- authCors: process.env.AUTH_CORS,
- },
- // ...
- },
- // ...
-})
-```
-
-If you’re adding the value directly within `medusa-config.ts`, make sure to add an extra escaping `/` for every backslash in the pattern. For example:
-
-```ts title="medusa-config.ts"
-module.exports = defineConfig({
- projectConfig: {
- http: {
- authCors: "/http:\\/\\/localhost:700\\d+$/",
- },
- // ...
- },
- // ...
-})
-```
-
-#### http.storeCors
-
-The `projectConfig.http.storeCors` configuration specifies the accepted URLs or patterns for API routes starting with `/store`. It can either be one accepted origin, or a comma-separated list of accepted origins.
-
-Every origin in that list must either be:
-
-- A full URL. For example, `http://localhost:7001`. The URL must not end with a backslash;
-- Or a regular expression pattern that can match more than one origin. For example, `.example.com`. The regex pattern that Medusa tests for is `^([\/~@;%#'])(.*?)\1([gimsuy]*)$`.
-
-Some example values of common use cases:
-
-```bash
-# Allow different ports locally starting with 800
-STORE_CORS=/http:\/\/localhost:800\d+$/
-
-# Allow any origin ending with vercel.app. For example, storefront.vercel.app
-STORE_CORS=/vercel\.app$/
-
-# Allow all HTTP requests
-STORE_CORS=/http:\/\/.+/
-```
-
-Then, set the configuration in `medusa-config.ts`:
-
-```ts title="medusa-config.ts"
-module.exports = defineConfig({
- projectConfig: {
- http: {
- storeCors: process.env.STORE_CORS,
- },
- // ...
- },
- // ...
-})
-```
-
-If you’re adding the value directly within `medusa-config.ts`, make sure to add an extra escaping `/` for every backslash in the pattern. For example:
-
-```ts title="medusa-config.ts"
-module.exports = defineConfig({
- projectConfig: {
- http: {
- storeCors: "/vercel\\.app$/",
- },
- // ...
- },
- // ...
-})
-```
-
-#### http.adminCors
-
-The `projectConfig.http.adminCors` configuration specifies the accepted URLs or patterns for API routes starting with `/admin`. It can either be one accepted origin, or a comma-separated list of accepted origins.
-
-Every origin in that list must either be:
-
-- A full URL. For example, `http://localhost:7001`. The URL must not end with a backslash;
-- Or a regular expression pattern that can match more than one origin. For example, `.example.com`. The regex pattern that Medusa tests for is `^([\/~@;%#'])(.*?)\1([gimsuy]*)$`.
-
-Some example values of common use cases:
-
-```bash
-# Allow different ports locally starting with 700
-ADMIN_CORS=/http:\/\/localhost:700\d+$/
-
-# Allow any origin ending with vercel.app. For example, admin.vercel.app
-ADMIN_CORS=/vercel\.app$/
-
-# Allow all HTTP requests
-ADMIN_CORS=/http:\/\/.+/
-```
-
-Then, set the configuration in `medusa-config.ts`:
-
-```ts title="medusa-config.ts"
-module.exports = defineConfig({
- projectConfig: {
- http: {
- adminCors: process.env.ADMIN_CORS,
- },
- // ...
- },
- // ...
-})
-```
-
-If you’re adding the value directly within `medusa-config.ts`, make sure to add an extra escaping `/` for every backslash in the pattern. For example:
-
-```ts title="medusa-config.ts"
-module.exports = defineConfig({
- projectConfig: {
- http: {
- adminCors: "/vercel\\.app$/",
- },
- // ...
- },
- // ...
-})
-```
-
-#### http.compression
-
-The `projectConfig.http.compression` configuration modifies the HTTP compression settings at the application layer. If you have access to the HTTP server, the recommended approach would be to enable it there. However, some platforms don't offer access to the HTTP layer and in those cases, this is a good alternative.
-
-If you enable HTTP compression and you want to disable it for specific API Routes, you can pass in the request header `"x-no-compression": true`. Learn more in the [API Reference](https://docs.medusajs.com/api/store#http-compression).
-
-For example:
-
-```ts title="medusa-config.ts"
-module.exports = defineConfig({
- projectConfig: {
- http: {
- compression: {
- enabled: true,
- level: 6,
- memLevel: 8,
- threshold: 1024,
- },
- },
- // ...
- },
- // ...
-})
-```
-
-This configuation is an object that accepts the following properties:
-
-- enabled: (\`boolean\`)
-- level: (\`number\`) The level of zlib compression to apply to responses. A higher level will result in better compression but will take longer to complete. A lower level will result in less compression but will be much faster.
-- memLevel: (\`number\`) How much memory should be allocated to the internal compression state. It value is between \`1\` (minimum level) and \`9\` (maximum level).
-- threshold: (\`number\` | \`string\`) The minimum response body size that compression is applied on. Its value can be the number of bytes or any string accepted by the \[bytes]\(https://www.npmjs.com/package/bytes) package.
-
-#### http.authMethodsPerActor
-
-The `projectConfig.http.authMethodsPerActor` configuration specifies the supported authentication providers per actor type (such as `user`, `customer`, or any custom actor).
-
-For example, you can allow Google login for `customers`, and allow email/password logins for `users` in the admin.
-
-`authMethodsPerActor` is a an object whose key is the actor type (for example, `user`), and the value is an array of supported auth provider IDs (for example, `emailpass`).
-
-Learn more about actor types in the [Auth Identity and Actor Type documentation](https://docs.medusajs.com/resources/commerce-modules/auth/auth-identity-and-actor-types/index.html.md).
-
-For example:
-
-```ts title="medusa-config.ts"
-module.exports = defineConfig({
- projectConfig: {
- http: {
- authMethodsPerActor: {
- user: ["emailpass"],
- customer: ["emailpass", "google"],
- },
- },
- // ...
- },
- // ...
-})
-```
-
-The above configurations allow admin users to login using email/password, and customers to login using email/password and Google.
-
-#### http.restrictedFields
-
-The `projectConfig.http.restrictedFields` configuration specifies the fields that can't be selected in API routes (using the `fields` query parameter) unless they're allowed in the [request's Query configurations](https://docs.medusajs.com/learn/fundamentals/module-links/query#request-query-configurations/index.html.md). This is useful to restrict sensitive fields from being exposed in the API.
-
-For example, you can restrict selecting customers in store API routes:
-
-```ts title="medusa-config.ts"
-module.exports = defineConfig({
- projectConfig: {
- http: {
- restrictedFields: {
- store: ["customer", "customers"],
- },
- },
- // ...
- },
- // ...
-})
-```
-
-The `restrictedFields` configuration accepts the following properties:
-
-- store: (\`string\[]\`)
-
-### redisOptions
-
-The `projectConfig.redisOptions` configuration defines options to pass to `ioredis`, which creates the Redis connection used to store the Medusa server session. Refer to [ioredis’s RedisOptions documentation](https://redis.github.io/ioredis/index.html#RedisOptions)
-for the list of available options.
-
-#### Example
-
-```ts title="medusa-config.ts"
-module.exports = defineConfig({
- projectConfig: {
- redisOptions: {
- connectionName: process.env.REDIS_CONNECTION_NAME ||
- "medusa",
- },
- // ...
- },
- // ...
-})
-```
-
-### redisPrefix
-
-The `projectConfig.redisPrefix` configuration defines a prefix on all keys stored in Redis for the Medusa server session. The default value is `sess:`.
-
-The value of this configuration is prepended to `sess:`. For example, if you set it to `medusa:`, then a key stored in Redis is prefixed by `medusa:sess`.
-
-This configuration is not used for modules that also connect to Redis, such as the [Redis Cache Module](https://docs.medusajs.com/resources/infrastructure-modules/cache/redis/index.html.md).
-
-#### Example
-
-```ts title="medusa-config.ts"
-module.exports = defineConfig({
- projectConfig: {
- redisPrefix: process.env.REDIS_URL || "medusa:",
- // ...
- },
- // ...
-})
-```
-
-### redisUrl
-
-The `projectConfig.redisUrl` configuration specifies the connection URL to Redis to store the Medusa server session. When specified, the Medusa server uses Redis to store the session data. Otherwie, the session data is stored in-memory.
-
-This configuration is not used for modules that also connect to Redis, such as the [Redis Cache Module](https://docs.medusajs.com/resources/infrastructure-modules/cache/redis/index.html.md). You'll have to configure the Redis connection for those modules separately.
-
-You must first have Redis installed. You can refer to [Redis's installation guide](https://redis.io/docs/getting-started/installation/).
-
-The Redis connection URL has the following format:
-
-```bash
-redis[s]://[[username][:password]@][host][:port][/db-number]
-```
-
-Where:
-
-- `redis[s]`: the protocol used to connect to Redis. Use `rediss` for a secure connection.
-- `[[username][:password]@]`: an optional username and password for the Redis server.
-- `[host]`: the host of the Redis server. When run locally, it should be `localhost`.
-- `[:port]`: an optional port that the Redis server is listening on. By default, it's `6379`.
-- `[/db-number]`: an optional database number to connect to. By default, it's `0`.
-
-For a local Redis installation, the connection URL should be `redis://localhost:6379` unless you’ve made any changes to the Redis configuration during installation.
-
-#### Example
-
-```ts title="medusa-config.ts"
-module.exports = defineConfig({
- projectConfig: {
- redisUrl: process.env.REDIS_URL ||
- "redis://localhost:6379",
- // ...
- },
- // ...
-})
-```
-
-### sessionOptions
-
-The `projectConfig.sessionOptions` configuration defines additional options to pass to [express-session](https://www.npmjs.com/package/express-session), which is used to store the Medusa server session.
-
-This configuration is not used for modules that also connect to Redis, such as the [Redis Cache Module](https://docs.medusajs.com/resources/infrastructure-modules/cache/redis/index.html.md).
-
-#### Example
-
-```ts title="medusa-config.ts"
-module.exports = defineConfig({
- projectConfig: {
- sessionOptions: {
- name: process.env.SESSION_NAME || "custom",
- },
- // ...
- },
- // ...
-})
-```
-
-#### Properties
-
-- name: (\`string\`)
-- resave: (\`boolean\`)
-- rolling: (\`boolean\`)
-- saveUninitialized: (\`boolean\`)
-- secret: (\`string\`) The secret to sign the session ID cookie. By default, the value of \[http.cookieSecret]\(#httpcookieSecret) is used. Refer to \[express-session’s documentation]\(https://www.npmjs.com/package/express-session#secret) for details.
-- ttl: (\`number\`) The time-to-live (TTL) of the session ID cookie in milliseconds. It is used when calculating the \`Expires\` \`Set-Cookie\` attribute of cookies. Refer to \[express-session’s documentation]\(https://www.npmjs.com/package/express-session#cookie) for more details.
-
-### workerMode
-
-The `projectConfig.workerMode` configuration specifies the worker mode of the Medusa application. You can learn more about it in the [Worker Mode chapter](https://docs.medusajs.com/learn/production/worker-mode/index.html.md).
-
-The value for this configuration can be one of the following:
-
-- `shared`: run the application in a single process, meaning the worker and server run in the same process.
-- `worker`: run the a worker process only.
-- `server`: run the application server only.
-
-#### Example
-
-```ts title="medusa-config.ts"
-module.exports = defineConfig({
- projectConfig: {
- workerMode: process.env.WORKER_MODE || "shared",
- // ...
- },
- // ...
-})
-```
-
-***
-
-## Admin Configurations (`admin`)
-
-The `admin` object contains configurations related to the Medusa Admin.
-
-### backendUrl
-
-The `admin.backendUrl` configuration specifies the URL of the Medusa application. Its default value is the browser origin. This is useful to set when running the admin on a separate domain.
-
-#### Example
-
-```ts title="medusa-config.ts"
-module.exports = defineConfig({
- admin: {
- backendUrl: process.env.MEDUSA_BACKEND_URL ||
- "http://localhost:9000",
- },
- // ...
-})
-```
-
-### disable
-
-The `admin.disable` configuration specifies whether to disable the Medusa Admin. If disabled, the Medusa Admin will not be compiled and you can't access it at `/app` path of your application. The default value is `false`.
-
-#### Example
-
-```ts title="medusa-config.ts"
-module.exports = defineConfig({
- admin: {
- disable: process.env.ADMIN_DISABLED === "true" ||
- false,
- },
- // ...
-})
-```
-
-### path
-
-The `admin.path` configuration indicates the path to the admin dashboard, which is `/app` by default. The value must start with `/` and can't end with a `/`.
-
-The value cannot be one of the reserved paths:
-
-- `/admin`
-- `/store`
-- `/auth`
-- `/`
-
-When using Docker, make sure that the root path of the Docker image isn't the same as the admin's path. For example, if the Docker image's root path is `/app`, change
-the value of the `admin.path` configuration, since it's `/app` by default.
-
-#### Example
-
-```ts title="medusa-config.ts"
-module.exports = defineConfig({
- admin: {
- path: process.env.ADMIN_PATH || `/app`,
- },
- // ...
-})
-```
-
-### storefrontUrl
-
-The `admin.storefrontUrl` configuration specifies the URL of the Medusa storefront application. This URL is used as a prefix to some links in the admin that require performing actions in the storefront.
-
-For example, this URL is used as a prefix to shareable payment links for orders with outstanding amounts.
-
-#### Example
-
-```js title="medusa-config.js"
-module.exports = defineConfig({
- admin: {
- storefrontUrl: process.env.MEDUSA_STOREFRONT_URL ||
- "http://localhost:8000",
- },
- // ...
-})
-```
-
-### vite
-
-The `admin.vite` configration specifies Vite configurations for the Medusa Admin. Its value is a function that receives the default Vite configuration and returns the modified configuration. The default value is `undefined`.
-
-Learn about configurations you can pass to Vite in [Vite's documentation](https://vite.dev/config/).
-
-#### Example
-
-For example, if you're using a third-party library that isn't ESM-compatible, add it to Vite's `optimizeDeps` configuration:
-
-```ts title="medusa-config.ts"
-module.exports = defineConfig({
- admin: {
- vite: () => {
- return {
- optimizeDeps: {
- include: ["qs"],
- },
- }
- },
- },
- // ...
-})
-```
-
-***
-
-## Module Configurations (`modules`)
-
-The `modules` configuration allows you to register and configure the [modules](https://docs.medusajs.com/learn/fundamentals/modules/index.html.md) registered in the Medusa application. Medusa's commerce and Infrastructure Modules are configured by default. So, you only need to pass your custom modules, or override the default configurations of the existing modules.
-
-`modules` is an array of objects for the modules to register. Each object has the following properties:
-
-1. `resolve`: a string indicating the path to the module, or the module's NPM package name. For example, `./src/modules/my-module`.
-2. `options`: (optional) an object indicating the [options to pass to the module](https://docs.medusajs.com/learn/fundamentals/modules/options/index.html.md). This object is specific to the module and its configurations. For example, your module may require an API key option, which you can pass in this object.
-
-For modules that are part of a plugin, learn about registering them in the [Register Modules in Plugins](#register-modules-in-plugins) section.
-
-### Example
-
-To register a custom module:
-
-```ts title="medusa-config.ts"
-module.exports = defineConfig({
- modules: [
- {
- resolve: "./src/modules/cms",
- options: {
- apiKey: process.env.CMS_API_KEY,
- },
- },
- ],
- // ...
-})
-```
-
-You can also override the default configurations of Medusa's modules. For example, to add a Notification Module Provider to the Notification Module:
-
-```ts title="medusa-config.ts"
-module.exports = defineConfig({
- modules: [
- {
- resolve: "@medusajs/medusa/notification",
- options: {
- providers: [
- // default provider
- {
- resolve: "@medusajs/medusa/notification-local",
- id: "local",
- options: {
- name: "Local Notification Provider",
- channels: ["feed"],
- },
- },
- // custom provider
- {
- resolve: "./src/modules/my-notification",
- id: "my-notification",
- options: {
- channels: ["email"],
- // provider options...
- },
- },
- ],
- },
- },
- ],
- // ...
-})
-```
-
-***
-
-## Plugin Configurations (`plugins`)
-
-The `plugins` configuration allows you to register and configure the [plugins](https://docs.medusajs.com/learn/fundamentals/plugins/index.html.md) registered in the Medusa application. Plugins include re-usable Medusa customizations, such as modules, workflows, API routes, and more.
-
-Aside from installing the plugin with NPM, you must also register it in the `medusa.config.ts` file.
-
-The `plugins` configuration is an array of objects for the plugins to register. Each object has the following properties:
-
-- A string, which is the name of the plugin's package as specified in the plugin's `package.json` file. This is useful if the plugin doesn't require any options.
-- An object having the following properties:
- - `resolve`: The name of the plugin's package as specified in the plugin's `package.json` file.
- - `options`: An object that includes [options to be passed to the modules](https://docs.medusajs.com/learn/fundamentals/modules/options#pass-options-to-a-module-in-a-plugin/index.html.md) within the plugin.
-
-### Example
-
-```ts title="medusa-config.ts"
-module.exports = {
- plugins: [
- `medusa-my-plugin-1`,
- {
- resolve: `medusa-my-plugin`,
- options: {
- apiKey: process.env.MY_API_KEY ||
- `test`,
- },
- },
- // ...
- ],
- // ...
-}
-```
-
-The above configuration registers two plugins: `medusa-my-plugin-1` and `medusa-my-plugin`. The latter plugin requires an API key option, which is passed in the `options` object.
-
-### Register Modules in Plugins
-
-When you register a plugin, its modules are automatically registered in the Medusa application. You don't have to register them manually in the `modules` configuration.
-
-However, this isn't the case for module providers. If your plugin includes a module provider, you must register it in the `modules` configuration, referencing the module provider's path.
-
-For example:
-
-```ts title="medusa-config.ts"
-module.exports = {
- plugins: [
- `medusa-my-plugin`,
- ],
- modules: [
- {
- resolve: "@medusajs/medusa/notification",
- options: {
- providers: [
- // ...
- {
- resolve: "medusa-my-plugin/providers/my-notification",
- id: "my-notification",
- options: {
- channels: ["email"],
- // provider options...
- },
- },
- ],
- },
- },
- ],
- // ...
-}
-```
-
-***
-
-## Feature Flags (`featureFlags`)
-
-The `featureFlags` configuration allows you to manage enabled beta features in the Medusa application.
-
-Some features in the Medusa application are guarded by a feature flag. This ensures constant shipping of new features while maintaining the engine’s stability. You can enable or disable these features using the `featureFlags` configuration.
-
-The `featureFlags`'s value is an object whose keys are the names of the feature flags, and their values a boolean indicating whether the feature flag is enabled.
-
-Only enable feature flags in testing or development environments. Enabling a feature flag may introduce breaking changes or unexpected behavior.
-
-You can find available feature flags and their key name [here](https://github.com/medusajs/medusa/tree/develop/packages/medusa/src/loaders/feature-flags).
-
-### Example
-
-```ts title="medusa-config.ts"
-module.exports = defineConfig({
- featureFlags: {
- index_engine: true,
- // ...
- },
- // ...
-})
-```
-
-After enabling a feature flag, make sure to run migrations, as the feature may introduce database changes:
-
-```bash
-npx medusa db:migrate
-```
-
-
-# Using TypeScript Aliases
-
-By default, Medusa doesn't support TypeScript aliases in production.
-
-If you prefer using TypeScript aliases, install following development dependencies:
-
-```bash npm2yarn
-npm install --save-dev tsc-alias rimraf
-```
-
-Where `tsc-alias` is a package that resolves TypeScript aliases, and `rimraf` is a package that removes files and directories.
-
-Then, add a new `resolve:aliases` script to your `package.json` and update the `build` script:
-
-```json title="package.json"
-{
- "scripts": {
- // other scripts...
- "resolve:aliases": "tsc --showConfig -p tsconfig.json > tsconfig.resolved.json && tsc-alias -p tsconfig.resolved.json && rimraf tsconfig.resolved.json",
- "build": "medusa build && npm run resolve:aliases"
- }
-}
-```
-
-You can now use TypeScript aliases in your Medusa application. For example, add the following in `tsconfig.json`:
-
-```json title="tsconfig.json"
-{
- "compilerOptions": {
- // ...
- "paths": {
- "@/*": ["./src/*"]
- }
- }
-}
-```
-
-Now, you can import modules, for example, using TypeScript aliases:
-
-```ts
-import { BrandModuleService } from "@/modules/brand/service"
-```
-
-
-# General Medusa Application Deployment Guide
-
-In this document, you'll learn the general steps to deploy your Medusa application. How you apply these steps depend on your chosen hosting provider or platform.
-
-Find how-to guides for specific platforms in [this documentation](https://docs.medusajs.com/resources/deployment/index.html.md).
-
-Want Medusa to manage and maintain your infrastructure? [Sign up and learn more about Medusa Cloud](https://medusajs.com/pricing)
-
-Medusa Cloud is our managed services offering that makes deploying and operating Medusa applications possible without having to worry about configuring, scaling, and maintaining infrastructure. Medusa Cloud hosts your server, Admin dashboard, database, and Redis instance.
-
-With Medusa Cloud, you maintain full customization control as you deploy your own modules and customizations directly from GitHub:
-
-- Push to deploy.
-- Multiple testing environments.
-- Preview environments for new PRs.
-- Test on production-like data.
+In this chapter, you'll learn about `moduleIntegrationTestRunner` from Medusa's Testing Framework and how to use it to write integration tests for a module's main service.
### Prerequisites
-- [Medusa application’s codebase hosted on GitHub repository.](https://docs.medusajs.com/learn/index.html.md)
+- [Testing Tools Setup](https://docs.medusajs.com/learn/debugging-and-testing/testing-tools/index.html.md)
-## What You'll Deploy
+## moduleIntegrationTestRunner Utility
-When you deploy the Medusa application, you need to deploy the following resources:
+`moduleIntegrationTestRunner` creates integration tests for a module. The integration tests run on a test Medusa application with only the specified module enabled.
-1. PostgreSQL database: This is the database that will hold your Medusa application's details.
-2. Redis database: This is the database that will store the Medusa server's session.
-3. Medusa application in [server and worker mode](https://docs.medusajs.com/learn/production/worker-mode/index.html.md), where:
- - The server mode handles incoming API requests and serving the Medusa Admin dashboard.
- - The worker mode handles background tasks, such as scheduled jobs and subscribers.
+For example, assuming you have a `blog` module, create a test file at `src/modules/blog/__tests__/service.spec.ts`:
-So, when choosing a hosting provider, make sure it supports deploying these resources. Also, for optimal experience, the hosting provider and plan must offer at least 2GB of RAM.
+```ts title="src/modules/blog/__tests__/service.spec.ts"
+import { moduleIntegrationTestRunner } from "@medusajs/test-utils"
+import { BLOG_MODULE } from ".."
+import BlogModuleService from "../service"
+import Post from "../models/post"
-***
-
-## 1. Configure Medusa Application
-
-### Worker Mode
-
-The `workerMode` configuration determines which mode the Medusa application runs in. When you deploy the Medusa application, you deploy two instances: one in server mode, and one in worker mode.
-
-Learn more about worker mode in the [Worker Module chapter](https://docs.medusajs.com/learn/production/worker-mode/index.html.md).
-
-So, add the following configuration in `medusa-config.ts`:
-
-```ts title="medusa-config.ts"
-module.exports = defineConfig({
- projectConfig: {
- // ...
- workerMode: process.env.MEDUSA_WORKER_MODE as "shared" | "worker" | "server",
+moduleIntegrationTestRunner({
+ moduleName: BLOG_MODULE,
+ moduleModels: [Post],
+ resolve: "./src/modules/blog",
+ testSuite: ({ service }) => {
+ // TODO write tests
},
})
+
+jest.setTimeout(60 * 1000)
```
-Later, you’ll set different values of the `MEDUSA_WORKER_MODE` environment variable for each Medusa application deployment or instance.
+The `moduleIntegrationTestRunner` function accepts as a parameter an object with the following properties:
-### Configure Medusa Admin
+- `moduleName`: The name of the module.
+- `moduleModels`: An array of models in the module. Refer to [this section](#write-tests-for-modules-without-data-models) if your module doesn't have data models.
+- `resolve`: The path to the module's directory.
+- `testSuite`: A function that defines the tests to run.
-The Medusa Admin is served by the Medusa server application. So, you need to disable it in the worker Medusa application only.
+The `testSuite` function accepts as a parameter an object having the `service` property, which is an instance of the module's main service.
-To disable the Medusa Admin in the worker Medusa application while keeping it enabled in the server Medusa application, add the following configuration in `medusa-config.ts`:
+The type argument provided to the `moduleIntegrationTestRunner` function is used as the type of the `service` property.
-```ts title="medusa-config.ts"
-module.exports = defineConfig({
- // ...
- admin: {
- disable: process.env.DISABLE_MEDUSA_ADMIN === "true",
- },
-})
-```
-
-Later, you’ll set different values of the `DISABLE_MEDUSA_ADMIN` environment variable for each Medusa application instance.
-
-### Configure Redis URL
-
-The `redisUrl` configuration specifies the connection URL to Redis to store the Medusa server's session.
-
-Learn more in the [Medusa Configuration documentation](https://docs.medusajs.com/learn/configurations/medusa-config#redisurl/index.html.md).
-
-So, add the following configuration in `medusa-config.ts` :
-
-```ts title="medusa-config.ts"
-module.exports = defineConfig({
- projectConfig: {
- // ...
- redisUrl: process.env.REDIS_URL,
- },
-})
-```
+The tests in the `testSuite` function are written using [Jest](https://jestjs.io/).
***
-## 2. Add predeploy Script
+## Run Tests
-Before you start the Medusa application in production, you should always run migrations and sync links.
-
-So, add the following script in `package.json`:
-
-```json
-"scripts": {
- // ...
- "predeploy": "medusa db:migrate"
-},
-```
-
-***
-
-## 3. Install Production Modules and Providers
-
-By default, your Medusa application uses modules and providers useful for development, such as the In-Memory Cache Module or the Local File Module Provider.
-
-It’s highly recommended to instead use modules and providers suitable for production, including:
-
-- [Redis Cache Module](https://docs.medusajs.com/resources/infrastructure-modules/cache/redis/index.html.md)
-- [Redis Event Bus Module](https://docs.medusajs.com/resources/infrastructure-modules/event/redis/index.html.md)
-- [Workflow Engine Redis Module](https://docs.medusajs.com/resources/infrastructure-modules/workflow-engine/redis/index.html.md)
-- [S3 File Module Provider](https://docs.medusajs.com/resources/infrastructure-modules/file/s3/index.html.md) (or other file module providers production-ready).
-- [SendGrid Notification Module Provider](https://docs.medusajs.com/resources/infrastructure-modules/notification/sendgrid/index.html.md) (or other notification module providers production-ready).
-
-Then, add these modules in `medusa-config.ts`:
-
-```ts title="medusa-config.ts"
-import { Modules } from "@medusajs/framework/utils"
-
-module.exports = defineConfig({
- // ...
- modules: [
- {
- resolve: "@medusajs/medusa/cache-redis",
- options: {
- redisUrl: process.env.REDIS_URL,
- },
- },
- {
- resolve: "@medusajs/medusa/event-bus-redis",
- options: {
- redisUrl: process.env.REDIS_URL,
- },
- },
- {
- resolve: "@medusajs/medusa/workflow-engine-redis",
- options: {
- redis: {
- url: process.env.REDIS_URL,
- },
- },
- },
- ],
-})
-```
-
-Check out the [Integrations](https://docs.medusajs.com/resources/integrations/index.html.md) and [Infrastructure Modules](https://docs.medusajs.com/resources/infrastructure-modules/index.html.md) documentation for other modules and providers to use.
-
-***
-
-## 4. Create PostgreSQL and Redis Databases
-
-Your Medusa application must connect to PostgreSQL and Redis databases. So, before you deploy it, create production PostgreSQL and Redis databases.
-
-If your hosting provider doesn't support databases, you can use [Neon for PostgreSQL database hosting](https://neon.tech/), and [Redis Cloud for the Redis database hosting](https://redis.io/cloud/).
-
-After hosting both databases, keep their connection URLs for the next steps.
-
-***
-
-## 5. Deploy Medusa Application in Server Mode
-
-As mentioned earlier, you'll deploy two instances or create two deployments of your Medusa application: one in server mode, and the other in worker mode.
-
-The deployment steps depend on your hosting provider. This section provides the general steps to perform during the deployment.
-
-### Set Environment Variables
-
-When setting the environment variables of the Medusa application, set the following variables:
-
-```bash
-COOKIE_SECRET=supersecret # TODO GENERATE SECURE SECRET
-JWT_SECRET=supersecret # TODO GENERATE SECURE SECRET
-STORE_CORS= # STOREFRONT URL
-ADMIN_CORS= # ADMIN URL
-AUTH_CORS= # STOREFRONT AND ADMIN URLS, SEPARATED BY COMMAS
-DISABLE_MEDUSA_ADMIN=false
-MEDUSA_WORKER_MODE=server
-PORT=9000
-DATABASE_URL # POSTGRES DATABASE URL
-REDIS_URL= # REDIS DATABASE URL
-```
-
-Where:
-
-- The value of `COOKIE_SECRET` and `JWT_SECRET` must be a randomly generated secret.
-- `STORE_CORS`'s value is the URL of your storefront. If you don’t have it yet, you can skip adding it for now.
-- `ADMIN_CORS`'s value is the URL of the admin dashboard, which is the same as the server Medusa application. You can add it later if you don't currently have it.
-- `AUTH_CORS`'s value is the URLs of any application authenticating users, customers, or other actor types, such as the storefront and admin URLs. The URLs are separated by commas. If you don’t have the URLs yet, you can set its value later.
-- Set `DISABLE_MEDUSA_ADMIN`'s value to `false` so that the admin is built with the server application.
-- Set the PostgreSQL database's connection URL as the value of `DATABASE_URL`
-- Set the Redis database's connection URL as the value of `REDIS_URL`.
-
-Feel free to add any other relevant environment variables, such as for integrations and Infrastructure Modules. If you're using environment variables in your admin customizations, make sure to set them as well, as they're inlined during the build process.
-
-### Set Start Command
-
-The Medusa application's production build, which is created using the `build` command, outputs the Medusa application to `.medusa/server`. So, you must install the dependencies in the `.medusa/server` directory, then run the `start` command in it.
-
-If your hosting provider doesn't support setting a current-working directory, set the start command to the following:
+Run the following command to run your module integration tests:
```bash npm2yarn
-cd .medusa/server && npm install && npm run predeploy && npm run start
+npm run test:integration:modules
```
-Notice that you run the `predeploy` command before starting the Medusa application to run migrations and sync links whenever there's an update.
+If you don't have a `test:integration:modules` script in `package.json`, refer to the [Medusa Testing Tools chapter](https://docs.medusajs.com/learn/debugging-and-testing/testing-tools#add-test-commands/index.html.md).
-### Set Backend URL in Admin Configuration
+This runs your Medusa application and runs the tests available in any `__tests__` directory under the `src/modules` directory.
-The Medusa Admin is built and hosted statically. To send requests to the Medusa server application, you must set the backend URL in the Medusa Admin's configuration.
+***
-After you’ve obtained the Medusa application’s URL, add the following configuration to `medusa-config.ts`:
+## Pass Module Options
-```ts title="medusa-config.ts"
-module.exports = defineConfig({
- // ...
- admin: {
- // ...
- backendUrl: process.env.MEDUSA_BACKEND_URL,
+If your module accepts options, you can set them using the `moduleOptions` property of the `moduleIntegrationTestRunner`'s parameter.
+
+For example:
+
+```ts
+import { moduleIntegrationTestRunner } from "@medusajs/test-utils"
+import BlogModuleService from "../service"
+
+moduleIntegrationTestRunner({
+ moduleOptions: {
+ apiKey: "123",
},
+ // ...
})
```
-Then, push the changes to the GitHub repository or deployed application.
+***
-In your hosting provider, add or modify the following environment variables for the Medusa application in server mode:
+## Write Tests for Modules without Data Models
-```bash
-ADMIN_CORS= # MEDUSA APPLICATION URL
-AUTH_CORS= # ADD MEDUSA APPLICATION URL
-MEDUSA_BACKEND_URL= # URL TO DEPLOYED MEDUSA APPLICATION
+If your module doesn't have a data model, pass a dummy model in the `moduleModels` property.
+
+For example:
+
+```ts
+import { moduleIntegrationTestRunner } from "@medusajs/test-utils"
+import BlogModuleService from "../service"
+import { model } from "@medusajs/framework/utils"
+
+const DummyModel = model.define("dummy_model", {
+ id: model.id().primaryKey(),
+})
+
+moduleIntegrationTestRunner({
+ moduleModels: [DummyModel],
+ // ...
+})
+
+jest.setTimeout(60 * 1000)
```
-Where you set the value of `ADMIN_CORS` and `MEDUSA_BACKEND_URL` to the Medusa application’s URL, and you add the URL to `AUTH_CORS`.
-
-After setting the environment variables, make sure to restart the deployment for the changes to take effect.
-
-Remember to separate URLs in `AUTH_CORS` by commas.
-
***
-## 6. Deploy Medusa Application in Worker Mode
+### Other Options and Inputs
-Next, you'll deploy the Medusa application in worker mode.
+Refer to [the Test Tooling Reference](https://docs.medusajs.com/resources/test-tools-reference/moduleIntegrationTestRunner/index.html.md) for other available parameter options and inputs of the `testSuite` function.
-As explained in the previous section, the deployment steps depend on your hosting provider. This section provides the general steps to perform during the deployment.
+***
-### Set Environment Variables
+## Database Used in Tests
-When setting the environment variables of the Medusa application, set the following variables:
+The `moduleIntegrationTestRunner` function creates a database with a random name before running the tests. Then, it drops that database after all the tests end.
-```bash
-COOKIE_SECRET=supersecret # TODO GENERATE SECURE SECRET
-JWT_SECRET=supersecret # TODO GENERATE SECURE SECRET
-DISABLE_MEDUSA_ADMIN=true
-MEDUSA_WORKER_MODE=worker
-PORT=9000
-DATABASE_URL # POSTGRES DATABASE URL
-REDIS_URL= # REDIS DATABASE URL
+To manage that database, such as changing its name or perform operations on it in your tests, refer to [the Test Tooling Reference](https://docs.medusajs.com/resources/test-tools-reference/moduleIntegrationTestRunner/index.html.md).
+
+
+# Write Integration Tests
+
+In this chapter, you'll learn about `medusaIntegrationTestRunner` from Medusa's Testing Framework and how to use it to write integration tests.
+
+### Prerequisites
+
+- [Testing Tools Setup](https://docs.medusajs.com/learn/debugging-and-testing/testing-tools/index.html.md)
+
+## medusaIntegrationTestRunner Utility
+
+The `medusaIntegrationTestRunner` is from Medusa's Testing Framework and it's used to create integration tests in your Medusa project. It runs a full Medusa application, allowing you test API routes, workflows, or other customizations.
+
+For example:
+
+```ts title="integration-tests/http/test.spec.ts" highlights={highlights}
+import { medusaIntegrationTestRunner } from "@medusajs/test-utils"
+
+medusaIntegrationTestRunner({
+ testSuite: ({ api, getContainer }) => {
+ // TODO write tests...
+ },
+})
+
+jest.setTimeout(60 * 1000)
```
-Where:
+The `medusaIntegrationTestRunner` function accepts an object as a parameter. The object has a required property `testSuite`.
-- The value of `COOKIE_SECRET` and `JWT_SECRET` must be a randomly generated secret.
-- Set `DISABLE_MEDUSA_ADMIN`'s value to `true` so that the admin isn't built with the worker application.
-- Set the PostgreSQL database's connection URL as the value of `DATABASE_URL`
-- Set the Redis database's connection URL as the value of `REDIS_URL`.
+`testSuite`'s value is a function that defines the tests to run. The function accepts as a parameter an object that has the following properties:
-Feel free to add any other relevant environment variables, such as for integrations and Infrastructure Modules.
+- `api`: a set of utility methods used to send requests to the Medusa application. It has the following methods:
+ - `get`: Send a `GET` request to an API route.
+ - `post`: Send a `POST` request to an API route.
+ - `delete`: Send a `DELETE` request to an API route.
+- `getContainer`: a function that retrieves the Medusa Container. Use the `getContainer().resolve` method to resolve resources from the Medusa Container.
-### Set Start Command
+The tests in the `testSuite` function are written using [Jest](https://jestjs.io/).
-The Medusa application's production build, which is created using the `build` command, outputs the Medusa application to `.medusa/server`. So, you must install the dependencies in the `.medusa/server` directory, then run the `start` command in it.
+### Jest Timeout
-If your hosting provider doesn't support setting a current-working directory, set the start command to the following:
+Since your tests connect to the database and perform actions that require more time than the typical tests, make sure to increase the timeout in your test:
+
+```ts title="integration-tests/http/test.spec.ts"
+// in your test's file
+jest.setTimeout(60 * 1000)
+```
+
+***
+
+### Run Tests
+
+Run the following command to run your tests:
```bash npm2yarn
-cd .medusa/server && npm run install && npm run start
+npm run test:integration
```
-***
+If you don't have a `test:integration` script in `package.json`, refer to the [Medusa Testing Tools chapter](https://docs.medusajs.com/learn/debugging-and-testing/testing-tools#add-test-commands/index.html.md).
-## 7. Test Deployed Application
-
-Once the application is deployed and live, go to `/health`, where `` is the URL of the Medusa application in server mode. If the deployment was successful, you’ll see the `OK` response.
-
-The Medusa Admin is also available at `/app`.
+This runs your Medusa application and runs the tests available under the `src/integrations/http` directory.
***
-## Create Admin User
+## Other Options and Inputs
-If your hosting provider supports running commands in your Medusa application's directory, run the following command to create an admin user:
-
-```bash
-npx medusa user -e admin-medusa@test.com -p supersecret
-```
-
-Replace the email `admin-medusa@test.com` and password `supersecret` with the credentials you want.
-
-You can use these credentials to log into the Medusa Admin dashboard.
-
-
-# Medusa's Architecture
-
-In this chapter, you'll learn about the architectural layers in Medusa.
-
-Find the full architectural diagram at the [end of this chapter](#full-diagram-of-medusas-architecture).
-
-## HTTP, Workflow, and Module Layers
-
-Medusa is a headless commerce platform. So, storefronts, admin dashboards, and other clients consume Medusa's functionalities through its API routes.
-
-In a common Medusa application, requests go through four layers in the stack. In order of entry, those are:
-
-1. API Routes (HTTP): Our API Routes are the typical entry point. The Medusa server is based on Express.js, which handles incoming requests. It can also connect to a Redis database that stores the server session data.
-2. Workflows: API Routes consume workflows that hold the opinionated business logic of your application.
-3. Modules: Workflows use domain-specific modules for resource management.
-4. Data store: Modules query the underlying datastore, which is a PostgreSQL database in common cases.
-
-These layers of stack can be implemented within [plugins](https://docs.medusajs.com/learn/fundamentals/plugins/index.html.md).
-
-
+Refer to [the Test Tooling Reference](https://docs.medusajs.com/resources/test-tools-reference/medusaIntegrationTestRunner/index.html.md) for other available parameter options and inputs of the `testSuite` function.
***
-## Database Layer
+## Database Used in Tests
-The Medusa application injects into each module, including your [custom modules](https://docs.medusajs.com/learn/fundamentals/modules/index.html.md), a connection to the configured PostgreSQL database. Modules use that connection to read and write data to the database.
+The `medusaIntegrationTestRunner` function creates a database with a random name before running the tests. Then, it drops that database after all the tests end.
-Modules can be implemented within [plugins](https://docs.medusajs.com/learn/fundamentals/plugins/index.html.md).
-
-
+To manage that database, such as changing its name or perform operations on it in your tests, refer to [the Test Tooling Reference](https://docs.medusajs.com/resources/test-tools-reference/medusaIntegrationTestRunner/index.html.md).
***
-## Third-Party Integrations Layer
+## Example Integration Tests
-Third-party services and systems are integrated through Medusa's Commerce and Infrastructure Modules. You also create custom third-party integrations through a [custom module](https://docs.medusajs.com/learn/fundamentals/modules/index.html.md).
-
-Modules can be implemented within [plugins](https://docs.medusajs.com/learn/fundamentals/plugins/index.html.md).
-
-### Commerce Modules
-
-[Commerce Modules](https://docs.medusajs.com/resources/commerce-modules/index.html.md) integrate third-party services relevant for commerce or user-facing features. For example, you can integrate [Stripe](https://docs.medusajs.com/resources/commerce-modules/payment/payment-provider/stripe/index.html.md) through a Payment Module Provider, or [ShipStation](https://docs.medusajs.com/resources/integrations/guides/shipstation/index.html.md) through a Fulfillment Module Provider.
-
-You can also integrate third-party services for custom functionalities. For example, you can integrate [Sanity](https://docs.medusajs.com/resources/integrations/guides/sanity/index.html.md) for rich CMS capabilities, or [Odoo](https://docs.medusajs.com/resources/recipes/erp/odoo/index.html.md) to sync your Medusa application with your ERP system.
-
-You can replace any of the third-party services mentioned above to build your preferred commerce ecosystem.
-
-
-
-### Infrastructure Modules
-
-[Infrastructure Modules](https://docs.medusajs.com/resources/infrastructure-modules/index.html.md) integrate third-party services and systems that customize Medusa's infrastructure. Medusa has the following Infrastructure Modules:
-
-- [Cache Module](https://docs.medusajs.com/resources/infrastructure-modules/cache/index.html.md): Caches data that require heavy computation. You can integrate a custom module to handle the caching with services like Memcached, or use the existing [Redis Cache Module](https://docs.medusajs.com/resources/infrastructure-modules/cache/redis/index.html.md).
-- [Event Module](https://docs.medusajs.com/resources/infrastructure-modules/event/index.html.md): A pub/sub system that allows you to subscribe to events and trigger them. You can integrate [Redis](https://docs.medusajs.com/resources/infrastructure-modules/event/redis/index.html.md) as the pub/sub system.
-- [File Module](https://docs.medusajs.com/resources/infrastructure-modules/file/index.html.md): Manages file uploads and storage, such as upload of product images. You can integrate [AWS S3](https://docs.medusajs.com/resources/infrastructure-modules/file/s3/index.html.md) for file storage.
-- [Locking Module](https://docs.medusajs.com/resources/infrastructure-modules/locking/index.html.md): Manages access to shared resources by multiple processes or threads, preventing conflict between processes and ensuring data consistency. You can integrate [Redis](https://docs.medusajs.com/resources/infrastructure-modules/locking/redis/index.html.md) for locking.
-- [Notification Module](https://docs.medusajs.com/resources/infrastructure-modules/notification/index.html.md): Sends notifications to customers and users, such as for order updates or newsletters. You can integrate [SendGrid](https://docs.medusajs.com/resources/infrastructure-modules/notification/sendgrid/index.html.md) for sending emails.
-- [Workflow Engine Module](https://docs.medusajs.com/resources/infrastructure-modules/workflow-engine/index.html.md): Orchestrates workflows that hold the business logic of your application. You can integrate [Redis](https://docs.medusajs.com/resources/infrastructure-modules/workflow-engine/redis/index.html.md) to orchestrate workflows.
-
-All of the third-party services mentioned above can be replaced to help you build your preferred architecture and ecosystem.
-
-
-
-***
-
-## Full Diagram of Medusa's Architecture
-
-The following diagram illustrates Medusa's architecture including all its layers.
-
-
-
-
-# Scheduled Jobs
-
-In this chapter, you’ll learn about scheduled jobs and how to use them.
-
-## What is a Scheduled Job?
-
-When building your commerce application, you may need to automate tasks and run them repeatedly at a specific schedule. For example, you need to automatically sync products to a third-party service once a day.
-
-In other commerce platforms, this feature isn't natively supported. Instead, you have to setup a separate application to execute cron jobs, which adds complexity as to how you expose this task to be executed in a cron job, or how do you debug it when it's not running within the platform's tooling.
-
-Medusa removes this overhead by supporting this feature natively with scheduled jobs. A scheduled job is an asynchronous function that the Medusa application runs at the interval you specify during the Medusa application's runtime. Your efforts are only spent on implementing the functionality performed by the job, such as syncing products to an ERP.
-
-- You want the action to execute at a specified schedule while the Medusa application **isn't** running. Instead, use the operating system's equivalent of a cron job.
-- You want to execute the action once when the application loads. Use [loaders](https://docs.medusajs.com/learn/fundamentals/modules/loaders/index.html.md) instead.
-- You want to execute the action if an event occurs. Use [subscribers](https://docs.medusajs.com/learn/fundamentals/events-and-subscribers/index.html.md) instead.
-
-***
-
-## How to Create a Scheduled Job?
-
-You create a scheduled job in a TypeScript or JavaScript file under the `src/jobs` directory. The file exports the asynchronous function to run, and the configurations indicating the schedule to run the function.
-
-For example, create the file `src/jobs/hello-world.ts` with the following content:
-
-
-
-```ts title="src/jobs/hello-world.ts" highlights={highlights}
-import { MedusaContainer } from "@medusajs/framework/types"
-
-export default async function greetingJob(container: MedusaContainer) {
- const logger = container.resolve("logger")
-
- logger.info("Greeting!")
-}
-
-export const config = {
- name: "greeting-every-minute",
- schedule: "* * * * *",
-}
-```
-
-You export an asynchronous function that receives the [Medusa container](https://docs.medusajs.com/learn/fundamentals/medusa-container/index.html.md) as a parameter. In the function, you resolve the [Logger utility](https://docs.medusajs.com/learn/debugging-and-testing/logging/index.html.md) from the Medusa container and log a message.
-
-You also export a `config` object that has the following properties:
-
-- `name`: A unique name for the job.
-- `schedule`: A string that holds a [cron expression](https://crontab.guru/) indicating the schedule to run the job.
-
-This scheduled job executes every minute and logs into the terminal `Greeting!`.
-
-### Test the Scheduled Job
-
-To test out your scheduled job, start the Medusa application:
-
-```bash npm2yarn
-npm run dev
-```
-
-After a minute, the following message will be logged to the terminal:
-
-```bash
-info: Greeting!
-```
-
-***
-
-## Example: Sync Products Once a Day
-
-In this section, you'll find a brief example of how you use a scheduled job to sync products to a third-party service.
-
-When implementing flows spanning across systems or [modules](https://docs.medusajs.com/learn/fundamentals/modules/index.html.md), you use [workflows](https://docs.medusajs.com/learn/fundamentals/workflows/index.html.md). A workflow is a task made up of a series of steps, and you construct it like you would a regular function, but it's a special function that supports rollback mechanism in case of errors, background execution, and more.
-
-You can learn how to create a workflow in [this chapter](https://docs.medusajs.com/learn/fundamentals/workflows/index.html.md), but this example assumes you already have a `syncProductToErpWorkflow` implemented. To execute this workflow once a day, create a scheduled job at `src/jobs/sync-products.ts` with the following content:
-
-```ts title="src/jobs/sync-products.ts"
-import { MedusaContainer } from "@medusajs/framework/types"
-import { syncProductToErpWorkflow } from "../workflows/sync-products-to-erp"
-
-export default async function syncProductsJob(container: MedusaContainer) {
- await syncProductToErpWorkflow(container)
- .run()
-}
-
-export const config = {
- name: "sync-products-job",
- schedule: "0 0 * * *",
-}
-```
-
-In the scheduled job function, you execute the `syncProductToErpWorkflow` by invoking it and passing it the container, then invoking the `run` method. You also specify in the exported configurations the schedule `0 0 * * *` which indicates midnight time of every day.
-
-The next time you start the Medusa application, it will run this job every day at midnight.
+The next chapters provide examples of writing integration tests for API routes and workflows.
# Worker Mode of Medusa Instance
@@ -4739,6 +4940,372 @@ MEDUSA_FF_ANALYTICS=false
```
+# Guide: Implement Brand Module
+
+In this chapter, you'll build a Brand Module that adds a `brand` table to the database and provides data-management features for it.
+
+A module is a reusable package of functionalities related to a single domain or integration. Medusa comes with multiple pre-built modules for core commerce needs, such as the [Cart Module](https://docs.medusajs.com/resources/commerce-modules/cart/index.html.md) that holds the data models and business logic for cart operations.
+
+In a module, you create data models and business logic to manage them. In the next chapters, you'll see how you use the module to build commerce features.
+
+
+
+Learn more about modules in [this chapter](https://docs.medusajs.com/learn/fundamentals/modules/index.html.md).
+
+## 1. Create Module Directory
+
+Modules are created in a sub-directory of `src/modules`. So, start by creating the directory `src/modules/brand` that will hold the Brand Module's files.
+
+
+
+***
+
+## 2. Create Data Model
+
+A data model represents a table in the database. You create data models using Medusa's Data Model Language (DML). It simplifies defining a table's columns, relations, and indexes with straightforward methods and configurations.
+
+Learn more about data models in [this chapter](https://docs.medusajs.com/learn/fundamentals/modules#1-create-data-model/index.html.md).
+
+You create a data model in a TypeScript or JavaScript file under the `models` directory of a module. So, to create a data model that represents a new `brand` table in the database, create the file `src/modules/brand/models/brand.ts` with the following content:
+
+
+
+```ts title="src/modules/brand/models/brand.ts"
+import { model } from "@medusajs/framework/utils"
+
+export const Brand = model.define("brand", {
+ id: model.id().primaryKey(),
+ name: model.text(),
+})
+```
+
+You create a `Brand` data model which has an `id` primary key property, and a `name` text property.
+
+You define the data model using the `define` method of the DML. It accepts two parameters:
+
+1. The first one is the name of the data model's table in the database. Use snake-case names.
+2. The second is an object, which is the data model's schema.
+
+Learn about other property types in [this chapter](https://docs.medusajs.com/learn/fundamentals/data-models/properties/index.html.md).
+
+***
+
+## 3. Create Module Service
+
+You perform database operations on your data models in a service, which is a class exported by the module and acts like an interface to its functionalities.
+
+In this step, you'll create the Brand Module's service that provides methods to manage the `Brand` data model. In the next chapters, you'll use this service when exposing custom features that involve managing brands.
+
+Learn more about services in [this chapter](https://docs.medusajs.com/learn/fundamentals/modules#2-create-service/index.html.md).
+
+You define a service in a `service.ts` or `service.js` file at the root of your module's directory. So, create the file `src/modules/brand/service.ts` with the following content:
+
+
+
+```ts title="src/modules/brand/service.ts" highlights={serviceHighlights}
+import { MedusaService } from "@medusajs/framework/utils"
+import { Brand } from "./models/brand"
+
+class BrandModuleService extends MedusaService({
+ Brand,
+}) {
+
+}
+
+export default BrandModuleService
+```
+
+The `BrandModuleService` extends a class returned by `MedusaService` from the Modules SDK. This function generates a class with data-management methods for your module's data models.
+
+The `MedusaService` function receives an object of the module's data models as a parameter, and generates methods to manage those data models. So, the `BrandModuleService` now has methods like `createBrands` and `retrieveBrand` to manage the `Brand` data model.
+
+You'll use these methods in the [next chapter](https://docs.medusajs.com/learn/customization/custom-features/workflow/index.html.md).
+
+Find a reference of all generated methods in [this guide](https://docs.medusajs.com/resources/service-factory-reference/index.html.md).
+
+***
+
+## 4. Export Module Definition
+
+A module must export a definition that tells Medusa the name of the module and its main service. This definition is exported in an `index.ts` file at the module's root directory.
+
+So, to export the Brand Module's definition, create the file `src/modules/brand/index.ts` with the following content:
+
+
+
+```ts title="src/modules/brand/index.ts"
+import { Module } from "@medusajs/framework/utils"
+import BrandModuleService from "./service"
+
+export const BRAND_MODULE = "brand"
+
+export default Module(BRAND_MODULE, {
+ service: BrandModuleService,
+})
+```
+
+You use `Module` from the Modules SDK to create the module's definition. It accepts two parameters:
+
+1. The module's name (`brand`). You'll use this name when you use this module in other customizations.
+2. An object with a required property `service` indicating the module's main service.
+
+You export `BRAND_MODULE` to reference the module's name more reliably in other customizations.
+
+***
+
+## 5. Add Module to Medusa's Configurations
+
+To start using your module, you must add it to Medusa's configurations in `medusa-config.ts`.
+
+The object passed to `defineConfig` in `medusa-config.ts` accepts a `modules` property, whose value is an array of modules to add to the application. So, add the following in `medusa-config.ts`:
+
+```ts title="medusa-config.ts"
+module.exports = defineConfig({
+ // ...
+ modules: [
+ {
+ resolve: "./src/modules/brand",
+ },
+ ],
+})
+```
+
+The Brand Module is now added to your Medusa application. You'll start using it in the [next chapter](https://docs.medusajs.com/learn/customization/custom-features/workflow/index.html.md).
+
+***
+
+## 6. Generate and Run Migrations
+
+A migration is a TypeScript or JavaScript file that defines database changes made by a module. Migrations ensure that your module is re-usable and removes friction when working in a team, making it easy to reflect changes across team members' databases.
+
+Learn more about migrations in [this chapter](https://docs.medusajs.com/learn/fundamentals/modules#5-generate-migrations/index.html.md).
+
+[Medusa's CLI tool](https://docs.medusajs.com/resources/medusa-cli/index.html.md) allows you to generate migration files for your module, then run those migrations to reflect the changes in the database. So, run the following commands in your Medusa application's directory:
+
+```bash
+npx medusa db:generate brand
+npx medusa db:migrate
+```
+
+The `db:generate` command accepts as an argument the name of the module to generate the migrations for, and the `db:migrate` command runs all migrations that haven't been run yet in the Medusa application.
+
+***
+
+## Next Step: Create Brand Workflow
+
+The Brand Module now creates a `brand` table in the database and provides a class to manage its records.
+
+In the next chapter, you'll implement the functionality to create a brand in a workflow. You'll then use that workflow in a later chapter to expose an endpoint that allows admin users to create a brand.
+
+
+# Guide: Create Brand API Route
+
+In the previous two chapters, you created a [Brand Module](https://docs.medusajs.com/learn/customization/custom-features/module/index.html.md) that added the concepts of brands to your application, then created a [workflow to create a brand](https://docs.medusajs.com/learn/customization/custom-features/workflow/index.html.md). In this chapter, you'll expose an API route that allows admin users to create a brand using the workflow from the previous chapter.
+
+An API Route is an endpoint that acts as an entry point for other clients to interact with your Medusa customizations, such as the admin dashboard, storefronts, or third-party systems.
+
+The Medusa core application provides a set of [admin](https://docs.medusajs.com/api/admin) and [store](https://docs.medusajs.com/api/store) API routes out-of-the-box. You can also create custom API routes to expose your custom functionalities.
+
+### Prerequisites
+
+- [createBrandWorkflow](https://docs.medusajs.com/learn/customization/custom-features/workflow/index.html.md)
+
+## 1. Create the API Route
+
+You create an API route in a `route.{ts,js}` file under a sub-directory of the `src/api` directory. The file exports API Route handler functions for at least one HTTP method (`GET`, `POST`, `DELETE`, etc…).
+
+Learn more about API routes [in this guide](https://docs.medusajs.com/learn/fundamentals/api-routes/index.html.md).
+
+The route's path is the path of `route.{ts,js}` relative to `src/api`. So, to create the API route at `/admin/brands`, create the file `src/api/admin/brands/route.ts` with the following content:
+
+
+
+```ts title="src/api/admin/brands/route.ts"
+import {
+ MedusaRequest,
+ MedusaResponse,
+} from "@medusajs/framework/http"
+import {
+ createBrandWorkflow,
+} from "../../../workflows/create-brand"
+
+type PostAdminCreateBrandType = {
+ name: string
+}
+
+export const POST = async (
+ req: MedusaRequest,
+ res: MedusaResponse
+) => {
+ const { result } = await createBrandWorkflow(req.scope)
+ .run({
+ input: req.validatedBody,
+ })
+
+ res.json({ brand: result })
+}
+```
+
+You export a route handler function with its name (`POST`) being the HTTP method of the API route you're exposing.
+
+The function receives two parameters: a `MedusaRequest` object to access request details, and `MedusaResponse` object to return or manipulate the response. The `MedusaRequest` object's `scope` property is the [Medusa container](https://docs.medusajs.com/learn/fundamentals/medusa-container/index.html.md) that holds Framework tools and custom and core modules' services.
+
+`MedusaRequest` accepts the request body's type as a type argument.
+
+In the API route's handler, you execute the `createBrandWorkflow` by invoking it and passing the Medusa container `req.scope` as a parameter, then invoking its `run` method. You pass the workflow's input in the `input` property of the `run` method's parameter. You pass the request body's parameters using the `validatedBody` property of `MedusaRequest`.
+
+You return a JSON response with the created brand using the `res.json` method.
+
+***
+
+## 2. Create Validation Schema
+
+The API route you created accepts the brand's name in the request body. So, you'll create a schema used to validate incoming request body parameters.
+
+Medusa uses [Zod](https://zod.dev/) to create validation schemas. These schemas are then used to validate incoming request bodies or query parameters.
+
+Learn more about API route validation in [this chapter](https://docs.medusajs.com/learn/fundamentals/api-routes/validation/index.html.md).
+
+You create a validation schema in a TypeScript or JavaScript file under a sub-directory of the `src/api` directory. So, create the file `src/api/admin/brands/validators.ts` with the following content:
+
+
+
+```ts title="src/api/admin/brands/validators.ts"
+import { z } from "zod"
+
+export const PostAdminCreateBrand = z.object({
+ name: z.string(),
+})
+```
+
+You export a validation schema that expects in the request body an object having a `name` property whose value is a string.
+
+You can then replace `PostAdminCreateBrandType` in `src/api/admin/brands/route.ts` with the following:
+
+```ts title="src/api/admin/brands/route.ts"
+// ...
+import { z } from "zod"
+import { PostAdminCreateBrand } from "./validators"
+
+type PostAdminCreateBrandType = z.infer
+
+// ...
+```
+
+***
+
+## 3. Add Validation Middleware
+
+A middleware is a function executed before the route handler when a request is sent to an API Route. It's useful to guard API routes, parse custom request body types, and apply validation on an API route.
+
+Learn more about middlewares in [this chapter](https://docs.medusajs.com/learn/fundamentals/api-routes/middlewares/index.html.md).
+
+Medusa provides a `validateAndTransformBody` middleware that accepts a Zod validation schema and returns a response error if a request is sent with body parameters that don't satisfy the validation schema.
+
+Middlewares are defined in the special file `src/api/middlewares.ts`. So, to add the validation middleware on the API route you created in the previous step, create the file `src/api/middlewares.ts` with the following content:
+
+
+
+```ts title="src/api/middlewares.ts"
+import {
+ defineMiddlewares,
+ validateAndTransformBody,
+} from "@medusajs/framework/http"
+import { PostAdminCreateBrand } from "./admin/brands/validators"
+
+export default defineMiddlewares({
+ routes: [
+ {
+ matcher: "/admin/brands",
+ method: "POST",
+ middlewares: [
+ validateAndTransformBody(PostAdminCreateBrand),
+ ],
+ },
+ ],
+})
+```
+
+You define the middlewares using the `defineMiddlewares` function and export its returned value. The function accepts an object having a `routes` property, which is an array of middleware objects.
+
+In the middleware object, you define three properties:
+
+- `matcher`: a string or regular expression indicating the API route path to apply the middleware on. You pass the create brand's route `/admin/brand`.
+- `method`: The HTTP method to restrict the middleware to, which is `POST`.
+- `middlewares`: An array of middlewares to apply on the route. You pass the `validateAndTransformBody` middleware, passing it the Zod schema you created earlier.
+
+The Medusa application will now validate the body parameters of `POST` requests sent to `/admin/brands` to ensure they match the Zod validation schema. If not, an error is returned in the response specifying the issues to fix in the request body.
+
+***
+
+## Test API Route
+
+To test out the API route, start the Medusa application with the following command:
+
+```bash npm2yarn
+npm run dev
+```
+
+Since the `/admin/brands` API route has a `/admin` prefix, it's only accessible by authenticated admin users.
+
+So, to retrieve an authenticated token of your admin user, send a `POST` request to the `/auth/user/emailpass` API Route:
+
+```bash
+curl -X POST 'http://localhost:9000/auth/user/emailpass' \
+-H 'Content-Type: application/json' \
+--data-raw '{
+ "email": "admin@medusa-test.com",
+ "password": "supersecret"
+}'
+```
+
+Make sure to replace the email and password with your admin user's credentials.
+
+Don't have an admin user? Refer to [this guide](https://docs.medusajs.com/learn/installation#create-medusa-admin-user/index.html.md).
+
+Then, send a `POST` request to `/admin/brands`, passing the token received from the previous request in the `Authorization` header:
+
+```bash
+curl -X POST 'http://localhost:9000/admin/brands' \
+-H 'Content-Type: application/json' \
+-H 'Authorization: Bearer {token}' \
+--data '{
+ "name": "Acme"
+}'
+```
+
+This returns the created brand in the response:
+
+```json title="Example Response"
+{
+ "brand": {
+ "id": "01J7AX9ES4X113HKY6C681KDZJ",
+ "name": "Acme",
+ "created_at": "2024-09-09T08:09:34.244Z",
+ "updated_at": "2024-09-09T08:09:34.244Z"
+ }
+}
+```
+
+***
+
+## Summary
+
+By following the previous example chapters, you implemented a custom feature that allows admin users to create a brand. You did that by:
+
+1. Creating a module that defines and manages a `brand` table in the database.
+2. Creating a workflow that uses the module's service to create a brand record, and implements the compensation logic to delete that brand in case an error occurs.
+3. Creating an API route that allows admin users to create a brand.
+
+***
+
+## Next Steps: Associate Brand with Product
+
+Now that you have brands in your Medusa application, you want to associate a brand with a product, which is defined in the [Product Module](https://docs.medusajs.com/resources/commerce-modules/product/index.html.md).
+
+In the next chapters, you'll learn how to build associations between data models defined in different modules.
+
+
# Create Brands UI Route in Admin
In this chapter, you'll add a UI route to the admin dashboard that shows all [brands](https://docs.medusajs.com/learn/customization/custom-features/module/index.html.md) in a new page. You'll retrieve the brands from the server and display them in a table with pagination.
@@ -5111,6 +5678,214 @@ Your customizations often span across systems, where you need to retrieve data o
In the next chapters, you'll learn about the concepts that facilitate integrating third-party systems in your application. You'll integrate a dummy third-party system and sync the brands between it and the Medusa application.
+# Guide: Define Module Link Between Brand and Product
+
+In this chapter, you'll learn how to define a module link between a brand defined in the [custom Brand Module](https://docs.medusajs.com/learn/customization/custom-features/module/index.html.md), and a product defined in the [Product Module](https://docs.medusajs.com/resources/commerce-modules/product/index.html.md) that's available in your Medusa application out-of-the-box.
+
+Modules are [isolated](https://docs.medusajs.com/learn/fundamentals/modules/isolation/index.html.md) from other resources, ensuring that they're integrated into the Medusa application without side effects. However, you may need to associate data models of different modules, or you're trying to extend data models from Commerce Modules with custom properties. To do that, you define module links.
+
+A module link forms an association between two data models of different modules while maintaining module isolation. You can then manage and query linked records of the data models using Medusa's Modules SDK.
+
+In this chapter, you'll define a module link between the `Brand` data model of the Brand Module, and the `Product` data model of the Product Module. In later chapters, you'll manage and retrieve linked product and brand records.
+
+Learn more about module links in [this chapters](https://docs.medusajs.com/learn/fundamentals/module-links/index.html.md).
+
+### Prerequisites
+
+- [Brand Module having a Brand data model](https://docs.medusajs.com/learn/customization/custom-features/module/index.html.md)
+
+## 1. Define Link
+
+Links are defined in a TypeScript or JavaScript file under the `src/links` directory. The file defines and exports the link using `defineLink` from the Modules SDK.
+
+So, to define a link between the `Product` and `Brand` models, create the file `src/links/product-brand.ts` with the following content:
+
+
+
+```ts title="src/links/product-brand.ts" highlights={highlights}
+import BrandModule from "../modules/brand"
+import ProductModule from "@medusajs/medusa/product"
+import { defineLink } from "@medusajs/framework/utils"
+
+export default defineLink(
+ {
+ linkable: ProductModule.linkable.product,
+ isList: true,
+ },
+ BrandModule.linkable.brand
+)
+```
+
+You import each module's definition object from the `index.ts` file of the module's directory. Each module object has a special `linkable` property that holds the data models' link configurations.
+
+The `defineLink` function accepts two parameters of the same type, which is either:
+
+- The data model's link configuration, which you access from the Module's `linkable` property;
+- Or an object that has two properties:
+ - `linkable`: the data model's link configuration, which you access from the Module's `linkable` property.
+ - `isList`: A boolean indicating whether many records of the data model can be linked to the other model.
+
+So, in the above code snippet, you define a link between the `Product` and `Brand` data models. Since a brand can be associated with multiple products, you enable `isList` in the `Product` model's object.
+
+***
+
+## 2. Sync the Link to the Database
+
+A module link is represented in the database as a table that stores the IDs of linked records. So, after defining the link, run the following command to create the module link's table in the database:
+
+```bash
+npx medusa db:migrate
+```
+
+This command reflects migrations on the database and syncs module links, which creates a table for the `product-brand` link.
+
+You can also run the `npx medusa db:sync-links` to just sync module links without running migrations.
+
+***
+
+## Next Steps: Extend Create Product Flow
+
+In the next chapter, you'll extend Medusa's workflow and API route that create a product to allow associating a brand with a product. You'll also learn how to link brand and product records.
+
+
+# Guide: Create Brand Workflow
+
+This chapter builds on the work from the [previous chapter](https://docs.medusajs.com/learn/customization/custom-features/module/index.html.md) where you created a Brand Module.
+
+After adding custom modules to your application, you build commerce features around them using workflows. A workflow is a series of queries and actions, called steps, that complete a task spanning across modules. You construct a workflow similar to a regular function, but it's a special function that allows you to define roll-back logic, retry configurations, and more advanced features.
+
+The workflow you'll create in this chapter will use the Brand Module's service to implement the feature of creating a brand. In the [next chapter](https://docs.medusajs.com/learn/customization/custom-features/api-route/index.html.md), you'll expose an API route that allows admin users to create a brand, and you'll use this workflow in the route's implementation.
+
+Learn more about workflows in [this chapter](https://docs.medusajs.com/learn/fundamentals/workflows/index.html.md).
+
+### Prerequisites
+
+- [Brand Module](https://docs.medusajs.com/learn/customization/custom-features/module/index.html.md)
+
+***
+
+## 1. Create createBrandStep
+
+A workflow consists of a series of steps, each step created in a TypeScript or JavaScript file under the `src/workflows` directory. A step is defined using `createStep` from the Workflows SDK
+
+The workflow you're creating in this guide has one step to create the brand. So, create the file `src/workflows/create-brand.ts` with the following content:
+
+
+
+```ts title="src/workflows/create-brand.ts"
+import {
+ createStep,
+ StepResponse,
+} from "@medusajs/framework/workflows-sdk"
+import { BRAND_MODULE } from "../modules/brand"
+import BrandModuleService from "../modules/brand/service"
+
+export type CreateBrandStepInput = {
+ name: string
+}
+
+export const createBrandStep = createStep(
+ "create-brand-step",
+ async (input: CreateBrandStepInput, { container }) => {
+ const brandModuleService: BrandModuleService = container.resolve(
+ BRAND_MODULE
+ )
+
+ const brand = await brandModuleService.createBrands(input)
+
+ return new StepResponse(brand, brand.id)
+ }
+)
+```
+
+You create a `createBrandStep` using the `createStep` function. It accepts the step's unique name as a first parameter, and the step's function as a second parameter.
+
+The step function receives two parameters: input passed to the step when it's invoked, and an object of general context and configurations. This object has a `container` property, which is the Medusa container.
+
+The [Medusa container](https://docs.medusajs.com/learn/fundamentals/medusa-container/index.html.md) is a registry of Framework and commerce tools accessible in your customizations, such as a workflow's step. The Medusa application registers the services of core and custom modules in the container, allowing you to resolve and use them.
+
+So, In the step function, you use the Medusa container to resolve the Brand Module's service and use its generated `createBrands` method, which accepts an object of brands to create.
+
+Learn more about the generated `create` method's usage in [this reference](https://docs.medusajs.com/resources/service-factory-reference/methods/create/index.html.md).
+
+A step must return an instance of `StepResponse`. Its first parameter is the data returned by the step, and the second is the data passed to the compensation function, which you'll learn about next.
+
+### Add Compensation Function to Step
+
+You define for each step a compensation function that's executed when an error occurs in the workflow. The compensation function defines the logic to roll-back the changes made by the step. This ensures your data remains consistent if an error occurs, which is especially useful when you integrate third-party services.
+
+Learn more about the compensation function in [this chapter](https://docs.medusajs.com/learn/fundamentals/workflows/compensation-function/index.html.md).
+
+To add a compensation function to the `createBrandStep`, pass it as a third parameter to `createStep`:
+
+```ts title="src/workflows/create-brand.ts"
+export const createBrandStep = createStep(
+ // ...
+ async (id: string, { container }) => {
+ const brandModuleService: BrandModuleService = container.resolve(
+ BRAND_MODULE
+ )
+
+ await brandModuleService.deleteBrands(id)
+ }
+)
+```
+
+The compensation function's first parameter is the brand's ID which you passed as a second parameter to the step function's returned `StepResponse`. It also accepts a context object with a `container` property as a second parameter, similar to the step function.
+
+In the compensation function, you resolve the Brand Module's service from the Medusa container, then use its generated `deleteBrands` method to delete the brand created by the step. This method accepts the ID of the brand to delete.
+
+Learn more about the generated `delete` method's usage in [this reference](https://docs.medusajs.com/resources/service-factory-reference/methods/delete/index.html.md).
+
+So, if an error occurs during the workflow's execution, the brand that was created by the step is deleted to maintain data consistency.
+
+***
+
+## 2. Create createBrandWorkflow
+
+You can now create the workflow that runs the `createBrandStep`. A workflow is created in a TypeScript or JavaScript file under the `src/workflows` directory. In the file, you use `createWorkflow` from the Workflows SDK to create the workflow.
+
+Add the following content in the same `src/workflows/create-brand.ts` file:
+
+```ts title="src/workflows/create-brand.ts"
+// other imports...
+import {
+ // ...
+ createWorkflow,
+ WorkflowResponse,
+} from "@medusajs/framework/workflows-sdk"
+
+// ...
+
+type CreateBrandWorkflowInput = {
+ name: string
+}
+
+export const createBrandWorkflow = createWorkflow(
+ "create-brand",
+ (input: CreateBrandWorkflowInput) => {
+ const brand = createBrandStep(input)
+
+ return new WorkflowResponse(brand)
+ }
+)
+```
+
+You create the `createBrandWorkflow` using the `createWorkflow` function. This function accepts two parameters: the workflow's unique name, and the workflow's constructor function holding the workflow's implementation.
+
+The constructor function accepts the workflow's input as a parameter. In the function, you invoke the `createBrandStep` you created in the previous step to create a brand.
+
+A workflow must return an instance of `WorkflowResponse`. It accepts as a parameter the data to return to the workflow's executor.
+
+***
+
+## Next Steps: Expose Create Brand API Route
+
+You now have a `createBrandWorkflow` that you can execute to create a brand.
+
+In the next chapter, you'll add an API route that allows admin users to create a brand. You'll learn how to create the API route, and execute in it the workflow you implemented in this chapter.
+
+
# Guide: Add Product's Brand Widget in Admin
In this chapter, you'll customize the product details page of the Medusa Admin dashboard to show the product's [brand](https://docs.medusajs.com/learn/customization/custom-features/module/index.html.md). You'll create a widget that is injected into a pre-defined zone in the page, and in the widget you'll retrieve the product's brand from the server and display it.
@@ -5265,432 +6040,6 @@ The [Admin Components guides](https://docs.medusajs.com/resources/admin-componen
In the next chapter, you'll add a UI route that displays the list of brands in your application and allows admin users.
-# Guide: Define Module Link Between Brand and Product
-
-In this chapter, you'll learn how to define a module link between a brand defined in the [custom Brand Module](https://docs.medusajs.com/learn/customization/custom-features/module/index.html.md), and a product defined in the [Product Module](https://docs.medusajs.com/resources/commerce-modules/product/index.html.md) that's available in your Medusa application out-of-the-box.
-
-Modules are [isolated](https://docs.medusajs.com/learn/fundamentals/modules/isolation/index.html.md) from other resources, ensuring that they're integrated into the Medusa application without side effects. However, you may need to associate data models of different modules, or you're trying to extend data models from Commerce Modules with custom properties. To do that, you define module links.
-
-A module link forms an association between two data models of different modules while maintaining module isolation. You can then manage and query linked records of the data models using Medusa's Modules SDK.
-
-In this chapter, you'll define a module link between the `Brand` data model of the Brand Module, and the `Product` data model of the Product Module. In later chapters, you'll manage and retrieve linked product and brand records.
-
-Learn more about module links in [this chapters](https://docs.medusajs.com/learn/fundamentals/module-links/index.html.md).
-
-### Prerequisites
-
-- [Brand Module having a Brand data model](https://docs.medusajs.com/learn/customization/custom-features/module/index.html.md)
-
-## 1. Define Link
-
-Links are defined in a TypeScript or JavaScript file under the `src/links` directory. The file defines and exports the link using `defineLink` from the Modules SDK.
-
-So, to define a link between the `Product` and `Brand` models, create the file `src/links/product-brand.ts` with the following content:
-
-
-
-```ts title="src/links/product-brand.ts" highlights={highlights}
-import BrandModule from "../modules/brand"
-import ProductModule from "@medusajs/medusa/product"
-import { defineLink } from "@medusajs/framework/utils"
-
-export default defineLink(
- {
- linkable: ProductModule.linkable.product,
- isList: true,
- },
- BrandModule.linkable.brand
-)
-```
-
-You import each module's definition object from the `index.ts` file of the module's directory. Each module object has a special `linkable` property that holds the data models' link configurations.
-
-The `defineLink` function accepts two parameters of the same type, which is either:
-
-- The data model's link configuration, which you access from the Module's `linkable` property;
-- Or an object that has two properties:
- - `linkable`: the data model's link configuration, which you access from the Module's `linkable` property.
- - `isList`: A boolean indicating whether many records of the data model can be linked to the other model.
-
-So, in the above code snippet, you define a link between the `Product` and `Brand` data models. Since a brand can be associated with multiple products, you enable `isList` in the `Product` model's object.
-
-***
-
-## 2. Sync the Link to the Database
-
-A module link is represented in the database as a table that stores the IDs of linked records. So, after defining the link, run the following command to create the module link's table in the database:
-
-```bash
-npx medusa db:migrate
-```
-
-This command reflects migrations on the database and syncs module links, which creates a table for the `product-brand` link.
-
-You can also run the `npx medusa db:sync-links` to just sync module links without running migrations.
-
-***
-
-## Next Steps: Extend Create Product Flow
-
-In the next chapter, you'll extend Medusa's workflow and API route that create a product to allow associating a brand with a product. You'll also learn how to link brand and product records.
-
-
-# Guide: Query Product's Brands
-
-In the previous chapters, you [defined a link](https://docs.medusajs.com/learn/customization/extend-features/define-link/index.html.md) between the [custom Brand Module](https://docs.medusajs.com/learn/customization/custom-features/module/index.html.md) and Medusa's [Product Module](https://docs.medusajs.com/resources/commerce-modules/product/index.html.md), then [extended the create-product flow](https://docs.medusajs.com/learn/customization/extend-features/extend-create-product/index.html.md) to link a product to a brand.
-
-In this chapter, you'll learn how to retrieve a product's brand (and vice-versa) in two ways: Using Medusa's existing API route, or in customizations, such as a custom API route.
-
-### Prerequisites
-
-- [Brand Module](https://docs.medusajs.com/learn/customization/custom-features/module/index.html.md)
-- [Defined link between the Brand and Product data models.](https://docs.medusajs.com/learn/customization/extend-features/define-link/index.html.md)
-
-***
-
-## Approach 1: Retrieve Brands in Existing API Routes
-
-Medusa's existing API routes accept a `fields` query parameter that allows you to specify the fields and relations of a model to retrieve. So, when you send a request to the [List Products](https://docs.medusajs.com/api/admin#products_getproducts), [Get Product](https://docs.medusajs.com/api/admin#products_getproductsid), or any product-related store or admin routes that accept a `fields` query parameter, you can specify in this parameter to return the product's brands.
-
-Learn more about using the `fields` query parameter to retrieve custom linked data models in the [Retrieve Custom Linked Data Models from Medusa's API Routes](https://docs.medusajs.com/learn/fundamentals/api-routes/retrieve-custom-links/index.html.md) chapter.
-
-For example, send the following request to retrieve the list of products with their brands:
-
-```bash
-curl 'http://localhost:9000/admin/products?fields=+brand.*' \
---header 'Authorization: Bearer {token}'
-```
-
-Make sure to replace `{token}` with your admin user's authentication token. Learn how to retrieve it in the [API reference](https://docs.medusajs.com/api/store#authentication).
-
-Any product that is linked to a brand will have a `brand` property in its object:
-
-```json title="Example Product Object"
-{
- "id": "prod_123",
- // ...
- "brand": {
- "id": "01JEB44M61BRM3ARM2RRMK7GJF",
- "name": "Acme",
- "created_at": "2024-12-05T09:59:08.737Z",
- "updated_at": "2024-12-05T09:59:08.737Z",
- "deleted_at": null
- }
-}
-```
-
-By using the `fields` query parameter, you don't have to re-create existing API routes to get custom data models that you linked to core data models.
-
-### Limitations: Filtering by Brands in Existing API Routes
-
-While you can retrieve linked records using the `fields` query parameter of an existing API route, you can't filter by linked records.
-
-Instead, you'll have to create a custom API route that uses Query to retrieve linked records with filters, as explained in the [Query documentation](https://docs.medusajs.com/learn/fundamentals/module-links/query#apply-filters-and-pagination-on-linked-records/index.html.md).
-
-***
-
-## Approach 2: Use Query to Retrieve Linked Records
-
-You can also retrieve linked records using Query. Query allows you to retrieve data across modules with filters, pagination, and more. You can resolve Query from the Medusa container and use it in your API route or workflow.
-
-Learn more about Query in [this chapter](https://docs.medusajs.com/learn/fundamentals/module-links/query/index.html.md).
-
-For example, you can create an API route that retrieves brands and their products. If you followed the [Create Brands API route chapter](https://docs.medusajs.com/learn/customization/custom-features/api-route/index.html.md), you'll have the file `src/api/admin/brands/route.ts` with a `POST` API route. Add a new `GET` function to the same file:
-
-```ts title="src/api/admin/brands/route.ts" highlights={highlights}
-// other imports...
-import {
- MedusaRequest,
- MedusaResponse,
-} from "@medusajs/framework/http"
-
-export const GET = async (
- req: MedusaRequest,
- res: MedusaResponse
-) => {
- const query = req.scope.resolve("query")
-
- const { data: brands } = await query.graph({
- entity: "brand",
- fields: ["*", "products.*"],
- })
-
- res.json({ brands })
-}
-```
-
-This adds a `GET` API route at `/admin/brands`. In the API route, you resolve Query from the Medusa container. Query has a `graph` method that runs a query to retrieve data. It accepts an object having the following properties:
-
-- `entity`: The data model's name as specified in the first parameter of `model.define`.
-- `fields`: An array of properties and relations to retrieve. You can pass:
- - A property's name, such as `id`, or `*` for all properties.
- - A relation or linked model's name, such as `products` (use the plural name since brands are linked to list of products). You suffix the name with `.*` to retrieve all its properties.
-
-`graph` returns an object having a `data` property, which is the retrieved brands. You return the brands in the response.
-
-### Test it Out
-
-To test the API route out, send a `GET` request to `/admin/brands`:
-
-```bash
-curl 'http://localhost:9000/admin/brands' \
--H 'Authorization: Bearer {token}'
-```
-
-Make sure to replace `{token}` with your admin user's authentication token. Learn how to retrieve it in the [API reference](https://docs.medusajs.com/api/store#authentication).
-
-This returns the brands in your store with their linked products. For example:
-
-```json title="Example Response"
-{
- "brands": [
- {
- "id": "123",
- // ...
- "products": [
- {
- "id": "prod_123",
- // ...
- }
- ]
- }
- ]
-}
-```
-
-### Limitations: Filtering by Brand in Query
-
-While you can use Query to retrieve linked records, you can't filter by linked records.
-
-For an alternative approach, refer to the [Query documentation](https://docs.medusajs.com/learn/fundamentals/module-links/query#apply-filters-and-pagination-on-linked-records/index.html.md).
-
-***
-
-## Summary
-
-By following the examples of the previous chapters, you:
-
-- Defined a link between the Brand and Product modules's data models, allowing you to associate a product with a brand.
-- Extended the create-product workflow and route to allow setting the product's brand while creating the product.
-- Queried a product's brand, and vice versa.
-
-***
-
-## Next Steps: Customize Medusa Admin
-
-Clients, such as the Medusa Admin dashboard, can now use brand-related features, such as creating a brand or setting the brand of a product.
-
-In the next chapters, you'll learn how to customize the Medusa Admin to show a product's brand on its details page, and to show a new page with the list of brands in your store.
-
-
-# Guide: Create Brand API Route
-
-In the previous two chapters, you created a [Brand Module](https://docs.medusajs.com/learn/customization/custom-features/module/index.html.md) that added the concepts of brands to your application, then created a [workflow to create a brand](https://docs.medusajs.com/learn/customization/custom-features/workflow/index.html.md). In this chapter, you'll expose an API route that allows admin users to create a brand using the workflow from the previous chapter.
-
-An API Route is an endpoint that acts as an entry point for other clients to interact with your Medusa customizations, such as the admin dashboard, storefronts, or third-party systems.
-
-The Medusa core application provides a set of [admin](https://docs.medusajs.com/api/admin) and [store](https://docs.medusajs.com/api/store) API routes out-of-the-box. You can also create custom API routes to expose your custom functionalities.
-
-### Prerequisites
-
-- [createBrandWorkflow](https://docs.medusajs.com/learn/customization/custom-features/workflow/index.html.md)
-
-## 1. Create the API Route
-
-You create an API route in a `route.{ts,js}` file under a sub-directory of the `src/api` directory. The file exports API Route handler functions for at least one HTTP method (`GET`, `POST`, `DELETE`, etc…).
-
-Learn more about API routes [in this guide](https://docs.medusajs.com/learn/fundamentals/api-routes/index.html.md).
-
-The route's path is the path of `route.{ts,js}` relative to `src/api`. So, to create the API route at `/admin/brands`, create the file `src/api/admin/brands/route.ts` with the following content:
-
-
-
-```ts title="src/api/admin/brands/route.ts"
-import {
- MedusaRequest,
- MedusaResponse,
-} from "@medusajs/framework/http"
-import {
- createBrandWorkflow,
-} from "../../../workflows/create-brand"
-
-type PostAdminCreateBrandType = {
- name: string
-}
-
-export const POST = async (
- req: MedusaRequest,
- res: MedusaResponse
-) => {
- const { result } = await createBrandWorkflow(req.scope)
- .run({
- input: req.validatedBody,
- })
-
- res.json({ brand: result })
-}
-```
-
-You export a route handler function with its name (`POST`) being the HTTP method of the API route you're exposing.
-
-The function receives two parameters: a `MedusaRequest` object to access request details, and `MedusaResponse` object to return or manipulate the response. The `MedusaRequest` object's `scope` property is the [Medusa container](https://docs.medusajs.com/learn/fundamentals/medusa-container/index.html.md) that holds Framework tools and custom and core modules' services.
-
-`MedusaRequest` accepts the request body's type as a type argument.
-
-In the API route's handler, you execute the `createBrandWorkflow` by invoking it and passing the Medusa container `req.scope` as a parameter, then invoking its `run` method. You pass the workflow's input in the `input` property of the `run` method's parameter. You pass the request body's parameters using the `validatedBody` property of `MedusaRequest`.
-
-You return a JSON response with the created brand using the `res.json` method.
-
-***
-
-## 2. Create Validation Schema
-
-The API route you created accepts the brand's name in the request body. So, you'll create a schema used to validate incoming request body parameters.
-
-Medusa uses [Zod](https://zod.dev/) to create validation schemas. These schemas are then used to validate incoming request bodies or query parameters.
-
-Learn more about API route validation in [this chapter](https://docs.medusajs.com/learn/fundamentals/api-routes/validation/index.html.md).
-
-You create a validation schema in a TypeScript or JavaScript file under a sub-directory of the `src/api` directory. So, create the file `src/api/admin/brands/validators.ts` with the following content:
-
-
-
-```ts title="src/api/admin/brands/validators.ts"
-import { z } from "zod"
-
-export const PostAdminCreateBrand = z.object({
- name: z.string(),
-})
-```
-
-You export a validation schema that expects in the request body an object having a `name` property whose value is a string.
-
-You can then replace `PostAdminCreateBrandType` in `src/api/admin/brands/route.ts` with the following:
-
-```ts title="src/api/admin/brands/route.ts"
-// ...
-import { z } from "zod"
-import { PostAdminCreateBrand } from "./validators"
-
-type PostAdminCreateBrandType = z.infer
-
-// ...
-```
-
-***
-
-## 3. Add Validation Middleware
-
-A middleware is a function executed before the route handler when a request is sent to an API Route. It's useful to guard API routes, parse custom request body types, and apply validation on an API route.
-
-Learn more about middlewares in [this chapter](https://docs.medusajs.com/learn/fundamentals/api-routes/middlewares/index.html.md).
-
-Medusa provides a `validateAndTransformBody` middleware that accepts a Zod validation schema and returns a response error if a request is sent with body parameters that don't satisfy the validation schema.
-
-Middlewares are defined in the special file `src/api/middlewares.ts`. So, to add the validation middleware on the API route you created in the previous step, create the file `src/api/middlewares.ts` with the following content:
-
-
-
-```ts title="src/api/middlewares.ts"
-import {
- defineMiddlewares,
- validateAndTransformBody,
-} from "@medusajs/framework/http"
-import { PostAdminCreateBrand } from "./admin/brands/validators"
-
-export default defineMiddlewares({
- routes: [
- {
- matcher: "/admin/brands",
- method: "POST",
- middlewares: [
- validateAndTransformBody(PostAdminCreateBrand),
- ],
- },
- ],
-})
-```
-
-You define the middlewares using the `defineMiddlewares` function and export its returned value. The function accepts an object having a `routes` property, which is an array of middleware objects.
-
-In the middleware object, you define three properties:
-
-- `matcher`: a string or regular expression indicating the API route path to apply the middleware on. You pass the create brand's route `/admin/brand`.
-- `method`: The HTTP method to restrict the middleware to, which is `POST`.
-- `middlewares`: An array of middlewares to apply on the route. You pass the `validateAndTransformBody` middleware, passing it the Zod schema you created earlier.
-
-The Medusa application will now validate the body parameters of `POST` requests sent to `/admin/brands` to ensure they match the Zod validation schema. If not, an error is returned in the response specifying the issues to fix in the request body.
-
-***
-
-## Test API Route
-
-To test out the API route, start the Medusa application with the following command:
-
-```bash npm2yarn
-npm run dev
-```
-
-Since the `/admin/brands` API route has a `/admin` prefix, it's only accessible by authenticated admin users.
-
-So, to retrieve an authenticated token of your admin user, send a `POST` request to the `/auth/user/emailpass` API Route:
-
-```bash
-curl -X POST 'http://localhost:9000/auth/user/emailpass' \
--H 'Content-Type: application/json' \
---data-raw '{
- "email": "admin@medusa-test.com",
- "password": "supersecret"
-}'
-```
-
-Make sure to replace the email and password with your admin user's credentials.
-
-Don't have an admin user? Refer to [this guide](https://docs.medusajs.com/learn/installation#create-medusa-admin-user/index.html.md).
-
-Then, send a `POST` request to `/admin/brands`, passing the token received from the previous request in the `Authorization` header:
-
-```bash
-curl -X POST 'http://localhost:9000/admin/brands' \
--H 'Content-Type: application/json' \
--H 'Authorization: Bearer {token}' \
---data '{
- "name": "Acme"
-}'
-```
-
-This returns the created brand in the response:
-
-```json title="Example Response"
-{
- "brand": {
- "id": "01J7AX9ES4X113HKY6C681KDZJ",
- "name": "Acme",
- "created_at": "2024-09-09T08:09:34.244Z",
- "updated_at": "2024-09-09T08:09:34.244Z"
- }
-}
-```
-
-***
-
-## Summary
-
-By following the previous example chapters, you implemented a custom feature that allows admin users to create a brand. You did that by:
-
-1. Creating a module that defines and manages a `brand` table in the database.
-2. Creating a workflow that uses the module's service to create a brand record, and implements the compensation logic to delete that brand in case an error occurs.
-3. Creating an API route that allows admin users to create a brand.
-
-***
-
-## Next Steps: Associate Brand with Product
-
-Now that you have brands in your Medusa application, you want to associate a brand with a product, which is defined in the [Product Module](https://docs.medusajs.com/resources/commerce-modules/product/index.html.md).
-
-In the next chapters, you'll learn how to build associations between data models defined in different modules.
-
-
# Guide: Extend Create Product Flow
After linking the [custom Brand data model](https://docs.medusajs.com/learn/customization/custom-features/module/index.html.md) and Medusa's [Product Module](https://docs.medusajs.com/resources/commerce-modules/product/index.html.md) in the [previous chapter](https://docs.medusajs.com/learn/customization/extend-features/define-link/index.html.md), you'll extend the create product workflow and API route to allow associating a brand with a product.
@@ -5903,300 +6252,197 @@ In the Medusa application's logs, you'll find the message `Linked brand to produ
Now that you've extending the create-product flow to link a brand to it, you want to retrieve the brand details of a product. You'll learn how to do so in the next chapter.
-# Guide: Implement Brand Module
+# Guide: Query Product's Brands
-In this chapter, you'll build a Brand Module that adds a `brand` table to the database and provides data-management features for it.
+In the previous chapters, you [defined a link](https://docs.medusajs.com/learn/customization/extend-features/define-link/index.html.md) between the [custom Brand Module](https://docs.medusajs.com/learn/customization/custom-features/module/index.html.md) and Medusa's [Product Module](https://docs.medusajs.com/resources/commerce-modules/product/index.html.md), then [extended the create-product flow](https://docs.medusajs.com/learn/customization/extend-features/extend-create-product/index.html.md) to link a product to a brand.
-A module is a reusable package of functionalities related to a single domain or integration. Medusa comes with multiple pre-built modules for core commerce needs, such as the [Cart Module](https://docs.medusajs.com/resources/commerce-modules/cart/index.html.md) that holds the data models and business logic for cart operations.
-
-In a module, you create data models and business logic to manage them. In the next chapters, you'll see how you use the module to build commerce features.
-
-
-
-Learn more about modules in [this chapter](https://docs.medusajs.com/learn/fundamentals/modules/index.html.md).
-
-## 1. Create Module Directory
-
-Modules are created in a sub-directory of `src/modules`. So, start by creating the directory `src/modules/brand` that will hold the Brand Module's files.
-
-
-
-***
-
-## 2. Create Data Model
-
-A data model represents a table in the database. You create data models using Medusa's Data Model Language (DML). It simplifies defining a table's columns, relations, and indexes with straightforward methods and configurations.
-
-Learn more about data models in [this chapter](https://docs.medusajs.com/learn/fundamentals/modules#1-create-data-model/index.html.md).
-
-You create a data model in a TypeScript or JavaScript file under the `models` directory of a module. So, to create a data model that represents a new `brand` table in the database, create the file `src/modules/brand/models/brand.ts` with the following content:
-
-
-
-```ts title="src/modules/brand/models/brand.ts"
-import { model } from "@medusajs/framework/utils"
-
-export const Brand = model.define("brand", {
- id: model.id().primaryKey(),
- name: model.text(),
-})
-```
-
-You create a `Brand` data model which has an `id` primary key property, and a `name` text property.
-
-You define the data model using the `define` method of the DML. It accepts two parameters:
-
-1. The first one is the name of the data model's table in the database. Use snake-case names.
-2. The second is an object, which is the data model's schema.
-
-Learn about other property types in [this chapter](https://docs.medusajs.com/learn/fundamentals/data-models/properties/index.html.md).
-
-***
-
-## 3. Create Module Service
-
-You perform database operations on your data models in a service, which is a class exported by the module and acts like an interface to its functionalities.
-
-In this step, you'll create the Brand Module's service that provides methods to manage the `Brand` data model. In the next chapters, you'll use this service when exposing custom features that involve managing brands.
-
-Learn more about services in [this chapter](https://docs.medusajs.com/learn/fundamentals/modules#2-create-service/index.html.md).
-
-You define a service in a `service.ts` or `service.js` file at the root of your module's directory. So, create the file `src/modules/brand/service.ts` with the following content:
-
-
-
-```ts title="src/modules/brand/service.ts" highlights={serviceHighlights}
-import { MedusaService } from "@medusajs/framework/utils"
-import { Brand } from "./models/brand"
-
-class BrandModuleService extends MedusaService({
- Brand,
-}) {
-
-}
-
-export default BrandModuleService
-```
-
-The `BrandModuleService` extends a class returned by `MedusaService` from the Modules SDK. This function generates a class with data-management methods for your module's data models.
-
-The `MedusaService` function receives an object of the module's data models as a parameter, and generates methods to manage those data models. So, the `BrandModuleService` now has methods like `createBrands` and `retrieveBrand` to manage the `Brand` data model.
-
-You'll use these methods in the [next chapter](https://docs.medusajs.com/learn/customization/custom-features/workflow/index.html.md).
-
-Find a reference of all generated methods in [this guide](https://docs.medusajs.com/resources/service-factory-reference/index.html.md).
-
-***
-
-## 4. Export Module Definition
-
-A module must export a definition that tells Medusa the name of the module and its main service. This definition is exported in an `index.ts` file at the module's root directory.
-
-So, to export the Brand Module's definition, create the file `src/modules/brand/index.ts` with the following content:
-
-
-
-```ts title="src/modules/brand/index.ts"
-import { Module } from "@medusajs/framework/utils"
-import BrandModuleService from "./service"
-
-export const BRAND_MODULE = "brand"
-
-export default Module(BRAND_MODULE, {
- service: BrandModuleService,
-})
-```
-
-You use `Module` from the Modules SDK to create the module's definition. It accepts two parameters:
-
-1. The module's name (`brand`). You'll use this name when you use this module in other customizations.
-2. An object with a required property `service` indicating the module's main service.
-
-You export `BRAND_MODULE` to reference the module's name more reliably in other customizations.
-
-***
-
-## 5. Add Module to Medusa's Configurations
-
-To start using your module, you must add it to Medusa's configurations in `medusa-config.ts`.
-
-The object passed to `defineConfig` in `medusa-config.ts` accepts a `modules` property, whose value is an array of modules to add to the application. So, add the following in `medusa-config.ts`:
-
-```ts title="medusa-config.ts"
-module.exports = defineConfig({
- // ...
- modules: [
- {
- resolve: "./src/modules/brand",
- },
- ],
-})
-```
-
-The Brand Module is now added to your Medusa application. You'll start using it in the [next chapter](https://docs.medusajs.com/learn/customization/custom-features/workflow/index.html.md).
-
-***
-
-## 6. Generate and Run Migrations
-
-A migration is a TypeScript or JavaScript file that defines database changes made by a module. Migrations ensure that your module is re-usable and removes friction when working in a team, making it easy to reflect changes across team members' databases.
-
-Learn more about migrations in [this chapter](https://docs.medusajs.com/learn/fundamentals/modules#5-generate-migrations/index.html.md).
-
-[Medusa's CLI tool](https://docs.medusajs.com/resources/medusa-cli/index.html.md) allows you to generate migration files for your module, then run those migrations to reflect the changes in the database. So, run the following commands in your Medusa application's directory:
-
-```bash
-npx medusa db:generate brand
-npx medusa db:migrate
-```
-
-The `db:generate` command accepts as an argument the name of the module to generate the migrations for, and the `db:migrate` command runs all migrations that haven't been run yet in the Medusa application.
-
-***
-
-## Next Step: Create Brand Workflow
-
-The Brand Module now creates a `brand` table in the database and provides a class to manage its records.
-
-In the next chapter, you'll implement the functionality to create a brand in a workflow. You'll then use that workflow in a later chapter to expose an endpoint that allows admin users to create a brand.
-
-
-# Guide: Create Brand Workflow
-
-This chapter builds on the work from the [previous chapter](https://docs.medusajs.com/learn/customization/custom-features/module/index.html.md) where you created a Brand Module.
-
-After adding custom modules to your application, you build commerce features around them using workflows. A workflow is a series of queries and actions, called steps, that complete a task spanning across modules. You construct a workflow similar to a regular function, but it's a special function that allows you to define roll-back logic, retry configurations, and more advanced features.
-
-The workflow you'll create in this chapter will use the Brand Module's service to implement the feature of creating a brand. In the [next chapter](https://docs.medusajs.com/learn/customization/custom-features/api-route/index.html.md), you'll expose an API route that allows admin users to create a brand, and you'll use this workflow in the route's implementation.
-
-Learn more about workflows in [this chapter](https://docs.medusajs.com/learn/fundamentals/workflows/index.html.md).
+In this chapter, you'll learn how to retrieve a product's brand (and vice-versa) in two ways: Using Medusa's existing API route, or in customizations, such as a custom API route.
### Prerequisites
- [Brand Module](https://docs.medusajs.com/learn/customization/custom-features/module/index.html.md)
+- [Defined link between the Brand and Product data models.](https://docs.medusajs.com/learn/customization/extend-features/define-link/index.html.md)
***
-## 1. Create createBrandStep
+## Approach 1: Retrieve Brands in Existing API Routes
-A workflow consists of a series of steps, each step created in a TypeScript or JavaScript file under the `src/workflows` directory. A step is defined using `createStep` from the Workflows SDK
+Medusa's existing API routes accept a `fields` query parameter that allows you to specify the fields and relations of a model to retrieve. So, when you send a request to the [List Products](https://docs.medusajs.com/api/admin#products_getproducts), [Get Product](https://docs.medusajs.com/api/admin#products_getproductsid), or any product-related store or admin routes that accept a `fields` query parameter, you can specify in this parameter to return the product's brands.
-The workflow you're creating in this guide has one step to create the brand. So, create the file `src/workflows/create-brand.ts` with the following content:
+Learn more about using the `fields` query parameter to retrieve custom linked data models in the [Retrieve Custom Linked Data Models from Medusa's API Routes](https://docs.medusajs.com/learn/fundamentals/api-routes/retrieve-custom-links/index.html.md) chapter.
-
+For example, send the following request to retrieve the list of products with their brands:
-```ts title="src/workflows/create-brand.ts"
-import {
- createStep,
- StepResponse,
-} from "@medusajs/framework/workflows-sdk"
-import { BRAND_MODULE } from "../modules/brand"
-import BrandModuleService from "../modules/brand/service"
-
-export type CreateBrandStepInput = {
- name: string
-}
-
-export const createBrandStep = createStep(
- "create-brand-step",
- async (input: CreateBrandStepInput, { container }) => {
- const brandModuleService: BrandModuleService = container.resolve(
- BRAND_MODULE
- )
-
- const brand = await brandModuleService.createBrands(input)
-
- return new StepResponse(brand, brand.id)
- }
-)
+```bash
+curl 'http://localhost:9000/admin/products?fields=+brand.*' \
+--header 'Authorization: Bearer {token}'
```
-You create a `createBrandStep` using the `createStep` function. It accepts the step's unique name as a first parameter, and the step's function as a second parameter.
+Make sure to replace `{token}` with your admin user's authentication token. Learn how to retrieve it in the [API reference](https://docs.medusajs.com/api/store#authentication).
-The step function receives two parameters: input passed to the step when it's invoked, and an object of general context and configurations. This object has a `container` property, which is the Medusa container.
+Any product that is linked to a brand will have a `brand` property in its object:
-The [Medusa container](https://docs.medusajs.com/learn/fundamentals/medusa-container/index.html.md) is a registry of Framework and commerce tools accessible in your customizations, such as a workflow's step. The Medusa application registers the services of core and custom modules in the container, allowing you to resolve and use them.
-
-So, In the step function, you use the Medusa container to resolve the Brand Module's service and use its generated `createBrands` method, which accepts an object of brands to create.
-
-Learn more about the generated `create` method's usage in [this reference](https://docs.medusajs.com/resources/service-factory-reference/methods/create/index.html.md).
-
-A step must return an instance of `StepResponse`. Its first parameter is the data returned by the step, and the second is the data passed to the compensation function, which you'll learn about next.
-
-### Add Compensation Function to Step
-
-You define for each step a compensation function that's executed when an error occurs in the workflow. The compensation function defines the logic to roll-back the changes made by the step. This ensures your data remains consistent if an error occurs, which is especially useful when you integrate third-party services.
-
-Learn more about the compensation function in [this chapter](https://docs.medusajs.com/learn/fundamentals/workflows/compensation-function/index.html.md).
-
-To add a compensation function to the `createBrandStep`, pass it as a third parameter to `createStep`:
-
-```ts title="src/workflows/create-brand.ts"
-export const createBrandStep = createStep(
+```json title="Example Product Object"
+{
+ "id": "prod_123",
// ...
- async (id: string, { container }) => {
- const brandModuleService: BrandModuleService = container.resolve(
- BRAND_MODULE
- )
-
- await brandModuleService.deleteBrands(id)
+ "brand": {
+ "id": "01JEB44M61BRM3ARM2RRMK7GJF",
+ "name": "Acme",
+ "created_at": "2024-12-05T09:59:08.737Z",
+ "updated_at": "2024-12-05T09:59:08.737Z",
+ "deleted_at": null
}
-)
+}
```
-The compensation function's first parameter is the brand's ID which you passed as a second parameter to the step function's returned `StepResponse`. It also accepts a context object with a `container` property as a second parameter, similar to the step function.
+By using the `fields` query parameter, you don't have to re-create existing API routes to get custom data models that you linked to core data models.
-In the compensation function, you resolve the Brand Module's service from the Medusa container, then use its generated `deleteBrands` method to delete the brand created by the step. This method accepts the ID of the brand to delete.
+### Limitations: Filtering by Brands in Existing API Routes
-Learn more about the generated `delete` method's usage in [this reference](https://docs.medusajs.com/resources/service-factory-reference/methods/delete/index.html.md).
+While you can retrieve linked records using the `fields` query parameter of an existing API route, you can't filter by linked records.
-So, if an error occurs during the workflow's execution, the brand that was created by the step is deleted to maintain data consistency.
+Instead, you'll have to create a custom API route that uses Query to retrieve linked records with filters, as explained in the [Query documentation](https://docs.medusajs.com/learn/fundamentals/module-links/query#apply-filters-and-pagination-on-linked-records/index.html.md).
***
-## 2. Create createBrandWorkflow
+## Approach 2: Use Query to Retrieve Linked Records
-You can now create the workflow that runs the `createBrandStep`. A workflow is created in a TypeScript or JavaScript file under the `src/workflows` directory. In the file, you use `createWorkflow` from the Workflows SDK to create the workflow.
+You can also retrieve linked records using Query. Query allows you to retrieve data across modules with filters, pagination, and more. You can resolve Query from the Medusa container and use it in your API route or workflow.
-Add the following content in the same `src/workflows/create-brand.ts` file:
+Learn more about Query in [this chapter](https://docs.medusajs.com/learn/fundamentals/module-links/query/index.html.md).
-```ts title="src/workflows/create-brand.ts"
+For example, you can create an API route that retrieves brands and their products. If you followed the [Create Brands API route chapter](https://docs.medusajs.com/learn/customization/custom-features/api-route/index.html.md), you'll have the file `src/api/admin/brands/route.ts` with a `POST` API route. Add a new `GET` function to the same file:
+
+```ts title="src/api/admin/brands/route.ts" highlights={highlights}
// other imports...
import {
- // ...
- createWorkflow,
- WorkflowResponse,
-} from "@medusajs/framework/workflows-sdk"
+ MedusaRequest,
+ MedusaResponse,
+} from "@medusajs/framework/http"
-// ...
+export const GET = async (
+ req: MedusaRequest,
+ res: MedusaResponse
+) => {
+ const query = req.scope.resolve("query")
+
+ const { data: brands } = await query.graph({
+ entity: "brand",
+ fields: ["*", "products.*"],
+ })
-type CreateBrandWorkflowInput = {
- name: string
+ res.json({ brands })
}
-
-export const createBrandWorkflow = createWorkflow(
- "create-brand",
- (input: CreateBrandWorkflowInput) => {
- const brand = createBrandStep(input)
-
- return new WorkflowResponse(brand)
- }
-)
```
-You create the `createBrandWorkflow` using the `createWorkflow` function. This function accepts two parameters: the workflow's unique name, and the workflow's constructor function holding the workflow's implementation.
+This adds a `GET` API route at `/admin/brands`. In the API route, you resolve Query from the Medusa container. Query has a `graph` method that runs a query to retrieve data. It accepts an object having the following properties:
-The constructor function accepts the workflow's input as a parameter. In the function, you invoke the `createBrandStep` you created in the previous step to create a brand.
+- `entity`: The data model's name as specified in the first parameter of `model.define`.
+- `fields`: An array of properties and relations to retrieve. You can pass:
+ - A property's name, such as `id`, or `*` for all properties.
+ - A relation or linked model's name, such as `products` (use the plural name since brands are linked to list of products). You suffix the name with `.*` to retrieve all its properties.
-A workflow must return an instance of `WorkflowResponse`. It accepts as a parameter the data to return to the workflow's executor.
+`graph` returns an object having a `data` property, which is the retrieved brands. You return the brands in the response.
+
+### Test it Out
+
+To test the API route out, send a `GET` request to `/admin/brands`:
+
+```bash
+curl 'http://localhost:9000/admin/brands' \
+-H 'Authorization: Bearer {token}'
+```
+
+Make sure to replace `{token}` with your admin user's authentication token. Learn how to retrieve it in the [API reference](https://docs.medusajs.com/api/store#authentication).
+
+This returns the brands in your store with their linked products. For example:
+
+```json title="Example Response"
+{
+ "brands": [
+ {
+ "id": "123",
+ // ...
+ "products": [
+ {
+ "id": "prod_123",
+ // ...
+ }
+ ]
+ }
+ ]
+}
+```
+
+### Limitations: Filtering by Brand in Query
+
+While you can use Query to retrieve linked records, you can't filter by linked records.
+
+For an alternative approach, refer to the [Query documentation](https://docs.medusajs.com/learn/fundamentals/module-links/query#apply-filters-and-pagination-on-linked-records/index.html.md).
***
-## Next Steps: Expose Create Brand API Route
+## Summary
-You now have a `createBrandWorkflow` that you can execute to create a brand.
+By following the examples of the previous chapters, you:
-In the next chapter, you'll add an API route that allows admin users to create a brand. You'll learn how to create the API route, and execute in it the workflow you implemented in this chapter.
+- Defined a link between the Brand and Product modules's data models, allowing you to associate a product with a brand.
+- Extended the create-product workflow and route to allow setting the product's brand while creating the product.
+- Queried a product's brand, and vice versa.
+
+***
+
+## Next Steps: Customize Medusa Admin
+
+Clients, such as the Medusa Admin dashboard, can now use brand-related features, such as creating a brand or setting the brand of a product.
+
+In the next chapters, you'll learn how to customize the Medusa Admin to show a product's brand on its details page, and to show a new page with the list of brands in your store.
+
+
+# Admin Development Constraints
+
+This chapter lists some constraints of admin widgets and UI routes.
+
+## Arrow Functions
+
+Widget and UI route components must be created as arrow functions.
+
+```ts highlights={arrowHighlights}
+// Don't
+function ProductWidget() {
+ // ...
+}
+
+// Do
+const ProductWidget = () => {
+ // ...
+}
+```
+
+***
+
+## Widget Zone
+
+A widget zone's value must be wrapped in double or single quotes. It can't be a template literal or a variable.
+
+```ts highlights={zoneHighlights}
+// Don't
+export const config = defineWidgetConfig({
+ zone: `product.details.before`,
+})
+
+// Don't
+const ZONE = "product.details.after"
+export const config = defineWidgetConfig({
+ zone: ZONE,
+})
+
+// Do
+export const config = defineWidgetConfig({
+ zone: "product.details.before",
+})
+```
# Guide: Schedule Syncing Brands from Third-Party
@@ -6667,88 +6913,6 @@ You can now use the CMS Module's service to perform actions on the third-party C
In the next chapter, you'll learn how to emit an event when a brand is created, then handle that event to sync the brand from Medusa to the third-party service.
-# Write Integration Tests
-
-In this chapter, you'll learn about `medusaIntegrationTestRunner` from Medusa's Testing Framework and how to use it to write integration tests.
-
-### Prerequisites
-
-- [Testing Tools Setup](https://docs.medusajs.com/learn/debugging-and-testing/testing-tools/index.html.md)
-
-## medusaIntegrationTestRunner Utility
-
-The `medusaIntegrationTestRunner` is from Medusa's Testing Framework and it's used to create integration tests in your Medusa project. It runs a full Medusa application, allowing you test API routes, workflows, or other customizations.
-
-For example:
-
-```ts title="integration-tests/http/test.spec.ts" highlights={highlights}
-import { medusaIntegrationTestRunner } from "@medusajs/test-utils"
-
-medusaIntegrationTestRunner({
- testSuite: ({ api, getContainer }) => {
- // TODO write tests...
- },
-})
-
-jest.setTimeout(60 * 1000)
-```
-
-The `medusaIntegrationTestRunner` function accepts an object as a parameter. The object has a required property `testSuite`.
-
-`testSuite`'s value is a function that defines the tests to run. The function accepts as a parameter an object that has the following properties:
-
-- `api`: a set of utility methods used to send requests to the Medusa application. It has the following methods:
- - `get`: Send a `GET` request to an API route.
- - `post`: Send a `POST` request to an API route.
- - `delete`: Send a `DELETE` request to an API route.
-- `getContainer`: a function that retrieves the Medusa Container. Use the `getContainer().resolve` method to resolve resources from the Medusa Container.
-
-The tests in the `testSuite` function are written using [Jest](https://jestjs.io/).
-
-### Jest Timeout
-
-Since your tests connect to the database and perform actions that require more time than the typical tests, make sure to increase the timeout in your test:
-
-```ts title="integration-tests/http/test.spec.ts"
-// in your test's file
-jest.setTimeout(60 * 1000)
-```
-
-***
-
-### Run Tests
-
-Run the following command to run your tests:
-
-```bash npm2yarn
-npm run test:integration
-```
-
-If you don't have a `test:integration` script in `package.json`, refer to the [Medusa Testing Tools chapter](https://docs.medusajs.com/learn/debugging-and-testing/testing-tools#add-test-commands/index.html.md).
-
-This runs your Medusa application and runs the tests available under the `src/integrations/http` directory.
-
-***
-
-## Other Options and Inputs
-
-Refer to [the Test Tooling Reference](https://docs.medusajs.com/resources/test-tools-reference/medusaIntegrationTestRunner/index.html.md) for other available parameter options and inputs of the `testSuite` function.
-
-***
-
-## Database Used in Tests
-
-The `medusaIntegrationTestRunner` function creates a database with a random name before running the tests. Then, it drops that database after all the tests end.
-
-To manage that database, such as changing its name or perform operations on it in your tests, refer to [the Test Tooling Reference](https://docs.medusajs.com/resources/test-tools-reference/medusaIntegrationTestRunner/index.html.md).
-
-***
-
-## Example Integration Tests
-
-The next chapters provide examples of writing integration tests for API routes and workflows.
-
-
# Guide: Sync Brands from Medusa to Third-Party
In the [previous chapter](https://docs.medusajs.com/learn/customization/integrate-systems/service/index.html.md), you created a CMS Module that integrates a dummy third-party system. You can now perform actions using that module within your custom flows.
@@ -7021,169 +7185,82 @@ info: API Key: "123"
You can also automate syncing data from a third-party system to Medusa at a regular interval. In the next chapter, you'll learn how to sync brands from the third-party CMS to Medusa once a day.
-# Write Tests for Modules
+# Environment Variables in Admin Customizations
-In this chapter, you'll learn about `moduleIntegrationTestRunner` from Medusa's Testing Framework and how to use it to write integration tests for a module's main service.
+In this chapter, you'll learn how to use environment variables in your admin customizations.
-### Prerequisites
+To learn how environment variables are generally loaded in Medusa based on your application's environment, check out [this chapter](https://docs.medusajs.com/learn/fundamentals/environment-variables/index.html.md).
-- [Testing Tools Setup](https://docs.medusajs.com/learn/debugging-and-testing/testing-tools/index.html.md)
+## How to Set Environment Variables
-## moduleIntegrationTestRunner Utility
-
-`moduleIntegrationTestRunner` creates integration tests for a module. The integration tests run on a test Medusa application with only the specified module enabled.
-
-For example, assuming you have a `blog` module, create a test file at `src/modules/blog/__tests__/service.spec.ts`:
-
-```ts title="src/modules/blog/__tests__/service.spec.ts"
-import { moduleIntegrationTestRunner } from "@medusajs/test-utils"
-import { BLOG_MODULE } from ".."
-import BlogModuleService from "../service"
-import Post from "../models/post"
-
-moduleIntegrationTestRunner({
- moduleName: BLOG_MODULE,
- moduleModels: [Post],
- resolve: "./src/modules/blog",
- testSuite: ({ service }) => {
- // TODO write tests
- },
-})
-
-jest.setTimeout(60 * 1000)
-```
-
-The `moduleIntegrationTestRunner` function accepts as a parameter an object with the following properties:
-
-- `moduleName`: The name of the module.
-- `moduleModels`: An array of models in the module. Refer to [this section](#write-tests-for-modules-without-data-models) if your module doesn't have data models.
-- `resolve`: The path to the module's directory.
-- `testSuite`: A function that defines the tests to run.
-
-The `testSuite` function accepts as a parameter an object having the `service` property, which is an instance of the module's main service.
-
-The type argument provided to the `moduleIntegrationTestRunner` function is used as the type of the `service` property.
-
-The tests in the `testSuite` function are written using [Jest](https://jestjs.io/).
-
-***
-
-## Run Tests
-
-Run the following command to run your module integration tests:
-
-```bash npm2yarn
-npm run test:integration:modules
-```
-
-If you don't have a `test:integration:modules` script in `package.json`, refer to the [Medusa Testing Tools chapter](https://docs.medusajs.com/learn/debugging-and-testing/testing-tools#add-test-commands/index.html.md).
-
-This runs your Medusa application and runs the tests available in any `__tests__` directory under the `src/modules` directory.
-
-***
-
-## Pass Module Options
-
-If your module accepts options, you can set them using the `moduleOptions` property of the `moduleIntegrationTestRunner`'s parameter.
+The Medusa Admin is built on top of [Vite](https://vite.dev/). To set an environment variable that you want to use in a widget or UI route, prefix the environment variable with `VITE_`.
For example:
-```ts
-import { moduleIntegrationTestRunner } from "@medusajs/test-utils"
-import BlogModuleService from "../service"
-
-moduleIntegrationTestRunner({
- moduleOptions: {
- apiKey: "123",
- },
- // ...
-})
+```plain
+VITE_MY_API_KEY=sk_123
```
***
-## Write Tests for Modules without Data Models
+## How to Use Environment Variables
-If your module doesn't have a data model, pass a dummy model in the `moduleModels` property.
+To access or use an environment variable starting with `VITE_`, use the `import.meta.env` object.
For example:
-```ts
-import { moduleIntegrationTestRunner } from "@medusajs/test-utils"
-import BlogModuleService from "../service"
-import { model } from "@medusajs/framework/utils"
+```tsx highlights={[["8"]]}
+import { defineWidgetConfig } from "@medusajs/admin-sdk"
+import { Container, Heading } from "@medusajs/ui"
-const DummyModel = model.define("dummy_model", {
- id: model.id().primaryKey(),
-})
-
-moduleIntegrationTestRunner({
- moduleModels: [DummyModel],
- // ...
-})
-
-jest.setTimeout(60 * 1000)
-```
-
-***
-
-### Other Options and Inputs
-
-Refer to [the Test Tooling Reference](https://docs.medusajs.com/resources/test-tools-reference/moduleIntegrationTestRunner/index.html.md) for other available parameter options and inputs of the `testSuite` function.
-
-***
-
-## Database Used in Tests
-
-The `moduleIntegrationTestRunner` function creates a database with a random name before running the tests. Then, it drops that database after all the tests end.
-
-To manage that database, such as changing its name or perform operations on it in your tests, refer to [the Test Tooling Reference](https://docs.medusajs.com/resources/test-tools-reference/moduleIntegrationTestRunner/index.html.md).
-
-
-# Admin Development Constraints
-
-This chapter lists some constraints of admin widgets and UI routes.
-
-## Arrow Functions
-
-Widget and UI route components must be created as arrow functions.
-
-```ts highlights={arrowHighlights}
-// Don't
-function ProductWidget() {
- // ...
-}
-
-// Do
const ProductWidget = () => {
- // ...
+ return (
+
+
+ API Key: {import.meta.env.VITE_MY_API_KEY}
+
+
+ )
}
-```
-***
-
-## Widget Zone
-
-A widget zone's value must be wrapped in double or single quotes. It can't be a template literal or a variable.
-
-```ts highlights={zoneHighlights}
-// Don't
-export const config = defineWidgetConfig({
- zone: `product.details.before`,
-})
-
-// Don't
-const ZONE = "product.details.after"
-export const config = defineWidgetConfig({
- zone: ZONE,
-})
-
-// Do
export const config = defineWidgetConfig({
zone: "product.details.before",
})
+
+export default ProductWidget
```
+In this example, you display the API key in a widget using `import.meta.env.VITE_MY_API_KEY`.
+
+### Type Error on import.meta.env
+
+If you receive a type error on `import.meta.env`, create the file `src/admin/vite-env.d.ts` with the following content:
+
+```ts title="src/admin/vite-env.d.ts"
+///
+```
+
+This file tells TypeScript to recognize the `import.meta.env` object and enhances the types of your custom environment variables.
+
+***
+
+## Check Node Environment in Admin Customizations
+
+To check the current environment, Vite exposes two variables:
+
+- `import.meta.env.DEV`: Returns `true` if the current environment is development.
+- `import.meta.env.PROD`: Returns `true` if the current environment is production.
+
+Learn more about other Vite environment variables in the [Vite documentation](https://vite.dev/guide/env-and-mode).
+
+***
+
+## Environment Variables in Production
+
+When you build the Medusa application, including the Medusa Admin, with the `build` command, the environment variables are inlined into the build. This means that you can't change the environment variables without rebuilding the application.
+
+For example, the `VITE_MY_API_KEY` environment variable in the example above will be replaced with the actual value during the build process.
+
# Admin Routing Customizations
@@ -7338,202 +7415,6 @@ export const handle = {
Refer to [react-router-dom’s documentation](https://reactrouter.com/en/6.29.0) for components and hooks that you can use in your admin customizations.
-# Environment Variables in Admin Customizations
-
-In this chapter, you'll learn how to use environment variables in your admin customizations.
-
-To learn how environment variables are generally loaded in Medusa based on your application's environment, check out [this chapter](https://docs.medusajs.com/learn/fundamentals/environment-variables/index.html.md).
-
-## How to Set Environment Variables
-
-The Medusa Admin is built on top of [Vite](https://vite.dev/). To set an environment variable that you want to use in a widget or UI route, prefix the environment variable with `VITE_`.
-
-For example:
-
-```plain
-VITE_MY_API_KEY=sk_123
-```
-
-***
-
-## How to Use Environment Variables
-
-To access or use an environment variable starting with `VITE_`, use the `import.meta.env` object.
-
-For example:
-
-```tsx highlights={[["8"]]}
-import { defineWidgetConfig } from "@medusajs/admin-sdk"
-import { Container, Heading } from "@medusajs/ui"
-
-const ProductWidget = () => {
- return (
-
-
- API Key: {import.meta.env.VITE_MY_API_KEY}
-
-
- )
-}
-
-export const config = defineWidgetConfig({
- zone: "product.details.before",
-})
-
-export default ProductWidget
-```
-
-In this example, you display the API key in a widget using `import.meta.env.VITE_MY_API_KEY`.
-
-### Type Error on import.meta.env
-
-If you receive a type error on `import.meta.env`, create the file `src/admin/vite-env.d.ts` with the following content:
-
-```ts title="src/admin/vite-env.d.ts"
-///
-```
-
-This file tells TypeScript to recognize the `import.meta.env` object and enhances the types of your custom environment variables.
-
-***
-
-## Check Node Environment in Admin Customizations
-
-To check the current environment, Vite exposes two variables:
-
-- `import.meta.env.DEV`: Returns `true` if the current environment is development.
-- `import.meta.env.PROD`: Returns `true` if the current environment is production.
-
-Learn more about other Vite environment variables in the [Vite documentation](https://vite.dev/guide/env-and-mode).
-
-***
-
-## Environment Variables in Production
-
-When you build the Medusa application, including the Medusa Admin, with the `build` command, the environment variables are inlined into the build. This means that you can't change the environment variables without rebuilding the application.
-
-For example, the `VITE_MY_API_KEY` environment variable in the example above will be replaced with the actual value during the build process.
-
-
-# Admin Widgets
-
-In this chapter, you’ll learn more about widgets and how to use them.
-
-## What is an Admin Widget?
-
-The Medusa Admin dashboard's pages are customizable to insert widgets of custom content in pre-defined injection zones. You create these widgets as React components that allow admin users to perform custom actions.
-
-For example, you can add a widget on the product details page that allow admin users to sync products to a third-party service.
-
-***
-
-## How to Create a Widget?
-
-### Prerequisites
-
-- [Medusa application installed](https://docs.medusajs.com/learn/installation/index.html.md)
-
-You create a widget in a `.tsx` file under the `src/admin/widgets` directory. The file’s default export must be the widget, which is the React component that renders the custom content. The file must also export the widget’s configurations indicating where to insert the widget.
-
-For example, create the file `src/admin/widgets/product-widget.tsx` with the following content:
-
-
-
-```tsx title="src/admin/widgets/product-widget.tsx" highlights={widgetHighlights}
-import { defineWidgetConfig } from "@medusajs/admin-sdk"
-import { Container, Heading } from "@medusajs/ui"
-
-// The widget
-const ProductWidget = () => {
- return (
-
-
- Product Widget
-
-
- )
-}
-
-// The widget's configurations
-export const config = defineWidgetConfig({
- zone: "product.details.before",
-})
-
-export default ProductWidget
-```
-
-You export the `ProductWidget` component, which shows the heading `Product Widget`. In the widget, you use [Medusa UI](https://docs.medusajs.com/ui/index.html.md), a package that Medusa maintains to allow you to customize the dashboard with the same components used to build it.
-
-To export the widget's configurations, you use `defineWidgetConfig` from the Admin Extension SDK. It accepts as a parameter an object with the `zone` property, whose value is a string or an array of strings, each being the name of the zone to inject the widget into.
-
-In the example above, the widget is injected at the top of a product’s details.
-
-The widget component must be created as an arrow function.
-
-### Test the Widget
-
-To test out the widget, start the Medusa application:
-
-```bash npm2yarn
-npm run dev
-```
-
-Then, open a product’s details page. You’ll find your custom widget at the top of the page.
-
-***
-
-## Props Passed in Detail Pages
-
-Widgets that are injected into a details page receive a `data` prop, which is the main data of the details page.
-
-For example, a widget injected into the `product.details.before` zone receives the product's details in the `data` prop:
-
-```tsx title="src/admin/widgets/product-widget.tsx" highlights={detailHighlights}
-import { defineWidgetConfig } from "@medusajs/admin-sdk"
-import { Container, Heading } from "@medusajs/ui"
-import {
- DetailWidgetProps,
- AdminProduct,
-} from "@medusajs/framework/types"
-
-// The widget
-const ProductWidget = ({
- data,
-}: DetailWidgetProps) => {
- return (
-
-
-
- Product Widget {data.title}
-
-
-
- )
-}
-
-// The widget's configurations
-export const config = defineWidgetConfig({
- zone: "product.details.before",
-})
-
-export default ProductWidget
-```
-
-The props type is `DetailWidgetProps`, and it accepts as a type argument the expected type of `data`. For the product details page, it's `AdminProduct`.
-
-***
-
-## Injection Zone
-
-Refer to [this reference](https://docs.medusajs.com/resources/admin-widget-injection-zones/index.html.md) for the full list of injection zones and their props.
-
-***
-
-## Admin Components List
-
-To build admin customizations that match the Medusa Admin's designs and layouts, refer to [this guide](https://docs.medusajs.com/resources/admin-components/index.html.md) to find common components.
-
-
# Admin UI Routes
In this chapter, you’ll learn how to create a UI route in the admin dashboard.
@@ -7770,203 +7651,383 @@ To build admin customizations that match the Medusa Admin's designs and layouts,
For more customizations related to routes, refer to the [Routing Customizations chapter](https://docs.medusajs.com/learn/fundamentals/admin/routing/index.html.md).
-# Pass Additional Data to Medusa's API Route
+# Seed Data with Custom CLI Script
-In this chapter, you'll learn how to pass additional data in requests to Medusa's API Route.
+In this chapter, you'll learn how to seed data using a custom CLI script.
-## Why Pass Additional Data?
+## How to Seed Data
-Some of Medusa's API Routes accept an `additional_data` parameter whose type is an object. The API Route passes the `additional_data` to the workflow, which in turn passes it to its hooks.
+To seed dummy data for development or demo purposes, use a custom CLI script.
-This is useful when you have a link from your custom module to a Commerce Module, and you want to perform an additional action when a request is sent to an existing API route.
+In the CLI script, use your custom workflows or Medusa's existing workflows, which you can browse in [this reference](https://docs.medusajs.com/resources/medusa-workflows-reference/index.html.md), to seed data.
-For example, the [Create Product API Route](https://docs.medusajs.com/api/admin#products_postproducts) accepts an `additional_data` parameter. If you have a data model linked to it, you consume the `productsCreated` hook to create a record of the data model using the custom data and link it to the product.
+### Example: Seed Dummy Products
-### API Routes Accepting Additional Data
+In this section, you'll follow an example of creating a custom CLI script that seeds fifty dummy products.
-### API Routes List
+First, install the [Faker](https://fakerjs.dev/) library to generate random data in your script:
-- Campaigns
- - [Create Campaign](https://docs.medusajs.com/api/admin#campaigns_postcampaigns)
- - [Update Campaign](https://docs.medusajs.com/api/admin#campaigns_postcampaignsid)
-- Cart
- - [Create Cart](https://docs.medusajs.com/api/store#carts_postcarts)
- - [Update Cart](https://docs.medusajs.com/api/store#carts_postcartsid)
-- Collections
- - [Create Collection](https://docs.medusajs.com/api/admin#collections_postcollections)
- - [Update Collection](https://docs.medusajs.com/api/admin#collections_postcollectionsid)
-- Customers
- - [Create Customer](https://docs.medusajs.com/api/admin#customers_postcustomers)
- - [Update Customer](https://docs.medusajs.com/api/admin#customers_postcustomersid)
- - [Create Address](https://docs.medusajs.com/api/admin#customers_postcustomersidaddresses)
- - [Update Address](https://docs.medusajs.com/api/admin#customers_postcustomersidaddressesaddress_id)
-- Draft Orders
- - [Create Draft Order](https://docs.medusajs.com/api/admin#draft-orders_postdraftorders)
-- Orders
- - [Complete Orders](https://docs.medusajs.com/api/admin#orders_postordersidcomplete)
- - [Cancel Order's Fulfillment](https://docs.medusajs.com/api/admin#orders_postordersidfulfillmentsfulfillment_idcancel)
- - [Create Shipment](https://docs.medusajs.com/api/admin#orders_postordersidfulfillmentsfulfillment_idshipments)
- - [Create Fulfillment](https://docs.medusajs.com/api/admin#orders_postordersidfulfillments)
-- Products
- - [Create Product](https://docs.medusajs.com/api/admin#products_postproducts)
- - [Update Product](https://docs.medusajs.com/api/admin#products_postproductsid)
- - [Create Product Variant](https://docs.medusajs.com/api/admin#products_postproductsidvariants)
- - [Update Product Variant](https://docs.medusajs.com/api/admin#products_postproductsidvariantsvariant_id)
- - [Create Product Option](https://docs.medusajs.com/api/admin#products_postproductsidoptions)
- - [Update Product Option](https://docs.medusajs.com/api/admin#products_postproductsidoptionsoption_id)
-- Product Tags
- - [Create Product Tag](https://docs.medusajs.com/api/admin#product-tags_postproducttags)
- - [Update Product Tag](https://docs.medusajs.com/api/admin#product-tags_postproducttagsid)
-- Product Types
- - [Create Product Type](https://docs.medusajs.com/api/admin#product-types_postproducttypes)
- - [Update Product Type](https://docs.medusajs.com/api/admin#product-types_postproducttypesid)
-- Promotions
- - [Create Promotion](https://docs.medusajs.com/api/admin#promotions_postpromotions)
- - [Update Promotion](https://docs.medusajs.com/api/admin#promotions_postpromotionsid)
-
-***
-
-## How to Pass Additional Data
-
-### 1. Specify Validation of Additional Data
-
-Before passing custom data in the `additional_data` object parameter, you must specify validation rules for the allowed properties in the object.
-
-To do that, use the middleware route object defined in `src/api/middlewares.ts`.
-
-For example, create the file `src/api/middlewares.ts` with the following content:
-
-```ts title="src/api/middlewares.ts"
-import { defineMiddlewares } from "@medusajs/framework/http"
-import { z } from "zod"
-
-export default defineMiddlewares({
- routes: [
- {
- method: "POST",
- matcher: "/admin/products",
- additionalDataValidator: {
- brand: z.string().optional(),
- },
- },
- ],
-})
+```bash npm2yarn
+npm install --save-dev @faker-js/faker
```
-The middleware route object accepts an optional parameter `additionalDataValidator` whose value is an object of key-value pairs. The keys indicate the name of accepted properties in the `additional_data` parameter, and the value is [Zod](https://zod.dev/) validation rules of the property.
+Then, create the file `src/scripts/demo-products.ts` with the following content:
-In this example, you indicate that the `additional_data` parameter accepts a `brand` property whose value is an optional string.
+```ts title="src/scripts/demo-products.ts" highlights={highlights} collapsibleLines="1-12" expandButtonLabel="Show Imports"
+import { ExecArgs } from "@medusajs/framework/types"
+import { faker } from "@faker-js/faker"
+import {
+ ContainerRegistrationKeys,
+ Modules,
+ ProductStatus,
+} from "@medusajs/framework/utils"
+import {
+ createInventoryLevelsWorkflow,
+ createProductsWorkflow,
+} from "@medusajs/medusa/core-flows"
-Refer to [Zod's documentation](https://zod.dev) for all available validation rules.
+export default async function seedDummyProducts({
+ container,
+}: ExecArgs) {
+ const salesChannelModuleService = container.resolve(
+ Modules.SALES_CHANNEL
+ )
+ const logger = container.resolve(
+ ContainerRegistrationKeys.LOGGER
+ )
+ const query = container.resolve(
+ ContainerRegistrationKeys.QUERY
+ )
-### 2. Pass the Additional Data in a Request
+ const defaultSalesChannel = await salesChannelModuleService
+ .listSalesChannels({
+ name: "Default Sales Channel",
+ })
-You can now pass a `brand` property in the `additional_data` parameter of a request to the Create Product API Route.
+ const sizeOptions = ["S", "M", "L", "XL"]
+ const colorOptions = ["Black", "White"]
+ const currency_code = "eur"
+ const productsNum = 50
-For example:
+ // TODO seed products
+}
+```
+
+So far, in the script, you:
+
+- Resolve the Sales Channel Module's main service to retrieve the application's default sales channel. This is the sales channel the dummy products will be available in.
+- Resolve the Logger to log messages in the terminal, and Query to later retrieve data useful for the seeded products.
+- Initialize some default data to use when seeding the products next.
+
+Next, replace the `TODO` with the following:
+
+```ts title="src/scripts/demo-products.ts"
+const productsData = new Array(productsNum).fill(0).map((_, index) => {
+ const title = faker.commerce.product() + "_" + index
+ return {
+ title,
+ is_giftcard: true,
+ description: faker.commerce.productDescription(),
+ status: ProductStatus.PUBLISHED,
+ options: [
+ {
+ title: "Size",
+ values: sizeOptions,
+ },
+ {
+ title: "Color",
+ values: colorOptions,
+ },
+ ],
+ images: [
+ {
+ url: faker.image.urlPlaceholder({
+ text: title,
+ }),
+ },
+ {
+ url: faker.image.urlPlaceholder({
+ text: title,
+ }),
+ },
+ ],
+ variants: new Array(10).fill(0).map((_, variantIndex) => ({
+ title: `${title} ${variantIndex}`,
+ sku: `variant-${variantIndex}${index}`,
+ prices: new Array(10).fill(0).map((_, priceIndex) => ({
+ currency_code,
+ amount: 10 * priceIndex,
+ })),
+ options: {
+ Size: sizeOptions[Math.floor(Math.random() * 3)],
+ },
+ })),
+ shipping_profile_id: "sp_123",
+ sales_channels: [
+ {
+ id: defaultSalesChannel[0].id,
+ },
+ ],
+ }
+})
+
+// TODO seed products
+```
+
+You generate fifty products using the sales channel and variables you initialized, and using Faker for random data, such as the product's title or images.
+
+Then, replace the new `TODO` with the following:
+
+```ts title="src/scripts/demo-products.ts"
+const { result: products } = await createProductsWorkflow(container).run({
+ input: {
+ products: productsData,
+ },
+})
+
+logger.info(`Seeded ${products.length} products.`)
+
+// TODO add inventory levels
+```
+
+You create the generated products using the `createProductsWorkflow` imported previously from `@medusajs/medusa/core-flows`. It accepts the product data as input, and returns the created products.
+
+Only thing left is to create inventory levels for the products. So, replace the last `TODO` with the following:
+
+```ts title="src/scripts/demo-products.ts"
+logger.info("Seeding inventory levels.")
+
+const { data: stockLocations } = await query.graph({
+ entity: "stock_location",
+ fields: ["id"],
+})
+
+const { data: inventoryItems } = await query.graph({
+ entity: "inventory_item",
+ fields: ["id"],
+})
+
+const inventoryLevels = inventoryItems.map((inventoryItem) => ({
+ location_id: stockLocations[0].id,
+ stocked_quantity: 1000000,
+ inventory_item_id: inventoryItem.id,
+}))
+
+await createInventoryLevelsWorkflow(container).run({
+ input: {
+ inventory_levels: inventoryLevels,
+ },
+})
+
+logger.info("Finished seeding inventory levels data.")
+```
+
+You use Query to retrieve the stock location, to use the first location in the application, and the inventory items.
+
+Then, you generate inventory levels for each inventory item, associating it with the first stock location.
+
+Finally, you use the `createInventoryLevelsWorkflow` from Medusa's core workflows to create the inventory levels.
+
+### Test Script
+
+To test out the script, run the following command in your project's directory:
```bash
-curl -X POST 'http://localhost:9000/admin/products' \
--H 'Content-Type: application/json' \
--H 'Authorization: Bearer {token}' \
---data '{
- "title": "Product 1",
- "options": [
- {
- "title": "Default option",
- "values": ["Default option value"]
- }
- ],
- "shipping_profile_id": "{shipping_profile_id}",
- "additional_data": {
- "brand": "Acme"
- }
-}'
+npx medusa exec ./src/scripts/demo-products.ts
```
-Make sure to replace the `{token}` in the authorization header with an admin user's authentication token, and `{shipping_profile_id}` with an existing shipping profile's ID.
+This seeds the products to your database. If you run your Medusa application and view the products in the dashboard, you'll find fifty new products.
-In this request, you pass in the `additional_data` parameter a `brand` property and set its value to `Acme`.
-The `additional_data` is then passed to hooks in the `createProductsWorkflow` used by the API route.
+# Admin Widgets
+
+In this chapter, you’ll learn more about widgets and how to use them.
+
+## What is an Admin Widget?
+
+The Medusa Admin dashboard's pages are customizable to insert widgets of custom content in pre-defined injection zones. You create these widgets as React components that allow admin users to perform custom actions.
+
+For example, you can add a widget on the product details page that allow admin users to sync products to a third-party service.
***
-## Use Additional Data in a Hook
+## How to Create a Widget?
-Learn about workflow hooks in [this guide](https://docs.medusajs.com/learn/fundamentals/workflows/workflow-hooks/index.html.md).
+### Prerequisites
-Step functions consuming the workflow hook can access the `additional_data` in the first parameter.
+- [Medusa application installed](https://docs.medusajs.com/learn/installation/index.html.md)
-For example, consider you want to store the data passed in `additional_data` in the product's `metadata` property.
+You create a widget in a `.tsx` file under the `src/admin/widgets` directory. The file’s default export must be the widget, which is the React component that renders the custom content. The file must also export the widget’s configurations indicating where to insert the widget.
-To do that, create the file `src/workflows/hooks/product-created.ts` with the following content:
+For example, create the file `src/admin/widgets/product-widget.tsx` with the following content:
-```ts title="src/workflows/hooks/product-created.ts"
-import { StepResponse } from "@medusajs/framework/workflows-sdk"
-import { createProductsWorkflow } from "@medusajs/medusa/core-flows"
-import { Modules } from "@medusajs/framework/utils"
+
-createProductsWorkflow.hooks.productsCreated(
- async ({ products, additional_data }, { container }) => {
- if (!additional_data?.brand) {
- return
- }
+```tsx title="src/admin/widgets/product-widget.tsx" highlights={widgetHighlights}
+import { defineWidgetConfig } from "@medusajs/admin-sdk"
+import { Container, Heading } from "@medusajs/ui"
- const productModuleService = container.resolve(
- Modules.PRODUCT
- )
+// The widget
+const ProductWidget = () => {
+ return (
+
+
+ Product Widget
+
+
+ )
+}
- await productModuleService.upsertProducts(
- products.map((product) => ({
- ...product,
- metadata: {
- ...product.metadata,
- brand: additional_data.brand,
- },
- }))
- )
+// The widget's configurations
+export const config = defineWidgetConfig({
+ zone: "product.details.before",
+})
- return new StepResponse(products, {
- products,
- additional_data,
- })
- }
-)
+export default ProductWidget
```
-This consumes the `productsCreated` hook, which runs after the products are created.
+You export the `ProductWidget` component, which shows the heading `Product Widget`. In the widget, you use [Medusa UI](https://docs.medusajs.com/ui/index.html.md), a package that Medusa maintains to allow you to customize the dashboard with the same components used to build it.
-If `brand` is passed in `additional_data`, you resolve the Product Module's main service and use its `upsertProducts` method to update the products, adding the brand to the `metadata` property.
+To export the widget's configurations, you use `defineWidgetConfig` from the Admin Extension SDK. It accepts as a parameter an object with the `zone` property, whose value is a string or an array of strings, each being the name of the zone to inject the widget into.
-### Compensation Function
+In the example above, the widget is injected at the top of a product’s details.
-Hooks also accept a compensation function as a second parameter to undo the actions made by the step function.
+The widget component must be created as an arrow function.
-For example, pass the following second parameter to the `productsCreated` hook:
+### Test the Widget
-```ts title="src/workflows/hooks/product-created.ts"
-createProductsWorkflow.hooks.productsCreated(
- async ({ products, additional_data }, { container }) => {
- // ...
+To test out the widget, start the Medusa application:
+
+```bash npm2yarn
+npm run dev
+```
+
+Then, open a product’s details page. You’ll find your custom widget at the top of the page.
+
+***
+
+## Props Passed in Detail Pages
+
+Widgets that are injected into a details page receive a `data` prop, which is the main data of the details page.
+
+For example, a widget injected into the `product.details.before` zone receives the product's details in the `data` prop:
+
+```tsx title="src/admin/widgets/product-widget.tsx" highlights={detailHighlights}
+import { defineWidgetConfig } from "@medusajs/admin-sdk"
+import { Container, Heading } from "@medusajs/ui"
+import {
+ DetailWidgetProps,
+ AdminProduct,
+} from "@medusajs/framework/types"
+
+// The widget
+const ProductWidget = ({
+ data,
+}: DetailWidgetProps) => {
+ return (
+
+
+
+ Product Widget {data.title}
+
+
+
+ )
+}
+
+// The widget's configurations
+export const config = defineWidgetConfig({
+ zone: "product.details.before",
+})
+
+export default ProductWidget
+```
+
+The props type is `DetailWidgetProps`, and it accepts as a type argument the expected type of `data`. For the product details page, it's `AdminProduct`.
+
+***
+
+## Injection Zone
+
+Refer to [this reference](https://docs.medusajs.com/resources/admin-widget-injection-zones/index.html.md) for the full list of injection zones and their props.
+
+***
+
+## Admin Components List
+
+To build admin customizations that match the Medusa Admin's designs and layouts, refer to [this guide](https://docs.medusajs.com/resources/admin-components/index.html.md) to find common components.
+
+
+# Add Data Model Check Constraints
+
+In this chapter, you'll learn how to add check constraints to your data model.
+
+## What is a Check Constraint?
+
+A check constraint is a condition that must be satisfied by records inserted into a database table, otherwise an error is thrown.
+
+For example, if you have a data model with a `price` property, you want to only allow positive number values. So, you add a check constraint that fails when inserting a record with a negative price value.
+
+***
+
+## How to Set a Check Constraint?
+
+To set check constraints on a data model, use the `checks` method. This method accepts an array of check constraints to apply on the data model.
+
+For example, to set a check constraint on a `price` property that ensures its value can only be a positive number:
+
+```ts highlights={checks1Highlights}
+import { model } from "@medusajs/framework/utils"
+
+const CustomProduct = model.define("custom_product", {
+ // ...
+ price: model.bigNumber(),
+})
+.checks([
+ (columns) => `${columns.price} >= 0`,
+])
+```
+
+The item passed in the array parameter of `checks` can be a callback function that accepts as a parameter an object whose keys are the names of the properties in the data model schema, and values the respective column name in the database.
+
+The function returns a string indicating the [SQL check constraint expression](https://www.postgresql.org/docs/current/ddl-constraints.html#DDL-CONSTRAINTS-CHECK-CONSTRAINTS). In the expression, use the `columns` parameter to access a property's column name.
+
+You can also pass an object to the `checks` method:
+
+```ts highlights={checks2Highlights}
+import { model } from "@medusajs/framework/utils"
+
+const CustomProduct = model.define("custom_product", {
+ // ...
+ price: model.bigNumber(),
+})
+.checks([
+ {
+ name: "custom_product_price_check",
+ expression: (columns) => `${columns.price} >= 0`,
},
- async ({ products, additional_data }, { container }) => {
- if (!additional_data.brand) {
- return
- }
-
- const productModuleService = container.resolve(
- Modules.PRODUCT
- )
-
- await productModuleService.upsertProducts(
- products
- )
- }
-)
+])
```
-This updates the products to their original state before adding the brand to their `metadata` property.
+The object accepts the following properties:
+
+- `name`: The check constraint's name.
+- `expression`: A function similar to the one that can be passed to the array. It accepts an object of columns and returns an [SQL check constraint expression](https://www.postgresql.org/docs/current/ddl-constraints.html#DDL-CONSTRAINTS-CHECK-CONSTRAINTS).
+
+***
+
+## Apply in Migrations
+
+After adding the check constraint, make sure to generate and run migrations if you already have the table in the database. Otherwise, the check constraint won't be reflected.
+
+To generate a migration for the data model's module then reflect it on the database, run the following command:
+
+```bash
+npx medusa db:generate custom_module
+npx medusa db:migrate
+```
+
+The first command generates the migration under the `migrations` directory of your module's directory, and the second reflects it on the database.
# Admin Development Tips
@@ -8100,1639 +8161,6 @@ The Medusa Admin dashboard can be displayed in languages other than English, whi
Learn how to add a new language translation for the Medusa Admin in [this guide](https://docs.medusajs.com/learn/resources/contribution-guidelines/admin-translations/index.html.md).
-# HTTP Methods
-
-In this chapter, you'll learn about how to add new API routes for each HTTP method.
-
-## HTTP Method Handler
-
-An API route is created for every HTTP method you export a handler function for in a route file.
-
-Allowed HTTP methods are: `GET`, `POST`, `DELETE`, `PUT`, `PATCH`, `OPTIONS`, and `HEAD`.
-
-For example, create the file `src/api/hello-world/route.ts` with the following content:
-
-```ts title="src/api/hello-world/route.ts"
-import type {
- MedusaRequest,
- MedusaResponse,
-} from "@medusajs/framework/http"
-
-export const GET = async (
- req: MedusaRequest,
- res: MedusaResponse
-) => {
- res.json({
- message: "[GET] Hello world!",
- })
-}
-
-export const POST = async (
- req: MedusaRequest,
- res: MedusaResponse
-) => {
- res.json({
- message: "[POST] Hello world!",
- })
-}
-```
-
-This adds two API Routes:
-
-- A `GET` route at `http://localhost:9000/hello-world`.
-- A `POST` route at `http://localhost:9000/hello-world`.
-
-
-# Throwing and Handling Errors
-
-In this guide, you'll learn how to throw errors in your Medusa application, how it affects an API route's response, and how to change the default error handler of your Medusa application.
-
-## Throw MedusaError
-
-When throwing an error in your API routes, middlewares, workflows, or any customization, throw a `MedusaError` from the Medusa Framework.
-
-The Medusa application's API route error handler then wraps your thrown error in a uniform object and returns it in the response.
-
-For example:
-
-```ts
-import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
-import { MedusaError } from "@medusajs/framework/utils"
-
-export const GET = async (
- req: MedusaRequest,
- res: MedusaResponse
-) => {
- if (!req.query.q) {
- throw new MedusaError(
- MedusaError.Types.INVALID_DATA,
- "The `q` query parameter is required."
- )
- }
-
- // ...
-}
-```
-
-The `MedusaError` class accepts in its constructor two parameters:
-
-1. The first is the error's type. `MedusaError` has a static property `Types` that you can use. `Types` is an enum whose possible values are explained in the next section.
-2. The second is the message to show in the error response.
-
-### Error Object in Response
-
-The error object returned in the response has two properties:
-
-- `type`: The error's type.
-- `message`: The error message, if available.
-- `code`: A common snake-case code. Its values can be:
- - `invalid_request_error` for the `DUPLICATE_ERROR` type.
- - `api_error`: for the `DB_ERROR` type.
- - `invalid_state_error` for `CONFLICT` error type.
- - `unknown_error` for any unidentified error type.
- - For other error types, this property won't be available unless you provide a code as a third parameter to the `MedusaError` constructor.
-
-### MedusaError Types
-
-|Type|Description|Status Code|
-|---|---|---|---|---|
-|\`DB\_ERROR\`|Indicates a database error.|\`500\`|
-|\`DUPLICATE\_ERROR\`|Indicates a duplicate of a record already exists. For example, when trying to create a customer whose email is registered by another customer.|\`422\`|
-|\`INVALID\_ARGUMENT\`|Indicates an error that occurred due to incorrect arguments or other unexpected state.|\`500\`|
-|\`INVALID\_DATA\`|Indicates a validation error.|\`400\`|
-|\`UNAUTHORIZED\`|Indicates that a user is not authorized to perform an action or access a route.|\`401\`|
-|\`NOT\_FOUND\`|Indicates that the requested resource, such as a route or a record, isn't found.|\`404\`|
-|\`NOT\_ALLOWED\`|Indicates that an operation isn't allowed.|\`400\`|
-|\`CONFLICT\`|Indicates that a request conflicts with another previous or ongoing request. The error message in this case is ignored for a default message.|\`409\`|
-|\`PAYMENT\_AUTHORIZATION\_ERROR\`|Indicates an error has occurred while authorizing a payment.|\`422\`|
-|Other error types|Any other error type results in an |\`500\`|
-
-***
-
-## Override Error Handler
-
-The `defineMiddlewares` function used to apply middlewares on routes accepts an `errorHandler` in its object parameter. Use it to override the default error handler for API routes.
-
-This error handler will also be used for errors thrown in Medusa's API routes and resources.
-
-For example, create `src/api/middlewares.ts` with the following:
-
-```ts title="src/api/middlewares.ts" collapsibleLines="1-8" expandMoreLabel="Show Imports"
-import {
- defineMiddlewares,
- MedusaNextFunction,
- MedusaRequest,
- MedusaResponse,
-} from "@medusajs/framework/http"
-import { MedusaError } from "@medusajs/framework/utils"
-
-export default defineMiddlewares({
- errorHandler: (
- error: MedusaError | any,
- req: MedusaRequest,
- res: MedusaResponse,
- next: MedusaNextFunction
- ) => {
- res.status(400).json({
- error: "Something happened.",
- })
- },
-})
-```
-
-The `errorHandler` property's value is a function that accepts four parameters:
-
-1. The error thrown. Its type can be `MedusaError` or any other thrown error type.
-2. A request object of type `MedusaRequest`.
-3. A response object of type `MedusaResponse`.
-4. A function of type MedusaNextFunction that executes the next middleware in the stack.
-
-This example overrides Medusa's default error handler with a handler that always returns a `400` status code with the same message.
-
-
-# Middlewares
-
-In this chapter, you’ll learn about middlewares and how to create them.
-
-## What is a Middleware?
-
-A middleware is a function executed when a request is sent to an API Route. It's executed before the route handler function.
-
-Middlewares are used to guard API routes, parse request content types other than `application/json`, manipulate request data, and more.
-
-As Medusa's server is based on Express, you can use any [Express middleware](https://expressjs.com/en/resources/middleware.html).
-
-### Middleware Types
-
-There are two types of middlewares:
-
-1. Global Middleware: A middleware that applies to all routes matching a specified pattern.
-2. Route Middleware: A middleware that applies to routes matching a specified pattern and HTTP method(s).
-
-These middlewares generally have the same definition and usage, but they differ in the routes they apply to. You'll learn how to create both types in the following sections.
-
-***
-
-## How to Create a Global Middleware?
-
-Middlewares of all types are defined in the special file `src/api/middlewares.ts`. Use the `defineMiddlewares` function from the Medusa Framework to define the middlewares, and export its value.
-
-For example:
-
-```ts title="src/api/middlewares.ts"
-import {
- defineMiddlewares,
- MedusaNextFunction,
- MedusaRequest,
- MedusaResponse,
-} from "@medusajs/framework/http"
-
-export default defineMiddlewares({
- routes: [
- {
- matcher: "/custom*",
- middlewares: [
- (
- req: MedusaRequest,
- res: MedusaResponse,
- next: MedusaNextFunction
- ) => {
- console.log("Received a request!")
-
- next()
- },
- ],
- },
- ],
-})
-```
-
-The `defineMiddlewares` function accepts a middleware configurations object that has the property `routes`. `routes`'s value is an array of middleware route objects, each having the following properties:
-
-- `matcher`: a string or regular expression indicating the API route path to apply the middleware on. The regular expression must be compatible with [path-to-regexp](https://github.com/pillarjs/path-to-regexp).
-- `middlewares`: An array of global and route middleware functions.
-
-In the example above, you define a global middleware that logs the message `Received a request!` whenever a request is sent to an API route path starting with `/custom`.
-
-### Test the Global Middleware
-
-To test the middleware:
-
-1. Start the application:
-
-```bash npm2yarn
-npm run dev
-```
-
-2. Send a request to any API route starting with `/custom`.
-3. See the following message in the terminal:
-
-```bash
-Received a request!
-```
-
-***
-
-## How to Create a Route Middleware?
-
-In the previous section, you learned how to create a global middleware. You define the route middleware in the same way in `src/api/middlewares.ts`, but you specify an additional property `method` in the middleware route object. Its value is one or more HTTP methods to apply the middleware to.
-
-For example:
-
-```ts title="src/api/middlewares.ts" highlights={highlights} collapsibleLines="1-7" expandButtonLabel="Show Imports"
-import {
- MedusaNextFunction,
- MedusaRequest,
- MedusaResponse,
- defineMiddlewares,
-} from "@medusajs/framework/http"
-
-export default defineMiddlewares({
- routes: [
- {
- matcher: "/custom*",
- method: ["POST", "PUT"],
- middlewares: [
- (
- req: MedusaRequest,
- res: MedusaResponse,
- next: MedusaNextFunction
- ) => {
- console.log("Received a request!")
-
- next()
- },
- ],
- },
- ],
-})
-```
-
-This example applies the middleware only when a `POST` or `PUT` request is sent to an API route path starting with `/custom`, changing the middleware from a global middleware to a route middleware.
-
-### Test the Route Middleware
-
-To test the middleware:
-
-1. Start the application:
-
-```bash npm2yarn
-npm run dev
-```
-
-2. Send a `POST` request to any API route starting with `/custom`.
-3. See the following message in the terminal:
-
-```bash
-Received a request!
-```
-
-***
-
-## When to Use Middlewares
-
-- You want to protect API routes by a custom condition.
-- You're modifying the request body.
-
-***
-
-## Middleware Function Parameters
-
-The middleware function accepts three parameters:
-
-1. A request object of type `MedusaRequest`.
-2. A response object of type `MedusaResponse`.
-3. A function of type `MedusaNextFunction` that executes the next middleware in the stack.
-
-You must call the `next` function in the middleware. Otherwise, other middlewares and the API route handler won’t execute.
-
-***
-
-## Middleware for Routes with Path Parameters
-
-To indicate a path parameter in a middleware's `matcher` pattern, use the format `:{param-name}`.
-
-For example:
-
-```ts title="src/api/middlewares.ts" collapsibleLines="1-7" expandMoreLabel="Show Imports" highlights={pathParamHighlights}
-import {
- MedusaNextFunction,
- MedusaRequest,
- MedusaResponse,
- defineMiddlewares,
-} from "@medusajs/framework/http"
-
-export default defineMiddlewares({
- routes: [
- {
- matcher: "/custom/:id",
- middlewares: [
- // ...
- ],
- },
- ],
-})
-```
-
-This applies a middleware to the routes defined in the file `src/api/custom/[id]/route.ts`.
-
-***
-
-## Request URLs with Trailing Backslashes
-
-A middleware whose `matcher` pattern doesn't end with a backslash won't be applied for requests to URLs with a trailing backslash.
-
-For example, consider you have the following middleware:
-
-```ts title="src/api/middlewares.ts" collapsibleLines="1-7" expandMoreLabel="Show Imports"
-import {
- MedusaNextFunction,
- MedusaRequest,
- MedusaResponse,
- defineMiddlewares,
-} from "@medusajs/framework/http"
-
-export default defineMiddlewares({
- routes: [
- {
- matcher: "/custom",
- middlewares: [
- (
- req: MedusaRequest,
- res: MedusaResponse,
- next: MedusaNextFunction
- ) => {
- console.log("Received a request!")
-
- next()
- },
- ],
- },
- ],
-})
-```
-
-If you send a request to `http://localhost:9000/custom`, the middleware will run.
-
-However, if you send a request to `http://localhost:9000/custom/`, the middleware won't run.
-
-In general, avoid adding trailing backslashes when sending requests to API routes.
-
-***
-
-## Middlewares and Route Ordering
-
-The ordering explained in this section was added in [Medusa v2.6](https://github.com/medusajs/medusa/releases/tag/v2.6)
-
-The Medusa application registers middlewares and API route handlers in the following order:
-
-1. Global middlewares in the following order:
- 1. Global middleware defined in the Medusa's core.
- 2. Global middleware defined in the plugins (in the order the plugins are registered in).
- 3. Global middleware you define in the application.
-2. Route middlewares in the following order:
- 1. Route middleware defined in the Medusa's core.
- 2. Route middleware defined in the plugins (in the order the plugins are registered in).
- 3. Route middleware you define in the application.
-3. API routes in the following order:
- 1. API routes defined in the Medusa's core.
- 2. API routes defined in the plugins (in the order the plugins are registered in).
- 3. API routes you define in the application.
-
-### Middlewares Sorting
-
-On top of the previous ordering, Medusa sorts global and route middlewares based on their matcher pattern in the following order:
-
-1. Wildcard matchers. For example, `/custom*`.
-2. Regex matchers. For example, `/custom/(products|collections)`.
-3. Static matchers without parameters. For example, `/custom`.
-4. Static matchers with parameters. For example, `/custom/:id`.
-
-For example, if you have the following middlewares:
-
-```ts title="src/api/middlewares.ts"
-export default defineMiddlewares({
- routes: [
- {
- matcher: "/custom/:id",
- middlewares: [/* ... */],
- },
- {
- matcher: "/custom",
- middlewares: [/* ... */],
- },
- {
- matcher: "/custom*",
- method: ["GET"],
- middlewares: [/* ... */],
- },
- {
- matcher: "/custom/:id",
- method: ["GET"],
- middlewares: [/* ... */],
- },
- ],
-})
-```
-
-The global middlewares are sorted into the following order before they're registered:
-
-1. Global middleware `/custom`.
-2. Global middleware `/custom/:id`.
-
-And the route middlewares are sorted into the following order before they're registered:
-
-1. Route middleware `/custom*`.
-2. Route middleware `/custom/:id`.
-
-Then, the middlwares are registered in the order mentioned earlier, with global middlewares first, then the route middlewares.
-
-### Middlewares and Route Execution Order
-
-When a request is sent to an API route, the global middlewares are executed first, then the route middlewares, and finally the route handler.
-
-For example, consider you have the following middlewares:
-
-```ts title="src/api/middlewares.ts"
-export default defineMiddlewares({
- routes: [
- {
- matcher: "/custom",
- middlewares: [
- (req, res, next) => {
- console.log("Global middleware")
- next()
- },
- ],
- },
- {
- matcher: "/custom",
- method: ["GET"],
- middlewares: [
- (req, res, next) => {
- console.log("Route middleware")
- next()
- },
- ],
- },
- ],
-})
-```
-
-When you send a request to `/custom` route, the following messages are logged in the terminal:
-
-```bash
-Global middleware
-Route middleware
-Hello from custom! # message logged from API route handler
-```
-
-The global middleware runs first, then the route middleware, and finally the route handler, assuming that it logs the message `Hello from custom!`.
-
-***
-
-## Overriding Middlewares
-
-A middleware can not override an existing middleware. Instead, middlewares are added to the end of the middleware stack.
-
-For example, if you define a custom validation middleware, such as `validateAndTransformBody`, on an existing route, then both the original and the custom validation middleware will run.
-
-
-# API Route Parameters
-
-In this chapter, you’ll learn about path, query, and request body parameters.
-
-## Path Parameters
-
-To create an API route that accepts a path parameter, create a directory within the route file's path whose name is of the format `[param]`.
-
-For example, to create an API Route at the path `/hello-world/:id`, where `:id` is a path parameter, create the file `src/api/hello-world/[id]/route.ts` with the following content:
-
-```ts title="src/api/hello-world/[id]/route.ts" highlights={singlePathHighlights}
-import type {
- MedusaRequest,
- MedusaResponse,
-} from "@medusajs/framework/http"
-
-export const GET = async (
- req: MedusaRequest,
- res: MedusaResponse
-) => {
- res.json({
- message: `[GET] Hello ${req.params.id}!`,
- })
-}
-```
-
-The `MedusaRequest` object has a `params` property. `params` holds the path parameters in key-value pairs.
-
-### Multiple Path Parameters
-
-To create an API route that accepts multiple path parameters, create within the file's path multiple directories whose names are of the format `[param]`.
-
-For example, to create an API route at `/hello-world/:id/name/:name`, create the file `src/api/hello-world/[id]/name/[name]/route.ts` with the following content:
-
-```ts title="src/api/hello-world/[id]/name/[name]/route.ts" highlights={multiplePathHighlights}
-import type {
- MedusaRequest,
- MedusaResponse,
-} from "@medusajs/framework/http"
-
-export const GET = async (
- req: MedusaRequest,
- res: MedusaResponse
-) => {
- res.json({
- message: `[GET] Hello ${
- req.params.id
- } - ${req.params.name}!`,
- })
-}
-```
-
-You access the `id` and `name` path parameters using the `req.params` property.
-
-***
-
-## Query Parameters
-
-You can access all query parameters in the `query` property of the `MedusaRequest` object. `query` is an object of key-value pairs, where the key is a query parameter's name, and the value is its value.
-
-For example:
-
-```ts title="src/api/hello-world/route.ts" highlights={queryHighlights}
-import type {
- MedusaRequest,
- MedusaResponse,
-} from "@medusajs/framework/http"
-
-export const GET = async (
- req: MedusaRequest,
- res: MedusaResponse
-) => {
- res.json({
- message: `Hello ${req.query.name}`,
- })
-}
-```
-
-The value of `req.query.name` is the value passed in `?name=John`, for example.
-
-### Validate Query Parameters
-
-You can apply validation rules on received query parameters to ensure they match specified rules and types.
-
-Learn more in [this documentation](https://docs.medusajs.com/learn/fundamentals/api-routes/validation#how-to-validate-request-query-paramters/index.html.md).
-
-***
-
-## Request Body Parameters
-
-The Medusa application parses the body of any request having a JSON, URL-encoded, or text request content types. The request body parameters are set in the `MedusaRequest`'s `body` property.
-
-Learn more about configuring body parsing in [this guide](https://docs.medusajs.com/learn/fundamentals/api-routes/parse-body/index.html.md).
-
-For example:
-
-```ts title="src/api/hello-world/route.ts" highlights={bodyHighlights}
-import type {
- MedusaRequest,
- MedusaResponse,
-} from "@medusajs/framework/http"
-
-type HelloWorldReq = {
- name: string
-}
-
-export const POST = async (
- req: MedusaRequest,
- res: MedusaResponse
-) => {
- res.json({
- message: `[POST] Hello ${req.body.name}!`,
- })
-}
-```
-
-In this example, you use the `name` request body parameter to create the message in the returned response.
-
-The `MedusaRequest` type accepts a type argument that indicates the type of the request body. This is useful for auto-completion and to avoid typing errors.
-
-To test it out, send the following request to your Medusa application:
-
-```bash
-curl -X POST 'http://localhost:9000/hello-world' \
--H 'Content-Type: application/json' \
---data-raw '{
- "name": "John"
-}'
-```
-
-This returns the following JSON object:
-
-```json
-{
- "message": "[POST] Hello John!"
-}
-```
-
-### Validate Body Parameters
-
-You can apply validation rules on received body parameters to ensure they match specified rules and types.
-
-Learn more in [this documentation](https://docs.medusajs.com/learn/fundamentals/api-routes/validation#how-to-validate-request-body/index.html.md).
-
-
-# Configure Request Body Parser
-
-In this chapter, you'll learn how to configure the request body parser for your API routes.
-
-## Default Body Parser Configuration
-
-The Medusa application configures the body parser by default to parse JSON, URL-encoded, and text request content types. You can parse other data types by adding the relevant [Express middleware](https://expressjs.com/en/guide/using-middleware.html) or preserve the raw body data by configuring the body parser, which is useful for webhook requests.
-
-This chapter shares some examples of configuring the body parser for different data types or use cases.
-
-***
-
-## Preserve Raw Body Data for Webhooks
-
-If your API route receives webhook requests, you might want to preserve the raw body data. To do this, you can configure the body parser to parse the raw body data and store it in the `req.rawBody` property.
-
-To do that, create the file `src/api/middlewares.ts` with the following content:
-
-```ts title="src/api/middlewares.ts" highlights={preserveHighlights}
-import { defineMiddlewares } from "@medusajs/framework/http"
-
-export default defineMiddlewares({
- routes: [
- {
- method: ["POST"],
- bodyParser: { preserveRawBody: true },
- matcher: "/custom",
- },
- ],
-})
-```
-
-The middleware route object passed to `routes` accepts a `bodyParser` property whose value is an object of configuration for the default body parser. By enabling the `preserveRawBody` property, the raw body data is preserved and stored in the `req.rawBody` property.
-
-Learn more about [middlewares](https://docs.medusajs.com/learn/fundamentals/api-routes/middlewares/index.html.md).
-
-You can then access the raw body data in your API route handler:
-
-```ts title="src/api/custom/route.ts"
-import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
-
-export async function POST(
- req: MedusaRequest,
- res: MedusaResponse
-) {
- console.log(req.rawBody)
-
- // TODO use raw body
-}
-```
-
-***
-
-## Configure Request Body Size Limit
-
-By default, the body parser limits the request body size to `100kb`. If a request body exceeds that size, the Medusa application throws an error.
-
-You can configure the body parser to accept larger request bodies by setting the `sizeLimit` property of the `bodyParser` object in a middleware route object. For example:
-
-```ts title="src/api/middlewares.ts" highlights={sizeLimitHighlights}
-import { defineMiddlewares } from "@medusajs/framework/http"
-
-export default defineMiddlewares({
- routes: [
- {
- method: ["POST"],
- bodyParser: { sizeLimit: "2mb" },
- matcher: "/custom",
- },
- ],
-})
-```
-
-The `sizeLimit` property accepts one of the following types of values:
-
-- A string representing the size limit in bytes (For example, `100kb`, `2mb`, `5gb`). It is passed to the [bytes](https://www.npmjs.com/package/bytes) library to parse the size.
-- A number representing the size limit in bytes. For example, `1024` for 1kb.
-
-***
-
-## Configure File Uploads
-
-To accept file uploads in your API routes, you can configure the [Express Multer middleware](https://expressjs.com/en/resources/middleware/multer.html) on your route.
-
-The `multer` package is available through the `@medusajs/medusa` package, so you don't need to install it. However, for better typing support, install the `@types/multer` package as a development dependency:
-
-```bash npm2yarn
-npm install --save-dev @types/multer
-```
-
-Then, to configure file upload for your route, create the file `src/api/middlewares.ts` with the following content:
-
-```ts title="src/api/middlewares.ts" highlights={uploadHighlights}
-import { defineMiddlewares } from "@medusajs/framework/http"
-import multer from "multer"
-
-const upload = multer({ storage: multer.memoryStorage() })
-
-export default defineMiddlewares({
- routes: [
- {
- method: ["POST"],
- matcher: "/custom",
- middlewares: [
- // @ts-ignore
- upload.array("files"),
- ],
- },
- ],
-})
-```
-
-In the example above, you configure the `multer` middleware to store the uploaded files in memory. Then, you apply the `upload.array("files")` middleware to the route to accept file uploads. By using the `array` method, you accept multiple file uploads with the same `files` field name.
-
-You can then access the uploaded files in your API route handler:
-
-```ts title="src/api/custom/route.ts"
-import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
-
-export async function POST(
- req: MedusaRequest,
- res: MedusaResponse
-) {
- const files = req.files as Express.Multer.File[]
-
- // TODO handle files
-}
-```
-
-The uploaded files are stored in the `req.files` property as an array of Multer file objects that have properties like `filename` and `mimetype`.
-
-### Uploading Files using File Module Provider
-
-The recommended way to upload the files to storage using the configured [File Module Provider](https://docs.medusajs.com/resources/infrastructure-modules/file/index.html.md) is to use the [uploadFilesWorkflow](https://docs.medusajs.com/resources/references/medusa-workflows/uploadFilesWorkflow/index.html.md):
-
-```ts title="src/api/custom/route.ts"
-import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
-import { MedusaError } from "@medusajs/framework/utils"
-import { uploadFilesWorkflow } from "@medusajs/medusa/core-flows"
-
-export async function POST(
- req: MedusaRequest,
- res: MedusaResponse
-) {
- const files = req.files as Express.Multer.File[]
-
- if (!files?.length) {
- throw new MedusaError(
- MedusaError.Types.INVALID_DATA,
- "No files were uploaded"
- )
- }
-
- const { result } = await uploadFilesWorkflow(req.scope).run({
- input: {
- files: files?.map((f) => ({
- filename: f.originalname,
- mimeType: f.mimetype,
- content: f.buffer.toString("binary"),
- access: "public",
- })),
- },
- })
-
- res.status(200).json({ files: result })
-}
-```
-
-Check out the [uploadFilesWorkflow reference](https://docs.medusajs.com/resources/references/medusa-workflows/uploadFilesWorkflow/index.html.md) for details on the expected input and output of the workflow.
-
-
-# API Route Response
-
-In this chapter, you'll learn how to send a response in your API route.
-
-## Send a JSON Response
-
-To send a JSON response, use the `json` method of the `MedusaResponse` object passed as the second parameter of your API route handler.
-
-For example:
-
-```ts title="src/api/custom/route.ts" highlights={jsonHighlights}
-import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
-
-export const GET = async (
- req: MedusaRequest,
- res: MedusaResponse
-) => {
- res.json({
- message: "Hello, World!",
- })
-}
-```
-
-This API route returns the following JSON object:
-
-```json
-{
- "message": "Hello, World!"
-}
-```
-
-***
-
-## Set Response Status Code
-
-By default, setting the JSON data using the `json` method returns a response with a `200` status code.
-
-To change the status code, use the `status` method of the `MedusaResponse` object.
-
-For example:
-
-```ts title="src/api/custom/route.ts" highlights={statusHighlight}
-import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
-
-export const GET = async (
- req: MedusaRequest,
- res: MedusaResponse
-) => {
- res.status(201).json({
- message: "Hello, World!",
- })
-}
-```
-
-The response of this API route has the status code `201`.
-
-***
-
-## Change Response Content Type
-
-To return response data other than a JSON object, use the `writeHead` method of the `MedusaResponse` object. It allows you to set the response headers, including the content type.
-
-For example, to create an API route that returns an event stream:
-
-```ts highlights={streamHighlights}
-import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
-
-export const GET = async (
- req: MedusaRequest,
- res: MedusaResponse
-) => {
- res.writeHead(200, {
- "Content-Type": "text/event-stream",
- "Cache-Control": "no-cache",
- Connection: "keep-alive",
- })
-
- const interval = setInterval(() => {
- res.write("Streaming data...\n")
- }, 3000)
-
- req.on("end", () => {
- clearInterval(interval)
- res.end()
- })
-}
-```
-
-The `writeHead` method accepts two parameters:
-
-1. The first one is the response's status code.
-2. The second is an object of key-value pairs to set the headers of the response.
-
-This API route opens a stream by setting the `Content-Type` in the header to `text/event-stream`. It then simulates a stream by creating an interval that writes the stream data every three seconds.
-
-***
-
-## Do More with Responses
-
-The `MedusaResponse` type is based on [Express's Response](https://expressjs.com/en/api.html#res). Refer to their API reference for other uses of responses.
-
-
-# Protected Routes
-
-In this chapter, you’ll learn how to create protected routes.
-
-## What is a Protected Route?
-
-A protected route is a route that requires requests to be user-authenticated before performing the route's functionality. Otherwise, the request fails, and the user is prevented access.
-
-***
-
-## Default Protected Routes
-
-Medusa applies an authentication guard on routes starting with `/admin`, including custom API routes.
-
-Requests to `/admin` must be user-authenticated to access the route.
-
-Refer to the API Reference for [Admin](https://docs.medusajs.com/api/admin#authentication) and [Store](https://docs.medusajs.com/api/store#authentication) authentication methods.
-
-***
-
-## Protect Custom API Routes
-
-To protect custom API Routes to only allow authenticated customer or admin users, use the `authenticate` middleware from the Medusa Framework.
-
-For example:
-
-```ts title="src/api/middlewares.ts" highlights={highlights}
-import {
- defineMiddlewares,
- authenticate,
-} from "@medusajs/framework/http"
-
-export default defineMiddlewares({
- routes: [
- {
- matcher: "/custom/admin*",
- middlewares: [authenticate("user", ["session", "bearer", "api-key"])],
- },
- {
- matcher: "/custom/customer*",
- middlewares: [authenticate("customer", ["session", "bearer"])],
- },
- ],
-})
-```
-
-The `authenticate` middleware function accepts three parameters:
-
-1. The type of user authenticating. Use `user` for authenticating admin users, and `customer` for authenticating customers. You can also pass `*` to allow all types of users, or pass an array of actor types.
-2. An array of types of authentication methods allowed. Both `user` and `customer` scopes support `session` and `bearer`. The `admin` scope also supports the `api-key` authentication method.
-3. An optional object of configurations accepting the following properties:
- - `allowUnauthenticated`: (default: `false`) A boolean indicating whether authentication is required. For example, you may have an API route where you want to access the logged-in customer if available, but guest customers can still access it too.
- - `allowUnregistered` (default: `false`): A boolean indicating if unregistered users should be allowed access. This is useful when you want to allow users who aren’t registered to access certain routes.
-
-### Example: Custom Actor Type
-
-For example, to require authentication of a custom actor type `manager` to an API route:
-
-```ts title="src/api/middlewares.ts"
-import {
- defineMiddlewares,
- authenticate,
-} from "@medusajs/framework/http"
-
-export default defineMiddlewares({
- routes: [
- {
- matcher: "/manager*",
- middlewares: [authenticate("manager", ["session", "bearer"])],
- },
- ],
-})
-```
-
-Refer to the [Custom Actor-Type Guide](https://docs.medusajs.com/resources/commerce-modules/auth/create-actor-type/index.html.md) for detailed explanation on how to create a custom actor type and apply authentication middlewares.
-
-### Example: Allow Multiple Actor Types
-
-To allow multiple actor types to access an API route, pass an array of actor types to the `authenticate` middleware:
-
-```ts title="src/api/middlewares.ts"
-import {
- defineMiddlewares,
- authenticate,
-} from "@medusajs/framework/http"
-
-export default defineMiddlewares({
- routes: [
- {
- matcher: "/custom*",
- middlewares: [authenticate(["user", "customer"], ["session", "bearer"])],
- },
- ],
-})
-```
-
-***
-
-## Authentication Opt-Out
-
-To disable the authentication guard on custom routes under the `/admin` path prefix, export an `AUTHENTICATE` variable in the route file with its value set to `false`.
-
-For example:
-
-```ts title="src/api/admin/custom/route.ts" highlights={[["15"]]}
-import type {
- AuthenticatedMedusaRequest,
- MedusaResponse,
-} from "@medusajs/framework/http"
-
-export const GET = async (
- req: AuthenticatedMedusaRequest,
- res: MedusaResponse
-) => {
- res.json({
- message: "Hello",
- })
-}
-
-export const AUTHENTICATE = false
-```
-
-Now, any request sent to the `/admin/custom` API route is allowed, regardless if the admin user is authenticated.
-
-***
-
-## Authenticated Request Type
-
-To access the authentication details in an API route, such as the logged-in user's ID, set the type of the first request parameter to `AuthenticatedMedusaRequest`. It extends `MedusaRequest`.
-
-The `auth_context.actor_id` property of `AuthenticatedMedusaRequest` holds the ID of the authenticated user or customer. If there isn't any authenticated user or customer, `auth_context` is `undefined`.
-
-If you opt-out of authentication in a route as mentioned in the [previous section](#authentication-opt-out), you can't access the authenticated user or customer anymore. Use the [authenticate middleware](#protect-custom-api-routes) instead.
-
-### Retrieve Logged-In Customer's Details
-
-You can access the logged-in customer’s ID in all API routes starting with `/store` using the `auth_context.actor_id` property of the `AuthenticatedMedusaRequest` object.
-
-For example:
-
-```ts title="src/api/store/custom/route.ts" highlights={[["19", "req.auth_context.actor_id", "Access the logged-in customer's ID."]]} collapsibleLines="1-7" expandButtonLabel="Show Imports"
-import type {
- AuthenticatedMedusaRequest,
- MedusaResponse,
-} from "@medusajs/framework/http"
-import { Modules } from "@medusajs/framework/utils"
-import { ICustomerModuleService } from "@medusajs/framework/types"
-
-export const GET = async (
- req: AuthenticatedMedusaRequest,
- res: MedusaResponse
-) => {
- if (req.auth_context?.actor_id) {
- // retrieve customer
- const customerModuleService: ICustomerModuleService = req.scope.resolve(
- Modules.CUSTOMER
- )
-
- const customer = await customerModuleService.retrieveCustomer(
- req.auth_context.actor_id
- )
- }
-
- // ...
-}
-```
-
-In this example, you resolve the Customer Module's main service, then use it to retrieve the logged-in customer, if available.
-
-### Retrieve Logged-In Admin User's Details
-
-You can access the logged-in admin user’s ID in all API Routes starting with `/admin` using the `auth_context.actor_id` property of the `AuthenticatedMedusaRequest` object.
-
-For example:
-
-```ts title="src/api/admin/custom/route.ts" highlights={[["17", "req.auth_context.actor_id", "Access the logged-in admin user's ID."]]} collapsibleLines="1-7" expandButtonLabel="Show Imports"
-import type {
- AuthenticatedMedusaRequest,
- MedusaResponse,
-} from "@medusajs/framework/http"
-import { Modules } from "@medusajs/framework/utils"
-import { IUserModuleService } from "@medusajs/framework/types"
-
-export const GET = async (
- req: AuthenticatedMedusaRequest,
- res: MedusaResponse
-) => {
- const userModuleService: IUserModuleService = req.scope.resolve(
- Modules.USER
- )
-
- const user = await userModuleService.retrieveUser(
- req.auth_context.actor_id
- )
-
- // ...
-}
-```
-
-In the route handler, you resolve the User Module's main service, then use it to retrieve the logged-in admin user.
-
-
-# Handling CORS in API Routes
-
-In this chapter, you’ll learn about the CORS middleware and how to configure it for custom API routes.
-
-## CORS Overview
-
-Cross-Origin Resource Sharing (CORS) allows only configured origins to access your API Routes.
-
-For example, if you allow only origins starting with `http://localhost:7001` to access your Admin API Routes, other origins accessing those routes get a CORS error.
-
-### CORS Configurations
-
-The `storeCors` and `adminCors` properties of Medusa's `http` configuration set the allowed origins for routes starting with `/store` and `/admin` respectively.
-
-These configurations accept a URL pattern to identify allowed origins.
-
-For example:
-
-```js title="medusa-config.ts"
-module.exports = defineConfig({
- projectConfig: {
- http: {
- storeCors: "http://localhost:8000",
- adminCors: "http://localhost:7001",
- // ...
- },
- },
-})
-```
-
-This allows the `http://localhost:7001` origin to access the Admin API Routes, and the `http://localhost:8000` origin to access Store API Routes.
-
-Learn more about the CORS configurations in [this resource guide](https://docs.medusajs.com/learn/configurations/medusa-config#http/index.html.md).
-
-***
-
-## CORS in Store and Admin Routes
-
-To disable the CORS middleware for a route, export a `CORS` variable in the route file with its value set to `false`.
-
-For example:
-
-```ts title="src/api/store/custom/route.ts" highlights={[["15"]]}
-import type {
- MedusaRequest,
- MedusaResponse,
-} from "@medusajs/framework/http"
-
-export const GET = (
- req: MedusaRequest,
- res: MedusaResponse
-) => {
- res.json({
- message: "[GET] Hello world!",
- })
-}
-
-export const CORS = false
-```
-
-This disables the CORS middleware on API Routes at the path `/store/custom`.
-
-***
-
-## CORS in Custom Routes
-
-If you create a route that doesn’t start with `/store` or `/admin`, you must apply the CORS middleware manually. Otherwise, all requests to your API route lead to a CORS error.
-
-You can do that in the exported middlewares configurations in `src/api/middlewares.ts`.
-
-For example:
-
-```ts title="src/api/middlewares.ts" highlights={highlights} collapsibleLines="1-10" expandButtonLabel="Show Imports"
-import { defineMiddlewares } from "@medusajs/framework/http"
-import type {
- MedusaNextFunction,
- MedusaRequest,
- MedusaResponse,
-} from "@medusajs/framework/http"
-import { ConfigModule } from "@medusajs/framework/types"
-import { parseCorsOrigins } from "@medusajs/framework/utils"
-import cors from "cors"
-
-export default defineMiddlewares({
- routes: [
- {
- matcher: "/custom*",
- middlewares: [
- (
- req: MedusaRequest,
- res: MedusaResponse,
- next: MedusaNextFunction
- ) => {
- const configModule: ConfigModule =
- req.scope.resolve("configModule")
-
- return cors({
- origin: parseCorsOrigins(
- configModule.projectConfig.http.storeCors
- ),
- credentials: true,
- })(req, res, next)
- },
- ],
- },
- ],
-})
-```
-
-This retrieves the configurations exported from `medusa-config.ts` and applies the `storeCors` to routes starting with `/custom`.
-
-
-# Retrieve Custom Links from Medusa's API Route
-
-In this chapter, you'll learn how to retrieve custom data models linked to existing Medusa data models from Medusa's API routes.
-
-## Why Retrieve Custom Linked Data Models?
-
-Often, you'll link custom data models to existing Medusa data models to implement custom features or expand on existing ones.
-
-For example, to add brands for products, you can create a `Brand` data model in a Brand Module, then [define a link](https://docs.medusajs.com/learn/fundamentals/module-links/index.html.md) to the [Product Module](https://docs.medusajs.com/resources/commerce-modules/product/index.html.md)'s `Product` data model.
-
-When you implement this customization, you might need to retrieve the brand of a product using the existing [Get Product API Route](https://docs.medusajs.com/api/admin#products_getproductsid). You can do this by passing the linked data model's name in the `fields` query parameter of the API route.
-
-***
-
-## How to Retrieve Custom Linked Data Models Using `fields`?
-
-Most of Medusa's API routes accept a `fields` query parameter that allows you to specify the fields and relations to retrieve in the resource, such as a product.
-
-For example, to retrieve the brand of a product, you can pass the `brand` field in the `fields` query parameter of the [Get Product API Route](https://docs.medusajs.com/api/admin#products_getproductsid):
-
-```bash
-curl 'http://localhost:9000/admin/products/{id}?fields=*brand' \
--H 'Authorization: Bearer {access_token}'
-```
-
-The `fields` query parameter accepts a comma-separated list of fields and relations to retrieve. To learn more about using the `fields` query parameter, refer to the [API Reference](https://docs.medusajs.com/api/store#select-fields-and-relations).
-
-By prefixing `brand` with an asterisk (`*`), you retrieve all the default fields of the product, including the `brand` field. If you don't include the `*` prefix, the response will only include the product's brand.
-
-***
-
-## API Routes that Restrict Retrievable Fields
-
-Some of Medusa's API routes restrict the fields and relations you can retrieve, which means you can't pass your custom linked data models in the `fields` query parameter. Medusa makes this restriction to ensure the API routes are performant and secure.
-
-The API routes that restrict the fields and relations you can retrieve are:
-
-- [Customer Store API Routes](https://docs.medusajs.com/api/store#customers)
-- [Customer Admin API Routes](https://docs.medusajs.com/api/admin#customers)
-- [Product Category Admin API Routes](https://docs.medusajs.com/api/admin#product-categories)
-
-### How to Override Allowed Fields and Relations
-
-For these routes, you need to override the allowed fields and relations to be retrieved. You can do this by adding a [middleware](https://docs.medusajs.com/learn/fundamentals/api-routes/middlewares/index.html.md) to those routes.
-
-For example, to allow retrieving the `b2b_company` of a customer using the [Get Customer Admin API Route](https://docs.medusajs.com/api/admin#customers_getcustomersid), create the file `src/api/middlewares.ts` with the following content:
-
-Learn how to create a middleware in the [Middlewares](https://docs.medusajs.com/learn/fundamentals/api-routes/middlewares/index.html.md) chapter.
-
-```ts title="src/api/middlewares.ts" highlights={highlights}
-import { defineMiddlewares } from "@medusajs/medusa"
-
-export default defineMiddlewares({
- routes: [
- {
- matcher: "/store/customers/me",
- method: "GET",
- middlewares: [
- (req, res, next) => {
- req.allowed?.push("b2b_company")
- next()
- },
- ],
- },
- ],
-})
-```
-
-In this example, you apply a middleware to the [Get Customer Admin API Route](https://docs.medusajs.com/api/admin#customers_getcustomersid).
-
-The request object passed to middlewares has an `allowed` property that contains the fields and relations that can be retrieved. So, you modify the `allowed` array to include the `b2b_company` field.
-
-You can now retrieve the `b2b_company` field using the `fields` query parameter of the [Get Customer Admin API Route](https://docs.medusajs.com/api/admin#customers_getcustomersid):
-
-```bash
-curl 'http://localhost:9000/admin/customers/{id}?fields=*b2b_company' \
--H 'Authorization: Bearer {access_token}'
-```
-
-In this example, you retrieve the `b2b_company` relation of the customer using the `fields` query parameter.
-
-
-# Request Body and Query Parameter Validation
-
-In this chapter, you'll learn how to validate request body and query parameters in your custom API route.
-
-## Request Validation
-
-Consider you're creating a `POST` API route at `/custom`. It accepts two parameters `a` and `b` that are required numbers, and returns their sum.
-
-Medusa provides two middlewares to validate the request body and query paramters of incoming requests to your custom API routes:
-
-- `validateAndTransformBody` to validate the request's body parameters against a schema.
-- `validateAndTransformQuery` to validate the request's query parameters against a schema.
-
-Both middlewares accept a [Zod](https://zod.dev/) schema as a parameter, which gives you flexibility in how you define your validation schema with complex rules.
-
-The next steps explain how to add request body and query parameter validation to the API route mentioned earlier.
-
-***
-
-## How to Validate Request Body
-
-### Step 1: Create Validation Schema
-
-Medusa uses [Zod](https://zod.dev/) to create validation schemas. These schemas are then used to validate incoming request bodies or query parameters.
-
-To create a validation schema with Zod, create a `validators.ts` file in any `src/api` subfolder. This file holds Zod schemas for each of your API routes.
-
-For example, create the file `src/api/custom/validators.ts` with the following content:
-
-```ts title="src/api/custom/validators.ts"
-import { z } from "zod"
-
-export const PostStoreCustomSchema = z.object({
- a: z.number(),
- b: z.number(),
-})
-```
-
-The `PostStoreCustomSchema` variable is a Zod schema that indicates the request body is valid if:
-
-1. It's an object.
-2. It has a property `a` that is a required number.
-3. It has a property `b` that is a required number.
-
-### Step 2: Add Request Body Validation Middleware
-
-To use this schema for validating the body parameters of requests to `/custom`, use the `validateAndTransformBody` middleware provided by `@medusajs/framework/http`. It accepts the Zod schema as a parameter.
-
-For example, create the file `src/api/middlewares.ts` with the following content:
-
-```ts title="src/api/middlewares.ts"
-import {
- defineMiddlewares,
- validateAndTransformBody,
-} from "@medusajs/framework/http"
-import { PostStoreCustomSchema } from "./custom/validators"
-
-export default defineMiddlewares({
- routes: [
- {
- matcher: "/custom",
- method: "POST",
- middlewares: [
- validateAndTransformBody(PostStoreCustomSchema),
- ],
- },
- ],
-})
-```
-
-This applies the `validateAndTransformBody` middleware on `POST` requests to `/custom`. It uses the `PostStoreCustomSchema` as the validation schema.
-
-#### How the Validation Works
-
-If a request's body parameters don't pass the validation, the `validateAndTransformBody` middleware throws an error indicating the validation errors.
-
-If a request's body parameters are validated successfully, the middleware sets the validated body parameters in the `validatedBody` property of `MedusaRequest`.
-
-### Step 3: Use Validated Body in API Route
-
-In your API route, consume the validated body using the `validatedBody` property of `MedusaRequest`.
-
-For example, create the file `src/api/custom/route.ts` with the following content:
-
-```ts title="src/api/custom/route.ts" highlights={routeHighlights}
-import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
-import { z } from "zod"
-import { PostStoreCustomSchema } from "./validators"
-
-type PostStoreCustomSchemaType = z.infer<
- typeof PostStoreCustomSchema
->
-
-export const POST = async (
- req: MedusaRequest,
- res: MedusaResponse
-) => {
- res.json({
- sum: req.validatedBody.a + req.validatedBody.b,
- })
-}
-```
-
-In the API route, you use the `validatedBody` property of `MedusaRequest` to access the values of the `a` and `b` properties.
-
-To pass the request body's type as a type parameter to `MedusaRequest`, use Zod's `infer` type that accepts the type of a schema as a parameter.
-
-### Test it Out
-
-To test out the validation, send a `POST` request to `/custom` passing `a` and `b` body parameters. You can try sending incorrect request body parameters to test out the validation.
-
-For example, if you omit the `a` parameter, you'll receive a `400` response code with the following response data:
-
-```json
-{
- "type": "invalid_data",
- "message": "Invalid request: Field 'a' is required"
-}
-```
-
-***
-
-## How to Validate Request Query Parameters
-
-The steps to validate the request query parameters are the similar to that of [validating the body](#how-to-validate-request-body).
-
-### Step 1: Create Validation Schema
-
-The first step is to create a schema with Zod with the rules of the accepted query parameters.
-
-Consider that the API route accepts two query parameters `a` and `b` that are numbers, similar to the previous section.
-
-Create the file `src/api/custom/validators.ts` with the following content:
-
-```ts title="src/api/custom/validators.ts"
-import { z } from "zod"
-
-export const PostStoreCustomSchema = z.object({
- a: z.preprocess(
- (val) => {
- if (val && typeof val === "string") {
- return parseInt(val)
- }
- return val
- },
- z
- .number()
- ),
- b: z.preprocess(
- (val) => {
- if (val && typeof val === "string") {
- return parseInt(val)
- }
- return val
- },
- z
- .number()
- ),
-})
-```
-
-Since a query parameter's type is originally a string or array of strings, you have to use Zod's `preprocess` method to validate other query types, such as numbers.
-
-For both `a` and `b`, you transform the query parameter's value to an integer first if it's a string, then, you check that the resulting value is a number.
-
-### Step 2: Add Request Query Validation Middleware
-
-Next, you'll use the schema to validate incoming requests' query parameters to the `/custom` API route.
-
-Add the `validateAndTransformQuery` middleware to the API route in the file `src/api/middlewares.ts`:
-
-```ts title="src/api/middlewares.ts"
-import {
- validateAndTransformQuery,
- defineMiddlewares,
-} from "@medusajs/framework/http"
-import { PostStoreCustomSchema } from "./custom/validators"
-
-export default defineMiddlewares({
- routes: [
- {
- matcher: "/custom",
- method: "POST",
- middlewares: [
- validateAndTransformQuery(
- PostStoreCustomSchema,
- {}
- ),
- ],
- },
- ],
-})
-```
-
-The `validateAndTransformQuery` accepts two parameters:
-
-- The first one is the Zod schema to validate the query parameters against.
-- The second one is an object of options for retrieving data using Query, which you can learn more about in [this chapter](https://docs.medusajs.com/learn/fundamentals/module-links/query/index.html.md).
-
-#### How the Validation Works
-
-If a request's query parameters don't pass the validation, the `validateAndTransformQuery` middleware throws an error indicating the validation errors.
-
-If a request's query parameters are validated successfully, the middleware sets the validated query parameters in the `validatedQuery` property of `MedusaRequest`.
-
-### Step 3: Use Validated Query in API Route
-
-Finally, use the validated query in the API route. The `MedusaRequest` parameter has a `validatedQuery` parameter that you can use to access the validated parameters.
-
-For example, create the file `src/api/custom/route.ts` with the following content:
-
-```ts title="src/api/custom/route.ts"
-import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
-
-export const GET = async (
- req: MedusaRequest,
- res: MedusaResponse
-) => {
- const a = req.validatedQuery.a as number
- const b = req.validatedQuery.b as number
-
- res.json({
- sum: a + b,
- })
-}
-```
-
-In the API route, you use the `validatedQuery` property of `MedusaRequest` to access the values of the `a` and `b` properties as numbers, then return in the response their sum.
-
-### Test it Out
-
-To test out the validation, send a `POST` request to `/custom` with `a` and `b` query parameters. You can try sending incorrect query parameters to see how the validation works.
-
-For example, if you omit the `a` parameter, you'll receive a `400` response code with the following response data:
-
-```json
-{
- "type": "invalid_data",
- "message": "Invalid request: Field 'a' is required"
-}
-```
-
-***
-
-## Learn More About Validation Schemas
-
-To see different examples and learn more about creating a validation schema, refer to [Zod's documentation](https://zod.dev).
-
-
-# Add Data Model Check Constraints
-
-In this chapter, you'll learn how to add check constraints to your data model.
-
-## What is a Check Constraint?
-
-A check constraint is a condition that must be satisfied by records inserted into a database table, otherwise an error is thrown.
-
-For example, if you have a data model with a `price` property, you want to only allow positive number values. So, you add a check constraint that fails when inserting a record with a negative price value.
-
-***
-
-## How to Set a Check Constraint?
-
-To set check constraints on a data model, use the `checks` method. This method accepts an array of check constraints to apply on the data model.
-
-For example, to set a check constraint on a `price` property that ensures its value can only be a positive number:
-
-```ts highlights={checks1Highlights}
-import { model } from "@medusajs/framework/utils"
-
-const CustomProduct = model.define("custom_product", {
- // ...
- price: model.bigNumber(),
-})
-.checks([
- (columns) => `${columns.price} >= 0`,
-])
-```
-
-The item passed in the array parameter of `checks` can be a callback function that accepts as a parameter an object whose keys are the names of the properties in the data model schema, and values the respective column name in the database.
-
-The function returns a string indicating the [SQL check constraint expression](https://www.postgresql.org/docs/current/ddl-constraints.html#DDL-CONSTRAINTS-CHECK-CONSTRAINTS). In the expression, use the `columns` parameter to access a property's column name.
-
-You can also pass an object to the `checks` method:
-
-```ts highlights={checks2Highlights}
-import { model } from "@medusajs/framework/utils"
-
-const CustomProduct = model.define("custom_product", {
- // ...
- price: model.bigNumber(),
-})
-.checks([
- {
- name: "custom_product_price_check",
- expression: (columns) => `${columns.price} >= 0`,
- },
-])
-```
-
-The object accepts the following properties:
-
-- `name`: The check constraint's name.
-- `expression`: A function similar to the one that can be passed to the array. It accepts an object of columns and returns an [SQL check constraint expression](https://www.postgresql.org/docs/current/ddl-constraints.html#DDL-CONSTRAINTS-CHECK-CONSTRAINTS).
-
-***
-
-## Apply in Migrations
-
-After adding the check constraint, make sure to generate and run migrations if you already have the table in the database. Otherwise, the check constraint won't be reflected.
-
-To generate a migration for the data model's module then reflect it on the database, run the following command:
-
-```bash
-npx medusa db:generate custom_module
-npx medusa db:migrate
-```
-
-The first command generates the migration under the `migrations` directory of your module's directory, and the second reflects it on the database.
-
-
# Data Model Database Index
In this chapter, you’ll learn how to define a database index on a data model.
@@ -10752,6 +9180,205 @@ The `cascades` method accepts an object. Its key is the operation’s name, such
In the example above, when a store is deleted, its associated products are also deleted.
+# Pass Additional Data to Medusa's API Route
+
+In this chapter, you'll learn how to pass additional data in requests to Medusa's API Route.
+
+## Why Pass Additional Data?
+
+Some of Medusa's API Routes accept an `additional_data` parameter whose type is an object. The API Route passes the `additional_data` to the workflow, which in turn passes it to its hooks.
+
+This is useful when you have a link from your custom module to a Commerce Module, and you want to perform an additional action when a request is sent to an existing API route.
+
+For example, the [Create Product API Route](https://docs.medusajs.com/api/admin#products_postproducts) accepts an `additional_data` parameter. If you have a data model linked to it, you consume the `productsCreated` hook to create a record of the data model using the custom data and link it to the product.
+
+### API Routes Accepting Additional Data
+
+### API Routes List
+
+- Campaigns
+ - [Create Campaign](https://docs.medusajs.com/api/admin#campaigns_postcampaigns)
+ - [Update Campaign](https://docs.medusajs.com/api/admin#campaigns_postcampaignsid)
+- Cart
+ - [Create Cart](https://docs.medusajs.com/api/store#carts_postcarts)
+ - [Update Cart](https://docs.medusajs.com/api/store#carts_postcartsid)
+- Collections
+ - [Create Collection](https://docs.medusajs.com/api/admin#collections_postcollections)
+ - [Update Collection](https://docs.medusajs.com/api/admin#collections_postcollectionsid)
+- Customers
+ - [Create Customer](https://docs.medusajs.com/api/admin#customers_postcustomers)
+ - [Update Customer](https://docs.medusajs.com/api/admin#customers_postcustomersid)
+ - [Create Address](https://docs.medusajs.com/api/admin#customers_postcustomersidaddresses)
+ - [Update Address](https://docs.medusajs.com/api/admin#customers_postcustomersidaddressesaddress_id)
+- Draft Orders
+ - [Create Draft Order](https://docs.medusajs.com/api/admin#draft-orders_postdraftorders)
+- Orders
+ - [Complete Orders](https://docs.medusajs.com/api/admin#orders_postordersidcomplete)
+ - [Cancel Order's Fulfillment](https://docs.medusajs.com/api/admin#orders_postordersidfulfillmentsfulfillment_idcancel)
+ - [Create Shipment](https://docs.medusajs.com/api/admin#orders_postordersidfulfillmentsfulfillment_idshipments)
+ - [Create Fulfillment](https://docs.medusajs.com/api/admin#orders_postordersidfulfillments)
+- Products
+ - [Create Product](https://docs.medusajs.com/api/admin#products_postproducts)
+ - [Update Product](https://docs.medusajs.com/api/admin#products_postproductsid)
+ - [Create Product Variant](https://docs.medusajs.com/api/admin#products_postproductsidvariants)
+ - [Update Product Variant](https://docs.medusajs.com/api/admin#products_postproductsidvariantsvariant_id)
+ - [Create Product Option](https://docs.medusajs.com/api/admin#products_postproductsidoptions)
+ - [Update Product Option](https://docs.medusajs.com/api/admin#products_postproductsidoptionsoption_id)
+- Product Tags
+ - [Create Product Tag](https://docs.medusajs.com/api/admin#product-tags_postproducttags)
+ - [Update Product Tag](https://docs.medusajs.com/api/admin#product-tags_postproducttagsid)
+- Product Types
+ - [Create Product Type](https://docs.medusajs.com/api/admin#product-types_postproducttypes)
+ - [Update Product Type](https://docs.medusajs.com/api/admin#product-types_postproducttypesid)
+- Promotions
+ - [Create Promotion](https://docs.medusajs.com/api/admin#promotions_postpromotions)
+ - [Update Promotion](https://docs.medusajs.com/api/admin#promotions_postpromotionsid)
+
+***
+
+## How to Pass Additional Data
+
+### 1. Specify Validation of Additional Data
+
+Before passing custom data in the `additional_data` object parameter, you must specify validation rules for the allowed properties in the object.
+
+To do that, use the middleware route object defined in `src/api/middlewares.ts`.
+
+For example, create the file `src/api/middlewares.ts` with the following content:
+
+```ts title="src/api/middlewares.ts"
+import { defineMiddlewares } from "@medusajs/framework/http"
+import { z } from "zod"
+
+export default defineMiddlewares({
+ routes: [
+ {
+ method: "POST",
+ matcher: "/admin/products",
+ additionalDataValidator: {
+ brand: z.string().optional(),
+ },
+ },
+ ],
+})
+```
+
+The middleware route object accepts an optional parameter `additionalDataValidator` whose value is an object of key-value pairs. The keys indicate the name of accepted properties in the `additional_data` parameter, and the value is [Zod](https://zod.dev/) validation rules of the property.
+
+In this example, you indicate that the `additional_data` parameter accepts a `brand` property whose value is an optional string.
+
+Refer to [Zod's documentation](https://zod.dev) for all available validation rules.
+
+### 2. Pass the Additional Data in a Request
+
+You can now pass a `brand` property in the `additional_data` parameter of a request to the Create Product API Route.
+
+For example:
+
+```bash
+curl -X POST 'http://localhost:9000/admin/products' \
+-H 'Content-Type: application/json' \
+-H 'Authorization: Bearer {token}' \
+--data '{
+ "title": "Product 1",
+ "options": [
+ {
+ "title": "Default option",
+ "values": ["Default option value"]
+ }
+ ],
+ "shipping_profile_id": "{shipping_profile_id}",
+ "additional_data": {
+ "brand": "Acme"
+ }
+}'
+```
+
+Make sure to replace the `{token}` in the authorization header with an admin user's authentication token, and `{shipping_profile_id}` with an existing shipping profile's ID.
+
+In this request, you pass in the `additional_data` parameter a `brand` property and set its value to `Acme`.
+
+The `additional_data` is then passed to hooks in the `createProductsWorkflow` used by the API route.
+
+***
+
+## Use Additional Data in a Hook
+
+Learn about workflow hooks in [this guide](https://docs.medusajs.com/learn/fundamentals/workflows/workflow-hooks/index.html.md).
+
+Step functions consuming the workflow hook can access the `additional_data` in the first parameter.
+
+For example, consider you want to store the data passed in `additional_data` in the product's `metadata` property.
+
+To do that, create the file `src/workflows/hooks/product-created.ts` with the following content:
+
+```ts title="src/workflows/hooks/product-created.ts"
+import { StepResponse } from "@medusajs/framework/workflows-sdk"
+import { createProductsWorkflow } from "@medusajs/medusa/core-flows"
+import { Modules } from "@medusajs/framework/utils"
+
+createProductsWorkflow.hooks.productsCreated(
+ async ({ products, additional_data }, { container }) => {
+ if (!additional_data?.brand) {
+ return
+ }
+
+ const productModuleService = container.resolve(
+ Modules.PRODUCT
+ )
+
+ await productModuleService.upsertProducts(
+ products.map((product) => ({
+ ...product,
+ metadata: {
+ ...product.metadata,
+ brand: additional_data.brand,
+ },
+ }))
+ )
+
+ return new StepResponse(products, {
+ products,
+ additional_data,
+ })
+ }
+)
+```
+
+This consumes the `productsCreated` hook, which runs after the products are created.
+
+If `brand` is passed in `additional_data`, you resolve the Product Module's main service and use its `upsertProducts` method to update the products, adding the brand to the `metadata` property.
+
+### Compensation Function
+
+Hooks also accept a compensation function as a second parameter to undo the actions made by the step function.
+
+For example, pass the following second parameter to the `productsCreated` hook:
+
+```ts title="src/workflows/hooks/product-created.ts"
+createProductsWorkflow.hooks.productsCreated(
+ async ({ products, additional_data }, { container }) => {
+ // ...
+ },
+ async ({ products, additional_data }, { container }) => {
+ if (!additional_data.brand) {
+ return
+ }
+
+ const productModuleService = container.resolve(
+ Modules.PRODUCT
+ )
+
+ await productModuleService.upsertProducts(
+ products
+ )
+ }
+)
+```
+
+This updates the products to their original state before adding the brand to their `metadata` property.
+
+
# Migrations
In this chapter, you'll learn what a migration is and how to generate a migration or write it manually.
@@ -10850,6 +9477,1758 @@ So, always rollback the migration before deleting it.
To learn more about the Medusa CLI's database commands, refer to [this CLI reference](https://docs.medusajs.com/resources/medusa-cli/commands/db/index.html.md).
+# Handling CORS in API Routes
+
+In this chapter, you’ll learn about the CORS middleware and how to configure it for custom API routes.
+
+## CORS Overview
+
+Cross-Origin Resource Sharing (CORS) allows only configured origins to access your API Routes.
+
+For example, if you allow only origins starting with `http://localhost:7001` to access your Admin API Routes, other origins accessing those routes get a CORS error.
+
+### CORS Configurations
+
+The `storeCors` and `adminCors` properties of Medusa's `http` configuration set the allowed origins for routes starting with `/store` and `/admin` respectively.
+
+These configurations accept a URL pattern to identify allowed origins.
+
+For example:
+
+```js title="medusa-config.ts"
+module.exports = defineConfig({
+ projectConfig: {
+ http: {
+ storeCors: "http://localhost:8000",
+ adminCors: "http://localhost:7001",
+ // ...
+ },
+ },
+})
+```
+
+This allows the `http://localhost:7001` origin to access the Admin API Routes, and the `http://localhost:8000` origin to access Store API Routes.
+
+Learn more about the CORS configurations in [this resource guide](https://docs.medusajs.com/learn/configurations/medusa-config#http/index.html.md).
+
+***
+
+## CORS in Store and Admin Routes
+
+To disable the CORS middleware for a route, export a `CORS` variable in the route file with its value set to `false`.
+
+For example:
+
+```ts title="src/api/store/custom/route.ts" highlights={[["15"]]}
+import type {
+ MedusaRequest,
+ MedusaResponse,
+} from "@medusajs/framework/http"
+
+export const GET = (
+ req: MedusaRequest,
+ res: MedusaResponse
+) => {
+ res.json({
+ message: "[GET] Hello world!",
+ })
+}
+
+export const CORS = false
+```
+
+This disables the CORS middleware on API Routes at the path `/store/custom`.
+
+***
+
+## CORS in Custom Routes
+
+If you create a route that doesn’t start with `/store` or `/admin`, you must apply the CORS middleware manually. Otherwise, all requests to your API route lead to a CORS error.
+
+You can do that in the exported middlewares configurations in `src/api/middlewares.ts`.
+
+For example:
+
+```ts title="src/api/middlewares.ts" highlights={highlights} collapsibleLines="1-10" expandButtonLabel="Show Imports"
+import { defineMiddlewares } from "@medusajs/framework/http"
+import type {
+ MedusaNextFunction,
+ MedusaRequest,
+ MedusaResponse,
+} from "@medusajs/framework/http"
+import { ConfigModule } from "@medusajs/framework/types"
+import { parseCorsOrigins } from "@medusajs/framework/utils"
+import cors from "cors"
+
+export default defineMiddlewares({
+ routes: [
+ {
+ matcher: "/custom*",
+ middlewares: [
+ (
+ req: MedusaRequest,
+ res: MedusaResponse,
+ next: MedusaNextFunction
+ ) => {
+ const configModule: ConfigModule =
+ req.scope.resolve("configModule")
+
+ return cors({
+ origin: parseCorsOrigins(
+ configModule.projectConfig.http.storeCors
+ ),
+ credentials: true,
+ })(req, res, next)
+ },
+ ],
+ },
+ ],
+})
+```
+
+This retrieves the configurations exported from `medusa-config.ts` and applies the `storeCors` to routes starting with `/custom`.
+
+
+# Middlewares
+
+In this chapter, you’ll learn about middlewares and how to create them.
+
+## What is a Middleware?
+
+A middleware is a function executed when a request is sent to an API Route. It's executed before the route handler function.
+
+Middlewares are used to guard API routes, parse request content types other than `application/json`, manipulate request data, and more.
+
+
+
+As Medusa's server is based on Express, you can use any [Express middleware](https://expressjs.com/en/resources/middleware.html).
+
+### Middleware Types
+
+There are two types of middlewares:
+
+|Type|Description|Example|
+|---|---|---|
+|Global Middleware|A middleware that applies to all routes matching a specified pattern.|\`/custom\*\`|
+|Route Middleware|A middleware that applies to routes matching a specified pattern and HTTP method(s).|A middleware that applies to all |
+
+These middlewares generally have the same definition and usage, but they differ in the routes they apply to. You'll learn how to create both types in the following sections.
+
+***
+
+## How to Create a Middleware?
+
+Middlewares of all types are defined in the special file `src/api/middlewares.ts`. Use the `defineMiddlewares` function from the Medusa Framework to define the middlewares, and export its value.
+
+For example:
+
+### Global Middleware
+
+```ts title="src/api/middlewares.ts"
+import {
+ defineMiddlewares,
+ MedusaNextFunction,
+ MedusaRequest,
+ MedusaResponse,
+} from "@medusajs/framework/http"
+
+export default defineMiddlewares({
+ routes: [
+ {
+ matcher: "/custom*",
+ middlewares: [
+ (
+ req: MedusaRequest,
+ res: MedusaResponse,
+ next: MedusaNextFunction
+ ) => {
+ console.log("Received a request!")
+
+ next()
+ },
+ ],
+ },
+ ],
+})
+```
+
+### Route Middleware
+
+```ts title="src/api/middlewares.ts" highlights={highlights}
+import {
+ defineMiddlewares,
+ MedusaNextFunction,
+ MedusaRequest,
+ MedusaResponse,
+} from "@medusajs/framework/http"
+
+export default defineMiddlewares({
+ routes: [
+ {
+ matcher: "/custom*",
+ method: ["POST", "PUT"],
+ middlewares: [
+ (
+ req: MedusaRequest,
+ res: MedusaResponse,
+ next: MedusaNextFunction
+ ) => {
+ console.log("Received a request!")
+
+ next()
+ },
+ ],
+ },
+ ],
+})
+```
+
+The `defineMiddlewares` function accepts a middleware configurations object that has the property `routes`. `routes`'s value is an array of middleware route objects, each having the following properties:
+
+- `matcher`: a string or regular expression indicating the API route path to apply the middleware on. The regular expression must be compatible with [path-to-regexp](https://github.com/pillarjs/path-to-regexp).
+- `middlewares`: An array of global and route middleware functions.
+- `method`: (optional) By default, a middleware is applied on all HTTP methods for a route. You can specify one or more HTTP methods to apply the middleware to in this option, making it a route middleware.
+
+### Test the Middleware
+
+To test the middleware:
+
+1. Start the application:
+
+```bash npm2yarn
+npm run dev
+```
+
+2. Send a request to any API route starting with `/custom`. If you specified an HTTP method in the `method` property, make sure to use that method.
+3. See the following message in the terminal:
+
+```bash
+Received a request!
+```
+
+***
+
+## When to Use Middlewares
+
+Middlewares are useful for:
+
+- [Protecting API routes](https://docs.medusajs.com/learn/fundamentals/api-routes/protected-routes/index.html.md) to ensure that only authenticated users can access them.
+- [Validating](https://docs.medusajs.com/learn/fundamentals/api-routes/validation/index.html.md) request query and body parameters.
+- [Parsing](https://docs.medusajs.com/learn/fundamentals/api-routes/parse-body/index.html.md) request content types other than `application/json`.
+- [Applying CORS](https://docs.medusajs.com/learn/fundamentals/api-routes/cors/index.html.md) configurations to custom API routes.
+
+***
+
+## Middleware Function Parameters
+
+The middleware function accepts three parameters:
+
+1. A request object of type `MedusaRequest`.
+2. A response object of type `MedusaResponse`.
+3. A function of type `MedusaNextFunction` that executes the next middleware in the stack.
+
+You must call the `next` function in the middleware. Otherwise, other middlewares and the API route handler won’t execute.
+
+For example:
+
+```ts title="src/api/middlewares.ts"
+import {
+ MedusaNextFunction,
+ MedusaRequest,
+ MedusaResponse,
+ defineMiddlewares,
+} from "@medusajs/framework/http"
+
+export default defineMiddlewares({
+ routes: [
+ {
+ matcher: "/custom*",
+ middlewares: [
+ (
+ req: MedusaRequest,
+ res: MedusaResponse,
+ next: MedusaNextFunction
+ ) => {
+ console.log("Received a request!", req.body)
+
+ next()
+ },
+ ],
+ },
+ ],
+})
+```
+
+This middleware logs the request body to the terminal, then calls the `next` function to execute the next middleware in the stack.
+
+***
+
+## Middleware for Routes with Path Parameters
+
+To indicate a path parameter in a middleware's `matcher` pattern, use the format `:{param-name}`.
+
+A middleware applied on a route with path parameters is a route middleware.
+
+For example:
+
+```ts title="src/api/middlewares.ts" collapsibleLines="1-7" expandMoreLabel="Show Imports" highlights={pathParamHighlights}
+import {
+ MedusaNextFunction,
+ MedusaRequest,
+ MedusaResponse,
+ defineMiddlewares,
+} from "@medusajs/framework/http"
+
+export default defineMiddlewares({
+ routes: [
+ {
+ matcher: "/custom/:id",
+ middlewares: [
+ // ...
+ ],
+ },
+ ],
+})
+```
+
+This applies a middleware to the routes defined in the file `src/api/custom/[id]/route.ts`.
+
+***
+
+## Request URLs with Trailing Backslashes
+
+A middleware whose `matcher` pattern doesn't end with a backslash won't be applied for requests to URLs with a trailing backslash.
+
+For example, consider you have the following middleware:
+
+```ts title="src/api/middlewares.ts" collapsibleLines="1-7" expandMoreLabel="Show Imports"
+import {
+ MedusaNextFunction,
+ MedusaRequest,
+ MedusaResponse,
+ defineMiddlewares,
+} from "@medusajs/framework/http"
+
+export default defineMiddlewares({
+ routes: [
+ {
+ matcher: "/custom",
+ middlewares: [
+ (
+ req: MedusaRequest,
+ res: MedusaResponse,
+ next: MedusaNextFunction
+ ) => {
+ console.log("Received a request!")
+
+ next()
+ },
+ ],
+ },
+ ],
+})
+```
+
+If you send a request to `http://localhost:9000/custom`, the middleware will run.
+
+However, if you send a request to `http://localhost:9000/custom/`, the middleware won't run.
+
+In general, avoid adding trailing backslashes when sending requests to API routes.
+
+***
+
+## How Are Middlewares Ordered and Applied?
+
+The information explained in this section is applicable starting from [Medusa v2.6](https://github.com/medusajs/medusa/releases/tag/v2.6).
+
+### Middleware and Routes Execution Order
+
+The Medusa application registers middlewares and API route handlers in the following order, stacking them on top of each other:
+
+
+
+1. Global middlewares in the following order:
+ 1. Global middleware defined in the Medusa's core.
+ 2. Global middleware defined in the plugins (in the order the plugins are registered in).
+ 3. Global middleware you define in the application.
+2. Route middlewares in the following order:
+ 1. Route middleware defined in the Medusa's core.
+ 2. Route middleware defined in the plugins (in the order the plugins are registered in).
+ 3. Route middleware you define in the application.
+3. API routes in the following order:
+ 1. API routes defined in the Medusa's core.
+ 2. API routes defined in the plugins (in the order the plugins are registered in).
+ 3. API routes you define in the application.
+
+Then, when a request is sent to an API route, the stack is executed in order: global middlewares are executed first, then the route middlewares, and finally the route handlers.
+
+
+
+For example, consider you have the following middlewares:
+
+```ts title="src/api/middlewares.ts"
+export default defineMiddlewares({
+ routes: [
+ {
+ matcher: "/custom",
+ middlewares: [
+ (req, res, next) => {
+ console.log("Global middleware")
+ next()
+ },
+ ],
+ },
+ {
+ matcher: "/custom",
+ method: ["GET"],
+ middlewares: [
+ (req, res, next) => {
+ console.log("Route middleware")
+ next()
+ },
+ ],
+ },
+ ],
+})
+```
+
+When you send a request to `/custom` route, the following messages are logged in the terminal:
+
+```bash
+Global middleware
+Route middleware
+Hello from custom! # message logged from API route handler
+```
+
+The global middleware runs first, then the route middleware, and finally the route handler, assuming that it logs the message `Hello from custom!`.
+
+### Middlewares Sorting
+
+On top of the previous ordering, Medusa sorts global and route middlewares based on their matcher pattern in the following order:
+
+1. Wildcard matchers. For example, `/custom*`.
+2. Regex matchers. For example, `/custom/(products|collections)`.
+3. Static matchers without parameters. For example, `/custom`.
+4. Static matchers with parameters. For example, `/custom/:id`.
+
+For example, if you have the following middlewares:
+
+```ts title="src/api/middlewares.ts"
+export default defineMiddlewares({
+ routes: [
+ {
+ matcher: "/custom/:id",
+ middlewares: [/* ... */],
+ },
+ {
+ matcher: "/custom",
+ middlewares: [/* ... */],
+ },
+ {
+ matcher: "/custom*",
+ method: ["GET"],
+ middlewares: [/* ... */],
+ },
+ {
+ matcher: "/custom/:id",
+ method: ["GET"],
+ middlewares: [/* ... */],
+ },
+ ],
+})
+```
+
+The global middlewares are sorted into the following order before they're registered:
+
+1. Global middleware `/custom`.
+2. Global middleware `/custom/:id`.
+
+And the route middlewares are sorted into the following order before they're registered:
+
+1. Route middleware `/custom*`.
+2. Route middleware `/custom/:id`.
+
+
+
+Then, the middlwares are registered in the order mentioned earlier, with global middlewares first, then the route middlewares.
+
+***
+
+## Overriding Middlewares
+
+A middleware can not override an existing middleware. Instead, middlewares are added to the end of the middleware stack.
+
+For example, if you define a custom validation middleware, such as `validateAndTransformBody`, on an existing route, then both the original and the custom validation middleware will run.
+
+Similarly, if you add an [authenticate](https://docs.medusajs.com/learn/fundamentals/api-routes/protected-routes#protect-custom-api-routes/index.html.md) middleware to an existing route, both the original and the custom authentication middleware will run. So, you can't override the original authentication middleware.
+
+### Alternative Solution to Overriding Middlewares
+
+If you need to change the middlewares applied to a route, you can create a custom [API route](https://docs.medusajs.com/learn/fundamentals/api-routes/index.html.md) that executes the same functionality as the original route, but with the middlewares you want.
+
+Learn more in the [Override API Routes](https://docs.medusajs.com/learn/fundamentals/api-routes/override/index.html.md) chapter.
+
+
+# HTTP Methods
+
+In this chapter, you'll learn about how to add new API routes for each HTTP method.
+
+## HTTP Method Handler
+
+An API route is created for every HTTP method you export a handler function for in a route file.
+
+Allowed HTTP methods are: `GET`, `POST`, `DELETE`, `PUT`, `PATCH`, `OPTIONS`, and `HEAD`.
+
+For example, create the file `src/api/hello-world/route.ts` with the following content:
+
+```ts title="src/api/hello-world/route.ts"
+import type {
+ MedusaRequest,
+ MedusaResponse,
+} from "@medusajs/framework/http"
+
+export const GET = async (
+ req: MedusaRequest,
+ res: MedusaResponse
+) => {
+ res.json({
+ message: "[GET] Hello world!",
+ })
+}
+
+export const POST = async (
+ req: MedusaRequest,
+ res: MedusaResponse
+) => {
+ res.json({
+ message: "[POST] Hello world!",
+ })
+}
+```
+
+This adds two API Routes:
+
+- A `GET` route at `http://localhost:9000/hello-world`.
+- A `POST` route at `http://localhost:9000/hello-world`.
+
+
+# Throwing and Handling Errors
+
+In this guide, you'll learn how to throw errors in your Medusa application, how it affects an API route's response, and how to change the default error handler of your Medusa application.
+
+## Throw MedusaError
+
+When throwing an error in your API routes, middlewares, workflows, or any customization, throw a `MedusaError` from the Medusa Framework.
+
+The Medusa application's API route error handler then wraps your thrown error in a uniform object and returns it in the response.
+
+For example:
+
+```ts
+import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
+import { MedusaError } from "@medusajs/framework/utils"
+
+export const GET = async (
+ req: MedusaRequest,
+ res: MedusaResponse
+) => {
+ if (!req.query.q) {
+ throw new MedusaError(
+ MedusaError.Types.INVALID_DATA,
+ "The `q` query parameter is required."
+ )
+ }
+
+ // ...
+}
+```
+
+The `MedusaError` class accepts in its constructor two parameters:
+
+1. The first is the error's type. `MedusaError` has a static property `Types` that you can use. `Types` is an enum whose possible values are explained in the next section.
+2. The second is the message to show in the error response.
+
+### Error Object in Response
+
+The error object returned in the response has two properties:
+
+- `type`: The error's type.
+- `message`: The error message, if available.
+- `code`: A common snake-case code. Its values can be:
+ - `invalid_request_error` for the `DUPLICATE_ERROR` type.
+ - `api_error`: for the `DB_ERROR` type.
+ - `invalid_state_error` for `CONFLICT` error type.
+ - `unknown_error` for any unidentified error type.
+ - For other error types, this property won't be available unless you provide a code as a third parameter to the `MedusaError` constructor.
+
+### MedusaError Types
+
+|Type|Description|Status Code|
+|---|---|---|---|---|
+|\`DB\_ERROR\`|Indicates a database error.|\`500\`|
+|\`DUPLICATE\_ERROR\`|Indicates a duplicate of a record already exists. For example, when trying to create a customer whose email is registered by another customer.|\`422\`|
+|\`INVALID\_ARGUMENT\`|Indicates an error that occurred due to incorrect arguments or other unexpected state.|\`500\`|
+|\`INVALID\_DATA\`|Indicates a validation error.|\`400\`|
+|\`UNAUTHORIZED\`|Indicates that a user is not authorized to perform an action or access a route.|\`401\`|
+|\`NOT\_FOUND\`|Indicates that the requested resource, such as a route or a record, isn't found.|\`404\`|
+|\`NOT\_ALLOWED\`|Indicates that an operation isn't allowed.|\`400\`|
+|\`CONFLICT\`|Indicates that a request conflicts with another previous or ongoing request. The error message in this case is ignored for a default message.|\`409\`|
+|\`PAYMENT\_AUTHORIZATION\_ERROR\`|Indicates an error has occurred while authorizing a payment.|\`422\`|
+|Other error types|Any other error type results in an |\`500\`|
+
+***
+
+## Override Error Handler
+
+The `defineMiddlewares` function used to apply middlewares on routes accepts an `errorHandler` in its object parameter. Use it to override the default error handler for API routes.
+
+This error handler will also be used for errors thrown in Medusa's API routes and resources.
+
+For example, create `src/api/middlewares.ts` with the following:
+
+```ts title="src/api/middlewares.ts" collapsibleLines="1-8" expandMoreLabel="Show Imports"
+import {
+ defineMiddlewares,
+ MedusaNextFunction,
+ MedusaRequest,
+ MedusaResponse,
+} from "@medusajs/framework/http"
+import { MedusaError } from "@medusajs/framework/utils"
+
+export default defineMiddlewares({
+ errorHandler: (
+ error: MedusaError | any,
+ req: MedusaRequest,
+ res: MedusaResponse,
+ next: MedusaNextFunction
+ ) => {
+ res.status(400).json({
+ error: "Something happened.",
+ })
+ },
+})
+```
+
+The `errorHandler` property's value is a function that accepts four parameters:
+
+1. The error thrown. Its type can be `MedusaError` or any other thrown error type.
+2. A request object of type `MedusaRequest`.
+3. A response object of type `MedusaResponse`.
+4. A function of type MedusaNextFunction that executes the next middleware in the stack.
+
+This example overrides Medusa's default error handler with a handler that always returns a `400` status code with the same message.
+
+
+# Override API Routes
+
+In this chapter, you'll learn the approach recommended when you need to override an existing API route in Medusa.
+
+## Approaches to Consider Before Overriding API Routes
+
+While building customizations in your Medusa application, you may need to make changes to existing API routes for your business use case.
+
+Medusa provides the following approaches to customize API routes:
+
+|Approach|Description|
+|---|---|
+|Pass Additional Data|Pass custom data to the API route with custom validation.|
+|Perform Custom Logic within an Existing Flows|API routes execute workflows to perform business logic, which may have hooks that allow you to perform custom logic.|
+|Use Custom Middlewares|Use custom middlewares to perform custom logic before the API route is executed. However, you cannot remove or replace middlewares applied to existing API routes.|
+|Listen to Events in Subscribers|Functionalities in API routes may trigger events that you can handle in subscribers. This is useful if you're performing an action that isn't integral to the API route's core functionality or response.|
+
+If the above approaches do not meet your needs, you can consider the approaches mentioned in the rest of this chapter.
+
+***
+
+## Replicate, Don't Override API Routes
+
+If the approaches mentioned in the [section above](#approaches-to-consider-before-overriding-api-routes) do not meet your needs, you can replicate an existing API route and modify it to suit your requirements.
+
+By replicating instead of overriding, the original API route remains intact, allowing you to easily revert to the original functionality if needed. You can also update your Medusa version without worrying about breaking changes in the original API route.
+
+***
+
+## How to Replicate an API Route?
+
+Medusa's API routes are generally slim and use logic contained in [workflows](https://docs.medusajs.com/learn/fundamentals/workflows/index.html.md). So, creating a custom route based on the original route is straightforward.
+
+You can view the source code for Medusa's API routes in the [Medusa GitHub repository](https://github.com/medusajs/medusa/tree/develop/packages/medusa/src/api).
+
+For example, if you need to allow vendors to access the `POST /admin/products` API route, you can create an API route in your Medusa project at `src/api/vendor/products/route.ts` with the [same code as the original route](https://github.com/medusajs/medusa/blob/develop/packages/medusa/src/api/admin/products/route.ts#L88). Then, you can make changes to it or its middlewares.
+
+***
+
+## When to Replicate an API Route?
+
+Some examples of when you might want to replicate an API route include:
+
+|Use Case|Description|
+|---|---|
+|Custom Validation|You want to change the validation logic for a specific API route, and the |
+|Change Authentication|You want to remove required authentication for a specific API route, or you want to allow custom |
+|Custom Response|You want to change the response format of an existing API route.|
+|Override Middleware|You want to override the middleware applied on existing API routes. Because of |
+
+
+# API Route Parameters
+
+In this chapter, you’ll learn about path, query, and request body parameters.
+
+## Path Parameters
+
+To create an API route that accepts a path parameter, create a directory within the route file's path whose name is of the format `[param]`.
+
+For example, to create an API Route at the path `/hello-world/:id`, where `:id` is a path parameter, create the file `src/api/hello-world/[id]/route.ts` with the following content:
+
+```ts title="src/api/hello-world/[id]/route.ts" highlights={singlePathHighlights}
+import type {
+ MedusaRequest,
+ MedusaResponse,
+} from "@medusajs/framework/http"
+
+export const GET = async (
+ req: MedusaRequest,
+ res: MedusaResponse
+) => {
+ res.json({
+ message: `[GET] Hello ${req.params.id}!`,
+ })
+}
+```
+
+The `MedusaRequest` object has a `params` property. `params` holds the path parameters in key-value pairs.
+
+### Multiple Path Parameters
+
+To create an API route that accepts multiple path parameters, create within the file's path multiple directories whose names are of the format `[param]`.
+
+For example, to create an API route at `/hello-world/:id/name/:name`, create the file `src/api/hello-world/[id]/name/[name]/route.ts` with the following content:
+
+```ts title="src/api/hello-world/[id]/name/[name]/route.ts" highlights={multiplePathHighlights}
+import type {
+ MedusaRequest,
+ MedusaResponse,
+} from "@medusajs/framework/http"
+
+export const GET = async (
+ req: MedusaRequest,
+ res: MedusaResponse
+) => {
+ res.json({
+ message: `[GET] Hello ${
+ req.params.id
+ } - ${req.params.name}!`,
+ })
+}
+```
+
+You access the `id` and `name` path parameters using the `req.params` property.
+
+***
+
+## Query Parameters
+
+You can access all query parameters in the `query` property of the `MedusaRequest` object. `query` is an object of key-value pairs, where the key is a query parameter's name, and the value is its value.
+
+For example:
+
+```ts title="src/api/hello-world/route.ts" highlights={queryHighlights}
+import type {
+ MedusaRequest,
+ MedusaResponse,
+} from "@medusajs/framework/http"
+
+export const GET = async (
+ req: MedusaRequest,
+ res: MedusaResponse
+) => {
+ res.json({
+ message: `Hello ${req.query.name}`,
+ })
+}
+```
+
+The value of `req.query.name` is the value passed in `?name=John`, for example.
+
+### Validate Query Parameters
+
+You can apply validation rules on received query parameters to ensure they match specified rules and types.
+
+Learn more in [this documentation](https://docs.medusajs.com/learn/fundamentals/api-routes/validation#how-to-validate-request-query-paramters/index.html.md).
+
+***
+
+## Request Body Parameters
+
+The Medusa application parses the body of any request having a JSON, URL-encoded, or text request content types. The request body parameters are set in the `MedusaRequest`'s `body` property.
+
+Learn more about configuring body parsing in [this guide](https://docs.medusajs.com/learn/fundamentals/api-routes/parse-body/index.html.md).
+
+For example:
+
+```ts title="src/api/hello-world/route.ts" highlights={bodyHighlights}
+import type {
+ MedusaRequest,
+ MedusaResponse,
+} from "@medusajs/framework/http"
+
+type HelloWorldReq = {
+ name: string
+}
+
+export const POST = async (
+ req: MedusaRequest,
+ res: MedusaResponse
+) => {
+ res.json({
+ message: `[POST] Hello ${req.body.name}!`,
+ })
+}
+```
+
+In this example, you use the `name` request body parameter to create the message in the returned response.
+
+The `MedusaRequest` type accepts a type argument that indicates the type of the request body. This is useful for auto-completion and to avoid typing errors.
+
+To test it out, send the following request to your Medusa application:
+
+```bash
+curl -X POST 'http://localhost:9000/hello-world' \
+-H 'Content-Type: application/json' \
+--data-raw '{
+ "name": "John"
+}'
+```
+
+This returns the following JSON object:
+
+```json
+{
+ "message": "[POST] Hello John!"
+}
+```
+
+### Validate Body Parameters
+
+You can apply validation rules on received body parameters to ensure they match specified rules and types.
+
+Learn more in [this documentation](https://docs.medusajs.com/learn/fundamentals/api-routes/validation#how-to-validate-request-body/index.html.md).
+
+
+# Configure Request Body Parser
+
+In this chapter, you'll learn how to configure the request body parser for your API routes.
+
+## Default Body Parser Configuration
+
+The Medusa application configures the body parser by default to parse JSON, URL-encoded, and text request content types. You can parse other data types by adding the relevant [Express middleware](https://expressjs.com/en/guide/using-middleware.html) or preserve the raw body data by configuring the body parser, which is useful for webhook requests.
+
+This chapter shares some examples of configuring the body parser for different data types or use cases.
+
+***
+
+## Preserve Raw Body Data for Webhooks
+
+If your API route receives webhook requests, you might want to preserve the raw body data. To do this, you can configure the body parser to parse the raw body data and store it in the `req.rawBody` property.
+
+To do that, create the file `src/api/middlewares.ts` with the following content:
+
+```ts title="src/api/middlewares.ts" highlights={preserveHighlights}
+import { defineMiddlewares } from "@medusajs/framework/http"
+
+export default defineMiddlewares({
+ routes: [
+ {
+ method: ["POST"],
+ bodyParser: { preserveRawBody: true },
+ matcher: "/custom",
+ },
+ ],
+})
+```
+
+The middleware route object passed to `routes` accepts a `bodyParser` property whose value is an object of configuration for the default body parser. By enabling the `preserveRawBody` property, the raw body data is preserved and stored in the `req.rawBody` property.
+
+Learn more about [middlewares](https://docs.medusajs.com/learn/fundamentals/api-routes/middlewares/index.html.md).
+
+You can then access the raw body data in your API route handler:
+
+```ts title="src/api/custom/route.ts"
+import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
+
+export async function POST(
+ req: MedusaRequest,
+ res: MedusaResponse
+) {
+ console.log(req.rawBody)
+
+ // TODO use raw body
+}
+```
+
+***
+
+## Configure Request Body Size Limit
+
+By default, the body parser limits the request body size to `100kb`. If a request body exceeds that size, the Medusa application throws an error.
+
+You can configure the body parser to accept larger request bodies by setting the `sizeLimit` property of the `bodyParser` object in a middleware route object. For example:
+
+```ts title="src/api/middlewares.ts" highlights={sizeLimitHighlights}
+import { defineMiddlewares } from "@medusajs/framework/http"
+
+export default defineMiddlewares({
+ routes: [
+ {
+ method: ["POST"],
+ bodyParser: { sizeLimit: "2mb" },
+ matcher: "/custom",
+ },
+ ],
+})
+```
+
+The `sizeLimit` property accepts one of the following types of values:
+
+- A string representing the size limit in bytes (For example, `100kb`, `2mb`, `5gb`). It is passed to the [bytes](https://www.npmjs.com/package/bytes) library to parse the size.
+- A number representing the size limit in bytes. For example, `1024` for 1kb.
+
+***
+
+## Configure File Uploads
+
+To accept file uploads in your API routes, you can configure the [Express Multer middleware](https://expressjs.com/en/resources/middleware/multer.html) on your route.
+
+The `multer` package is available through the `@medusajs/medusa` package, so you don't need to install it. However, for better typing support, install the `@types/multer` package as a development dependency:
+
+```bash npm2yarn
+npm install --save-dev @types/multer
+```
+
+Then, to configure file upload for your route, create the file `src/api/middlewares.ts` with the following content:
+
+```ts title="src/api/middlewares.ts" highlights={uploadHighlights}
+import { defineMiddlewares } from "@medusajs/framework/http"
+import multer from "multer"
+
+const upload = multer({ storage: multer.memoryStorage() })
+
+export default defineMiddlewares({
+ routes: [
+ {
+ method: ["POST"],
+ matcher: "/custom",
+ middlewares: [
+ // @ts-ignore
+ upload.array("files"),
+ ],
+ },
+ ],
+})
+```
+
+In the example above, you configure the `multer` middleware to store the uploaded files in memory. Then, you apply the `upload.array("files")` middleware to the route to accept file uploads. By using the `array` method, you accept multiple file uploads with the same `files` field name.
+
+You can then access the uploaded files in your API route handler:
+
+```ts title="src/api/custom/route.ts"
+import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
+
+export async function POST(
+ req: MedusaRequest,
+ res: MedusaResponse
+) {
+ const files = req.files as Express.Multer.File[]
+
+ // TODO handle files
+}
+```
+
+The uploaded files are stored in the `req.files` property as an array of Multer file objects that have properties like `filename` and `mimetype`.
+
+### Uploading Files using File Module Provider
+
+The recommended way to upload the files to storage using the configured [File Module Provider](https://docs.medusajs.com/resources/infrastructure-modules/file/index.html.md) is to use the [uploadFilesWorkflow](https://docs.medusajs.com/resources/references/medusa-workflows/uploadFilesWorkflow/index.html.md):
+
+```ts title="src/api/custom/route.ts"
+import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
+import { MedusaError } from "@medusajs/framework/utils"
+import { uploadFilesWorkflow } from "@medusajs/medusa/core-flows"
+
+export async function POST(
+ req: MedusaRequest,
+ res: MedusaResponse
+) {
+ const files = req.files as Express.Multer.File[]
+
+ if (!files?.length) {
+ throw new MedusaError(
+ MedusaError.Types.INVALID_DATA,
+ "No files were uploaded"
+ )
+ }
+
+ const { result } = await uploadFilesWorkflow(req.scope).run({
+ input: {
+ files: files?.map((f) => ({
+ filename: f.originalname,
+ mimeType: f.mimetype,
+ content: f.buffer.toString("binary"),
+ access: "public",
+ })),
+ },
+ })
+
+ res.status(200).json({ files: result })
+}
+```
+
+Check out the [uploadFilesWorkflow reference](https://docs.medusajs.com/resources/references/medusa-workflows/uploadFilesWorkflow/index.html.md) for details on the expected input and output of the workflow.
+
+
+# Protected API Routes
+
+In this chapter, you’ll learn how to create protected API routes.
+
+## What is a Protected API Route?
+
+By default, an API route is publicly accessible, meaning that any user can access it without authentication. This is useful for public API routes that allow users to browse products, view collections, and so on.
+
+A protected API route is an API route that requires requests to be user-authenticated before performing the route's functionality. Otherwise, the request fails, and the user is prevented access.
+
+Protected API routes are useful for routes that require user authentication, such as creating a product or managing an order. These routes must only be accessed by authenticated admin users.
+
+Refer to the API Reference for [Admin](https://docs.medusajs.com/api/admin#authentication) and [Store](https://docs.medusajs.com/api/store#authentication) to learn how to send authenticated requests.
+
+***
+
+## Default Protected Routes
+
+Any API route, including your custom API routes, are protected if they start with the following prefixes:
+
+|Route Prefix|Access|
+|---|---|
+|\`/admin\`|Only authenticated admin users can access.|
+|\`/store/customers/me\`|Only authenticated customers can access.|
+
+Refer to the API Reference for [Admin](https://docs.medusajs.com/api/admin#authentication) and [Store](https://docs.medusajs.com/api/store#authentication) to learn how to send authenticated requests.
+
+### Opt-Out of Default Authentication Requirement
+
+If you create a custom API route under a prefix that is protected by default, you can opt-out of the authentication requirement by exporting an `AUTHENTICATE` variable in the route file with its value set to `false`.
+
+For example, to disable authentication requirement for a custom API route created at `/admin/custom`, you can export an `AUTHENTICATE` variable in the route file:
+
+```ts title="src/api/admin/custom/route.ts" highlights={[["15"]]}
+import type {
+ AuthenticatedMedusaRequest,
+ MedusaResponse,
+} from "@medusajs/framework/http"
+
+export const GET = async (
+ req: AuthenticatedMedusaRequest,
+ res: MedusaResponse
+) => {
+ res.json({
+ message: "Hello",
+ })
+}
+
+export const AUTHENTICATE = false
+```
+
+Now, any request sent to the `/admin/custom` API route is allowed, regardless if the admin user is authenticated.
+
+***
+
+## Protect Custom API Routes
+
+You can protect API routes using the `authenticate` [middleware](https://docs.medusajs.com/learn/fundamentals/api-routes/middlewares/index.html.md) from the Medusa Framework. When applied to a route, the middleware checks that:
+
+- The correct actor type (for example, `user`, `customer`, or a custom actor type) is authenticated.
+- The correct authentication method is used (for example, `session`, `bearer`, or `api-key`).
+
+For example, you can add the `authenticate` middleware in the `src/api/middlewares.ts` file to protect a custom API route:
+
+```ts title="src/api/middlewares.ts" highlights={highlights}
+import {
+ defineMiddlewares,
+ authenticate,
+} from "@medusajs/framework/http"
+
+export default defineMiddlewares({
+ routes: [
+ {
+ matcher: "/custom/admin*",
+ middlewares: [authenticate("user", ["session", "bearer", "api-key"])],
+ },
+ {
+ matcher: "/custom/customer*",
+ middlewares: [authenticate("customer", ["session", "bearer"])],
+ },
+ ],
+})
+```
+
+The `authenticate` middleware function accepts three parameters:
+
+1. The type of user authenticating. Use `user` for authenticating admin users, and `customer` for authenticating customers. You can also pass `*` to allow all types of users, or pass an array of actor types.
+2. An array of types of authentication methods allowed. Both `user` and `customer` scopes support `session` and `bearer`. The `admin` scope also supports the `api-key` authentication method.
+3. An optional object of configurations accepting the following properties:
+ - `allowUnauthenticated`: (default: `false`) A boolean indicating whether authentication is required. For example, you may have an API route where you want to access the logged-in customer if available, but guest customers can still access it too.
+ - `allowUnregistered` (default: `false`): A boolean indicating if unregistered users should be allowed access. This is useful when you want to allow users who aren’t registered to access certain routes.
+
+### Example: Custom Actor Type
+
+For example, to require authentication of a custom actor type `manager` to an API route:
+
+```ts title="src/api/middlewares.ts"
+import {
+ defineMiddlewares,
+ authenticate,
+} from "@medusajs/framework/http"
+
+export default defineMiddlewares({
+ routes: [
+ {
+ matcher: "/manager*",
+ middlewares: [authenticate("manager", ["session", "bearer"])],
+ },
+ ],
+})
+```
+
+Refer to the [Custom Actor-Type Guide](https://docs.medusajs.com/resources/commerce-modules/auth/create-actor-type/index.html.md) for detailed explanation on how to create a custom actor type and apply authentication middlewares.
+
+### Example: Allow Multiple Actor Types
+
+To allow multiple actor types to access an API route, pass an array of actor types to the `authenticate` middleware:
+
+```ts title="src/api/middlewares.ts"
+import {
+ defineMiddlewares,
+ authenticate,
+} from "@medusajs/framework/http"
+
+export default defineMiddlewares({
+ routes: [
+ {
+ matcher: "/custom*",
+ middlewares: [authenticate(["user", "customer"], ["session", "bearer"])],
+ },
+ ],
+})
+```
+
+### Override Authentication for Medusa's API Routes
+
+In some cases, you may want to override the authentication requirement for Medusa's API routes. For example, you may want to allow custom actor types to access existing protected API routes.
+
+It's not possible to change the [authentication middleware](https://docs.medusajs.com/learn/fundamentals/api-routes/middlewares/index.html.md) applied to an existing API route. Instead, you need to replicate the API route and apply the authentication middleware to it.
+
+Learn more in the [Override API Routes](https://docs.medusajs.com/learn/fundamentals/api-routes/override/index.html.md) chapter.
+
+***
+
+## Access Authentication Details in API Routes
+
+To access the authentication details in an API route, such as the logged-in user's ID, set the type of the first request parameter to `AuthenticatedMedusaRequest`. It extends `MedusaRequest`:
+
+```ts highlights={[["7", "AuthenticatedMedusaRequest"]]}
+import type {
+ AuthenticatedMedusaRequest,
+ MedusaResponse,
+} from "@medusajs/framework/http"
+
+export const GET = async (
+ req: AuthenticatedMedusaRequest,
+ res: MedusaResponse
+) => {
+ // ...
+}
+```
+
+The `auth_context.actor_id` property of `AuthenticatedMedusaRequest` holds the ID of the authenticated user or customer. If there isn't any authenticated user or customer, `auth_context` is `undefined`.
+
+For example:
+
+```ts title="src/api/store/custom/route.ts" highlights={[["10", "actor_id"]]}
+import type {
+ AuthenticatedMedusaRequest,
+ MedusaResponse,
+} from "@medusajs/framework/http"
+
+export const GET = async (
+ req: AuthenticatedMedusaRequest,
+ res: MedusaResponse
+) => {
+ const id = req.auth_context?.actor_id
+
+ // ...
+}
+```
+
+In this example, you retrieve the ID of the authenticated user, customer, or custom actor type from the `auth_context` property of the `AuthenticatedMedusaRequest` object.
+
+If you opt-out of authentication in a route as mentioned in the [Opt-Out section](#opt-out-of-default-authentication-requirement), you can't access the authenticated user or customer anymore. Use the [authenticate middleware](#protect-custom-api-routes) instead to protect the route.
+
+### Retrieve Logged-In Customer's Details
+
+You can access the logged-in customer’s ID in all API routes starting with `/store` using the `auth_context.actor_id` property of the `AuthenticatedMedusaRequest` object. You can then use [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query/index.html.md) to retrieve the customer details, or pass the ID to a [workflow](https://docs.medusajs.com/learn/fundamentals/workflows/index.html.md) that performs business logic.
+
+For example:
+
+```ts title="src/api/store/custom/route.ts" highlights={customerHighlights}
+import type {
+ AuthenticatedMedusaRequest,
+ MedusaResponse,
+} from "@medusajs/framework/http"
+
+export const GET = async (
+ req: AuthenticatedMedusaRequest,
+ res: MedusaResponse
+) => {
+ const customerId = req.auth_context?.actor_id
+ const query = req.scope.resolve("query")
+
+ const { data: [customer] } = await query.graph({
+ entity: "customer",
+ fields: ["*"],
+ filters: {
+ id: customerId,
+ },
+ }, {
+ throwIfKeyNotFound: true,
+ })
+
+ // do something with the customer data...
+}
+```
+
+In this example, you retrieve the customer's ID and resolve Query from the [Medusa container](https://docs.medusajs.com/learn/fundamentals/medusa-container/index.html.md).
+
+Then, you use Query to retrieve the customer details. The `throwIfKeyNotFound` option throws an error if the customer with the specified ID is not found.
+
+After that, you can use the customer's details in your API route.
+
+### Retrieve Logged-In Admin User's Details
+
+You can access the logged-in admin user’s ID in all API routes starting with `/admin` using the `auth_context.actor_id` property of the `AuthenticatedMedusaRequest` object. You can then use [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query/index.html.md) to retrieve the user details, or pass the ID to a [workflow](https://docs.medusajs.com/learn/fundamentals/workflows/index.html.md) that performs business logic.
+
+For example:
+
+```ts title="src/api/admin/custom/route.ts" highlights={adminHighlights}
+import type {
+ AuthenticatedMedusaRequest,
+ MedusaResponse,
+} from "@medusajs/framework/http"
+
+export const GET = async (
+ req: AuthenticatedMedusaRequest,
+ res: MedusaResponse
+) => {
+ const userId = req.auth_context?.actor_id
+ const query = req.scope.resolve("query")
+
+ const { data: [user] } = await query.graph({
+ entity: "user",
+ fields: ["*"],
+ filters: {
+ id: userId,
+ },
+ }, {
+ throwIfKeyNotFound: true,
+ })
+
+ // do something with the user data...
+}
+```
+
+In this example, you retrieve the admin user's ID and resolve Query from the [Medusa container](https://docs.medusajs.com/learn/fundamentals/medusa-container/index.html.md).
+
+Then, you use Query to retrieve the user details. The `throwIfKeyNotFound` option throws an error if the user with the specified ID is not found.
+
+After that, you can use the user's details in your API route.
+
+
+# API Route Response
+
+In this chapter, you'll learn how to send a response in your API route.
+
+## Send a JSON Response
+
+To send a JSON response, use the `json` method of the `MedusaResponse` object passed as the second parameter of your API route handler.
+
+For example:
+
+```ts title="src/api/custom/route.ts" highlights={jsonHighlights}
+import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
+
+export const GET = async (
+ req: MedusaRequest,
+ res: MedusaResponse
+) => {
+ res.json({
+ message: "Hello, World!",
+ })
+}
+```
+
+This API route returns the following JSON object:
+
+```json
+{
+ "message": "Hello, World!"
+}
+```
+
+***
+
+## Set Response Status Code
+
+By default, setting the JSON data using the `json` method returns a response with a `200` status code.
+
+To change the status code, use the `status` method of the `MedusaResponse` object.
+
+For example:
+
+```ts title="src/api/custom/route.ts" highlights={statusHighlight}
+import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
+
+export const GET = async (
+ req: MedusaRequest,
+ res: MedusaResponse
+) => {
+ res.status(201).json({
+ message: "Hello, World!",
+ })
+}
+```
+
+The response of this API route has the status code `201`.
+
+***
+
+## Change Response Content Type
+
+To return response data other than a JSON object, use the `writeHead` method of the `MedusaResponse` object. It allows you to set the response headers, including the content type.
+
+For example, to create an API route that returns an event stream:
+
+```ts highlights={streamHighlights}
+import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
+
+export const GET = async (
+ req: MedusaRequest,
+ res: MedusaResponse
+) => {
+ res.writeHead(200, {
+ "Content-Type": "text/event-stream",
+ "Cache-Control": "no-cache",
+ Connection: "keep-alive",
+ })
+
+ const interval = setInterval(() => {
+ res.write("Streaming data...\n")
+ }, 3000)
+
+ req.on("end", () => {
+ clearInterval(interval)
+ res.end()
+ })
+}
+```
+
+The `writeHead` method accepts two parameters:
+
+1. The first one is the response's status code.
+2. The second is an object of key-value pairs to set the headers of the response.
+
+This API route opens a stream by setting the `Content-Type` in the header to `text/event-stream`. It then simulates a stream by creating an interval that writes the stream data every three seconds.
+
+***
+
+## Do More with Responses
+
+The `MedusaResponse` type is based on [Express's Response](https://expressjs.com/en/api.html#res). Refer to their API reference for other uses of responses.
+
+
+# Retrieve Custom Links from Medusa's API Route
+
+In this chapter, you'll learn how to retrieve custom data models linked to existing Medusa data models from Medusa's API routes.
+
+## Why Retrieve Custom Linked Data Models?
+
+Often, you'll link custom data models to existing Medusa data models to implement custom features or expand on existing ones.
+
+For example, to add brands for products, you can create a `Brand` data model in a Brand Module, then [define a link](https://docs.medusajs.com/learn/fundamentals/module-links/index.html.md) to the [Product Module](https://docs.medusajs.com/resources/commerce-modules/product/index.html.md)'s `Product` data model.
+
+When you implement this customization, you might need to retrieve the brand of a product using the existing [Get Product API Route](https://docs.medusajs.com/api/admin#products_getproductsid). You can do this by passing the linked data model's name in the `fields` query parameter of the API route.
+
+***
+
+## How to Retrieve Custom Linked Data Models Using `fields`?
+
+Most of Medusa's API routes accept a `fields` query parameter that allows you to specify the fields and relations to retrieve in the resource, such as a product.
+
+For example, to retrieve the brand of a product, you can pass the `brand` field in the `fields` query parameter of the [Get Product API Route](https://docs.medusajs.com/api/admin#products_getproductsid):
+
+```bash
+curl 'http://localhost:9000/admin/products/{id}?fields=*brand' \
+-H 'Authorization: Bearer {access_token}'
+```
+
+The `fields` query parameter accepts a comma-separated list of fields and relations to retrieve. To learn more about using the `fields` query parameter, refer to the [API Reference](https://docs.medusajs.com/api/store#select-fields-and-relations).
+
+By prefixing `brand` with an asterisk (`*`), you retrieve all the default fields of the product, including the `brand` field. If you don't include the `*` prefix, the response will only include the product's brand.
+
+***
+
+## API Routes that Restrict Retrievable Fields
+
+Some of Medusa's API routes restrict the fields and relations you can retrieve, which means you can't pass your custom linked data models in the `fields` query parameter. Medusa makes this restriction to ensure the API routes are performant and secure.
+
+The API routes that restrict the fields and relations you can retrieve are:
+
+- [Customer Store API Routes](https://docs.medusajs.com/api/store#customers)
+- [Customer Admin API Routes](https://docs.medusajs.com/api/admin#customers)
+- [Product Category Admin API Routes](https://docs.medusajs.com/api/admin#product-categories)
+
+### How to Override Allowed Fields and Relations
+
+For these routes, you need to override the allowed fields and relations to be retrieved. You can do this by adding a [middleware](https://docs.medusajs.com/learn/fundamentals/api-routes/middlewares/index.html.md) to those routes.
+
+For example, to allow retrieving the `b2b_company` of a customer using the [Get Customer Admin API Route](https://docs.medusajs.com/api/admin#customers_getcustomersid), create the file `src/api/middlewares.ts` with the following content:
+
+Learn how to create a middleware in the [Middlewares](https://docs.medusajs.com/learn/fundamentals/api-routes/middlewares/index.html.md) chapter.
+
+```ts title="src/api/middlewares.ts" highlights={highlights}
+import { defineMiddlewares } from "@medusajs/medusa"
+
+export default defineMiddlewares({
+ routes: [
+ {
+ matcher: "/store/customers/me",
+ method: "GET",
+ middlewares: [
+ (req, res, next) => {
+ req.allowed?.push("b2b_company")
+ next()
+ },
+ ],
+ },
+ ],
+})
+```
+
+In this example, you apply a middleware to the [Get Customer Admin API Route](https://docs.medusajs.com/api/admin#customers_getcustomersid).
+
+The request object passed to middlewares has an `allowed` property that contains the fields and relations that can be retrieved. So, you modify the `allowed` array to include the `b2b_company` field.
+
+You can now retrieve the `b2b_company` field using the `fields` query parameter of the [Get Customer Admin API Route](https://docs.medusajs.com/api/admin#customers_getcustomersid):
+
+```bash
+curl 'http://localhost:9000/admin/customers/{id}?fields=*b2b_company' \
+-H 'Authorization: Bearer {access_token}'
+```
+
+In this example, you retrieve the `b2b_company` relation of the customer using the `fields` query parameter.
+
+
+# Request Body and Query Parameter Validation
+
+In this chapter, you'll learn how to validate request body and query parameters in your custom API route.
+
+## Request Validation
+
+Consider you're creating a `POST` API route at `/custom`. It accepts two parameters `a` and `b` that are required numbers, and returns their sum.
+
+Medusa provides two middlewares to validate the request body and query paramters of incoming requests to your custom API routes:
+
+- `validateAndTransformBody` to validate the request's body parameters against a schema.
+- `validateAndTransformQuery` to validate the request's query parameters against a schema.
+
+Both middlewares accept a [Zod](https://zod.dev/) schema as a parameter, which gives you flexibility in how you define your validation schema with complex rules.
+
+The next steps explain how to add request body and query parameter validation to the API route mentioned earlier.
+
+***
+
+## How to Validate Request Body
+
+### Step 1: Create Validation Schema
+
+Medusa uses [Zod](https://zod.dev/) to create validation schemas. These schemas are then used to validate incoming request bodies or query parameters.
+
+To create a validation schema with Zod, create a `validators.ts` file in any `src/api` subfolder. This file holds Zod schemas for each of your API routes.
+
+For example, create the file `src/api/custom/validators.ts` with the following content:
+
+```ts title="src/api/custom/validators.ts"
+import { z } from "zod"
+
+export const PostStoreCustomSchema = z.object({
+ a: z.number(),
+ b: z.number(),
+})
+```
+
+The `PostStoreCustomSchema` variable is a Zod schema that indicates the request body is valid if:
+
+1. It's an object.
+2. It has a property `a` that is a required number.
+3. It has a property `b` that is a required number.
+
+### Step 2: Add Request Body Validation Middleware
+
+To use this schema for validating the body parameters of requests to `/custom`, use the `validateAndTransformBody` middleware provided by `@medusajs/framework/http`. It accepts the Zod schema as a parameter.
+
+For example, create the file `src/api/middlewares.ts` with the following content:
+
+```ts title="src/api/middlewares.ts"
+import {
+ defineMiddlewares,
+ validateAndTransformBody,
+} from "@medusajs/framework/http"
+import { PostStoreCustomSchema } from "./custom/validators"
+
+export default defineMiddlewares({
+ routes: [
+ {
+ matcher: "/custom",
+ method: "POST",
+ middlewares: [
+ validateAndTransformBody(PostStoreCustomSchema),
+ ],
+ },
+ ],
+})
+```
+
+This applies the `validateAndTransformBody` middleware on `POST` requests to `/custom`. It uses the `PostStoreCustomSchema` as the validation schema.
+
+#### How the Validation Works
+
+If a request's body parameters don't pass the validation, the `validateAndTransformBody` middleware throws an error indicating the validation errors.
+
+If a request's body parameters are validated successfully, the middleware sets the validated body parameters in the `validatedBody` property of `MedusaRequest`.
+
+### Step 3: Use Validated Body in API Route
+
+In your API route, consume the validated body using the `validatedBody` property of `MedusaRequest`.
+
+For example, create the file `src/api/custom/route.ts` with the following content:
+
+```ts title="src/api/custom/route.ts" highlights={routeHighlights}
+import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
+import { z } from "zod"
+import { PostStoreCustomSchema } from "./validators"
+
+type PostStoreCustomSchemaType = z.infer<
+ typeof PostStoreCustomSchema
+>
+
+export const POST = async (
+ req: MedusaRequest,
+ res: MedusaResponse
+) => {
+ res.json({
+ sum: req.validatedBody.a + req.validatedBody.b,
+ })
+}
+```
+
+In the API route, you use the `validatedBody` property of `MedusaRequest` to access the values of the `a` and `b` properties.
+
+To pass the request body's type as a type parameter to `MedusaRequest`, use Zod's `infer` type that accepts the type of a schema as a parameter.
+
+### Test it Out
+
+To test out the validation, send a `POST` request to `/custom` passing `a` and `b` body parameters. You can try sending incorrect request body parameters to test out the validation.
+
+For example, if you omit the `a` parameter, you'll receive a `400` response code with the following response data:
+
+```json
+{
+ "type": "invalid_data",
+ "message": "Invalid request: Field 'a' is required"
+}
+```
+
+***
+
+## How to Validate Request Query Parameters
+
+The steps to validate the request query parameters are the similar to that of [validating the body](#how-to-validate-request-body).
+
+### Step 1: Create Validation Schema
+
+The first step is to create a schema with Zod with the rules of the accepted query parameters.
+
+Consider that the API route accepts two query parameters `a` and `b` that are numbers, similar to the previous section.
+
+Create the file `src/api/custom/validators.ts` with the following content:
+
+```ts title="src/api/custom/validators.ts"
+import { z } from "zod"
+
+export const PostStoreCustomSchema = z.object({
+ a: z.preprocess(
+ (val) => {
+ if (val && typeof val === "string") {
+ return parseInt(val)
+ }
+ return val
+ },
+ z
+ .number()
+ ),
+ b: z.preprocess(
+ (val) => {
+ if (val && typeof val === "string") {
+ return parseInt(val)
+ }
+ return val
+ },
+ z
+ .number()
+ ),
+})
+```
+
+Since a query parameter's type is originally a string or array of strings, you have to use Zod's `preprocess` method to validate other query types, such as numbers.
+
+For both `a` and `b`, you transform the query parameter's value to an integer first if it's a string, then, you check that the resulting value is a number.
+
+### Step 2: Add Request Query Validation Middleware
+
+Next, you'll use the schema to validate incoming requests' query parameters to the `/custom` API route.
+
+Add the `validateAndTransformQuery` middleware to the API route in the file `src/api/middlewares.ts`:
+
+```ts title="src/api/middlewares.ts"
+import {
+ validateAndTransformQuery,
+ defineMiddlewares,
+} from "@medusajs/framework/http"
+import { PostStoreCustomSchema } from "./custom/validators"
+
+export default defineMiddlewares({
+ routes: [
+ {
+ matcher: "/custom",
+ method: "POST",
+ middlewares: [
+ validateAndTransformQuery(
+ PostStoreCustomSchema,
+ {}
+ ),
+ ],
+ },
+ ],
+})
+```
+
+The `validateAndTransformQuery` accepts two parameters:
+
+- The first one is the Zod schema to validate the query parameters against.
+- The second one is an object of options for retrieving data using Query, which you can learn more about in [this chapter](https://docs.medusajs.com/learn/fundamentals/module-links/query/index.html.md).
+
+#### How the Validation Works
+
+If a request's query parameters don't pass the validation, the `validateAndTransformQuery` middleware throws an error indicating the validation errors.
+
+If a request's query parameters are validated successfully, the middleware sets the validated query parameters in the `validatedQuery` property of `MedusaRequest`.
+
+### Step 3: Use Validated Query in API Route
+
+Finally, use the validated query in the API route. The `MedusaRequest` parameter has a `validatedQuery` parameter that you can use to access the validated parameters.
+
+For example, create the file `src/api/custom/route.ts` with the following content:
+
+```ts title="src/api/custom/route.ts"
+import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
+
+export const GET = async (
+ req: MedusaRequest,
+ res: MedusaResponse
+) => {
+ const a = req.validatedQuery.a as number
+ const b = req.validatedQuery.b as number
+
+ res.json({
+ sum: a + b,
+ })
+}
+```
+
+In the API route, you use the `validatedQuery` property of `MedusaRequest` to access the values of the `a` and `b` properties as numbers, then return in the response their sum.
+
+### Test it Out
+
+To test out the validation, send a `POST` request to `/custom` with `a` and `b` query parameters. You can try sending incorrect query parameters to see how the validation works.
+
+For example, if you omit the `a` parameter, you'll receive a `400` response code with the following response data:
+
+```json
+{
+ "type": "invalid_data",
+ "message": "Invalid request: Field 'a' is required"
+}
+```
+
+***
+
+## Learn More About Validation Schemas
+
+To see different examples and learn more about creating a validation schema, refer to [Zod's documentation](https://zod.dev).
+
+
+# Event Data Payload
+
+In this chapter, you'll learn how subscribers receive an event's data payload.
+
+## Access Event's Data Payload
+
+When events are emitted, they’re emitted with a data payload.
+
+The object that the subscriber function receives as a parameter has an `event` property, which is an object holding the event payload in a `data` property with additional context.
+
+For example:
+
+```ts title="src/subscribers/product-created.ts" highlights={highlights} collapsibleLines="1-5" expandButtonLabel="Show Imports"
+import type {
+ SubscriberArgs,
+ SubscriberConfig,
+} from "@medusajs/framework"
+
+export default async function productCreateHandler({
+ event,
+}: SubscriberArgs<{ id: string }>) {
+ const productId = event.data.id
+ console.log(`The product ${productId} was created`)
+}
+
+export const config: SubscriberConfig = {
+ event: "product.created",
+}
+```
+
+The `event` object has the following properties:
+
+- data: (\`object\`) The data payload of the event. Its properties are different for each event.
+- name: (string) The name of the triggered event.
+- metadata: (\`object\`) Additional data and context of the emitted event.
+
+This logs the product ID received in the `product.created` event’s data payload to the console.
+
+{/* ---
+
+## List of Events with Data Payload
+
+Refer to [this reference](!resources!/references/events) for a full list of events emitted by Medusa and their data payloads. */}
+
+
# Emit Workflow and Service Events
In this chapter, you'll learn about event types and how to emit an event in a service or workflow.
@@ -11018,49 +11397,2179 @@ If you execute the `performAction` method of your service, the event is emitted
Any subscribers listening to the event are also executed.
-# Event Data Payload
+# Create a Plugin
-In this chapter, you'll learn how subscribers receive an event's data payload.
+In this chapter, you'll learn how to create a Medusa plugin and publish it.
-## Access Event's Data Payload
+A [plugin](https://docs.medusajs.com/learn/fundamentals/plugins/index.html.md) is a package of reusable Medusa customizations that you can install in any Medusa application. By creating and publishing a plugin, you can reuse your Medusa customizations across multiple projects or share them with the community.
-When events are emitted, they’re emitted with a data payload.
+Plugins are available starting from [Medusa v2.3.0](https://github.com/medusajs/medusa/releases/tag/v2.3.0).
-The object that the subscriber function receives as a parameter has an `event` property, which is an object holding the event payload in a `data` property with additional context.
+## 1. Create a Plugin Project
+
+Plugins are created in a separate Medusa project. This makes the development and publishing of the plugin easier. Later, you'll install that plugin in your Medusa application to test it out and use it.
+
+Medusa's `create-medusa-app` CLI tool provides the option to create a plugin project. Run the following command to create a new plugin project:
+
+```bash
+npx create-medusa-app my-plugin --plugin
+```
+
+This will create a new Medusa plugin project in the `my-plugin` directory.
+
+### Plugin Directory Structure
+
+After the installation is done, the plugin structure will look like this:
+
+
+
+- `src/`: Contains the Medusa customizations.
+- `src/admin`: Contains [admin extensions](https://docs.medusajs.com/learn/fundamentals/admin/index.html.md).
+- `src/api`: Contains [API routes](https://docs.medusajs.com/learn/fundamentals/api-routes/index.html.md) and [middlewares](https://docs.medusajs.com/learn/fundamentals/api-routes/middlewares/index.html.md). You can add store, admin, or any custom API routes.
+- `src/jobs`: Contains [scheduled jobs](https://docs.medusajs.com/learn/fundamentals/scheduled-jobs/index.html.md).
+- `src/links`: Contains [module links](https://docs.medusajs.com/learn/fundamentals/module-links/index.html.md).
+- `src/modules`: Contains [modules](https://docs.medusajs.com/learn/fundamentals/modules/index.html.md).
+- `src/provider`: Contains [module providers](#create-module-providers).
+- `src/subscribers`: Contains [subscribers](https://docs.medusajs.com/learn/fundamentals/events-and-subscribers/index.html.md).
+- `src/workflows`: Contains [workflows](https://docs.medusajs.com/learn/fundamentals/workflows/index.html.md). You can also add [hooks](https://docs.medusajs.com/learn/fundamentals/workflows/add-workflow-hook/index.html.md) under `src/workflows/hooks`.
+- `package.json`: Contains the plugin's package information, including general information and dependencies.
+- `tsconfig.json`: Contains the TypeScript configuration for the plugin.
+
+***
+
+## 2. Prepare Plugin
+
+### Package Name
+
+Before developing, testing, and publishing your plugin, make sure its name in `package.json` is correct. This is the name you'll use to install the plugin in your Medusa application.
For example:
-```ts title="src/subscribers/product-created.ts" highlights={highlights} collapsibleLines="1-5" expandButtonLabel="Show Imports"
-import type {
- SubscriberArgs,
- SubscriberConfig,
-} from "@medusajs/framework"
-
-export default async function productCreateHandler({
- event,
-}: SubscriberArgs<{ id: string }>) {
- const productId = event.data.id
- console.log(`The product ${productId} was created`)
-}
-
-export const config: SubscriberConfig = {
- event: "product.created",
+```json title="package.json"
+{
+ "name": "@myorg/plugin-name",
+ // ...
}
```
-The `event` object has the following properties:
+### Package Keywords
-- data: (\`object\`) The data payload of the event. Its properties are different for each event.
-- name: (string) The name of the triggered event.
-- metadata: (\`object\`) Additional data and context of the emitted event.
+Medusa scrapes NPM for a list of plugins that integrate third-party services, to later showcase them on the Medusa website. If you want your plugin to appear in that listing, make sure to add the `medusa-v2` and `medusa-plugin-integration` keywords to the `keywords` field in `package.json`.
-This logs the product ID received in the `product.created` event’s data payload to the console.
+Only plugins that integrate third-party services are listed in the Medusa integrations page. If your plugin doesn't integrate a third-party service, you can skip this step.
-{/* ---
+```json title="package.json"
+{
+ "keywords": [
+ "medusa-plugin-integration",
+ "medusa-v2"
+ ],
+ // ...
+}
+```
-## List of Events with Data Payload
+In addition, make sure to use one of the following keywords based on your integration type:
-Refer to [this reference](!resources!/references/events) for a full list of events emitted by Medusa and their data payloads. */}
+|Keyword|Description|Example|
+|---|---|---|
+|\`medusa-plugin-analytics\`|Analytics service integration|Google Analytics|
+|\`medusa-plugin-auth\`|Authentication service integration|Auth0|
+|\`medusa-plugin-cms\`|CMS service integration|Contentful|
+|\`medusa-plugin-notification\`|Notification service integration|Twilio SMS|
+|\`medusa-plugin-payment\`|Payment service integration|PayPal|
+|\`medusa-plugin-search\`|Search service integration|MeiliSearch|
+|\`medusa-plugin-shipping\`|Shipping service integration|DHL|
+|\`medusa-plugin-other\`|Other third-party integrations|Sentry|
+
+### Package Dependencies
+
+Your plugin project will already have the dependencies mentioned in this section. Unless you made changes to the dependencies, you can skip this section.
+
+In the `package.json` file you must have the Medusa dependencies as `devDependencies` and `peerDependencies`. In addition, you must have `@swc/core` as a `devDependency`, as it's used by the plugin CLI tools.
+
+For example, assuming `2.5.0` is the latest Medusa version:
+
+```json title="package.json"
+{
+ "devDependencies": {
+ "@medusajs/admin-sdk": "2.5.0",
+ "@medusajs/cli": "2.5.0",
+ "@medusajs/framework": "2.5.0",
+ "@medusajs/medusa": "2.5.0",
+ "@medusajs/test-utils": "2.5.0",
+ "@medusajs/ui": "4.0.4",
+ "@medusajs/icons": "2.5.0",
+ "@swc/core": "1.5.7",
+ },
+ "peerDependencies": {
+ "@medusajs/admin-sdk": "2.5.0",
+ "@medusajs/cli": "2.5.0",
+ "@medusajs/framework": "2.5.0",
+ "@medusajs/test-utils": "2.5.0",
+ "@medusajs/medusa": "2.5.0",
+ "@medusajs/ui": "4.0.3",
+ "@medusajs/icons": "2.5.0",
+ }
+}
+```
+
+### Package Exports
+
+Your plugin project will already have the exports mentioned in this section. Unless you made changes to the exports or you created your plugin before [Medusa v2.7.0](https://github.com/medusajs/medusa/releases/tag/v2.7.0), you can skip this section.
+
+In the `package.json` file, make sure your plugin has the following exports:
+
+```json title="package.json"
+{
+ "exports": {
+ "./package.json": "./package.json",
+ "./workflows": "./.medusa/server/src/workflows/index.js",
+ "./.medusa/server/src/modules/*": "./.medusa/server/src/modules/*/index.js",
+ "./providers/*": "./.medusa/server/src/providers/*/index.js",
+ "./admin": {
+ "import": "./.medusa/server/src/admin/index.mjs",
+ "require": "./.medusa/server/src/admin/index.js",
+ "default": "./.medusa/server/src/admin/index.js"
+ },
+ "./*": "./.medusa/server/src/*.js"
+ }
+}
+```
+
+Aside from the `./package.json`, `./providers`, and `./admin`, these exports are only a recommendation. You can cherry-pick the files and directories you want to export.
+
+The plugin exports the following files and directories:
+
+- `./package.json`: The `package.json` file. Medusa needs to access the `package.json` when registering the plugin.
+- `./workflows`: The workflows exported in `./src/workflows/index.ts`.
+- `./.medusa/server/src/modules/*`: The definition file of modules. This is useful if you create links to the plugin's modules in the Medusa application.
+- `./providers/*`: The definition file of module providers. This is useful if your plugin includes a module provider, allowing you to register the plugin's providers in Medusa applications. Learn more in the [Create Module Providers](#create-module-providers) section.
+- `./admin`: The admin extensions exported in `./src/admin/index.ts`.
+- `./*`: Any other files in the plugin's `src` directory.
+
+***
+
+## 3. Publish Plugin Locally for Development and Testing
+
+Medusa's CLI tool provides commands to simplify developing and testing your plugin in a local Medusa application. You start by publishing your plugin in the local package registry, then install it in your Medusa application. You can then watch for changes in the plugin as you develop it.
+
+### Publish and Install Local Package
+
+### Prerequisites
+
+- [Medusa application installed.](https://docs.medusajs.com/learn/installation/index.html.md)
+
+The first time you create your plugin, you need to publish the package into a local package registry, then install it in your Medusa application. This is a one-time only process.
+
+To publish the plugin to the local registry, run the following command in your plugin project:
+
+```bash title="Plugin project"
+npx medusa plugin:publish
+```
+
+This command uses [Yalc](https://github.com/wclr/yalc) under the hood to publish the plugin to a local package registry. The plugin is published locally under the name you specified in `package.json`.
+
+Next, navigate to your Medusa application:
+
+```bash title="Medusa application"
+cd ~/path/to/medusa-app
+```
+
+Make sure to replace `~/path/to/medusa-app` with the path to your Medusa application.
+
+Then, if your project was created before v2.3.1 of Medusa, make sure to install `yalc` as a development dependency:
+
+```bash npm2yarn badgeLabel="Medusa Application" badgeColor="green"
+npm install --save-dev yalc
+```
+
+After that, run the following Medusa CLI command to install the plugin:
+
+```bash title="Medusa application"
+npx medusa plugin:add @myorg/plugin-name
+```
+
+Make sure to replace `@myorg/plugin-name` with the name of your plugin as specified in `package.json`. Your plugin will be installed from the local package registry into your Medusa application.
+
+### Register Plugin in Medusa Application
+
+After installing the plugin, you need to register it in your Medusa application in the configurations defined in `medusa-config.ts`.
+
+Add the plugin to the `plugins` array in the `medusa-config.ts` file:
+
+```ts title="medusa-config.ts" highlights={pluginHighlights}
+module.exports = defineConfig({
+ // ...
+ plugins: [
+ {
+ resolve: "@myorg/plugin-name",
+ options: {},
+ },
+ ],
+})
+```
+
+The `plugins` configuration is an array of objects where each object has a `resolve` key whose value is the name of the plugin package.
+
+#### Pass Module Options through Plugin
+
+Each plugin configuration also accepts an `options` property, whose value is an object of options to pass to the plugin's modules.
+
+For example:
+
+```ts title="medusa-config.ts" highlights={pluginOptionsHighlight}
+module.exports = defineConfig({
+ // ...
+ plugins: [
+ {
+ resolve: "@myorg/plugin-name",
+ options: {
+ apiKey: true,
+ },
+ },
+ ],
+})
+```
+
+The `options` property in the plugin configuration is passed to all modules in the plugin. Learn more about module options in [this chapter](https://docs.medusajs.com/learn/fundamentals/modules/options/index.html.md).
+
+### Watch Plugin Changes During Development
+
+While developing your plugin, you can watch for changes in the plugin and automatically update the plugin in the Medusa application using it. This is the only command you'll continuously need during your plugin development.
+
+To do that, run the following command in your plugin project:
+
+```bash title="Plugin project"
+npx medusa plugin:develop
+```
+
+This command will:
+
+- Watch for changes in the plugin. Whenever a file is changed, the plugin is automatically built.
+- Publish the plugin changes to the local package registry. This will automatically update the plugin in the Medusa application using it. You can also benefit from real-time HMR updates of admin extensions.
+
+### Start Medusa Application
+
+You can start your Medusa application's development server to test out your plugin:
+
+```bash npm2yarn badgeLabel="Medusa Application" badgeColor="green"
+npm run dev
+```
+
+While your Medusa application is running and the plugin is being watched, you can test your plugin while developing it in the Medusa application.
+
+***
+
+## 4. Create Customizations in the Plugin
+
+You can now build your plugin's customizations. The following guide explains how to build different customizations in your plugin.
+
+- [Create a module](https://docs.medusajs.com/learn/fundamentals/modules/index.html.md)
+- [Create a module link](https://docs.medusajs.com/learn/fundamentals/module-links/index.html.md)
+- [Create a workflow](https://docs.medusajs.com/learn/fundamentals/workflows/index.html.md)
+- [Add a workflow hook](https://docs.medusajs.com/learn/fundamentals/workflows/add-workflow-hook/index.html.md)
+- [Create an API route](https://docs.medusajs.com/learn/fundamentals/api-routes/index.html.md)
+- [Add a subscriber](https://docs.medusajs.com/learn/fundamentals/events-and-subscribers/index.html.md)
+- [Add a scheduled job](https://docs.medusajs.com/learn/fundamentals/scheduled-jobs/index.html.md)
+- [Add an admin widget](https://docs.medusajs.com/learn/fundamentals/admin/widgets/index.html.md)
+- [Add an admin UI route](https://docs.medusajs.com/learn/fundamentals/admin/ui-routes/index.html.md)
+
+While building those customizations, you can test them in your Medusa application by [watching the plugin changes](#watch-plugin-changes-during-development) and [starting the Medusa application](#start-medusa-application).
+
+### Generating Migrations for Modules
+
+During your development, you may need to generate migrations for modules in your plugin. To do that, first, add the following environment variables in your plugin project:
+
+```plain title="Plugin project"
+DB_USERNAME=postgres
+DB_PASSWORD=123...
+DB_HOST=localhost
+DB_PORT=5432
+DB_NAME=db_name
+```
+
+You can add these environment variables in a `.env` file in your plugin project. The variables are:
+
+- `DB_USERNAME`: The username of the PostgreSQL user to connect to the database.
+- `DB_PASSWORD`: The password of the PostgreSQL user to connect to the database.
+- `DB_HOST`: The host of the PostgreSQL database. Typically, it's `localhost` if you're running the database locally.
+- `DB_PORT`: The port of the PostgreSQL database. Typically, it's `5432` if you're running the database locally.
+- `DB_NAME`: The name of the PostgreSQL database to connect to.
+
+Then, run the following command in your plugin project to generate migrations for the modules in your plugin:
+
+```bash title="Plugin project"
+npx medusa plugin:db:generate
+```
+
+This command generates migrations for all modules in the plugin.
+
+Finally, run these migrations on the Medusa application that the plugin is installed in using the `db:migrate` command:
+
+```bash title="Medusa application"
+npx medusa db:migrate
+```
+
+The migrations in your application, including your plugin, will run and update the database.
+
+### Importing Module Resources
+
+In the [Prepare Plugin](#2-prepare-plugin) section, you learned about [exported resources](#package-exports) in your plugin.
+
+These exports allow you to import your plugin resources in your Medusa application, including workflows, links and modules.
+
+For example, to import the plugin's workflow in your Medusa application:
+
+`@myorg/plugin-name` is the plugin package's name.
+
+```ts
+import { Workflow1, Workflow2 } from "@myorg/plugin-name/workflows"
+import BlogModule from "@myorg/plugin-name/modules/blog"
+// import other files created in plugin like ./src/types/blog.ts
+import BlogType from "@myorg/plugin-name/types/blog"
+```
+
+### Create Module Providers
+
+The [exported resources](#package-exports) also allow you to import module providers in your plugin and register them in the Medusa application's configuration. A module provider is a module that provides the underlying logic or integration related to a commerce or Infrastructure Module.
+
+For example, assuming your plugin has a [Notification Module Provider](https://docs.medusajs.com/resources/infrastructure-modules/notification/index.html.md) called `my-notification`, you can register it in your Medusa application's configuration like this:
+
+`@myorg/plugin-name` is the plugin package's name.
+
+```ts highlights={[["9"]]} title="medusa-config.ts"
+module.exports = defineConfig({
+ // ...
+ modules: [
+ {
+ resolve: "@medusajs/medusa/notification",
+ options: {
+ providers: [
+ {
+ resolve: "@myorg/plugin-name/providers/my-notification",
+ id: "my-notification",
+ options: {
+ channels: ["email"],
+ // provider options...
+ },
+ },
+ ],
+ },
+ },
+ ],
+})
+```
+
+You pass to `resolve` the path to the provider relative to the plugin package. So, in this example, the `my-notification` provider is located in `./src/providers/my-notification/index.ts` of the plugin.
+
+To learn how to create module providers, refer to the following guides:
+
+- [File Module Provider](https://docs.medusajs.com/resources/references/file-provider-module/index.html.md)
+- [Notification Module Provider](https://docs.medusajs.com/resources/references/notification-provider-module/index.html.md)
+- [Auth Module Provider](https://docs.medusajs.com/resources/references/auth/provider/index.html.md)
+- [Payment Module Provider](https://docs.medusajs.com/resources/references/payment/provider/index.html.md)
+- [Fulfillment Module Provider](https://docs.medusajs.com/resources/references/fulfillment/provider/index.html.md)
+- [Tax Module Provider](https://docs.medusajs.com/resources/references/tax/provider/index.html.md)
+
+***
+
+## 5. Publish Plugin to NPM
+
+Make sure to add the keywords mentioned in the [Package Keywords](#package-keywords) section in your plugin's `package.json` file.
+
+Medusa's CLI tool provides a command that bundles your plugin to be published to npm. Once you're ready to publish your plugin publicly, run the following command in your plugin project:
+
+```bash
+npx medusa plugin:build
+```
+
+The command will compile an output in the `.medusa/server` directory.
+
+You can now publish the plugin to npm using the [NPM CLI tool](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm). Run the following command to publish the plugin to npm:
+
+```bash
+npm publish
+```
+
+If you haven't logged in before with your NPM account, you'll be asked to log in first. Then, your package is published publicly to be used in any Medusa application.
+
+### Install Public Plugin in Medusa Application
+
+You install a plugin that's published publicly using your package manager. For example:
+
+```bash npm2yarn
+npm install @myorg/plugin-name
+```
+
+Where `@myorg/plugin-name` is the name of your plugin as published on NPM.
+
+Then, register the plugin in your Medusa application's configurations as explained in [this section](#register-plugin-in-medusa-application).
+
+***
+
+## Update a Published Plugin
+
+To update the Medusa dependencies in a plugin, refer to [this documentation](https://docs.medusajs.com/learn/update#update-plugin-project/index.html.md).
+
+If you've published a plugin and you've made changes to it, you'll have to publish the update to NPM again.
+
+First, run the following command to change the version of the plugin:
+
+```bash
+npm version
+```
+
+Where `` indicates the type of version update you’re publishing. For example, it can be `major` or `minor`. Refer to the [npm version documentation](https://docs.npmjs.com/cli/v10/commands/npm-version) for more information.
+
+Then, re-run the same commands for publishing a plugin:
+
+```bash
+npx medusa plugin:build
+npm publish
+```
+
+This will publish an updated version of your plugin under a new version.
+
+
+# Add Columns to a Link Table
+
+In this chapter, you'll learn how to add custom columns to a link definition's table and manage them.
+
+## Link Table's Default Columns
+
+When you define a link between two data models, Medusa creates a link table in the database to store the IDs of the linked records. You can learn more about the created table in the [Module Links chapter](https://docs.medusajs.com/learn/fundamentals/module-links/index.html.md).
+
+In various cases, you might need to store additional data in the link table. For example, if you define a link between a `product` and a `post`, you might want to store the publish date of the product's post in the link table.
+
+In those cases, you can add a custom column to a link's table in the link definition. You can later set that column whenever you create or update a link between the linked records.
+
+***
+
+## How to Add Custom Columns to a Link's Table?
+
+The `defineLink` function used to define a link accepts a third parameter, which is an object of options.
+
+To add custom columns to a link's table, pass in the third parameter of `defineLink` a `database` property:
+
+```ts highlights={linkHighlights}
+import BlogModule from "../modules/blog"
+import ProductModule from "@medusajs/medusa/product"
+import { defineLink } from "@medusajs/framework/utils"
+
+export default defineLink(
+ ProductModule.linkable.product,
+ BlogModule.linkable.blog,
+ {
+ database: {
+ extraColumns: {
+ metadata: {
+ type: "json",
+ },
+ },
+ },
+ }
+)
+```
+
+This adds to the table created for the link between `product` and `blog` a `metadata` column of type `json`.
+
+### Database Options
+
+The `database` property defines configuration for the table created in the database.
+
+Its `extraColumns` property defines custom columns to create in the link's table.
+
+`extraColumns`'s value is an object whose keys are the names of the columns, and values are the column's configurations as an object.
+
+### Column Configurations
+
+The column's configurations object accepts the following properties:
+
+- `type`: The column's type. Possible values are:
+ - `string`
+ - `text`
+ - `integer`
+ - `boolean`
+ - `date`
+ - `time`
+ - `datetime`
+ - `enum`
+ - `json`
+ - `array`
+ - `enumArray`
+ - `float`
+ - `double`
+ - `decimal`
+ - `bigint`
+ - `mediumint`
+ - `smallint`
+ - `tinyint`
+ - `blob`
+ - `uuid`
+ - `uint8array`
+- `defaultValue`: The column's default value.
+- `nullable`: Whether the column can have `null` values.
+
+***
+
+## Set Custom Column when Creating Link
+
+The object you pass to Link's `create` method accepts a `data` property. Its value is an object whose keys are custom column names, and values are the value of the custom column for this link.
+
+For example:
+
+Learn more about Link, how to resolve it, and its methods in [this chapter](https://docs.medusajs.com/learn/fundamentals/module-links/link/index.html.md).
+
+```ts
+await link.create({
+ [Modules.PRODUCT]: {
+ product_id: "123",
+ },
+ [BLOG_MODULE]: {
+ post_id: "321",
+ },
+ data: {
+ metadata: {
+ test: true,
+ },
+ },
+})
+```
+
+***
+
+## Retrieve Custom Column with Link
+
+To retrieve linked records with their custom columns, use [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query/index.html.md). A module link's definition, exported by a file under `src/links`, has a special `entryPoint` property. Use this property when specifying the `entity` property in Query's `graph` method.
+
+For example:
+
+```ts highlights={retrieveHighlights}
+import productPostLink from "../links/product-post"
+
+// ...
+
+const { data } = await query.graph({
+ entity: productPostLink.entryPoint,
+ fields: ["metadata", "product.*", "post.*"],
+ filters: {
+ product_id: "prod_123",
+ },
+})
+```
+
+This retrieves the product of id `prod_123` and its linked `post` records.
+
+In the `fields` array you pass `metadata`, which is the custom column to retrieve of the link.
+
+***
+
+## Update Custom Column's Value
+
+Link's `create` method updates a link's data if the link between the specified records already exists.
+
+So, to update the value of a custom column in a created link, use the `create` method again passing it a new value for the custom column.
+
+For example:
+
+```ts
+await link.create({
+ [Modules.PRODUCT]: {
+ product_id: "123",
+ },
+ [BLOG_MODULE]: {
+ post_id: "321",
+ },
+ data: {
+ metadata: {
+ test: false,
+ },
+ },
+})
+```
+
+
+# Scheduled Jobs Number of Executions
+
+In this chapter, you'll learn how to set a limit on the number of times a scheduled job is executed.
+
+## numberOfExecutions Option
+
+The export configuration object of the scheduled job accepts an optional property `numberOfExecutions`. Its value is a number indicating how many times the scheduled job can be executed during the Medusa application's runtime.
+
+For example:
+
+```ts highlights={highlights}
+export default async function myCustomJob() {
+ console.log("I'll be executed three times only.")
+}
+
+export const config = {
+ name: "hello-world",
+ // execute every minute
+ schedule: "* * * * *",
+ numberOfExecutions: 3,
+}
+```
+
+The above scheduled job has the `numberOfExecutions` configuration set to `3`.
+
+So, it'll only execute 3 times, each every minute, then it won't be executed anymore.
+
+If you restart the Medusa application, the scheduled job will be executed again until reaching the number of executions specified.
+
+
+# Module Link Direction
+
+In this chapter, you'll learn about the difference in module link directions, and which to use based on your use case.
+
+The details in this chapter don't apply to [Read-Only Module Links](https://docs.medusajs.com/learn/fundamentals/module-links/read-only/index.html.md). Refer to the [Read-Only Module Links chapter](https://docs.medusajs.com/learn/fundamentals/module-links/read-only/index.html.md) for more information on read-only links and their direction.
+
+## Link Direction
+
+The module link's direction depends on the order you pass the data model configuration parameters to `defineLink`.
+
+For example, the following defines a link from the Blog Module's `post` data model to the Product Module's `product` data model:
+
+```ts
+export default defineLink(
+ BlogModule.linkable.post,
+ ProductModule.linkable.product
+)
+```
+
+Whereas the following defines a link from the Product Module's `product` data model to the Blog Module's `post` data model:
+
+```ts
+export default defineLink(
+ ProductModule.linkable.product,
+ BlogModule.linkable.post
+)
+```
+
+The above links are two different links that serve different purposes.
+
+***
+
+## Which Link Direction to Use?
+
+### Extend Data Models
+
+If you're adding a link to a data model to extend it and add new fields, define the link from the main data model to the custom data model.
+
+For example, consider you want to add a `subtitle` custom field to the `product` data model. To do that, you define a `Subtitle` data model in your module, then define a link from the `Product` data model to it:
+
+```ts
+export default defineLink(
+ ProductModule.linkable.product,
+ BlogModule.linkable.subtitle
+)
+```
+
+### Associate Data Models
+
+If you're linking data models to indicate an association between them, define the link from the custom data model to the main data model.
+
+For example, consider you have `Post` data model representing a blog post, and you want to associate a blog post with a product. To do that, define a link from the `Post` data model to `Product`:
+
+```ts
+export default defineLink(
+ BlogModule.linkable.post,
+ ProductModule.linkable.product
+)
+```
+
+
+# Query
+
+In this chapter, you’ll learn about Query and how to use it to fetch data from modules.
+
+## What is Query?
+
+Query fetches data across modules. It’s a set of methods registered in the Medusa container under the `query` key.
+
+In all resources that can access the [Medusa Container](https://docs.medusajs.com/learn/fundamentals/medusa-container/index.html.md), such as API routes or workflows, you can resolve Query to fetch data across custom modules and Medusa’s Commerce Modules.
+
+***
+
+## Query Example
+
+For example, create the route `src/api/query/route.ts` with the following content:
+
+```ts title="src/api/query/route.ts" highlights={exampleHighlights} collapsibleLines="1-8" expandButtonLabel="Show Imports"
+import {
+ MedusaRequest,
+ MedusaResponse,
+} from "@medusajs/framework/http"
+import {
+ ContainerRegistrationKeys,
+} from "@medusajs/framework/utils"
+
+export const GET = async (
+ req: MedusaRequest,
+ res: MedusaResponse
+) => {
+ const query = req.scope.resolve(ContainerRegistrationKeys.QUERY)
+
+ const { data: posts } = await query.graph({
+ entity: "post",
+ fields: ["id", "title"],
+ })
+
+ res.json({ posts })
+}
+```
+
+In the above example, you resolve Query from the Medusa container using the `ContainerRegistrationKeys.QUERY` (`query`) key.
+
+Then, you run a query using its `graph` method. This method accepts as a parameter an object with the following required properties:
+
+- `entity`: The data model's name, as specified in the first parameter of the `model.define` method used for the data model's definition.
+- `fields`: An array of the data model’s properties to retrieve in the result.
+
+The method returns an object that has a `data` property, which holds an array of the retrieved data. For example:
+
+```json title="Returned Data"
+{
+ "data": [
+ {
+ "id": "123",
+ "title": "My Post"
+ }
+ ]
+}
+```
+
+***
+
+## Querying the Graph
+
+When you use the `query.graph` method, you're running a query through an internal graph that the Medusa application creates.
+
+This graph collects data models of all modules in your application, including commerce and custom modules, and identifies relations and links between them.
+
+***
+
+## Retrieve Linked Records
+
+Retrieve the records of a linked data model by passing in `fields` the data model's name suffixed with `.*`.
+
+For example:
+
+```ts highlights={[["6"]]}
+const { data: posts } = await query.graph({
+ entity: "post",
+ fields: [
+ "id",
+ "title",
+ "product.*",
+ ],
+})
+```
+
+`.*` means that all of data model's properties should be retrieved. You can also retrieve specific properties by replacing the `*` with the property name, for each property.
+
+For example:
+
+```ts
+const { data: posts } = await query.graph({
+ entity: "post",
+ fields: [
+ "id",
+ "title",
+ "product.id",
+ "product.title",
+ ],
+})
+```
+
+In the example above, you retrieve only the `id` and `title` properties of the `product` linked to a `post`.
+
+### Retrieve List Link Records
+
+If the linked data model has `isList` enabled in the link definition, pass in `fields` the data model's plural name suffixed with `.*`.
+
+For example:
+
+```ts highlights={[["6"]]}
+const { data: posts } = await query.graph({
+ entity: "post",
+ fields: [
+ "id",
+ "title",
+ "products.*",
+ ],
+})
+```
+
+In the example above, you retrieve all products linked to a post.
+
+### Apply Filters and Pagination on Linked Records
+
+Consider you want to apply filters or pagination configurations on the product(s) linked to `post`. To do that, you must query the module link's table instead.
+
+As mentioned in the [Module Link](https://docs.medusajs.com/learn/fundamentals/module-links/index.html.md) documentation, Medusa creates a table for your module link. So, not only can you retrieve linked records, but you can also retrieve the records in a module link's table.
+
+A module link's definition, exported by a file under `src/links`, has a special `entryPoint` property. Use this property when specifying the `entity` property in Query's `graph` method.
+
+For example:
+
+```ts highlights={queryLinkTableHighlights}
+import ProductPostLink from "../../../links/product-post"
+
+// ...
+
+const { data: productCustoms } = await query.graph({
+ entity: ProductPostLink.entryPoint,
+ fields: ["*", "product.*", "post.*"],
+ pagination: {
+ take: 5,
+ skip: 0,
+ },
+})
+```
+
+In the object passed to the `graph` method:
+
+- You pass the `entryPoint` property of the link definition as the value for `entity`. So, Query will retrieve records from the module link's table.
+- You pass three items to the `field` property:
+ - `*` to retrieve the link table's fields. This is useful if the link table has [custom columns](https://docs.medusajs.com/learn/fundamentals/module-links/custom-columns/index.html.md).
+ - `product.*` to retrieve the fields of a product record linked to a `Post` record.
+ - `post.*` to retrieve the fields of a `Post` record linked to a product record.
+
+You can then apply any [filters](#apply-filters) or [pagination configurations](#apply-pagination) on the module link's table. For example, you can apply filters on the `product_id`, `post_id`, and any other custom columns you defined in the link table.
+
+The returned `data` is similar to the following:
+
+```json title="Example Result"
+[{
+ "id": "123",
+ "product_id": "prod_123",
+ "post_id": "123",
+ "product": {
+ "id": "prod_123",
+ // other product fields...
+ },
+ "post": {
+ "id": "123",
+ // other post fields...
+ }
+}]
+```
+
+***
+
+## Apply Filters
+
+```ts highlights={[["4"], ["5"], ["6"]]}
+const { data: posts } = await query.graph({
+ entity: "post",
+ fields: ["id", "title"],
+ filters: {
+ id: "post_123",
+ },
+})
+```
+
+The `query.graph` function accepts a `filters` property. You can use this property to filter retrieved records.
+
+In the example above, you filter the `post` records by the ID `post_123`.
+
+You can also filter by multiple values of a property. For example:
+
+```ts highlights={[["4"], ["5"], ["6"], ["7"], ["8"], ["9"]]}
+const { data: posts } = await query.graph({
+ entity: "post",
+ fields: ["id", "title"],
+ filters: {
+ id: [
+ "post_123",
+ "post_321",
+ ],
+ },
+})
+```
+
+In the example above, you filter the `post` records by multiple IDs.
+
+Filters don't apply on fields of linked data models from other modules. Refer to the [Retrieve Linked Records](#retrieve-linked-records) section for an alternative solution.
+
+### Advanced Query Filters
+
+Under the hood, Query uses one of the following methods from the data model's module's service to retrieve records:
+
+- `listX` if you don't pass [pagination parameters](#apply-pagination). For example, `listPosts`.
+- `listAndCountX` if you pass pagination parameters. For example, `listAndCountPosts`.
+
+Both methods accepts a filter object that can be used to filter records.
+
+Those filters don't just allow you to filter by exact values. You can also filter by properties that don't match a value, match multiple values, and other filter types.
+
+Refer to the [Service Factory Reference](https://docs.medusajs.com/resources/service-factory-reference/tips/filtering/index.html.md) for examples of advanced filters. The following sections provide some quick examples.
+
+#### Filter by Not Matching a Value
+
+```ts highlights={[["4"], ["5"], ["6"], ["7"], ["8"]]}
+const { data: posts } = await query.graph({
+ entity: "post",
+ fields: ["id", "title"],
+ filters: {
+ title: {
+ $ne: null,
+ },
+ },
+})
+```
+
+In the example above, only posts that have a title are retrieved.
+
+#### Filter by Not Matching Multiple Values
+
+```ts highlights={[["4"], ["5"], ["6"], ["7"], ["8"]]}
+const { data: posts } = await query.graph({
+ entity: "post",
+ fields: ["id", "title"],
+ filters: {
+ title: {
+ $nin: ["My Post", "Another Post"],
+ },
+ },
+})
+```
+
+In the example above, only posts that don't have the title `My Post` or `Another Post` are retrieved.
+
+#### Filter by a Range
+
+```ts highlights={[["10"], ["11"], ["12"], ["13"], ["14"], ["15"]]}
+const startToday = new Date()
+startToday.setHours(0, 0, 0, 0)
+
+const endToday = new Date()
+endToday.setHours(23, 59, 59, 59)
+
+const { data: posts } = await query.graph({
+ entity: "post",
+ fields: ["id", "title"],
+ filters: {
+ published_at: {
+ $gt: startToday,
+ $lt: endToday,
+ },
+ },
+})
+```
+
+In the example above, only posts that were published today are retrieved.
+
+#### Filter Text by Like Value
+
+This filter only applies to text-like properties, including `text`, `id`, and `enum` properties.
+
+```ts highlights={[["4"], ["5"], ["6"], ["7"], ["8"]]}
+const { data: posts } = await query.graph({
+ entity: "post",
+ fields: ["id", "title"],
+ filters: {
+ title: {
+ $like: "%My%",
+ },
+ },
+})
+```
+
+In the example above, only posts that have the word `My` in their title are retrieved.
+
+#### Filter a Relation's Property
+
+```ts highlights={[["4"], ["5"], ["6"], ["7"], ["8"]]}
+const { data: posts } = await query.graph({
+ entity: "post",
+ fields: ["id", "title"],
+ filters: {
+ author: {
+ name: "John",
+ },
+ },
+})
+```
+
+While it's not possible to filter by a linked data model's property, you can filter by a relation's property (that is, the property of a related data model that is defined in the same module).
+
+In the example above, only posts that have an author with the name `John` are retrieved.
+
+***
+
+## Apply Pagination
+
+```ts highlights={[["8", "skip", "The number of records to skip before fetching the results."], ["9", "take", "The number of records to fetch."]]}
+const {
+ data: posts,
+ metadata: { count, take, skip } = {},
+} = await query.graph({
+ entity: "post",
+ fields: ["id", "title"],
+ pagination: {
+ skip: 0,
+ take: 10,
+ },
+})
+```
+
+The `graph` method's object parameter accepts a `pagination` property to configure the pagination of retrieved records.
+
+To paginate the returned records, pass the following properties to `pagination`:
+
+- `skip`: (required to apply pagination) The number of records to skip before fetching the results.
+- `take`: The number of records to fetch.
+
+When you provide the pagination fields, the `query.graph` method's returned object has a `metadata` property. Its value is an object having the following properties:
+
+- skip: (\`number\`) The number of records skipped.
+- take: (\`number\`) The number of records requested to fetch.
+- count: (\`number\`) The total number of records.
+
+### Sort Records
+
+```ts highlights={[["5"], ["6"], ["7"]]}
+const { data: posts } = await query.graph({
+ entity: "post",
+ fields: ["id", "title"],
+ pagination: {
+ order: {
+ name: "DESC",
+ },
+ },
+})
+```
+
+Sorting doesn't work on fields of linked data models from other modules.
+
+To sort returned records, pass an `order` property to `pagination`.
+
+The `order` property is an object whose keys are property names, and values are either:
+
+- `ASC` to sort records by that property in ascending order.
+- `DESC` to sort records by that property in descending order.
+
+***
+
+## Configure Query to Throw Errors
+
+By default, if Query doesn't find records matching your query, it returns an empty array. You can add option to configure Query to throw an error when no records are found.
+
+The `query.graph` method accepts as a second parameter an object that can have a `throwIfKeyNotFound` property. Its value is a boolean indicating whether to throw an error if no record is found when filtering by IDs. By default, it's `false`.
+
+For example:
+
+```ts
+const { data: posts } = await query.graph({
+ entity: "post",
+ fields: ["id", "title"],
+ filters: {
+ id: "post_123",
+ },
+}, {
+ throwIfKeyNotFound: true,
+})
+```
+
+In the example above, if no post is found with the ID `post_123`, Query will throw an error. This is useful to stop execution when a record is expected to exist.
+
+### Throw Error on Related Data Model
+
+The `throwIfKeyNotFound` option can also be used to throw an error if the ID of a related data model's record (in the same module) is passed in the filters, and the related record doesn't exist.
+
+For example:
+
+```ts
+const { data: posts } = await query.graph({
+ entity: "post",
+ fields: ["id", "title", "author.*"],
+ filters: {
+ id: "post_123",
+ author_id: "author_123",
+ },
+}, {
+ throwIfKeyNotFound: true,
+})
+```
+
+In the example above, Query throws an error either if no post is found with the ID `post_123` or if its found but its author ID isn't `author_123`.
+
+In the above example, it's assumed that a post belongs to an author, so it has an `author_id` property. However, this also works in the opposite case, where an author has many posts.
+
+For example:
+
+```ts
+const { data: posts } = await query.graph({
+ entity: "author",
+ fields: ["id", "name", "posts.*"],
+ filters: {
+ id: "author_123",
+ posts: {
+ id: "post_123",
+ },
+ },
+}, {
+ throwIfKeyNotFound: true,
+})
+```
+
+In the example above, Query throws an error if no author is found with the ID `author_123` or if the author is found but doesn't have a post with the ID `post_123`.
+
+***
+
+## Request Query Configurations
+
+For API routes that retrieve a single or list of resources, Medusa provides a `validateAndTransformQuery` middleware that:
+
+- Validates accepted query parameters, as explained in [this documentation](https://docs.medusajs.com/learn/fundamentals/api-routes/validation/index.html.md).
+- Parses configurations that are received as query parameters to be passed to Query.
+
+Using this middleware allows you to have default configurations for retrieved fields and relations or pagination, while allowing clients to customize them per request.
+
+### Step 1: Add Middleware
+
+The first step is to use the `validateAndTransformQuery` middleware on the `GET` route. You add the middleware in `src/api/middlewares.ts`:
+
+```ts title="src/api/middlewares.ts"
+import {
+ validateAndTransformQuery,
+ defineMiddlewares,
+} from "@medusajs/framework/http"
+import { createFindParams } from "@medusajs/medusa/api/utils/validators"
+
+export const GetCustomSchema = createFindParams()
+
+export default defineMiddlewares({
+ routes: [
+ {
+ matcher: "/customs",
+ method: "GET",
+ middlewares: [
+ validateAndTransformQuery(
+ GetCustomSchema,
+ {
+ defaults: [
+ "id",
+ "title",
+ "products.*",
+ ],
+ isList: true,
+ }
+ ),
+ ],
+ },
+ ],
+})
+```
+
+The `validateAndTransformQuery` accepts two parameters:
+
+1. A Zod validation schema for the query parameters, which you can learn more about in the [API Route Validation documentation](https://docs.medusajs.com/learn/fundamentals/api-routes/validation/index.html.md). Medusa has a `createFindParams` utility that generates a Zod schema that accepts four query parameters:
+ 1. `fields`: The fields and relations to retrieve in the returned resources.
+ 2. `offset`: The number of items to skip before retrieving the returned items.
+ 3. `limit`: The maximum number of items to return.
+ 4. `order`: The fields to order the returned items by in ascending or descending order.
+2. A Query configuration object. It accepts the following properties:
+ 1. `defaults`: An array of default fields and relations to retrieve in each resource.
+ 2. `isList`: A boolean indicating whether a list of items are returned in the response.
+ 3. `allowed`: An array of fields and relations allowed to be passed in the `fields` query parameter.
+ 4. `defaultLimit`: A number indicating the default limit to use if no limit is provided. By default, it's `50`.
+
+### Step 2: Use Configurations in API Route
+
+After applying this middleware, your API route now accepts the `fields`, `offset`, `limit`, and `order` query parameters mentioned above.
+
+The middleware transforms these parameters to configurations that you can pass to Query in your API route handler. These configurations are stored in the `queryConfig` parameter of the `MedusaRequest` object.
+
+As of [Medusa v2.2.0](https://github.com/medusajs/medusa/releases/tag/v2.2.0), `remoteQueryConfig` has been deprecated in favor of `queryConfig`. Their usage is still the same, only the property name has changed.
+
+For example, Create the file `src/api/customs/route.ts` with the following content:
+
+```ts title="src/api/customs/route.ts"
+import {
+ MedusaRequest,
+ MedusaResponse,
+} from "@medusajs/framework/http"
+import {
+ ContainerRegistrationKeys,
+} from "@medusajs/framework/utils"
+
+export const GET = async (
+ req: MedusaRequest,
+ res: MedusaResponse
+) => {
+ const query = req.scope.resolve(ContainerRegistrationKeys.QUERY)
+
+ const { data: posts } = await query.graph({
+ entity: "post",
+ ...req.queryConfig,
+ })
+
+ res.json({ posts: posts })
+}
+```
+
+This adds a `GET` API route at `/customs`, which is the API route you added the middleware for.
+
+In the API route, you pass `req.queryConfig` to `query.graph`. `queryConfig` has properties like `fields` and `pagination` to configure the query based on the default values you specified in the middleware, and the query parameters passed in the request.
+
+### Test it Out
+
+To test it out, start your Medusa application and send a `GET` request to the `/customs` API route. A list of records are retrieved with the specified fields in the middleware.
+
+```json title="Returned Data"
+{
+ "posts": [
+ {
+ "id": "123",
+ "title": "test"
+ }
+ ]
+}
+```
+
+Try passing one of the Query configuration parameters, like `fields` or `limit`, and you'll see its impact on the returned result.
+
+Learn more about [specifing fields and relations](https://docs.medusajs.com/api/store#select-fields-and-relations) and [pagination](https://docs.medusajs.com/api/store#pagination) in the API reference.
+
+
+# Query Context
+
+In this chapter, you'll learn how to pass contexts when retrieving data with [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query/index.html.md).
+
+## What is Query Context?
+
+Query context is a way to pass additional information when retrieving data with Query. This data can be useful when applying custom transformations to the retrieved data based on the current context.
+
+For example, consider you have a Blog Module with posts and authors. You can accept the user's language as a context and return the posts in the user's language. Another example is how Medusa uses Query Context to [retrieve product variants' prices based on the customer's currency](https://docs.medusajs.com/resources/commerce-modules/product/guides/price/index.html.md).
+
+***
+
+## How to Use Query Context
+
+The `query.graph` method accepts an optional `context` parameter that can be used to pass additional context either to the data model you're retrieving (for example, `post`), or its related and linked models (for example, `author`).
+
+You initialize a context using `QueryContext` from the Modules SDK. It accepts an object of contexts as an argument.
+
+For example, to retrieve posts using Query while passing the user's language as a context:
+
+```ts
+const { data } = await query.graph({
+ entity: "post",
+ fields: ["*"],
+ context: QueryContext({
+ lang: "es",
+ }),
+})
+```
+
+In this example, you pass in the context a `lang` property whose value is `es`.
+
+Then, to handle the context while retrieving records of the data model, in the associated module's service you override the generated `list` method of the data model.
+
+For example, continuing the example above, you can override the `listPosts` method of the Blog Module's service to handle the context:
+
+```ts highlights={highlights2}
+import { MedusaContext, MedusaService } from "@medusajs/framework/utils"
+import { Context, FindConfig } from "@medusajs/framework/types"
+import Post from "./models/post"
+import Author from "./models/author"
+
+class BlogModuleService extends MedusaService({
+ Post,
+ Author,
+}){
+ // @ts-ignore
+ async listPosts(
+ filters?: any,
+ config?: FindConfig | undefined,
+ @MedusaContext() sharedContext?: Context | undefined
+ ) {
+ const context = filters.context ?? {}
+ delete filters.context
+
+ let posts = await super.listPosts(filters, config, sharedContext)
+
+ if (context.lang === "es") {
+ posts = posts.map((post) => {
+ return {
+ ...post,
+ title: post.title + " en español",
+ }
+ })
+ }
+
+ return posts
+ }
+}
+
+export default BlogModuleService
+```
+
+In the above example, you override the generated `listPosts` method. This method receives as a first parameter the filters passed to the query, but it also includes a `context` property that holds the context passed to the query.
+
+You extract the context from `filters`, then retrieve the posts using the parent's `listPosts` method. After that, if the language is set in the context, you transform the titles of the posts.
+
+All posts returned will now have their titles appended with "en español".
+
+Learn more about the generated `list` method in [this reference](https://docs.medusajs.com/resources/service-factory-reference/methods/list/index.html.md).
+
+### Using Pagination with Query
+
+If you pass pagination fields to `query.graph`, you must also override the `listAndCount` method in the service.
+
+For example, following along with the previous example, you must override the `listAndCountPosts` method of the Blog Module's service:
+
+```ts
+import { MedusaContext, MedusaService } from "@medusajs/framework/utils"
+import { Context, FindConfig } from "@medusajs/framework/types"
+import Post from "./models/post"
+import Author from "./models/author"
+
+class BlogModuleService extends MedusaService({
+ Post,
+ Author,
+}){
+ // @ts-ignore
+ async listAndCountPosts(
+ filters?: any,
+ config?: FindConfig | undefined,
+ @MedusaContext() sharedContext?: Context | undefined
+ ) {
+ const context = filters.context ?? {}
+ delete filters.context
+
+ const result = await super.listAndCountPosts(
+ filters,
+ config,
+ sharedContext
+ )
+
+ if (context.lang === "es") {
+ result.posts = posts.map((post) => {
+ return {
+ ...post,
+ title: post.title + " en español",
+ }
+ })
+ }
+
+ return result
+ }
+}
+
+export default BlogModuleService
+```
+
+Now, the `listAndCountPosts` method will handle the context passed to `query.graph` when you pass pagination fields. You can also move the logic to transform the posts' titles to a separate method and call it from both `listPosts` and `listAndCountPosts`.
+
+***
+
+## Passing Query Context to Related Data Models
+
+If you're retrieving a data model and you want to pass context to its associated model in the same module, you can pass them as part of `QueryContext`'s parameter, then handle them in the same `list` method.
+
+For linked data models, check out the [next section](#passing-query-context-to-linked-data-models).
+
+For example, to pass a context for the post's authors:
+
+```ts highlights={highlights3}
+const { data } = await query.graph({
+ entity: "post",
+ fields: ["*"],
+ context: QueryContext({
+ lang: "es",
+ author: QueryContext({
+ lang: "es",
+ }),
+ }),
+})
+```
+
+Then, in the `listPosts` method, you can handle the context for the post's authors:
+
+```ts highlights={highlights4}
+import { MedusaContext, MedusaService } from "@medusajs/framework/utils"
+import { Context, FindConfig } from "@medusajs/framework/types"
+import Post from "./models/post"
+import Author from "./models/author"
+
+class BlogModuleService extends MedusaService({
+ Post,
+ Author,
+}){
+ // @ts-ignore
+ async listPosts(
+ filters?: any,
+ config?: FindConfig | undefined,
+ @MedusaContext() sharedContext?: Context | undefined
+ ) {
+ const context = filters.context ?? {}
+ delete filters.context
+
+ let posts = await super.listPosts(filters, config, sharedContext)
+
+ const isPostLangEs = context.lang === "es"
+ const isAuthorLangEs = context.author?.lang === "es"
+
+ if (isPostLangEs || isAuthorLangEs) {
+ posts = posts.map((post) => {
+ return {
+ ...post,
+ title: isPostLangEs ? post.title + " en español" : post.title,
+ author: {
+ ...post.author,
+ name: isAuthorLangEs ? post.author.name + " en español" : post.author.name,
+ },
+ }
+ })
+ }
+
+ return posts
+ }
+}
+
+export default BlogModuleService
+```
+
+The context in `filters` will also have the context for `author`, which you can use to make transformations to the post's authors.
+
+***
+
+## Passing Query Context to Linked Data Models
+
+If you're retrieving a data model and you want to pass context to a linked model in a different module, pass to the `context` property an object instead, where its keys are the linked model's name and the values are the context for that linked model.
+
+For example, consider the Product Module's `Product` data model is linked to the Blog Module's `Post` data model. You can pass context to the `Post` data model while retrieving products like so:
+
+```ts highlights={highlights5}
+const { data } = await query.graph({
+ entity: "product",
+ fields: ["*", "post.*"],
+ context: {
+ post: QueryContext({
+ lang: "es",
+ }),
+ },
+})
+```
+
+In this example, you retrieve products and their associated posts. You also pass a context for `post`, indicating the customer's language.
+
+To handle the context, you override the generated `listPosts` method of the Blog Module as explained [previously](#how-to-use-query-context).
+
+
+# Link
+
+In this chapter, you’ll learn what Link is and how to use it to manage links.
+
+As of [Medusa v2.2.0](https://github.com/medusajs/medusa/releases/tag/v2.2.0), Remote Link has been deprecated in favor of Link. They have the same usage, so you only need to change the key used to resolve the tool from the Medusa container as explained below.
+
+## What is Link?
+
+Link is a class with utility methods to manage links between data models. It’s registered in the Medusa container under the `link` registration name.
+
+For example:
+
+```ts collapsibleLines="1-9" expandButtonLabel="Show Imports"
+import {
+ MedusaRequest,
+ MedusaResponse,
+} from "@medusajs/framework/http"
+import {
+ ContainerRegistrationKeys,
+} from "@medusajs/framework/utils"
+
+export async function POST(
+ req: MedusaRequest,
+ res: MedusaResponse
+): Promise {
+ const link = req.scope.resolve(
+ ContainerRegistrationKeys.LINK
+ )
+
+ // ...
+}
+```
+
+You can use its methods to manage links, such as create or delete links.
+
+***
+
+## Create Link
+
+To create a link between records of two data models, use the `create` method of Link.
+
+For example:
+
+```ts
+import { Modules } from "@medusajs/framework/utils"
+
+// ...
+
+await link.create({
+ [Modules.PRODUCT]: {
+ product_id: "prod_123",
+ },
+ "helloModuleService": {
+ my_custom_id: "mc_123",
+ },
+})
+```
+
+The `create` method accepts as a parameter an object. The object’s keys are the names of the linked modules.
+
+The keys (names of linked modules) must be in the same [direction](https://docs.medusajs.com/learn/fundamentals/module-links/directions/index.html.md) of the link definition.
+
+The value of each module’s property is an object, whose keys are of the format `{data_model_snake_name}_id`, and values are the IDs of the linked record.
+
+So, in the example above, you link a record of the `MyCustom` data model in a `hello` module to a `Product` record in the Product Module.
+
+### Enforced Integrity Constraints on Link Creation
+
+Medusa enforces integrity constraints on links based on the link's relation type. So, an error is thrown in the following scenarios:
+
+- If the link is one-to-one and one of the linked records already has a link to another record of the same data model. For example:
+
+```ts
+// no error
+await link.create({
+ [Modules.PRODUCT]: {
+ product_id: "prod_123",
+ },
+ "helloModuleService": {
+ my_custom_id: "mc_123",
+ },
+})
+
+// throws an error because `prod_123` already has a link to `mc_123`
+await link.create({
+ [Modules.PRODUCT]: {
+ product_id: "prod_123",
+ },
+ "helloModuleService": {
+ my_custom_id: "mc_456",
+ },
+})
+```
+
+- If the link is one-to-many and the "one" side already has a link to another record of the same data model. For example, if a product can have many `MyCustom` records, but a `MyCustom` record can only have one product:
+
+```ts
+// no error
+await link.create({
+ [Modules.PRODUCT]: {
+ product_id: "prod_123",
+ },
+ "helloModuleService": {
+ my_custom_id: "mc_123",
+ },
+})
+
+// also no error
+await link.create({
+ [Modules.PRODUCT]: {
+ product_id: "prod_123",
+ },
+ "helloModuleService": {
+ my_custom_id: "mc_456",
+ },
+})
+
+// throws an error because `mc_123` already has a link to `prod_123`
+await link.create({
+ [Modules.PRODUCT]: {
+ product_id: "prod_456",
+ },
+ "helloModuleService": {
+ my_custom_id: "mc_123",
+ },
+})
+```
+
+There are no integrity constraints in a many-to-many link, so you can create multiple links between the same records.
+
+***
+
+## Dismiss Link
+
+To remove a link between records of two data models, use the `dismiss` method of Link.
+
+For example:
+
+```ts
+import { Modules } from "@medusajs/framework/utils"
+
+// ...
+
+await link.dismiss({
+ [Modules.PRODUCT]: {
+ product_id: "prod_123",
+ },
+ "helloModuleService": {
+ my_custom_id: "mc_123",
+ },
+})
+```
+
+The `dismiss` method accepts the same parameter type as the [create method](#create-link).
+
+The keys (names of linked modules) must be in the same [direction](https://docs.medusajs.com/learn/fundamentals/module-links/directions/index.html.md) of the link definition.
+
+***
+
+## Cascade Delete Linked Records
+
+If a record is deleted, use the `delete` method of Link to delete all linked records.
+
+For example:
+
+```ts
+import { Modules } from "@medusajs/framework/utils"
+
+// ...
+
+await productModuleService.deleteVariants([variant.id])
+
+await link.delete({
+ [Modules.PRODUCT]: {
+ product_id: "prod_123",
+ },
+})
+```
+
+This deletes all records linked to the deleted product.
+
+***
+
+## Restore Linked Records
+
+If a record that was previously soft-deleted is now restored, use the `restore` method of Link to restore all linked records.
+
+For example:
+
+```ts
+import { Modules } from "@medusajs/framework/utils"
+
+// ...
+
+await productModuleService.restoreProducts(["prod_123"])
+
+await link.restore({
+ [Modules.PRODUCT]: {
+ product_id: "prod_123",
+ },
+})
+```
+
+
+# Read-Only Module Link
+
+In this chapter, you’ll learn what a read-only module link is and how to define one.
+
+## What is a Read-Only Module Link?
+
+Consider a scenario where you need to access related records from another module, but don't want the overhead of managing or storing the links between them. This can include cases where you're working with external data models not stored in your Medusa database, such as third-party systems.
+
+In those cases, instead of defining a [Module Link](https://docs.medusajs.com/learn/fundamentals/module-links/index.html.md) whose linked records must be stored in a link table in the database, you can use a read-only module link. A read-only module link builds a virtual relation from one data model to another in a different module without creating a link table in the database. Instead, the linked record's ID is stored in the first data model's field.
+
+For example, Medusa creates a read-only module link from the `Cart` data model of the [Cart Module](https://docs.medusajs.com/resources/commerce-modules/cart/index.html.md) to the `Customer` data model of the [Customer Module](https://docs.medusajs.com/resources/commerce-modules/customer/index.html.md). This link allows you to access the details of the cart's customer without managing the link. Instead, the customer's ID is stored in the `Cart` data model.
+
+
+
+***
+
+## How to Define a Read-Only Module Link
+
+The `defineLink` function accepts an optional third-parameter object that can hold additional configurations for the module link.
+
+If you're not familiar with the `defineLink` function, refer to the [Module Links chapter](https://docs.medusajs.com/learn/fundamentals/module-links/index.html.md) for more information.
+
+To make the module link read-only, pass the `readOnly` property as `true`. You must also set in the link configuration of the first data model a `field` property that specifies the data model's field where the linked record's ID is stored.
+
+For example:
+
+```ts highlights={highlights}
+import BlogModule from "../modules/blog"
+import ProductModule from "@medusajs/medusa/product"
+import { defineLink } from "@medusajs/framework/utils"
+
+export default defineLink(
+ {
+ linkable: BlogModule.linkable.post,
+ field: "product_id",
+ },
+ ProductModule.linkable.product,
+ {
+ readOnly: true,
+ }
+)
+```
+
+In this example, you define a read-only module link from the Blog Module's `post` data model to the Product Module's `product` data model. You do that by:
+
+- Passing an object as a first parameter that accepts the linkable configuration and the field where the linked record's ID is stored.
+- Setting the `readOnly` property to `true` in the third parameter.
+
+Unlike the stored module link, Medusa will not create a table in the database for this link. Instead, Medusa uses the ID stored in the specified field of the first data model to retrieve the linked record.
+
+***
+
+## Retrieve Read-Only Linked Record
+
+[Query](https://docs.medusajs.com/learn/fundamentals/module-links/query/index.html.md) allows you to retrieve records linked through a read-only module link.
+
+For example, assuming you have the module link created in [the above section](#how-to-define-a-read-only-module-link), you can retrieve a post and its linked product as follows:
+
+```ts
+const { result } = await query.graph({
+ entity: "post",
+ fields: ["id", "product.*"],
+ filters: {
+ id: "post_123",
+ },
+})
+```
+
+In the above example, you retrieve a post and its linked product. Medusa will use the ID of the product in the post's `product_id` field to determine which product should be retrieved.
+
+***
+
+## Read-Only Module Link Direction
+
+A read-only module is uni-directional. So, you can only retrieve the linked record from the first data model. If you need to access the linked record from the second data model, you must define another read-only module link in the opposite direction.
+
+In the `blog` -> `product` example, you can access a post's product, but you can't access a product's posts. You would have to define another read-only module link from `product` to `blog` to access a product's posts.
+
+***
+
+## Inverse Read-Only Module Link
+
+An inverse read-only module link is a read-only module link that allows you to access the linked record based on the ID stored in the second data model.
+
+For example, consider you want to access a product's posts. You can define a read-only module link from the Product Module's `product` data model to the Blog Module's `post` data model:
+
+```ts
+import BlogModule from "../modules/blog"
+import ProductModule from "@medusajs/medusa/product"
+import { defineLink } from "@medusajs/framework/utils"
+
+export default defineLink(
+ {
+ linkable: ProductModule.linkable.product,
+ field: "id",
+ },
+ {
+ ...BlogModule.linkable.post.id,
+ primaryKey: "product_id",
+ },
+ {
+ readOnly: true,
+ }
+)
+```
+
+In the above example, you define a read-only module link from the Product Module's `product` data model to the Blog Module's `post` data model. This link allows you to access a product's posts.
+
+Since you can't add a `post_id` field to the `product` data model, you must:
+
+1. Set the `field` property in the first data model's link configuration to the product's ID field.
+2. Spread the `BlogModule.linkable.post.id` object in the second parameter object and set the `primaryKey` property to the field in the `post` data model that holds the product's ID.
+
+You can now retrieve a product and its linked posts:
+
+```ts
+const { result } = await query.graph({
+ entity: "product",
+ fields: ["id", "post.*"],
+ filters: {
+ id: "prod_123",
+ },
+})
+```
+
+***
+
+## One-to-One or One-to-Many?
+
+When you retrieve the linked record through a read-only module link, the retrieved data may be an object (one-to-one) or an array of objects (one-to-many) based on different criteria.
+
+|Scenario|Relation Type|
+|---|---|---|
+|The first data model's |One-to-one relation|
+|The first data model's |One-to-many relation|
+|The read-only module link is inversed.|One-to-many relation if multiple records in the second data model have the same ID of the first data model. Otherwise, one-to-one relation.|
+
+### One-to-One Relation
+
+Consider the first read-only module link you defined in this chapter:
+
+```ts
+import BlogModule from "../modules/blog"
+import ProductModule from "@medusajs/medusa/product"
+
+export default defineLink(
+ {
+ linkable: BlogModule.linkable.post,
+ field: "product_id",
+ },
+ ProductModule.linkable.product,
+ {
+ readOnly: true,
+ }
+)
+```
+
+Since the `product_id` field of a post stores the ID of a single product, the link is a one-to-one relation. When querying a post, you'll get a single product object:
+
+```json title="Example Data"
+[
+ {
+ "id": "post_123",
+ "product_id": "prod_123",
+ "product": {
+ "id": "prod_123",
+ // ...
+ }
+ }
+]
+```
+
+### One-to-Many Relation
+
+Consider the read-only module link from the `post` data model uses an array of product IDs:
+
+```ts
+import BlogModule from "../modules/blog"
+import ProductModule from "@medusajs/medusa/product"
+
+export default defineLink(
+ {
+ linkable: BlogModule.linkable.post,
+ field: "product_ids",
+ },
+ ProductModule.linkable.product,
+ {
+ readOnly: true,
+ }
+)
+```
+
+Where `product_ids` in the `post` data model is an array of strings. In this case, the link would be a one-to-many relation. So, an array of products would be returned when querying a post:
+
+```json title="Example Data"
+[
+ {
+ "id": "post_123",
+ "product_ids": ["prod_123", "prod_124"],
+ "product": [
+ {
+ "id": "prod_123",
+ // ...
+ },
+ {
+ "id": "prod_124",
+ // ...
+ }
+ ]
+ }
+]
+```
+
+### Relation with Inversed Read-Only Link
+
+If you define an inversed read-only module link where the ID of the linked record is stored in the second data model, the link can be either one-to-one or one-to-many based on the number of records in the second data model that have the same ID of the first data model.
+
+For example, consider the `product` -> `post` link you defined in an earlier section:
+
+```ts
+import BlogModule from "../modules/blog"
+import ProductModule from "@medusajs/medusa/product"
+import { defineLink } from "@medusajs/framework/utils"
+
+export default defineLink(
+ {
+ linkable: ProductModule.linkable.product,
+ field: "id",
+ },
+ {
+ ...BlogModule.linkable.post.id,
+ primaryKey: "product_id",
+ },
+ {
+ readOnly: true,
+ }
+)
+```
+
+In the above snippet, the ID of the product is stored in the `post`'s `product_id` string field.
+
+When you retrieve the post of a product, it may be a post object, or an array of post objects if multiple posts are linked to the product:
+
+```json title="Example Data"
+[
+ {
+ "id": "prod_123",
+ "post": {
+ "id": "post_123",
+ "product_id": "prod_123"
+ // ...
+ }
+ },
+ {
+ "id": "prod_321",
+ "post": [
+ {
+ "id": "post_123",
+ "product_id": "prod_321"
+ // ...
+ },
+ {
+ "id": "post_124",
+ "product_id": "prod_321"
+ // ...
+ }
+ ]
+ }
+]
+```
+
+If, however, you use an array field in `post`, the relation would always be one-to-many:
+
+```json title="Example Data"
+[
+ {
+ "id": "prod_123",
+ "post": [
+ {
+ "id": "post_123",
+ "product_id": "prod_123"
+ // ...
+ }
+ ]
+ }
+]
+```
+
+#### Force One-to-Many Relation
+
+Alternatively, you can force a one-to-many relation by setting `isList` to `true` in the first data model's link configuration. For example:
+
+```ts
+import BlogModule from "../modules/blog"
+import ProductModule from "@medusajs/medusa/product"
+import { defineLink } from "@medusajs/framework/utils"
+
+export default defineLink(
+ {
+ linkable: ProductModule.linkable.product,
+ field: "id",
+ isList: true,
+ },
+ {
+ ...BlogModule.linkable.post.id,
+ primaryKey: "product_id",
+ },
+ {
+ readOnly: true,
+ }
+)
+```
+
+In this case, the relation would always be one-to-many, even if only one post is linked to a product:
+
+```json title="Example Data"
+[
+ {
+ "id": "prod_123",
+ "post": [
+ {
+ "id": "post_123",
+ "product_id": "prod_123"
+ // ...
+ }
+ ]
+ }
+]
+```
+
+***
+
+## Example: Read-Only Module Link for Virtual Data Models
+
+Read-only module links are most useful when working with data models that aren't stored in your Medusa database. For example, data that is stored in a third-party system. In those cases, you can define a read-only module link between a data model in Medusa and the data model in the external system, facilitating the retrieval of the linked data.
+
+To define the read-only module link to a virtual data model, you must:
+
+1. Create a `list` method in the custom module's service. This method retrieves the linked records filtered by the ID(s) of the first data model.
+ - You can also create a `listAndCount` method to retrieve the related records with pagination.
+2. Define the read-only module link from the first data model to the virtual data model.
+3. Use Query to retrieve the first data model and its linked records from the virtual data model.
+
+For example, consider you have a third-party Content-Management System (CMS) that you're integrating with Medusa, and you want to retrieve the posts in the CMS associated with a product in Medusa.
+
+To do that, first, create a CMS Module having the following service:
+
+Refer to the [Modules chapter](https://docs.medusajs.com/learn/fundamentals/modules/index.html.md) to learn how to create a module and its service.
+
+```ts title="src/modules/cms/service.ts"
+import { FindConfig } from "@medusajs/framework/types"
+
+type CmsModuleOptions = {
+ apiKey: string
+}
+
+export default class CmsModuleService {
+ private client
+
+ constructor({}, options: CmsModuleOptions) {
+ this.client = new Client(options)
+ }
+
+ async list(
+ filter: {
+ id: string | string[]
+ }
+ ) {
+ return this.client.getPosts(filter)
+ /**
+ - Example of returned data:
+ -
+ - [
+ - {
+ - "id": "post_123",
+ - "product_id": "prod_321"
+ - },
+ - {
+ - "id": "post_456",
+ - "product_id": "prod_654"
+ - }
+ - ]
+ */
+ }
+
+ // To retrieve with pagination
+ async listAndCount(
+ filter: {
+ id: string | string[]
+ },
+ config?: FindConfig | undefined
+ ) {
+ return this.client.getPosts(filter, {
+ limit: config?.take,
+ offset: config?.skip,
+ })
+ /**
+ - Example of returned data:
+ -
+ - {
+ - count: 2,
+ - data: [
+ - {
+ - "id": "post_123",
+ - "product_id": "prod_321"
+ - },
+ - {
+ - "id": "post_456",
+ - "product_id": "prod_654"
+ - }
+ - ]
+ - }
+ */
+ }
+}
+```
+
+The above service initializes a client, assuming your CMS has an SDK that allows you to retrieve posts.
+
+The service must have a `list` method to be part of the read-only module link. This method accepts the ID(s) of the products to retrieve their associated posts. The posts must include the product's ID in a field, such as `product_id`.
+
+You can also create a `listAndCount` method to retrieve the posts with pagination. This method is called if you pass [pagination parameters to Query](https://docs.medusajs.com/learn/fundamentals/module-links/query#apply-pagination/index.html.md).
+
+Next, define a read-only module link from the Product Module to the CMS Module:
+
+```ts title="src/links/product-cms.ts"
+import { defineLink } from "@medusajs/framework/utils"
+import ProductModule from "@medusajs/medusa/product"
+import { CMS_MODULE } from "../modules/cms"
+
+export default defineLink(
+ {
+ linkable: ProductModule.linkable.product,
+ field: "id",
+ },
+ {
+ linkable: {
+ serviceName: CMS_MODULE,
+ alias: "cms_post",
+ primaryKey: "product_id",
+ },
+ },
+ {
+ readOnly: true,
+ }
+)
+```
+
+To define the read-only module link, you must pass to `defineLink`:
+
+1. The first parameter: an object with the linkable configuration of the data model in Medusa, and the fields that will be passed as a filter to the CMS service. For example, if you want to filter by product title instead, you can pass `title` instead of `id`.
+2. The second parameter: an object with the linkable configuration of the virtual data model in the CMS. This object must have the following properties:
+ - `serviceName`: The name of the service, which is the CMS Module's name. Medusa uses this name to resolve the module's service from the [Medusa container](https://docs.medusajs.com/learn/fundamentals/medusa-container/index.html.md).
+ - `alias`: The alias to use when querying the linked records. You'll see how that works in a bit.
+ - `primaryKey`: The field in the CMS data model that holds the ID of a product.
+3. The third parameter: an object with the `readOnly` property set to `true`.
+
+Now, you can use Query to retrieve a product and its linked post from the CMS:
+
+```ts
+const { data } = await query.graph({
+ entity: "product",
+ fields: ["id", "cms_post.*"],
+})
+```
+
+In the above example, each product that has a CMS post with the `product_id` field set to the product's ID will be retrieved:
+
+```json title="Example Data"
+[
+ {
+ "id": "prod_123",
+ "cms_post": {
+ "id": "post_123",
+ "product_id": "prod_123",
+ // ...
+ }
+ }
+]
+```
+
+If multiple posts have their `product_id` set to a product's ID, an array of posts is returned instead:
+
+```json title="Example Data"
+[
+ {
+ "id": "prod_123",
+ "cms_post": [
+ {
+ "id": "post_123",
+ "product_id": "prod_123",
+ // ...
+ },
+ {
+ "id": "post_124",
+ "product_id": "prod_123",
+ // ...
+ }
+ ]
+ }
+]
+```
+
+[Sanity Integration Tutorial](https://docs.medusajs.com/resources/integrations/guides/sanity/index.html.md).
# Commerce Modules
@@ -11173,506 +13682,6 @@ export default async function helloWorldLoader({
```
-# Infrastructure Modules
-
-In this chapter, you’ll learn about Infrastructure Modules.
-
-## What is an Infrastructure Module?
-
-An Infrastructure Module implements features and mechanisms related to the Medusa application’s architecture and infrastructure.
-
-Since modules are interchangeable, you have more control over Medusa’s architecture. For example, you can choose to use Memcached for event handling instead of Redis.
-
-***
-
-## Infrastructure Module Types
-
-There are different Infrastructure Module types including:
-
-
-
-- Cache Module: Defines the caching mechanism or logic to cache computational results.
-- Event Module: Integrates a pub/sub service to handle subscribing to and emitting events.
-- Workflow Engine Module: Integrates a service to store and track workflow executions and steps.
-- File Module: Integrates a storage service to handle uploading and managing files.
-- Notification Module: Integrates a third-party service or defines custom logic to send notifications to users and customers.
-- Locking Module: Integrates a service that manages access to shared resources by multiple processes or threads.
-
-***
-
-## Infrastructure Modules List
-
-Refer to the [Infrastructure Modules reference](https://docs.medusajs.com/resources/infrastructure-modules/index.html.md) for a list of Medusa’s Infrastructure Modules, available modules to install, and how to create an Infrastructure Module.
-
-
-# Seed Data with Custom CLI Script
-
-In this chapter, you'll learn how to seed data using a custom CLI script.
-
-## How to Seed Data
-
-To seed dummy data for development or demo purposes, use a custom CLI script.
-
-In the CLI script, use your custom workflows or Medusa's existing workflows, which you can browse in [this reference](https://docs.medusajs.com/resources/medusa-workflows-reference/index.html.md), to seed data.
-
-### Example: Seed Dummy Products
-
-In this section, you'll follow an example of creating a custom CLI script that seeds fifty dummy products.
-
-First, install the [Faker](https://fakerjs.dev/) library to generate random data in your script:
-
-```bash npm2yarn
-npm install --save-dev @faker-js/faker
-```
-
-Then, create the file `src/scripts/demo-products.ts` with the following content:
-
-```ts title="src/scripts/demo-products.ts" highlights={highlights} collapsibleLines="1-12" expandButtonLabel="Show Imports"
-import { ExecArgs } from "@medusajs/framework/types"
-import { faker } from "@faker-js/faker"
-import {
- ContainerRegistrationKeys,
- Modules,
- ProductStatus,
-} from "@medusajs/framework/utils"
-import {
- createInventoryLevelsWorkflow,
- createProductsWorkflow,
-} from "@medusajs/medusa/core-flows"
-
-export default async function seedDummyProducts({
- container,
-}: ExecArgs) {
- const salesChannelModuleService = container.resolve(
- Modules.SALES_CHANNEL
- )
- const logger = container.resolve(
- ContainerRegistrationKeys.LOGGER
- )
- const query = container.resolve(
- ContainerRegistrationKeys.QUERY
- )
-
- const defaultSalesChannel = await salesChannelModuleService
- .listSalesChannels({
- name: "Default Sales Channel",
- })
-
- const sizeOptions = ["S", "M", "L", "XL"]
- const colorOptions = ["Black", "White"]
- const currency_code = "eur"
- const productsNum = 50
-
- // TODO seed products
-}
-```
-
-So far, in the script, you:
-
-- Resolve the Sales Channel Module's main service to retrieve the application's default sales channel. This is the sales channel the dummy products will be available in.
-- Resolve the Logger to log messages in the terminal, and Query to later retrieve data useful for the seeded products.
-- Initialize some default data to use when seeding the products next.
-
-Next, replace the `TODO` with the following:
-
-```ts title="src/scripts/demo-products.ts"
-const productsData = new Array(productsNum).fill(0).map((_, index) => {
- const title = faker.commerce.product() + "_" + index
- return {
- title,
- is_giftcard: true,
- description: faker.commerce.productDescription(),
- status: ProductStatus.PUBLISHED,
- options: [
- {
- title: "Size",
- values: sizeOptions,
- },
- {
- title: "Color",
- values: colorOptions,
- },
- ],
- images: [
- {
- url: faker.image.urlPlaceholder({
- text: title,
- }),
- },
- {
- url: faker.image.urlPlaceholder({
- text: title,
- }),
- },
- ],
- variants: new Array(10).fill(0).map((_, variantIndex) => ({
- title: `${title} ${variantIndex}`,
- sku: `variant-${variantIndex}${index}`,
- prices: new Array(10).fill(0).map((_, priceIndex) => ({
- currency_code,
- amount: 10 * priceIndex,
- })),
- options: {
- Size: sizeOptions[Math.floor(Math.random() * 3)],
- },
- })),
- shipping_profile_id: "sp_123",
- sales_channels: [
- {
- id: defaultSalesChannel[0].id,
- },
- ],
- }
-})
-
-// TODO seed products
-```
-
-You generate fifty products using the sales channel and variables you initialized, and using Faker for random data, such as the product's title or images.
-
-Then, replace the new `TODO` with the following:
-
-```ts title="src/scripts/demo-products.ts"
-const { result: products } = await createProductsWorkflow(container).run({
- input: {
- products: productsData,
- },
-})
-
-logger.info(`Seeded ${products.length} products.`)
-
-// TODO add inventory levels
-```
-
-You create the generated products using the `createProductsWorkflow` imported previously from `@medusajs/medusa/core-flows`. It accepts the product data as input, and returns the created products.
-
-Only thing left is to create inventory levels for the products. So, replace the last `TODO` with the following:
-
-```ts title="src/scripts/demo-products.ts"
-logger.info("Seeding inventory levels.")
-
-const { data: stockLocations } = await query.graph({
- entity: "stock_location",
- fields: ["id"],
-})
-
-const { data: inventoryItems } = await query.graph({
- entity: "inventory_item",
- fields: ["id"],
-})
-
-const inventoryLevels = inventoryItems.map((inventoryItem) => ({
- location_id: stockLocations[0].id,
- stocked_quantity: 1000000,
- inventory_item_id: inventoryItem.id,
-}))
-
-await createInventoryLevelsWorkflow(container).run({
- input: {
- inventory_levels: inventoryLevels,
- },
-})
-
-logger.info("Finished seeding inventory levels data.")
-```
-
-You use Query to retrieve the stock location, to use the first location in the application, and the inventory items.
-
-Then, you generate inventory levels for each inventory item, associating it with the first stock location.
-
-Finally, you use the `createInventoryLevelsWorkflow` from Medusa's core workflows to create the inventory levels.
-
-### Test Script
-
-To test out the script, run the following command in your project's directory:
-
-```bash
-npx medusa exec ./src/scripts/demo-products.ts
-```
-
-This seeds the products to your database. If you run your Medusa application and view the products in the dashboard, you'll find fifty new products.
-
-
-# Loaders
-
-In this chapter, you’ll learn about loaders and how to use them.
-
-## What is a Loader?
-
-When building a commerce application, you'll often need to execute an action the first time the application starts. For example, if your application needs to connect to databases other than Medusa's PostgreSQL database, you might need to establish a connection on application startup.
-
-In Medusa, you can execute an action when the application starts using a loader. A loader is a function exported by a [module](https://docs.medusajs.com/learn/fundamentals/modules/index.html.md), which is a package of business logic for a single domain. When the Medusa application starts, it executes all loaders exported by configured modules.
-
-Loaders are useful to register custom resources, such as database connections, in the [module's container](https://docs.medusajs.com/learn/fundamentals/modules/container/index.html.md), which is similar to the [Medusa container](https://docs.medusajs.com/learn/fundamentals/medusa-container/index.html.md) but includes only [resources available to the module](https://docs.medusajs.com/resources/medusa-container-resources#module-container-resources/index.html.md). Modules are isolated, so they can't access resources outside of them, such as a service in another module.
-
-Medusa isolates modules to ensure that they're re-usable across applications, aren't tightly coupled to other resources, and don't have implications when integrated into the Medusa application. Learn more about why modules are isolated in [this chapter](https://docs.medusajs.com/learn/fundamentals/modules/isolation/index.html.md), and check out [this reference for the list of resources in the module's container](https://docs.medusajs.com/resources/medusa-container-resources#module-container-resources/index.html.md).
-
-***
-
-## How to Create a Loader?
-
-### 1. Implement Loader Function
-
-You create a loader function in a TypeScript or JavaScript file under a module's `loaders` directory.
-
-For example, consider you have a `hello` module, you can create a loader at `src/modules/hello/loaders/hello-world.ts` with the following content:
-
-
-
-Learn how to create a module in [this chapter](https://docs.medusajs.com/learn/fundamentals/modules/index.html.md).
-
-```ts title="src/modules/hello/loaders/hello-world.ts"
-import {
- LoaderOptions,
-} from "@medusajs/framework/types"
-
-export default async function helloWorldLoader({
- container,
-}: LoaderOptions) {
- const logger = container.resolve("logger")
-
- logger.info("[HELLO MODULE] Just started the Medusa application!")
-}
-```
-
-The loader file exports an async function, which is the function executed when the application loads.
-
-The function receives an object parameter that has a `container` property, which is the module's container that you can use to resolve resources from. In this example, you resolve the Logger utility to log a message in the terminal.
-
-Find the list of resources in the module's container in [this reference](https://docs.medusajs.com/resources/medusa-container-resources#module-container-resources/index.html.md).
-
-### 2. Export Loader in Module Definition
-
-After implementing the loader, you must export it in the module's definition in the `index.ts` file at the root of the module's directory. Otherwise, the Medusa application will not run it.
-
-So, to export the loader you implemented above in the `hello` module, add the following to `src/modules/hello/index.ts`:
-
-```ts title="src/modules/hello/index.ts"
-// other imports...
-import helloWorldLoader from "./loaders/hello-world"
-
-export default Module("hello", {
- // ...
- loaders: [helloWorldLoader],
-})
-```
-
-The second parameter of the `Module` function accepts a `loaders` property whose value is an array of loader functions. The Medusa application will execute these functions when it starts.
-
-### Test the Loader
-
-Assuming your module is [added to Medusa's configuration](https://docs.medusajs.com/learn/fundamentals/modules#4-add-module-to-medusas-configurations/index.html.md), you can test the loader by starting the Medusa application:
-
-```bash npm2yarn
-npm run dev
-```
-
-Then, you'll find the following message logged in the terminal:
-
-```plain
-info: [HELLO MODULE] Just started the Medusa application!
-```
-
-This indicates that the loader in the `hello` module ran and logged this message.
-
-***
-
-## When are Loaders Executed?
-
-When you start the Medusa application, it executes the loaders of all modules in their registration order.
-
-A loader is executed before the module's main service is instantiated. So, you can use loaders to register in the module's container resources that you want to use in the module's service. For example, you can register a database connection.
-
-Loaders are also useful to only load a module if a certain condition is met. For example, if you try to connect to a database in a loader but the connection fails, you can throw an error in the loader to prevent the module from being loaded. This is useful if your module depends on an external service to work.
-
-***
-
-## Example: Register Custom MongoDB Connection
-
-As mentioned in this chapter's introduction, loaders are most useful when you need to register a custom resource in the module's container to re-use it in other customizations in the module.
-
-Consider your have a MongoDB module that allows you to perform operations on a MongoDB database.
-
-### Prerequisites
-
-- [MongoDB database that you can connect to from a local machine.](https://www.mongodb.com)
-- [Install the MongoDB SDK in your Medusa application.](https://www.mongodb.com/docs/drivers/node/current/quick-start/download-and-install/#install-the-node.js-driver)
-
-To connect to the database, you create the following loader in your module:
-
-```ts title="src/modules/mongo/loaders/connection.ts" highlights={loaderHighlights}
-import { LoaderOptions } from "@medusajs/framework/types"
-import { asValue } from "awilix"
-import { MongoClient } from "mongodb"
-
-type ModuleOptions = {
- connection_url?: string
- db_name?: string
-}
-
-export default async function mongoConnectionLoader({
- container,
- options,
-}: LoaderOptions) {
- if (!options.connection_url) {
- throw new Error(`[MONGO MDOULE]: connection_url option is required.`)
- }
- if (!options.db_name) {
- throw new Error(`[MONGO MDOULE]: db_name option is required.`)
- }
- const logger = container.resolve("logger")
-
- try {
- const clientDb = (
- await (new MongoClient(options.connection_url)).connect()
- ).db(options.db_name)
-
- logger.info("Connected to MongoDB")
-
- container.register(
- "mongoClient",
- asValue(clientDb)
- )
- } catch (e) {
- logger.error(
- `[MONGO MDOULE]: An error occurred while connecting to MongoDB: ${e}`
- )
- }
-}
-```
-
-The loader function accepts in its object parameter an `options` property, which is the options passed to the module in Medusa's configurations. For example:
-
-```ts title="medusa-config.ts" highlights={optionHighlights}
-module.exports = defineConfig({
- // ...
- modules: [
- {
- resolve: "./src/modules/mongo",
- options: {
- connection_url: process.env.MONGO_CONNECTION_URL,
- db_name: process.env.MONGO_DB_NAME,
- },
- },
- ],
-})
-```
-
-Passing options is useful when your module needs informations like connection URLs or API keys, as it ensures your module can be re-usable across applications. For the MongoDB Module, you expect two options:
-
-- `connection_url`: the URL to connect to the MongoDB database.
-- `db_name`: The name of the database to connect to.
-
-In the loader, you check first that these options are set before proceeding. Then, you create an instance of the MongoDB client and connect to the database specified in the options.
-
-After creating the client, you register it in the module's container using the container's `register` method. The method accepts two parameters:
-
-1. The key to register the resource under, which in this case is `mongoClient`. You'll use this name later to resolve the client.
-2. The resource to register in the container, which is the MongoDB client you created. However, you don't pass the resource as-is. Instead, you need to use an `asValue` function imported from the [awilix package](https://github.com/jeffijoe/awilix), which is the package used to implement the container functionality in Medusa.
-
-### Use Custom Registered Resource in Module's Service
-
-After registering the custom MongoDB client in the module's container, you can now resolve and use it in the module's service.
-
-For example:
-
-```ts title="src/modules/mongo/service.ts"
-import type { Db } from "mongodb"
-
-type InjectedDependencies = {
- mongoClient: Db
-}
-
-export default class MongoModuleService {
- private mongoClient_: Db
-
- constructor({ mongoClient }: InjectedDependencies) {
- this.mongoClient_ = mongoClient
- }
-
- async createMovie({ title }: {
- title: string
- }) {
- const moviesCol = this.mongoClient_.collection("movie")
-
- const insertedMovie = await moviesCol.insertOne({
- title,
- })
-
- const movie = await moviesCol.findOne({
- _id: insertedMovie.insertedId,
- })
-
- return movie
- }
-
- async deleteMovie(id: string) {
- const moviesCol = this.mongoClient_.collection("movie")
-
- await moviesCol.deleteOne({
- _id: {
- equals: id,
- },
- })
- }
-}
-```
-
-The service `MongoModuleService` resolves the `mongoClient` resource you registered in the loader and sets it as a class property. You then use it in the `createMovie` and `deleteMovie` methods, which create and delete a document in a `movie` collection in the MongoDB database, respectively.
-
-Make sure to export the loader in the module's definition in the `index.ts` file at the root directory of the module:
-
-```ts title="src/modules/mongo/index.ts" highlights={[["9"]]}
-import { Module } from "@medusajs/framework/utils"
-import MongoModuleService from "./service"
-import mongoConnectionLoader from "./loaders/connection"
-
-export const MONGO_MODULE = "mongo"
-
-export default Module(MONGO_MODULE, {
- service: MongoModuleService,
- loaders: [mongoConnectionLoader],
-})
-```
-
-### Test it Out
-
-You can test the connection out by starting the Medusa application. If it's successful, you'll see the following message logged in the terminal:
-
-```bash
-info: Connected to MongoDB
-```
-
-You can now resolve the MongoDB Module's main service in your customizations to perform operations on the MongoDB database.
-
-
-# Modules Directory Structure
-
-In this document, you'll learn about the expected files and directories in your module.
-
-
-
-## index.ts
-
-The `index.ts` file in the root of your module's directory is the only required file. It must export the module's definition as explained in a [previous chapter](https://docs.medusajs.com/learn/fundamentals/modules/index.html.md).
-
-***
-
-## service.ts
-
-A module must have a main service. It's created in the `service.ts` file at the root of your module directory as explained in a [previous chapter](https://docs.medusajs.com/learn/fundamentals/modules/index.html.md).
-
-***
-
-## Other Directories
-
-The following directories are optional and their content are explained more in the following chapters:
-
-- `models`: Holds the data models representing tables in the database.
-- `migrations`: Holds the migration files used to reflect changes on the database.
-- `loaders`: Holds the scripts to run on the Medusa application's start-up.
-
-
# Perform Database Operations in a Service
In this chapter, you'll learn how to perform database operations in a module's service.
@@ -12280,6 +14289,419 @@ class BlogModuleService {
```
+# Infrastructure Modules
+
+In this chapter, you’ll learn about Infrastructure Modules.
+
+## What is an Infrastructure Module?
+
+An Infrastructure Module implements features and mechanisms related to the Medusa application’s architecture and infrastructure.
+
+Since modules are interchangeable, you have more control over Medusa’s architecture. For example, you can choose to use Memcached for event handling instead of Redis.
+
+***
+
+## Infrastructure Module Types
+
+There are different Infrastructure Module types including:
+
+
+
+- Cache Module: Defines the caching mechanism or logic to cache computational results.
+- Event Module: Integrates a pub/sub service to handle subscribing to and emitting events.
+- Workflow Engine Module: Integrates a service to store and track workflow executions and steps.
+- File Module: Integrates a storage service to handle uploading and managing files.
+- Notification Module: Integrates a third-party service or defines custom logic to send notifications to users and customers.
+- Locking Module: Integrates a service that manages access to shared resources by multiple processes or threads.
+
+***
+
+## Infrastructure Modules List
+
+Refer to the [Infrastructure Modules reference](https://docs.medusajs.com/resources/infrastructure-modules/index.html.md) for a list of Medusa’s Infrastructure Modules, available modules to install, and how to create an Infrastructure Module.
+
+
+# Loaders
+
+In this chapter, you’ll learn about loaders and how to use them.
+
+## What is a Loader?
+
+When building a commerce application, you'll often need to execute an action the first time the application starts. For example, if your application needs to connect to databases other than Medusa's PostgreSQL database, you might need to establish a connection on application startup.
+
+In Medusa, you can execute an action when the application starts using a loader. A loader is a function exported by a [module](https://docs.medusajs.com/learn/fundamentals/modules/index.html.md), which is a package of business logic for a single domain. When the Medusa application starts, it executes all loaders exported by configured modules.
+
+Loaders are useful to register custom resources, such as database connections, in the [module's container](https://docs.medusajs.com/learn/fundamentals/modules/container/index.html.md), which is similar to the [Medusa container](https://docs.medusajs.com/learn/fundamentals/medusa-container/index.html.md) but includes only [resources available to the module](https://docs.medusajs.com/resources/medusa-container-resources#module-container-resources/index.html.md). Modules are isolated, so they can't access resources outside of them, such as a service in another module.
+
+Medusa isolates modules to ensure that they're re-usable across applications, aren't tightly coupled to other resources, and don't have implications when integrated into the Medusa application. Learn more about why modules are isolated in [this chapter](https://docs.medusajs.com/learn/fundamentals/modules/isolation/index.html.md), and check out [this reference for the list of resources in the module's container](https://docs.medusajs.com/resources/medusa-container-resources#module-container-resources/index.html.md).
+
+***
+
+## How to Create a Loader?
+
+### 1. Implement Loader Function
+
+You create a loader function in a TypeScript or JavaScript file under a module's `loaders` directory.
+
+For example, consider you have a `hello` module, you can create a loader at `src/modules/hello/loaders/hello-world.ts` with the following content:
+
+
+
+Learn how to create a module in [this chapter](https://docs.medusajs.com/learn/fundamentals/modules/index.html.md).
+
+```ts title="src/modules/hello/loaders/hello-world.ts"
+import {
+ LoaderOptions,
+} from "@medusajs/framework/types"
+
+export default async function helloWorldLoader({
+ container,
+}: LoaderOptions) {
+ const logger = container.resolve("logger")
+
+ logger.info("[HELLO MODULE] Just started the Medusa application!")
+}
+```
+
+The loader file exports an async function, which is the function executed when the application loads.
+
+The function receives an object parameter that has a `container` property, which is the module's container that you can use to resolve resources from. In this example, you resolve the Logger utility to log a message in the terminal.
+
+Find the list of resources in the module's container in [this reference](https://docs.medusajs.com/resources/medusa-container-resources#module-container-resources/index.html.md).
+
+### 2. Export Loader in Module Definition
+
+After implementing the loader, you must export it in the module's definition in the `index.ts` file at the root of the module's directory. Otherwise, the Medusa application will not run it.
+
+So, to export the loader you implemented above in the `hello` module, add the following to `src/modules/hello/index.ts`:
+
+```ts title="src/modules/hello/index.ts"
+// other imports...
+import helloWorldLoader from "./loaders/hello-world"
+
+export default Module("hello", {
+ // ...
+ loaders: [helloWorldLoader],
+})
+```
+
+The second parameter of the `Module` function accepts a `loaders` property whose value is an array of loader functions. The Medusa application will execute these functions when it starts.
+
+### Test the Loader
+
+Assuming your module is [added to Medusa's configuration](https://docs.medusajs.com/learn/fundamentals/modules#4-add-module-to-medusas-configurations/index.html.md), you can test the loader by starting the Medusa application:
+
+```bash npm2yarn
+npm run dev
+```
+
+Then, you'll find the following message logged in the terminal:
+
+```plain
+info: [HELLO MODULE] Just started the Medusa application!
+```
+
+This indicates that the loader in the `hello` module ran and logged this message.
+
+***
+
+## When are Loaders Executed?
+
+When you start the Medusa application, it executes the loaders of all modules in their registration order.
+
+A loader is executed before the module's main service is instantiated. So, you can use loaders to register in the module's container resources that you want to use in the module's service. For example, you can register a database connection.
+
+Loaders are also useful to only load a module if a certain condition is met. For example, if you try to connect to a database in a loader but the connection fails, you can throw an error in the loader to prevent the module from being loaded. This is useful if your module depends on an external service to work.
+
+***
+
+## Example: Register Custom MongoDB Connection
+
+As mentioned in this chapter's introduction, loaders are most useful when you need to register a custom resource in the module's container to re-use it in other customizations in the module.
+
+Consider your have a MongoDB module that allows you to perform operations on a MongoDB database.
+
+### Prerequisites
+
+- [MongoDB database that you can connect to from a local machine.](https://www.mongodb.com)
+- [Install the MongoDB SDK in your Medusa application.](https://www.mongodb.com/docs/drivers/node/current/quick-start/download-and-install/#install-the-node.js-driver)
+
+To connect to the database, you create the following loader in your module:
+
+```ts title="src/modules/mongo/loaders/connection.ts" highlights={loaderHighlights}
+import { LoaderOptions } from "@medusajs/framework/types"
+import { asValue } from "awilix"
+import { MongoClient } from "mongodb"
+
+type ModuleOptions = {
+ connection_url?: string
+ db_name?: string
+}
+
+export default async function mongoConnectionLoader({
+ container,
+ options,
+}: LoaderOptions) {
+ if (!options.connection_url) {
+ throw new Error(`[MONGO MDOULE]: connection_url option is required.`)
+ }
+ if (!options.db_name) {
+ throw new Error(`[MONGO MDOULE]: db_name option is required.`)
+ }
+ const logger = container.resolve("logger")
+
+ try {
+ const clientDb = (
+ await (new MongoClient(options.connection_url)).connect()
+ ).db(options.db_name)
+
+ logger.info("Connected to MongoDB")
+
+ container.register(
+ "mongoClient",
+ asValue(clientDb)
+ )
+ } catch (e) {
+ logger.error(
+ `[MONGO MDOULE]: An error occurred while connecting to MongoDB: ${e}`
+ )
+ }
+}
+```
+
+The loader function accepts in its object parameter an `options` property, which is the options passed to the module in Medusa's configurations. For example:
+
+```ts title="medusa-config.ts" highlights={optionHighlights}
+module.exports = defineConfig({
+ // ...
+ modules: [
+ {
+ resolve: "./src/modules/mongo",
+ options: {
+ connection_url: process.env.MONGO_CONNECTION_URL,
+ db_name: process.env.MONGO_DB_NAME,
+ },
+ },
+ ],
+})
+```
+
+Passing options is useful when your module needs informations like connection URLs or API keys, as it ensures your module can be re-usable across applications. For the MongoDB Module, you expect two options:
+
+- `connection_url`: the URL to connect to the MongoDB database.
+- `db_name`: The name of the database to connect to.
+
+In the loader, you check first that these options are set before proceeding. Then, you create an instance of the MongoDB client and connect to the database specified in the options.
+
+After creating the client, you register it in the module's container using the container's `register` method. The method accepts two parameters:
+
+1. The key to register the resource under, which in this case is `mongoClient`. You'll use this name later to resolve the client.
+2. The resource to register in the container, which is the MongoDB client you created. However, you don't pass the resource as-is. Instead, you need to use an `asValue` function imported from the [awilix package](https://github.com/jeffijoe/awilix), which is the package used to implement the container functionality in Medusa.
+
+### Use Custom Registered Resource in Module's Service
+
+After registering the custom MongoDB client in the module's container, you can now resolve and use it in the module's service.
+
+For example:
+
+```ts title="src/modules/mongo/service.ts"
+import type { Db } from "mongodb"
+
+type InjectedDependencies = {
+ mongoClient: Db
+}
+
+export default class MongoModuleService {
+ private mongoClient_: Db
+
+ constructor({ mongoClient }: InjectedDependencies) {
+ this.mongoClient_ = mongoClient
+ }
+
+ async createMovie({ title }: {
+ title: string
+ }) {
+ const moviesCol = this.mongoClient_.collection("movie")
+
+ const insertedMovie = await moviesCol.insertOne({
+ title,
+ })
+
+ const movie = await moviesCol.findOne({
+ _id: insertedMovie.insertedId,
+ })
+
+ return movie
+ }
+
+ async deleteMovie(id: string) {
+ const moviesCol = this.mongoClient_.collection("movie")
+
+ await moviesCol.deleteOne({
+ _id: {
+ equals: id,
+ },
+ })
+ }
+}
+```
+
+The service `MongoModuleService` resolves the `mongoClient` resource you registered in the loader and sets it as a class property. You then use it in the `createMovie` and `deleteMovie` methods, which create and delete a document in a `movie` collection in the MongoDB database, respectively.
+
+Make sure to export the loader in the module's definition in the `index.ts` file at the root directory of the module:
+
+```ts title="src/modules/mongo/index.ts" highlights={[["9"]]}
+import { Module } from "@medusajs/framework/utils"
+import MongoModuleService from "./service"
+import mongoConnectionLoader from "./loaders/connection"
+
+export const MONGO_MODULE = "mongo"
+
+export default Module(MONGO_MODULE, {
+ service: MongoModuleService,
+ loaders: [mongoConnectionLoader],
+})
+```
+
+### Test it Out
+
+You can test the connection out by starting the Medusa application. If it's successful, you'll see the following message logged in the terminal:
+
+```bash
+info: Connected to MongoDB
+```
+
+You can now resolve the MongoDB Module's main service in your customizations to perform operations on the MongoDB database.
+
+
+# Module Isolation
+
+In this chapter, you'll learn how modules are isolated, and what that means for your custom development.
+
+- Modules can't access resources, such as services or data models, from other modules.
+- Use Medusa's linking concepts, as explained in the [Module Links chapters](https://docs.medusajs.com/learn/fundamentals/module-links/index.html.md), to extend a module's data models and retrieve data across modules.
+
+## How are Modules Isolated?
+
+A module is unaware of any resources other than its own, such as services or data models. This means it can't access these resources if they're implemented in another module.
+
+For example, your custom module can't resolve the Product Module's main service or have direct relationships from its data model to the Product Module's data models.
+
+***
+
+## Why are Modules Isolated
+
+Some of the module isolation's benefits include:
+
+- Integrate your module into any Medusa application without side-effects to your setup.
+- Replace existing modules with your custom implementation, if your use case is drastically different.
+- Use modules in other environments, such as Edge functions and Next.js apps.
+
+***
+
+## How to Extend Data Model of Another Module?
+
+To extend the data model of another module, such as the `product` data model of the Product Module, use Medusa's linking concepts as explained in the [Module Links chapters](https://docs.medusajs.com/learn/fundamentals/module-links/index.html.md).
+
+***
+
+## How to Use Services of Other Modules?
+
+If you're building a feature that uses functionalities from different modules, use a workflow whose steps resolve the modules' services to perform these functionalities.
+
+Workflows ensure data consistency through their roll-back mechanism and tracking of each execution's status, steps, input, and output.
+
+### Example
+
+For example, consider you have two modules:
+
+1. A module that stores and manages brands in your application.
+2. A module that integrates a third-party Content Management System (CMS).
+
+To sync brands from your application to the third-party system, create the following steps:
+
+```ts title="Example Steps" highlights={stepsHighlights}
+const retrieveBrandsStep = createStep(
+ "retrieve-brands",
+ async (_, { container }) => {
+ const brandModuleService = container.resolve(
+ "brandModuleService"
+ )
+
+ const brands = await brandModuleService.listBrands()
+
+ return new StepResponse(brands)
+ }
+)
+
+const createBrandsInCmsStep = createStep(
+ "create-brands-in-cms",
+ async ({ brands }, { container }) => {
+ const cmsModuleService = container.resolve(
+ "cmsModuleService"
+ )
+
+ const cmsBrands = await cmsModuleService.createBrands(brands)
+
+ return new StepResponse(cmsBrands, cmsBrands)
+ },
+ async (brands, { container }) => {
+ const cmsModuleService = container.resolve(
+ "cmsModuleService"
+ )
+
+ await cmsModuleService.deleteBrands(
+ brands.map((brand) => brand.id)
+ )
+ }
+)
+```
+
+The `retrieveBrandsStep` retrieves the brands from a brand module, and the `createBrandsInCmsStep` creates the brands in a third-party system using a CMS module.
+
+Then, create the following workflow that uses these steps:
+
+```ts title="Example Workflow"
+export const syncBrandsWorkflow = createWorkflow(
+ "sync-brands",
+ () => {
+ const brands = retrieveBrandsStep()
+
+ createBrandsInCmsStep({ brands })
+ }
+)
+```
+
+You can then use this workflow in an API route, scheduled job, or other resources that use this functionality.
+
+
+# Modules Directory Structure
+
+In this document, you'll learn about the expected files and directories in your module.
+
+
+
+## index.ts
+
+The `index.ts` file in the root of your module's directory is the only required file. It must export the module's definition as explained in a [previous chapter](https://docs.medusajs.com/learn/fundamentals/modules/index.html.md).
+
+***
+
+## service.ts
+
+A module must have a main service. It's created in the `service.ts` file at the root of your module directory as explained in a [previous chapter](https://docs.medusajs.com/learn/fundamentals/modules/index.html.md).
+
+***
+
+## Other Directories
+
+The following directories are optional and their content are explained more in the following chapters:
+
+- `models`: Holds the data models representing tables in the database.
+- `migrations`: Holds the migration files used to reflect changes on the database.
+- `loaders`: Holds the scripts to run on the Medusa application's start-up.
+
+
# Multiple Services in a Module
In this chapter, you'll learn how to use multiple services in a module.
@@ -12408,107 +14830,6 @@ The `configModule` has a `modules` property that includes all registered modules
If its value is not a `boolean`, set the service's options to the module configuration's `options` property.
-# Module Isolation
-
-In this chapter, you'll learn how modules are isolated, and what that means for your custom development.
-
-- Modules can't access resources, such as services or data models, from other modules.
-- Use Medusa's linking concepts, as explained in the [Module Links chapters](https://docs.medusajs.com/learn/fundamentals/module-links/index.html.md), to extend a module's data models and retrieve data across modules.
-
-## How are Modules Isolated?
-
-A module is unaware of any resources other than its own, such as services or data models. This means it can't access these resources if they're implemented in another module.
-
-For example, your custom module can't resolve the Product Module's main service or have direct relationships from its data model to the Product Module's data models.
-
-***
-
-## Why are Modules Isolated
-
-Some of the module isolation's benefits include:
-
-- Integrate your module into any Medusa application without side-effects to your setup.
-- Replace existing modules with your custom implementation, if your use case is drastically different.
-- Use modules in other environments, such as Edge functions and Next.js apps.
-
-***
-
-## How to Extend Data Model of Another Module?
-
-To extend the data model of another module, such as the `product` data model of the Product Module, use Medusa's linking concepts as explained in the [Module Links chapters](https://docs.medusajs.com/learn/fundamentals/module-links/index.html.md).
-
-***
-
-## How to Use Services of Other Modules?
-
-If you're building a feature that uses functionalities from different modules, use a workflow whose steps resolve the modules' services to perform these functionalities.
-
-Workflows ensure data consistency through their roll-back mechanism and tracking of each execution's status, steps, input, and output.
-
-### Example
-
-For example, consider you have two modules:
-
-1. A module that stores and manages brands in your application.
-2. A module that integrates a third-party Content Management System (CMS).
-
-To sync brands from your application to the third-party system, create the following steps:
-
-```ts title="Example Steps" highlights={stepsHighlights}
-const retrieveBrandsStep = createStep(
- "retrieve-brands",
- async (_, { container }) => {
- const brandModuleService = container.resolve(
- "brandModuleService"
- )
-
- const brands = await brandModuleService.listBrands()
-
- return new StepResponse(brands)
- }
-)
-
-const createBrandsInCmsStep = createStep(
- "create-brands-in-cms",
- async ({ brands }, { container }) => {
- const cmsModuleService = container.resolve(
- "cmsModuleService"
- )
-
- const cmsBrands = await cmsModuleService.createBrands(brands)
-
- return new StepResponse(cmsBrands, cmsBrands)
- },
- async (brands, { container }) => {
- const cmsModuleService = container.resolve(
- "cmsModuleService"
- )
-
- await cmsModuleService.deleteBrands(
- brands.map((brand) => brand.id)
- )
- }
-)
-```
-
-The `retrieveBrandsStep` retrieves the brands from a brand module, and the `createBrandsInCmsStep` creates the brands in a third-party system using a CMS module.
-
-Then, create the following workflow that uses these steps:
-
-```ts title="Example Workflow"
-export const syncBrandsWorkflow = createWorkflow(
- "sync-brands",
- () => {
- const brands = retrieveBrandsStep()
-
- createBrandsInCmsStep({ brands })
- }
-)
-```
-
-You can then use this workflow in an API route, scheduled job, or other resources that use this functionality.
-
-
# Service Factory
In this chapter, you’ll learn about what the service factory is and how to use it.
@@ -12684,595 +15005,41 @@ export default BlogModuleService
```
-# Create a Plugin
+# Service Constraints
-In this chapter, you'll learn how to create a Medusa plugin and publish it.
+This chapter lists constraints to keep in mind when creating a service.
-A [plugin](https://docs.medusajs.com/learn/fundamentals/plugins/index.html.md) is a package of reusable Medusa customizations that you can install in any Medusa application. By creating and publishing a plugin, you can reuse your Medusa customizations across multiple projects or share them with the community.
+## Use Async Methods
-Plugins are available starting from [Medusa v2.3.0](https://github.com/medusajs/medusa/releases/tag/v2.3.0).
+Medusa wraps service method executions to inject useful context or transactions. However, since Medusa can't detect whether the method is asynchronous, it always executes methods in the wrapper with the `await` keyword.
-## 1. Create a Plugin Project
-
-Plugins are created in a separate Medusa project. This makes the development and publishing of the plugin easier. Later, you'll install that plugin in your Medusa application to test it out and use it.
-
-Medusa's `create-medusa-app` CLI tool provides the option to create a plugin project. Run the following command to create a new plugin project:
-
-```bash
-npx create-medusa-app my-plugin --plugin
-```
-
-This will create a new Medusa plugin project in the `my-plugin` directory.
-
-### Plugin Directory Structure
-
-After the installation is done, the plugin structure will look like this:
-
-
-
-- `src/`: Contains the Medusa customizations.
-- `src/admin`: Contains [admin extensions](https://docs.medusajs.com/learn/fundamentals/admin/index.html.md).
-- `src/api`: Contains [API routes](https://docs.medusajs.com/learn/fundamentals/api-routes/index.html.md) and [middlewares](https://docs.medusajs.com/learn/fundamentals/api-routes/middlewares/index.html.md). You can add store, admin, or any custom API routes.
-- `src/jobs`: Contains [scheduled jobs](https://docs.medusajs.com/learn/fundamentals/scheduled-jobs/index.html.md).
-- `src/links`: Contains [module links](https://docs.medusajs.com/learn/fundamentals/module-links/index.html.md).
-- `src/modules`: Contains [modules](https://docs.medusajs.com/learn/fundamentals/modules/index.html.md).
-- `src/provider`: Contains [module providers](#create-module-providers).
-- `src/subscribers`: Contains [subscribers](https://docs.medusajs.com/learn/fundamentals/events-and-subscribers/index.html.md).
-- `src/workflows`: Contains [workflows](https://docs.medusajs.com/learn/fundamentals/workflows/index.html.md). You can also add [hooks](https://docs.medusajs.com/learn/fundamentals/workflows/add-workflow-hook/index.html.md) under `src/workflows/hooks`.
-- `package.json`: Contains the plugin's package information, including general information and dependencies.
-- `tsconfig.json`: Contains the TypeScript configuration for the plugin.
-
-***
-
-## 2. Prepare Plugin
-
-### Package Name
-
-Before developing, testing, and publishing your plugin, make sure its name in `package.json` is correct. This is the name you'll use to install the plugin in your Medusa application.
-
-For example:
-
-```json title="package.json"
-{
- "name": "@myorg/plugin-name",
- // ...
-}
-```
-
-### Package Keywords
-
-Medusa scrapes NPM for a list of plugins that integrate third-party services, to later showcase them on the Medusa website. If you want your plugin to appear in that listing, make sure to add the `medusa-v2` and `medusa-plugin-integration` keywords to the `keywords` field in `package.json`.
-
-Only plugins that integrate third-party services are listed in the Medusa integrations page. If your plugin doesn't integrate a third-party service, you can skip this step.
-
-```json title="package.json"
-{
- "keywords": [
- "medusa-plugin-integration",
- "medusa-v2"
- ],
- // ...
-}
-```
-
-In addition, make sure to use one of the following keywords based on your integration type:
-
-|Keyword|Description|Example|
-|---|---|---|
-|\`medusa-plugin-analytics\`|Analytics service integration|Google Analytics|
-|\`medusa-plugin-auth\`|Authentication service integration|Auth0|
-|\`medusa-plugin-cms\`|CMS service integration|Contentful|
-|\`medusa-plugin-notification\`|Notification service integration|Twilio SMS|
-|\`medusa-plugin-payment\`|Payment service integration|PayPal|
-|\`medusa-plugin-search\`|Search service integration|MeiliSearch|
-|\`medusa-plugin-shipping\`|Shipping service integration|DHL|
-|\`medusa-plugin-other\`|Other third-party integrations|Sentry|
-
-### Package Dependencies
-
-Your plugin project will already have the dependencies mentioned in this section. Unless you made changes to the dependencies, you can skip this section.
-
-In the `package.json` file you must have the Medusa dependencies as `devDependencies` and `peerDependencies`. In addition, you must have `@swc/core` as a `devDependency`, as it's used by the plugin CLI tools.
-
-For example, assuming `2.5.0` is the latest Medusa version:
-
-```json title="package.json"
-{
- "devDependencies": {
- "@medusajs/admin-sdk": "2.5.0",
- "@medusajs/cli": "2.5.0",
- "@medusajs/framework": "2.5.0",
- "@medusajs/medusa": "2.5.0",
- "@medusajs/test-utils": "2.5.0",
- "@medusajs/ui": "4.0.4",
- "@medusajs/icons": "2.5.0",
- "@swc/core": "1.5.7",
- },
- "peerDependencies": {
- "@medusajs/admin-sdk": "2.5.0",
- "@medusajs/cli": "2.5.0",
- "@medusajs/framework": "2.5.0",
- "@medusajs/test-utils": "2.5.0",
- "@medusajs/medusa": "2.5.0",
- "@medusajs/ui": "4.0.3",
- "@medusajs/icons": "2.5.0",
- }
-}
-```
-
-### Package Exports
-
-Your plugin project will already have the exports mentioned in this section. Unless you made changes to the exports or you created your plugin before [Medusa v2.7.0](https://github.com/medusajs/medusa/releases/tag/v2.7.0), you can skip this section.
-
-In the `package.json` file, make sure your plugin has the following exports:
-
-```json title="package.json"
-{
- "exports": {
- "./package.json": "./package.json",
- "./workflows": "./.medusa/server/src/workflows/index.js",
- "./.medusa/server/src/modules/*": "./.medusa/server/src/modules/*/index.js",
- "./providers/*": "./.medusa/server/src/providers/*/index.js",
- "./admin": {
- "import": "./.medusa/server/src/admin/index.mjs",
- "require": "./.medusa/server/src/admin/index.js",
- "default": "./.medusa/server/src/admin/index.js"
- },
- "./*": "./.medusa/server/src/*.js"
- }
-}
-```
-
-Aside from the `./package.json`, `./providers`, and `./admin`, these exports are only a recommendation. You can cherry-pick the files and directories you want to export.
-
-The plugin exports the following files and directories:
-
-- `./package.json`: The `package.json` file. Medusa needs to access the `package.json` when registering the plugin.
-- `./workflows`: The workflows exported in `./src/workflows/index.ts`.
-- `./.medusa/server/src/modules/*`: The definition file of modules. This is useful if you create links to the plugin's modules in the Medusa application.
-- `./providers/*`: The definition file of module providers. This is useful if your plugin includes a module provider, allowing you to register the plugin's providers in Medusa applications. Learn more in the [Create Module Providers](#create-module-providers) section.
-- `./admin`: The admin extensions exported in `./src/admin/index.ts`.
-- `./*`: Any other files in the plugin's `src` directory.
-
-***
-
-## 3. Publish Plugin Locally for Development and Testing
-
-Medusa's CLI tool provides commands to simplify developing and testing your plugin in a local Medusa application. You start by publishing your plugin in the local package registry, then install it in your Medusa application. You can then watch for changes in the plugin as you develop it.
-
-### Publish and Install Local Package
-
-### Prerequisites
-
-- [Medusa application installed.](https://docs.medusajs.com/learn/installation/index.html.md)
-
-The first time you create your plugin, you need to publish the package into a local package registry, then install it in your Medusa application. This is a one-time only process.
-
-To publish the plugin to the local registry, run the following command in your plugin project:
-
-```bash title="Plugin project"
-npx medusa plugin:publish
-```
-
-This command uses [Yalc](https://github.com/wclr/yalc) under the hood to publish the plugin to a local package registry. The plugin is published locally under the name you specified in `package.json`.
-
-Next, navigate to your Medusa application:
-
-```bash title="Medusa application"
-cd ~/path/to/medusa-app
-```
-
-Make sure to replace `~/path/to/medusa-app` with the path to your Medusa application.
-
-Then, if your project was created before v2.3.1 of Medusa, make sure to install `yalc` as a development dependency:
-
-```bash npm2yarn badgeLabel="Medusa Application" badgeColor="green"
-npm install --save-dev yalc
-```
-
-After that, run the following Medusa CLI command to install the plugin:
-
-```bash title="Medusa application"
-npx medusa plugin:add @myorg/plugin-name
-```
-
-Make sure to replace `@myorg/plugin-name` with the name of your plugin as specified in `package.json`. Your plugin will be installed from the local package registry into your Medusa application.
-
-### Register Plugin in Medusa Application
-
-After installing the plugin, you need to register it in your Medusa application in the configurations defined in `medusa-config.ts`.
-
-Add the plugin to the `plugins` array in the `medusa-config.ts` file:
-
-```ts title="medusa-config.ts" highlights={pluginHighlights}
-module.exports = defineConfig({
- // ...
- plugins: [
- {
- resolve: "@myorg/plugin-name",
- options: {},
- },
- ],
-})
-```
-
-The `plugins` configuration is an array of objects where each object has a `resolve` key whose value is the name of the plugin package.
-
-#### Pass Module Options through Plugin
-
-Each plugin configuration also accepts an `options` property, whose value is an object of options to pass to the plugin's modules.
-
-For example:
-
-```ts title="medusa-config.ts" highlights={pluginOptionsHighlight}
-module.exports = defineConfig({
- // ...
- plugins: [
- {
- resolve: "@myorg/plugin-name",
- options: {
- apiKey: true,
- },
- },
- ],
-})
-```
-
-The `options` property in the plugin configuration is passed to all modules in the plugin. Learn more about module options in [this chapter](https://docs.medusajs.com/learn/fundamentals/modules/options/index.html.md).
-
-### Watch Plugin Changes During Development
-
-While developing your plugin, you can watch for changes in the plugin and automatically update the plugin in the Medusa application using it. This is the only command you'll continuously need during your plugin development.
-
-To do that, run the following command in your plugin project:
-
-```bash title="Plugin project"
-npx medusa plugin:develop
-```
-
-This command will:
-
-- Watch for changes in the plugin. Whenever a file is changed, the plugin is automatically built.
-- Publish the plugin changes to the local package registry. This will automatically update the plugin in the Medusa application using it. You can also benefit from real-time HMR updates of admin extensions.
-
-### Start Medusa Application
-
-You can start your Medusa application's development server to test out your plugin:
-
-```bash npm2yarn badgeLabel="Medusa Application" badgeColor="green"
-npm run dev
-```
-
-While your Medusa application is running and the plugin is being watched, you can test your plugin while developing it in the Medusa application.
-
-***
-
-## 4. Create Customizations in the Plugin
-
-You can now build your plugin's customizations. The following guide explains how to build different customizations in your plugin.
-
-- [Create a module](https://docs.medusajs.com/learn/fundamentals/modules/index.html.md)
-- [Create a module link](https://docs.medusajs.com/learn/fundamentals/module-links/index.html.md)
-- [Create a workflow](https://docs.medusajs.com/learn/fundamentals/workflows/index.html.md)
-- [Add a workflow hook](https://docs.medusajs.com/learn/fundamentals/workflows/add-workflow-hook/index.html.md)
-- [Create an API route](https://docs.medusajs.com/learn/fundamentals/api-routes/index.html.md)
-- [Add a subscriber](https://docs.medusajs.com/learn/fundamentals/events-and-subscribers/index.html.md)
-- [Add a scheduled job](https://docs.medusajs.com/learn/fundamentals/scheduled-jobs/index.html.md)
-- [Add an admin widget](https://docs.medusajs.com/learn/fundamentals/admin/widgets/index.html.md)
-- [Add an admin UI route](https://docs.medusajs.com/learn/fundamentals/admin/ui-routes/index.html.md)
-
-While building those customizations, you can test them in your Medusa application by [watching the plugin changes](#watch-plugin-changes-during-development) and [starting the Medusa application](#start-medusa-application).
-
-### Generating Migrations for Modules
-
-During your development, you may need to generate migrations for modules in your plugin. To do that, first, add the following environment variables in your plugin project:
-
-```plain title="Plugin project"
-DB_USERNAME=postgres
-DB_PASSWORD=123...
-DB_HOST=localhost
-DB_PORT=5432
-DB_NAME=db_name
-```
-
-You can add these environment variables in a `.env` file in your plugin project. The variables are:
-
-- `DB_USERNAME`: The username of the PostgreSQL user to connect to the database.
-- `DB_PASSWORD`: The password of the PostgreSQL user to connect to the database.
-- `DB_HOST`: The host of the PostgreSQL database. Typically, it's `localhost` if you're running the database locally.
-- `DB_PORT`: The port of the PostgreSQL database. Typically, it's `5432` if you're running the database locally.
-- `DB_NAME`: The name of the PostgreSQL database to connect to.
-
-Then, run the following command in your plugin project to generate migrations for the modules in your plugin:
-
-```bash title="Plugin project"
-npx medusa plugin:db:generate
-```
-
-This command generates migrations for all modules in the plugin.
-
-Finally, run these migrations on the Medusa application that the plugin is installed in using the `db:migrate` command:
-
-```bash title="Medusa application"
-npx medusa db:migrate
-```
-
-The migrations in your application, including your plugin, will run and update the database.
-
-### Importing Module Resources
-
-In the [Prepare Plugin](#2-prepare-plugin) section, you learned about [exported resources](#package-exports) in your plugin.
-
-These exports allow you to import your plugin resources in your Medusa application, including workflows, links and modules.
-
-For example, to import the plugin's workflow in your Medusa application:
-
-`@myorg/plugin-name` is the plugin package's name.
+For example, if you have a synchronous `getMessage` method, and you use it in other resources like workflows, Medusa executes it as an async method:
```ts
-import { Workflow1, Workflow2 } from "@myorg/plugin-name/workflows"
-import BlogModule from "@myorg/plugin-name/modules/blog"
-// import other files created in plugin like ./src/types/blog.ts
-import BlogType from "@myorg/plugin-name/types/blog"
+await blogModuleService.getMessage()
```
-### Create Module Providers
+So, make sure your service's methods are always async to avoid unexpected errors or behavior.
-The [exported resources](#package-exports) also allow you to import module providers in your plugin and register them in the Medusa application's configuration. A module provider is a module that provides the underlying logic or integration related to a commerce or Infrastructure Module.
+```ts highlights={[["8", "", "Method must be async."], ["13", "async", "Correct way of defining the method."]]}
+import { MedusaService } from "@medusajs/framework/utils"
+import Post from "./models/post"
-For example, assuming your plugin has a [Notification Module Provider](https://docs.medusajs.com/resources/infrastructure-modules/notification/index.html.md) called `my-notification`, you can register it in your Medusa application's configuration like this:
-
-`@myorg/plugin-name` is the plugin package's name.
-
-```ts highlights={[["9"]]} title="medusa-config.ts"
-module.exports = defineConfig({
- // ...
- modules: [
- {
- resolve: "@medusajs/medusa/notification",
- options: {
- providers: [
- {
- resolve: "@myorg/plugin-name/providers/my-notification",
- id: "my-notification",
- options: {
- channels: ["email"],
- // provider options...
- },
- },
- ],
- },
- },
- ],
-})
-```
-
-You pass to `resolve` the path to the provider relative to the plugin package. So, in this example, the `my-notification` provider is located in `./src/providers/my-notification/index.ts` of the plugin.
-
-To learn how to create module providers, refer to the following guides:
-
-- [File Module Provider](https://docs.medusajs.com/resources/references/file-provider-module/index.html.md)
-- [Notification Module Provider](https://docs.medusajs.com/resources/references/notification-provider-module/index.html.md)
-- [Auth Module Provider](https://docs.medusajs.com/resources/references/auth/provider/index.html.md)
-- [Payment Module Provider](https://docs.medusajs.com/resources/references/payment/provider/index.html.md)
-- [Fulfillment Module Provider](https://docs.medusajs.com/resources/references/fulfillment/provider/index.html.md)
-- [Tax Module Provider](https://docs.medusajs.com/resources/references/tax/provider/index.html.md)
-
-***
-
-## 5. Publish Plugin to NPM
-
-Make sure to add the keywords mentioned in the [Package Keywords](#package-keywords) section in your plugin's `package.json` file.
-
-Medusa's CLI tool provides a command that bundles your plugin to be published to npm. Once you're ready to publish your plugin publicly, run the following command in your plugin project:
-
-```bash
-npx medusa plugin:build
-```
-
-The command will compile an output in the `.medusa/server` directory.
-
-You can now publish the plugin to npm using the [NPM CLI tool](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm). Run the following command to publish the plugin to npm:
-
-```bash
-npm publish
-```
-
-If you haven't logged in before with your NPM account, you'll be asked to log in first. Then, your package is published publicly to be used in any Medusa application.
-
-### Install Public Plugin in Medusa Application
-
-You install a plugin that's published publicly using your package manager. For example:
-
-```bash npm2yarn
-npm install @myorg/plugin-name
-```
-
-Where `@myorg/plugin-name` is the name of your plugin as published on NPM.
-
-Then, register the plugin in your Medusa application's configurations as explained in [this section](#register-plugin-in-medusa-application).
-
-***
-
-## Update a Published Plugin
-
-To update the Medusa dependencies in a plugin, refer to [this documentation](https://docs.medusajs.com/learn/update#update-plugin-project/index.html.md).
-
-If you've published a plugin and you've made changes to it, you'll have to publish the update to NPM again.
-
-First, run the following command to change the version of the plugin:
-
-```bash
-npm version
-```
-
-Where `` indicates the type of version update you’re publishing. For example, it can be `major` or `minor`. Refer to the [npm version documentation](https://docs.npmjs.com/cli/v10/commands/npm-version) for more information.
-
-Then, re-run the same commands for publishing a plugin:
-
-```bash
-npx medusa plugin:build
-npm publish
-```
-
-This will publish an updated version of your plugin under a new version.
-
-
-# Add Columns to a Link Table
-
-In this chapter, you'll learn how to add custom columns to a link definition's table and manage them.
-
-## Link Table's Default Columns
-
-When you define a link between two data models, Medusa creates a link table in the database to store the IDs of the linked records. You can learn more about the created table in the [Module Links chapter](https://docs.medusajs.com/learn/fundamentals/module-links/index.html.md).
-
-In various cases, you might need to store additional data in the link table. For example, if you define a link between a `product` and a `post`, you might want to store the publish date of the product's post in the link table.
-
-In those cases, you can add a custom column to a link's table in the link definition. You can later set that column whenever you create or update a link between the linked records.
-
-***
-
-## How to Add Custom Columns to a Link's Table?
-
-The `defineLink` function used to define a link accepts a third parameter, which is an object of options.
-
-To add custom columns to a link's table, pass in the third parameter of `defineLink` a `database` property:
-
-```ts highlights={linkHighlights}
-import BlogModule from "../modules/blog"
-import ProductModule from "@medusajs/medusa/product"
-import { defineLink } from "@medusajs/framework/utils"
-
-export default defineLink(
- ProductModule.linkable.product,
- BlogModule.linkable.blog,
- {
- database: {
- extraColumns: {
- metadata: {
- type: "json",
- },
- },
- },
+class BlogModuleService extends MedusaService({
+ Post,
+}){
+ // Don't
+ getMessage(): string {
+ return "Hello, World!"
}
-)
-```
-This adds to the table created for the link between `product` and `blog` a `metadata` column of type `json`.
+ // Do
+ async getMessage(): Promise {
+ return "Hello, World!"
+ }
+}
-### Database Options
-
-The `database` property defines configuration for the table created in the database.
-
-Its `extraColumns` property defines custom columns to create in the link's table.
-
-`extraColumns`'s value is an object whose keys are the names of the columns, and values are the column's configurations as an object.
-
-### Column Configurations
-
-The column's configurations object accepts the following properties:
-
-- `type`: The column's type. Possible values are:
- - `string`
- - `text`
- - `integer`
- - `boolean`
- - `date`
- - `time`
- - `datetime`
- - `enum`
- - `json`
- - `array`
- - `enumArray`
- - `float`
- - `double`
- - `decimal`
- - `bigint`
- - `mediumint`
- - `smallint`
- - `tinyint`
- - `blob`
- - `uuid`
- - `uint8array`
-- `defaultValue`: The column's default value.
-- `nullable`: Whether the column can have `null` values.
-
-***
-
-## Set Custom Column when Creating Link
-
-The object you pass to Link's `create` method accepts a `data` property. Its value is an object whose keys are custom column names, and values are the value of the custom column for this link.
-
-For example:
-
-Learn more about Link, how to resolve it, and its methods in [this chapter](https://docs.medusajs.com/learn/fundamentals/module-links/link/index.html.md).
-
-```ts
-await link.create({
- [Modules.PRODUCT]: {
- product_id: "123",
- },
- [BLOG_MODULE]: {
- post_id: "321",
- },
- data: {
- metadata: {
- test: true,
- },
- },
-})
-```
-
-***
-
-## Retrieve Custom Column with Link
-
-To retrieve linked records with their custom columns, use [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query/index.html.md). A module link's definition, exported by a file under `src/links`, has a special `entryPoint` property. Use this property when specifying the `entity` property in Query's `graph` method.
-
-For example:
-
-```ts highlights={retrieveHighlights}
-import productPostLink from "../links/product-post"
-
-// ...
-
-const { data } = await query.graph({
- entity: productPostLink.entryPoint,
- fields: ["metadata", "product.*", "post.*"],
- filters: {
- product_id: "prod_123",
- },
-})
-```
-
-This retrieves the product of id `prod_123` and its linked `post` records.
-
-In the `fields` array you pass `metadata`, which is the custom column to retrieve of the link.
-
-***
-
-## Update Custom Column's Value
-
-Link's `create` method updates a link's data if the link between the specified records already exists.
-
-So, to update the value of a custom column in a created link, use the `create` method again passing it a new value for the custom column.
-
-For example:
-
-```ts
-await link.create({
- [Modules.PRODUCT]: {
- product_id: "123",
- },
- [BLOG_MODULE]: {
- post_id: "321",
- },
- data: {
- metadata: {
- test: false,
- },
- },
-})
+export default BlogModuleService
```
@@ -13441,1039 +15208,73 @@ export default Module(BLOG_MODULE, {
Now, when the Medusa application starts, the loader will run, validating the module's options and throwing an error if the `apiKey` option is missing.
-# Link
+# Expose a Workflow Hook
-In this chapter, you’ll learn what Link is and how to use it to manage links.
+In this chapter, you'll learn how to expose a hook in your workflow.
-As of [Medusa v2.2.0](https://github.com/medusajs/medusa/releases/tag/v2.2.0), Remote Link has been deprecated in favor of Link. They have the same usage, so you only need to change the key used to resolve the tool from the Medusa container as explained below.
+## When to Expose a Hook
-## What is Link?
+Your workflow is reusable in other applications, and you allow performing an external action at some point in your workflow.
-Link is a class with utility methods to manage links between data models. It’s registered in the Medusa container under the `link` registration name.
+Your workflow isn't reusable by other applications. Use a step that performs what a hook handler would instead.
+
+***
+
+## How to Expose a Hook in a Workflow?
+
+To expose a hook in your workflow, use `createHook` from the Workflows SDK.
For example:
-```ts collapsibleLines="1-9" expandButtonLabel="Show Imports"
-import {
- MedusaRequest,
- MedusaResponse,
-} from "@medusajs/framework/http"
-import {
- ContainerRegistrationKeys,
-} from "@medusajs/framework/utils"
-
-export async function POST(
- req: MedusaRequest,
- res: MedusaResponse
-): Promise {
- const link = req.scope.resolve(
- ContainerRegistrationKeys.LINK
- )
-
- // ...
-}
-```
-
-You can use its methods to manage links, such as create or delete links.
-
-***
-
-## Create Link
-
-To create a link between records of two data models, use the `create` method of Link.
-
-For example:
-
-```ts
-import { Modules } from "@medusajs/framework/utils"
-
-// ...
-
-await link.create({
- [Modules.PRODUCT]: {
- product_id: "prod_123",
- },
- "helloModuleService": {
- my_custom_id: "mc_123",
- },
-})
-```
-
-The `create` method accepts as a parameter an object. The object’s keys are the names of the linked modules.
-
-The keys (names of linked modules) must be in the same [direction](https://docs.medusajs.com/learn/fundamentals/module-links/directions/index.html.md) of the link definition.
-
-The value of each module’s property is an object, whose keys are of the format `{data_model_snake_name}_id`, and values are the IDs of the linked record.
-
-So, in the example above, you link a record of the `MyCustom` data model in a `hello` module to a `Product` record in the Product Module.
-
-### Enforced Integrity Constraints on Link Creation
-
-Medusa enforces integrity constraints on links based on the link's relation type. So, an error is thrown in the following scenarios:
-
-- If the link is one-to-one and one of the linked records already has a link to another record of the same data model. For example:
-
-```ts
-// no error
-await link.create({
- [Modules.PRODUCT]: {
- product_id: "prod_123",
- },
- "helloModuleService": {
- my_custom_id: "mc_123",
- },
-})
-
-// throws an error because `prod_123` already has a link to `mc_123`
-await link.create({
- [Modules.PRODUCT]: {
- product_id: "prod_123",
- },
- "helloModuleService": {
- my_custom_id: "mc_456",
- },
-})
-```
-
-- If the link is one-to-many and the "one" side already has a link to another record of the same data model. For example, if a product can have many `MyCustom` records, but a `MyCustom` record can only have one product:
-
-```ts
-// no error
-await link.create({
- [Modules.PRODUCT]: {
- product_id: "prod_123",
- },
- "helloModuleService": {
- my_custom_id: "mc_123",
- },
-})
-
-// also no error
-await link.create({
- [Modules.PRODUCT]: {
- product_id: "prod_123",
- },
- "helloModuleService": {
- my_custom_id: "mc_456",
- },
-})
-
-// throws an error because `mc_123` already has a link to `prod_123`
-await link.create({
- [Modules.PRODUCT]: {
- product_id: "prod_456",
- },
- "helloModuleService": {
- my_custom_id: "mc_123",
- },
-})
-```
-
-There are no integrity constraints in a many-to-many link, so you can create multiple links between the same records.
-
-***
-
-## Dismiss Link
-
-To remove a link between records of two data models, use the `dismiss` method of Link.
-
-For example:
-
-```ts
-import { Modules } from "@medusajs/framework/utils"
-
-// ...
-
-await link.dismiss({
- [Modules.PRODUCT]: {
- product_id: "prod_123",
- },
- "helloModuleService": {
- my_custom_id: "mc_123",
- },
-})
-```
-
-The `dismiss` method accepts the same parameter type as the [create method](#create-link).
-
-The keys (names of linked modules) must be in the same [direction](https://docs.medusajs.com/learn/fundamentals/module-links/directions/index.html.md) of the link definition.
-
-***
-
-## Cascade Delete Linked Records
-
-If a record is deleted, use the `delete` method of Link to delete all linked records.
-
-For example:
-
-```ts
-import { Modules } from "@medusajs/framework/utils"
-
-// ...
-
-await productModuleService.deleteVariants([variant.id])
-
-await link.delete({
- [Modules.PRODUCT]: {
- product_id: "prod_123",
- },
-})
-```
-
-This deletes all records linked to the deleted product.
-
-***
-
-## Restore Linked Records
-
-If a record that was previously soft-deleted is now restored, use the `restore` method of Link to restore all linked records.
-
-For example:
-
-```ts
-import { Modules } from "@medusajs/framework/utils"
-
-// ...
-
-await productModuleService.restoreProducts(["prod_123"])
-
-await link.restore({
- [Modules.PRODUCT]: {
- product_id: "prod_123",
- },
-})
-```
-
-
-# Module Link Direction
-
-In this chapter, you'll learn about the difference in module link directions, and which to use based on your use case.
-
-The details in this chapter don't apply to [Read-Only Module Links](https://docs.medusajs.com/learn/fundamentals/module-links/read-only/index.html.md). Refer to the [Read-Only Module Links chapter](https://docs.medusajs.com/learn/fundamentals/module-links/read-only/index.html.md) for more information on read-only links and their direction.
-
-## Link Direction
-
-The module link's direction depends on the order you pass the data model configuration parameters to `defineLink`.
-
-For example, the following defines a link from the Blog Module's `post` data model to the Product Module's `product` data model:
-
-```ts
-export default defineLink(
- BlogModule.linkable.post,
- ProductModule.linkable.product
-)
-```
-
-Whereas the following defines a link from the Product Module's `product` data model to the Blog Module's `post` data model:
-
-```ts
-export default defineLink(
- ProductModule.linkable.product,
- BlogModule.linkable.post
-)
-```
-
-The above links are two different links that serve different purposes.
-
-***
-
-## Which Link Direction to Use?
-
-### Extend Data Models
-
-If you're adding a link to a data model to extend it and add new fields, define the link from the main data model to the custom data model.
-
-For example, consider you want to add a `subtitle` custom field to the `product` data model. To do that, you define a `Subtitle` data model in your module, then define a link from the `Product` data model to it:
-
-```ts
-export default defineLink(
- ProductModule.linkable.product,
- BlogModule.linkable.subtitle
-)
-```
-
-### Associate Data Models
-
-If you're linking data models to indicate an association between them, define the link from the custom data model to the main data model.
-
-For example, consider you have `Post` data model representing a blog post, and you want to associate a blog post with a product. To do that, define a link from the `Post` data model to `Product`:
-
-```ts
-export default defineLink(
- BlogModule.linkable.post,
- ProductModule.linkable.product
-)
-```
-
-
-# Service Constraints
-
-This chapter lists constraints to keep in mind when creating a service.
-
-## Use Async Methods
-
-Medusa wraps service method executions to inject useful context or transactions. However, since Medusa can't detect whether the method is asynchronous, it always executes methods in the wrapper with the `await` keyword.
-
-For example, if you have a synchronous `getMessage` method, and you use it in other resources like workflows, Medusa executes it as an async method:
-
-```ts
-await blogModuleService.getMessage()
-```
-
-So, make sure your service's methods are always async to avoid unexpected errors or behavior.
-
-```ts highlights={[["8", "", "Method must be async."], ["13", "async", "Correct way of defining the method."]]}
-import { MedusaService } from "@medusajs/framework/utils"
-import Post from "./models/post"
-
-class BlogModuleService extends MedusaService({
- Post,
-}){
- // Don't
- getMessage(): string {
- return "Hello, World!"
- }
-
- // Do
- async getMessage(): Promise {
- return "Hello, World!"
- }
-}
-
-export default BlogModuleService
-```
-
-
-# Query Context
-
-In this chapter, you'll learn how to pass contexts when retrieving data with [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query/index.html.md).
-
-## What is Query Context?
-
-Query context is a way to pass additional information when retrieving data with Query. This data can be useful when applying custom transformations to the retrieved data based on the current context.
-
-For example, consider you have a Blog Module with posts and authors. You can accept the user's language as a context and return the posts in the user's language. Another example is how Medusa uses Query Context to [retrieve product variants' prices based on the customer's currency](https://docs.medusajs.com/resources/commerce-modules/product/guides/price/index.html.md).
-
-***
-
-## How to Use Query Context
-
-The `query.graph` method accepts an optional `context` parameter that can be used to pass additional context either to the data model you're retrieving (for example, `post`), or its related and linked models (for example, `author`).
-
-You initialize a context using `QueryContext` from the Modules SDK. It accepts an object of contexts as an argument.
-
-For example, to retrieve posts using Query while passing the user's language as a context:
-
-```ts
-const { data } = await query.graph({
- entity: "post",
- fields: ["*"],
- context: QueryContext({
- lang: "es",
- }),
-})
-```
-
-In this example, you pass in the context a `lang` property whose value is `es`.
-
-Then, to handle the context while retrieving records of the data model, in the associated module's service you override the generated `list` method of the data model.
-
-For example, continuing the example above, you can override the `listPosts` method of the Blog Module's service to handle the context:
-
-```ts highlights={highlights2}
-import { MedusaContext, MedusaService } from "@medusajs/framework/utils"
-import { Context, FindConfig } from "@medusajs/framework/types"
-import Post from "./models/post"
-import Author from "./models/author"
-
-class BlogModuleService extends MedusaService({
- Post,
- Author,
-}){
- // @ts-ignore
- async listPosts(
- filters?: any,
- config?: FindConfig | undefined,
- @MedusaContext() sharedContext?: Context | undefined
- ) {
- const context = filters.context ?? {}
- delete filters.context
-
- let posts = await super.listPosts(filters, config, sharedContext)
-
- if (context.lang === "es") {
- posts = posts.map((post) => {
- return {
- ...post,
- title: post.title + " en español",
- }
- })
- }
-
- return posts
- }
-}
-
-export default BlogModuleService
-```
-
-In the above example, you override the generated `listPosts` method. This method receives as a first parameter the filters passed to the query, but it also includes a `context` property that holds the context passed to the query.
-
-You extract the context from `filters`, then retrieve the posts using the parent's `listPosts` method. After that, if the language is set in the context, you transform the titles of the posts.
-
-All posts returned will now have their titles appended with "en español".
-
-Learn more about the generated `list` method in [this reference](https://docs.medusajs.com/resources/service-factory-reference/methods/list/index.html.md).
-
-### Using Pagination with Query
-
-If you pass pagination fields to `query.graph`, you must also override the `listAndCount` method in the service.
-
-For example, following along with the previous example, you must override the `listAndCountPosts` method of the Blog Module's service:
-
-```ts
-import { MedusaContext, MedusaService } from "@medusajs/framework/utils"
-import { Context, FindConfig } from "@medusajs/framework/types"
-import Post from "./models/post"
-import Author from "./models/author"
-
-class BlogModuleService extends MedusaService({
- Post,
- Author,
-}){
- // @ts-ignore
- async listAndCountPosts(
- filters?: any,
- config?: FindConfig | undefined,
- @MedusaContext() sharedContext?: Context | undefined
- ) {
- const context = filters.context ?? {}
- delete filters.context
-
- const result = await super.listAndCountPosts(
- filters,
- config,
- sharedContext
+```ts title="src/workflows/my-workflow/index.ts" highlights={hookHighlights}
+import {
+ createStep,
+ createHook,
+ createWorkflow,
+ WorkflowResponse,
+} from "@medusajs/framework/workflows-sdk"
+import { createProductStep } from "./steps/create-product"
+
+export const myWorkflow = createWorkflow(
+ "my-workflow",
+ function (input) {
+ const product = createProductStep(input)
+ const productCreatedHook = createHook(
+ "productCreated",
+ { productId: product.id }
)
- if (context.lang === "es") {
- result.posts = posts.map((post) => {
- return {
- ...post,
- title: post.title + " en español",
- }
- })
- }
-
- return result
- }
-}
-
-export default BlogModuleService
-```
-
-Now, the `listAndCountPosts` method will handle the context passed to `query.graph` when you pass pagination fields. You can also move the logic to transform the posts' titles to a separate method and call it from both `listPosts` and `listAndCountPosts`.
-
-***
-
-## Passing Query Context to Related Data Models
-
-If you're retrieving a data model and you want to pass context to its associated model in the same module, you can pass them as part of `QueryContext`'s parameter, then handle them in the same `list` method.
-
-For linked data models, check out the [next section](#passing-query-context-to-linked-data-models).
-
-For example, to pass a context for the post's authors:
-
-```ts highlights={highlights3}
-const { data } = await query.graph({
- entity: "post",
- fields: ["*"],
- context: QueryContext({
- lang: "es",
- author: QueryContext({
- lang: "es",
- }),
- }),
-})
-```
-
-Then, in the `listPosts` method, you can handle the context for the post's authors:
-
-```ts highlights={highlights4}
-import { MedusaContext, MedusaService } from "@medusajs/framework/utils"
-import { Context, FindConfig } from "@medusajs/framework/types"
-import Post from "./models/post"
-import Author from "./models/author"
-
-class BlogModuleService extends MedusaService({
- Post,
- Author,
-}){
- // @ts-ignore
- async listPosts(
- filters?: any,
- config?: FindConfig | undefined,
- @MedusaContext() sharedContext?: Context | undefined
- ) {
- const context = filters.context ?? {}
- delete filters.context
-
- let posts = await super.listPosts(filters, config, sharedContext)
-
- const isPostLangEs = context.lang === "es"
- const isAuthorLangEs = context.author?.lang === "es"
-
- if (isPostLangEs || isAuthorLangEs) {
- posts = posts.map((post) => {
- return {
- ...post,
- title: isPostLangEs ? post.title + " en español" : post.title,
- author: {
- ...post.author,
- name: isAuthorLangEs ? post.author.name + " en español" : post.author.name,
- },
- }
- })
- }
-
- return posts
- }
-}
-
-export default BlogModuleService
-```
-
-The context in `filters` will also have the context for `author`, which you can use to make transformations to the post's authors.
-
-***
-
-## Passing Query Context to Linked Data Models
-
-If you're retrieving a data model and you want to pass context to a linked model in a different module, pass to the `context` property an object instead, where its keys are the linked model's name and the values are the context for that linked model.
-
-For example, consider the Product Module's `Product` data model is linked to the Blog Module's `Post` data model. You can pass context to the `Post` data model while retrieving products like so:
-
-```ts highlights={highlights5}
-const { data } = await query.graph({
- entity: "product",
- fields: ["*", "post.*"],
- context: {
- post: QueryContext({
- lang: "es",
- }),
- },
-})
-```
-
-In this example, you retrieve products and their associated posts. You also pass a context for `post`, indicating the customer's language.
-
-To handle the context, you override the generated `listPosts` method of the Blog Module as explained [previously](#how-to-use-query-context).
-
-
-# Read-Only Module Link
-
-In this chapter, you’ll learn what a read-only module link is and how to define one.
-
-## What is a Read-Only Module Link?
-
-Consider a scenario where you need to access related records from another module, but don't want the overhead of managing or storing the links between them. This can include cases where you're working with external data models not stored in your Medusa database, such as third-party systems.
-
-In those cases, instead of defining a [Module Link](https://docs.medusajs.com/learn/fundamentals/module-links/index.html.md) whose linked records must be stored in a link table in the database, you can use a read-only module link. A read-only module link builds a virtual relation from one data model to another in a different module without creating a link table in the database. Instead, the linked record's ID is stored in the first data model's field.
-
-For example, Medusa creates a read-only module link from the `Cart` data model of the [Cart Module](https://docs.medusajs.com/resources/commerce-modules/cart/index.html.md) to the `Customer` data model of the [Customer Module](https://docs.medusajs.com/resources/commerce-modules/customer/index.html.md). This link allows you to access the details of the cart's customer without managing the link. Instead, the customer's ID is stored in the `Cart` data model.
-
-
-
-***
-
-## How to Define a Read-Only Module Link
-
-The `defineLink` function accepts an optional third-parameter object that can hold additional configurations for the module link.
-
-If you're not familiar with the `defineLink` function, refer to the [Module Links chapter](https://docs.medusajs.com/learn/fundamentals/module-links/index.html.md) for more information.
-
-To make the module link read-only, pass the `readOnly` property as `true`. You must also set in the link configuration of the first data model a `field` property that specifies the data model's field where the linked record's ID is stored.
-
-For example:
-
-```ts highlights={highlights}
-import BlogModule from "../modules/blog"
-import ProductModule from "@medusajs/medusa/product"
-import { defineLink } from "@medusajs/framework/utils"
-
-export default defineLink(
- {
- linkable: BlogModule.linkable.post,
- field: "product_id",
- },
- ProductModule.linkable.product,
- {
- readOnly: true,
- }
-)
-```
-
-In this example, you define a read-only module link from the Blog Module's `post` data model to the Product Module's `product` data model. You do that by:
-
-- Passing an object as a first parameter that accepts the linkable configuration and the field where the linked record's ID is stored.
-- Setting the `readOnly` property to `true` in the third parameter.
-
-Unlike the stored module link, Medusa will not create a table in the database for this link. Instead, Medusa uses the ID stored in the specified field of the first data model to retrieve the linked record.
-
-***
-
-## Retrieve Read-Only Linked Record
-
-[Query](https://docs.medusajs.com/learn/fundamentals/module-links/query/index.html.md) allows you to retrieve records linked through a read-only module link.
-
-For example, assuming you have the module link created in [the above section](#how-to-define-a-read-only-module-link), you can retrieve a post and its linked product as follows:
-
-```ts
-const { result } = await query.graph({
- entity: "post",
- fields: ["id", "product.*"],
- filters: {
- id: "post_123",
- },
-})
-```
-
-In the above example, you retrieve a post and its linked product. Medusa will use the ID of the product in the post's `product_id` field to determine which product should be retrieved.
-
-***
-
-## Read-Only Module Link Direction
-
-A read-only module is uni-directional. So, you can only retrieve the linked record from the first data model. If you need to access the linked record from the second data model, you must define another read-only module link in the opposite direction.
-
-In the `blog` -> `product` example, you can access a post's product, but you can't access a product's posts. You would have to define another read-only module link from `product` to `blog` to access a product's posts.
-
-***
-
-## Inverse Read-Only Module Link
-
-An inverse read-only module link is a read-only module link that allows you to access the linked record based on the ID stored in the second data model.
-
-For example, consider you want to access a product's posts. You can define a read-only module link from the Product Module's `product` data model to the Blog Module's `post` data model:
-
-```ts
-import BlogModule from "../modules/blog"
-import ProductModule from "@medusajs/medusa/product"
-import { defineLink } from "@medusajs/framework/utils"
-
-export default defineLink(
- {
- linkable: ProductModule.linkable.product,
- field: "id",
- },
- {
- ...BlogModule.linkable.post.id,
- primaryKey: "product_id",
- },
- {
- readOnly: true,
- }
-)
-```
-
-In the above example, you define a read-only module link from the Product Module's `product` data model to the Blog Module's `post` data model. This link allows you to access a product's posts.
-
-Since you can't add a `post_id` field to the `product` data model, you must:
-
-1. Set the `field` property in the first data model's link configuration to the product's ID field.
-2. Spread the `BlogModule.linkable.post.id` object in the second parameter object and set the `primaryKey` property to the field in the `post` data model that holds the product's ID.
-
-You can now retrieve a product and its linked posts:
-
-```ts
-const { result } = await query.graph({
- entity: "product",
- fields: ["id", "post.*"],
- filters: {
- id: "prod_123",
- },
-})
-```
-
-***
-
-## One-to-One or One-to-Many?
-
-When you retrieve the linked record through a read-only module link, the retrieved data may be an object (one-to-one) or an array of objects (one-to-many) based on different criteria.
-
-|Scenario|Relation Type|
-|---|---|---|
-|The first data model's |One-to-one relation|
-|The first data model's |One-to-many relation|
-|The read-only module link is inversed.|One-to-many relation if multiple records in the second data model have the same ID of the first data model. Otherwise, one-to-one relation.|
-
-### One-to-One Relation
-
-Consider the first read-only module link you defined in this chapter:
-
-```ts
-import BlogModule from "../modules/blog"
-import ProductModule from "@medusajs/medusa/product"
-
-export default defineLink(
- {
- linkable: BlogModule.linkable.post,
- field: "product_id",
- },
- ProductModule.linkable.product,
- {
- readOnly: true,
- }
-)
-```
-
-Since the `product_id` field of a post stores the ID of a single product, the link is a one-to-one relation. When querying a post, you'll get a single product object:
-
-```json title="Example Data"
-[
- {
- "id": "post_123",
- "product_id": "prod_123",
- "product": {
- "id": "prod_123",
- // ...
- }
- }
-]
-```
-
-### One-to-Many Relation
-
-Consider the read-only module link from the `post` data model uses an array of product IDs:
-
-```ts
-import BlogModule from "../modules/blog"
-import ProductModule from "@medusajs/medusa/product"
-
-export default defineLink(
- {
- linkable: BlogModule.linkable.post,
- field: "product_ids",
- },
- ProductModule.linkable.product,
- {
- readOnly: true,
- }
-)
-```
-
-Where `product_ids` in the `post` data model is an array of strings. In this case, the link would be a one-to-many relation. So, an array of products would be returned when querying a post:
-
-```json title="Example Data"
-[
- {
- "id": "post_123",
- "product_ids": ["prod_123", "prod_124"],
- "product": [
- {
- "id": "prod_123",
- // ...
- },
- {
- "id": "prod_124",
- // ...
- }
- ]
- }
-]
-```
-
-### Relation with Inversed Read-Only Link
-
-If you define an inversed read-only module link where the ID of the linked record is stored in the second data model, the link can be either one-to-one or one-to-many based on the number of records in the second data model that have the same ID of the first data model.
-
-For example, consider the `product` -> `post` link you defined in an earlier section:
-
-```ts
-import BlogModule from "../modules/blog"
-import ProductModule from "@medusajs/medusa/product"
-import { defineLink } from "@medusajs/framework/utils"
-
-export default defineLink(
- {
- linkable: ProductModule.linkable.product,
- field: "id",
- },
- {
- ...BlogModule.linkable.post.id,
- primaryKey: "product_id",
- },
- {
- readOnly: true,
- }
-)
-```
-
-In the above snippet, the ID of the product is stored in the `post`'s `product_id` string field.
-
-When you retrieve the post of a product, it may be a post object, or an array of post objects if multiple posts are linked to the product:
-
-```json title="Example Data"
-[
- {
- "id": "prod_123",
- "post": {
- "id": "post_123",
- "product_id": "prod_123"
- // ...
- }
- },
- {
- "id": "prod_321",
- "post": [
- {
- "id": "post_123",
- "product_id": "prod_321"
- // ...
- },
- {
- "id": "post_124",
- "product_id": "prod_321"
- // ...
- }
- ]
- }
-]
-```
-
-If, however, you use an array field in `post`, the relation would always be one-to-many:
-
-```json title="Example Data"
-[
- {
- "id": "prod_123",
- "post": [
- {
- "id": "post_123",
- "product_id": "prod_123"
- // ...
- }
- ]
- }
-]
-```
-
-#### Force One-to-Many Relation
-
-Alternatively, you can force a one-to-many relation by setting `isList` to `true` in the first data model's link configuration. For example:
-
-```ts
-import BlogModule from "../modules/blog"
-import ProductModule from "@medusajs/medusa/product"
-import { defineLink } from "@medusajs/framework/utils"
-
-export default defineLink(
- {
- linkable: ProductModule.linkable.product,
- field: "id",
- isList: true,
- },
- {
- ...BlogModule.linkable.post.id,
- primaryKey: "product_id",
- },
- {
- readOnly: true,
- }
-)
-```
-
-In this case, the relation would always be one-to-many, even if only one post is linked to a product:
-
-```json title="Example Data"
-[
- {
- "id": "prod_123",
- "post": [
- {
- "id": "post_123",
- "product_id": "prod_123"
- // ...
- }
- ]
- }
-]
-```
-
-***
-
-## Example: Read-Only Module Link for Virtual Data Models
-
-Read-only module links are most useful when working with data models that aren't stored in your Medusa database. For example, data that is stored in a third-party system. In those cases, you can define a read-only module link between a data model in Medusa and the data model in the external system, facilitating the retrieval of the linked data.
-
-To define the read-only module link to a virtual data model, you must:
-
-1. Create a `list` method in the custom module's service. This method retrieves the linked records filtered by the ID(s) of the first data model.
- - You can also create a `listAndCount` method to retrieve the related records with pagination.
-2. Define the read-only module link from the first data model to the virtual data model.
-3. Use Query to retrieve the first data model and its linked records from the virtual data model.
-
-For example, consider you have a third-party Content-Management System (CMS) that you're integrating with Medusa, and you want to retrieve the posts in the CMS associated with a product in Medusa.
-
-To do that, first, create a CMS Module having the following service:
-
-Refer to the [Modules chapter](https://docs.medusajs.com/learn/fundamentals/modules/index.html.md) to learn how to create a module and its service.
-
-```ts title="src/modules/cms/service.ts"
-import { FindConfig } from "@medusajs/framework/types"
-
-type CmsModuleOptions = {
- apiKey: string
-}
-
-export default class CmsModuleService {
- private client
-
- constructor({}, options: CmsModuleOptions) {
- this.client = new Client(options)
- }
-
- async list(
- filter: {
- id: string | string[]
- }
- ) {
- return this.client.getPosts(filter)
- /**
- - Example of returned data:
- -
- - [
- - {
- - "id": "post_123",
- - "product_id": "prod_321"
- - },
- - {
- - "id": "post_456",
- - "product_id": "prod_654"
- - }
- - ]
- */
- }
-
- // To retrieve with pagination
- async listAndCount(
- filter: {
- id: string | string[]
- },
- config?: FindConfig | undefined
- ) {
- return this.client.getPosts(filter, {
- limit: config?.take,
- offset: config?.skip,
+ return new WorkflowResponse(product, {
+ hooks: [productCreatedHook],
})
- /**
- - Example of returned data:
- -
- - {
- - count: 2,
- - data: [
- - {
- - "id": "post_123",
- - "product_id": "prod_321"
- - },
- - {
- - "id": "post_456",
- - "product_id": "prod_654"
- - }
- - ]
- - }
- */
- }
-}
-```
-
-The above service initializes a client, assuming your CMS has an SDK that allows you to retrieve posts.
-
-The service must have a `list` method to be part of the read-only module link. This method accepts the ID(s) of the products to retrieve their associated posts. The posts must include the product's ID in a field, such as `product_id`.
-
-You can also create a `listAndCount` method to retrieve the posts with pagination. This method is called if you pass [pagination parameters to Query](https://docs.medusajs.com/learn/fundamentals/module-links/query#apply-pagination/index.html.md).
-
-Next, define a read-only module link from the Product Module to the CMS Module:
-
-```ts title="src/links/product-cms.ts"
-import { defineLink } from "@medusajs/framework/utils"
-import ProductModule from "@medusajs/medusa/product"
-import { CMS_MODULE } from "../modules/cms"
-
-export default defineLink(
- {
- linkable: ProductModule.linkable.product,
- field: "id",
- },
- {
- linkable: {
- serviceName: CMS_MODULE,
- alias: "cms_post",
- primaryKey: "product_id",
- },
- },
- {
- readOnly: true,
}
)
```
-To define the read-only module link, you must pass to `defineLink`:
+The `createHook` function accepts two parameters:
-1. The first parameter: an object with the linkable configuration of the data model in Medusa, and the fields that will be passed as a filter to the CMS service. For example, if you want to filter by product title instead, you can pass `title` instead of `id`.
-2. The second parameter: an object with the linkable configuration of the virtual data model in the CMS. This object must have the following properties:
- - `serviceName`: The name of the service, which is the CMS Module's name. Medusa uses this name to resolve the module's service from the [Medusa container](https://docs.medusajs.com/learn/fundamentals/medusa-container/index.html.md).
- - `alias`: The alias to use when querying the linked records. You'll see how that works in a bit.
- - `primaryKey`: The field in the CMS data model that holds the ID of a product.
-3. The third parameter: an object with the `readOnly` property set to `true`.
+1. The first is a string indicating the hook's name. You use this to consume the hook later.
+2. The second is the input to pass to the hook handler.
-Now, you can use Query to retrieve a product and its linked post from the CMS:
+The workflow must also pass an object having a `hooks` property as a second parameter to the `WorkflowResponse` constructor. Its value is an array of the workflow's hooks.
-```ts
-const { data } = await query.graph({
- entity: "product",
- fields: ["id", "cms_post.*"],
-})
-```
+### How to Consume the Hook?
-In the above example, each product that has a CMS post with the `product_id` field set to the product's ID will be retrieved:
+To consume the hook of the workflow, create the file `src/workflows/hooks/my-workflow.ts` with the following content:
-```json title="Example Data"
-[
- {
- "id": "prod_123",
- "cms_post": {
- "id": "post_123",
- "product_id": "prod_123",
- // ...
- }
+```ts title="src/workflows/hooks/my-workflow.ts" highlights={handlerHighlights}
+import { myWorkflow } from "../my-workflow"
+
+myWorkflow.hooks.productCreated(
+ async ({ productId }, { container }) => {
+ // TODO perform an action
}
-]
+)
```
-If multiple posts have their `product_id` set to a product's ID, an array of posts is returned instead:
+The hook is available on the workflow's `hooks` property using its name `productCreated`.
-```json title="Example Data"
-[
- {
- "id": "prod_123",
- "cms_post": [
- {
- "id": "post_123",
- "product_id": "prod_123",
- // ...
- },
- {
- "id": "post_124",
- "product_id": "prod_123",
- // ...
- }
- ]
- }
-]
-```
-
-[Sanity Integration Tutorial](https://docs.medusajs.com/resources/integrations/guides/sanity/index.html.md).
+You invoke the hook, passing a step function (the hook handler) as a parameter.
# Compensation Function
@@ -14732,966 +15533,6 @@ So, if an error occurs during the loop, the compensation function will still rec
For more details on error handling in workflows and steps, check the [Handling Errors chapter](https://docs.medusajs.com/learn/fundamentals/workflows/errors/index.html.md).
-# Query
-
-In this chapter, you’ll learn about Query and how to use it to fetch data from modules.
-
-## What is Query?
-
-Query fetches data across modules. It’s a set of methods registered in the Medusa container under the `query` key.
-
-In all resources that can access the [Medusa Container](https://docs.medusajs.com/learn/fundamentals/medusa-container/index.html.md), such as API routes or workflows, you can resolve Query to fetch data across custom modules and Medusa’s Commerce Modules.
-
-***
-
-## Query Example
-
-For example, create the route `src/api/query/route.ts` with the following content:
-
-```ts title="src/api/query/route.ts" highlights={exampleHighlights} collapsibleLines="1-8" expandButtonLabel="Show Imports"
-import {
- MedusaRequest,
- MedusaResponse,
-} from "@medusajs/framework/http"
-import {
- ContainerRegistrationKeys,
-} from "@medusajs/framework/utils"
-
-export const GET = async (
- req: MedusaRequest,
- res: MedusaResponse
-) => {
- const query = req.scope.resolve(ContainerRegistrationKeys.QUERY)
-
- const { data: posts } = await query.graph({
- entity: "post",
- fields: ["id", "title"],
- })
-
- res.json({ posts })
-}
-```
-
-In the above example, you resolve Query from the Medusa container using the `ContainerRegistrationKeys.QUERY` (`query`) key.
-
-Then, you run a query using its `graph` method. This method accepts as a parameter an object with the following required properties:
-
-- `entity`: The data model's name, as specified in the first parameter of the `model.define` method used for the data model's definition.
-- `fields`: An array of the data model’s properties to retrieve in the result.
-
-The method returns an object that has a `data` property, which holds an array of the retrieved data. For example:
-
-```json title="Returned Data"
-{
- "data": [
- {
- "id": "123",
- "title": "My Post"
- }
- ]
-}
-```
-
-***
-
-## Querying the Graph
-
-When you use the `query.graph` method, you're running a query through an internal graph that the Medusa application creates.
-
-This graph collects data models of all modules in your application, including commerce and custom modules, and identifies relations and links between them.
-
-***
-
-## Retrieve Linked Records
-
-Retrieve the records of a linked data model by passing in `fields` the data model's name suffixed with `.*`.
-
-For example:
-
-```ts highlights={[["6"]]}
-const { data: posts } = await query.graph({
- entity: "post",
- fields: [
- "id",
- "title",
- "product.*",
- ],
-})
-```
-
-`.*` means that all of data model's properties should be retrieved. You can also retrieve specific properties by replacing the `*` with the property name, for each property.
-
-For example:
-
-```ts
-const { data: posts } = await query.graph({
- entity: "post",
- fields: [
- "id",
- "title",
- "product.id",
- "product.title",
- ],
-})
-```
-
-In the example above, you retrieve only the `id` and `title` properties of the `product` linked to a `post`.
-
-### Retrieve List Link Records
-
-If the linked data model has `isList` enabled in the link definition, pass in `fields` the data model's plural name suffixed with `.*`.
-
-For example:
-
-```ts highlights={[["6"]]}
-const { data: posts } = await query.graph({
- entity: "post",
- fields: [
- "id",
- "title",
- "products.*",
- ],
-})
-```
-
-In the example above, you retrieve all products linked to a post.
-
-### Apply Filters and Pagination on Linked Records
-
-Consider you want to apply filters or pagination configurations on the product(s) linked to `post`. To do that, you must query the module link's table instead.
-
-As mentioned in the [Module Link](https://docs.medusajs.com/learn/fundamentals/module-links/index.html.md) documentation, Medusa creates a table for your module link. So, not only can you retrieve linked records, but you can also retrieve the records in a module link's table.
-
-A module link's definition, exported by a file under `src/links`, has a special `entryPoint` property. Use this property when specifying the `entity` property in Query's `graph` method.
-
-For example:
-
-```ts highlights={queryLinkTableHighlights}
-import ProductPostLink from "../../../links/product-post"
-
-// ...
-
-const { data: productCustoms } = await query.graph({
- entity: ProductPostLink.entryPoint,
- fields: ["*", "product.*", "post.*"],
- pagination: {
- take: 5,
- skip: 0,
- },
-})
-```
-
-In the object passed to the `graph` method:
-
-- You pass the `entryPoint` property of the link definition as the value for `entity`. So, Query will retrieve records from the module link's table.
-- You pass three items to the `field` property:
- - `*` to retrieve the link table's fields. This is useful if the link table has [custom columns](https://docs.medusajs.com/learn/fundamentals/module-links/custom-columns/index.html.md).
- - `product.*` to retrieve the fields of a product record linked to a `Post` record.
- - `post.*` to retrieve the fields of a `Post` record linked to a product record.
-
-You can then apply any [filters](#apply-filters) or [pagination configurations](#apply-pagination) on the module link's table. For example, you can apply filters on the `product_id`, `post_id`, and any other custom columns you defined in the link table.
-
-The returned `data` is similar to the following:
-
-```json title="Example Result"
-[{
- "id": "123",
- "product_id": "prod_123",
- "post_id": "123",
- "product": {
- "id": "prod_123",
- // other product fields...
- },
- "post": {
- "id": "123",
- // other post fields...
- }
-}]
-```
-
-***
-
-## Apply Filters
-
-```ts highlights={[["4"], ["5"], ["6"]]}
-const { data: posts } = await query.graph({
- entity: "post",
- fields: ["id", "title"],
- filters: {
- id: "post_123",
- },
-})
-```
-
-The `query.graph` function accepts a `filters` property. You can use this property to filter retrieved records.
-
-In the example above, you filter the `post` records by the ID `post_123`.
-
-You can also filter by multiple values of a property. For example:
-
-```ts highlights={[["4"], ["5"], ["6"], ["7"], ["8"], ["9"]]}
-const { data: posts } = await query.graph({
- entity: "post",
- fields: ["id", "title"],
- filters: {
- id: [
- "post_123",
- "post_321",
- ],
- },
-})
-```
-
-In the example above, you filter the `post` records by multiple IDs.
-
-Filters don't apply on fields of linked data models from other modules. Refer to the [Retrieve Linked Records](#retrieve-linked-records) section for an alternative solution.
-
-### Advanced Query Filters
-
-Under the hood, Query uses one of the following methods from the data model's module's service to retrieve records:
-
-- `listX` if you don't pass [pagination parameters](#apply-pagination). For example, `listPosts`.
-- `listAndCountX` if you pass pagination parameters. For example, `listAndCountPosts`.
-
-Both methods accepts a filter object that can be used to filter records.
-
-Those filters don't just allow you to filter by exact values. You can also filter by properties that don't match a value, match multiple values, and other filter types.
-
-Refer to the [Service Factory Reference](https://docs.medusajs.com/resources/service-factory-reference/tips/filtering/index.html.md) for examples of advanced filters. The following sections provide some quick examples.
-
-#### Filter by Not Matching a Value
-
-```ts highlights={[["4"], ["5"], ["6"], ["7"], ["8"]]}
-const { data: posts } = await query.graph({
- entity: "post",
- fields: ["id", "title"],
- filters: {
- title: {
- $ne: null,
- },
- },
-})
-```
-
-In the example above, only posts that have a title are retrieved.
-
-#### Filter by Not Matching Multiple Values
-
-```ts highlights={[["4"], ["5"], ["6"], ["7"], ["8"]]}
-const { data: posts } = await query.graph({
- entity: "post",
- fields: ["id", "title"],
- filters: {
- title: {
- $nin: ["My Post", "Another Post"],
- },
- },
-})
-```
-
-In the example above, only posts that don't have the title `My Post` or `Another Post` are retrieved.
-
-#### Filter by a Range
-
-```ts highlights={[["10"], ["11"], ["12"], ["13"], ["14"], ["15"]]}
-const startToday = new Date()
-startToday.setHours(0, 0, 0, 0)
-
-const endToday = new Date()
-endToday.setHours(23, 59, 59, 59)
-
-const { data: posts } = await query.graph({
- entity: "post",
- fields: ["id", "title"],
- filters: {
- published_at: {
- $gt: startToday,
- $lt: endToday,
- },
- },
-})
-```
-
-In the example above, only posts that were published today are retrieved.
-
-#### Filter Text by Like Value
-
-This filter only applies to text-like properties, including `text`, `id`, and `enum` properties.
-
-```ts highlights={[["4"], ["5"], ["6"], ["7"], ["8"]]}
-const { data: posts } = await query.graph({
- entity: "post",
- fields: ["id", "title"],
- filters: {
- title: {
- $like: "%My%",
- },
- },
-})
-```
-
-In the example above, only posts that have the word `My` in their title are retrieved.
-
-#### Filter a Relation's Property
-
-```ts highlights={[["4"], ["5"], ["6"], ["7"], ["8"]]}
-const { data: posts } = await query.graph({
- entity: "post",
- fields: ["id", "title"],
- filters: {
- author: {
- name: "John",
- },
- },
-})
-```
-
-While it's not possible to filter by a linked data model's property, you can filter by a relation's property (that is, the property of a related data model that is defined in the same module).
-
-In the example above, only posts that have an author with the name `John` are retrieved.
-
-***
-
-## Apply Pagination
-
-```ts highlights={[["8", "skip", "The number of records to skip before fetching the results."], ["9", "take", "The number of records to fetch."]]}
-const {
- data: posts,
- metadata: { count, take, skip } = {},
-} = await query.graph({
- entity: "post",
- fields: ["id", "title"],
- pagination: {
- skip: 0,
- take: 10,
- },
-})
-```
-
-The `graph` method's object parameter accepts a `pagination` property to configure the pagination of retrieved records.
-
-To paginate the returned records, pass the following properties to `pagination`:
-
-- `skip`: (required to apply pagination) The number of records to skip before fetching the results.
-- `take`: The number of records to fetch.
-
-When you provide the pagination fields, the `query.graph` method's returned object has a `metadata` property. Its value is an object having the following properties:
-
-- skip: (\`number\`) The number of records skipped.
-- take: (\`number\`) The number of records requested to fetch.
-- count: (\`number\`) The total number of records.
-
-### Sort Records
-
-```ts highlights={[["5"], ["6"], ["7"]]}
-const { data: posts } = await query.graph({
- entity: "post",
- fields: ["id", "title"],
- pagination: {
- order: {
- name: "DESC",
- },
- },
-})
-```
-
-Sorting doesn't work on fields of linked data models from other modules.
-
-To sort returned records, pass an `order` property to `pagination`.
-
-The `order` property is an object whose keys are property names, and values are either:
-
-- `ASC` to sort records by that property in ascending order.
-- `DESC` to sort records by that property in descending order.
-
-***
-
-## Configure Query to Throw Errors
-
-By default, if Query doesn't find records matching your query, it returns an empty array. You can add option to configure Query to throw an error when no records are found.
-
-The `query.graph` method accepts as a second parameter an object that can have a `throwIfKeyNotFound` property. Its value is a boolean indicating whether to throw an error if no record is found when filtering by IDs. By default, it's `false`.
-
-For example:
-
-```ts
-const { data: posts } = await query.graph({
- entity: "post",
- fields: ["id", "title"],
- filters: {
- id: "post_123",
- },
-}, {
- throwIfKeyNotFound: true,
-})
-```
-
-In the example above, if no post is found with the ID `post_123`, Query will throw an error. This is useful to stop execution when a record is expected to exist.
-
-### Throw Error on Related Data Model
-
-The `throwIfKeyNotFound` option can also be used to throw an error if the ID of a related data model's record (in the same module) is passed in the filters, and the related record doesn't exist.
-
-For example:
-
-```ts
-const { data: posts } = await query.graph({
- entity: "post",
- fields: ["id", "title", "author.*"],
- filters: {
- id: "post_123",
- author_id: "author_123",
- },
-}, {
- throwIfKeyNotFound: true,
-})
-```
-
-In the example above, Query throws an error either if no post is found with the ID `post_123` or if its found but its author ID isn't `author_123`.
-
-In the above example, it's assumed that a post belongs to an author, so it has an `author_id` property. However, this also works in the opposite case, where an author has many posts.
-
-For example:
-
-```ts
-const { data: posts } = await query.graph({
- entity: "author",
- fields: ["id", "name", "posts.*"],
- filters: {
- id: "author_123",
- posts: {
- id: "post_123",
- },
- },
-}, {
- throwIfKeyNotFound: true,
-})
-```
-
-In the example above, Query throws an error if no author is found with the ID `author_123` or if the author is found but doesn't have a post with the ID `post_123`.
-
-***
-
-## Request Query Configurations
-
-For API routes that retrieve a single or list of resources, Medusa provides a `validateAndTransformQuery` middleware that:
-
-- Validates accepted query parameters, as explained in [this documentation](https://docs.medusajs.com/learn/fundamentals/api-routes/validation/index.html.md).
-- Parses configurations that are received as query parameters to be passed to Query.
-
-Using this middleware allows you to have default configurations for retrieved fields and relations or pagination, while allowing clients to customize them per request.
-
-### Step 1: Add Middleware
-
-The first step is to use the `validateAndTransformQuery` middleware on the `GET` route. You add the middleware in `src/api/middlewares.ts`:
-
-```ts title="src/api/middlewares.ts"
-import {
- validateAndTransformQuery,
- defineMiddlewares,
-} from "@medusajs/framework/http"
-import { createFindParams } from "@medusajs/medusa/api/utils/validators"
-
-export const GetCustomSchema = createFindParams()
-
-export default defineMiddlewares({
- routes: [
- {
- matcher: "/customs",
- method: "GET",
- middlewares: [
- validateAndTransformQuery(
- GetCustomSchema,
- {
- defaults: [
- "id",
- "title",
- "products.*",
- ],
- isList: true,
- }
- ),
- ],
- },
- ],
-})
-```
-
-The `validateAndTransformQuery` accepts two parameters:
-
-1. A Zod validation schema for the query parameters, which you can learn more about in the [API Route Validation documentation](https://docs.medusajs.com/learn/fundamentals/api-routes/validation/index.html.md). Medusa has a `createFindParams` utility that generates a Zod schema that accepts four query parameters:
- 1. `fields`: The fields and relations to retrieve in the returned resources.
- 2. `offset`: The number of items to skip before retrieving the returned items.
- 3. `limit`: The maximum number of items to return.
- 4. `order`: The fields to order the returned items by in ascending or descending order.
-2. A Query configuration object. It accepts the following properties:
- 1. `defaults`: An array of default fields and relations to retrieve in each resource.
- 2. `isList`: A boolean indicating whether a list of items are returned in the response.
- 3. `allowed`: An array of fields and relations allowed to be passed in the `fields` query parameter.
- 4. `defaultLimit`: A number indicating the default limit to use if no limit is provided. By default, it's `50`.
-
-### Step 2: Use Configurations in API Route
-
-After applying this middleware, your API route now accepts the `fields`, `offset`, `limit`, and `order` query parameters mentioned above.
-
-The middleware transforms these parameters to configurations that you can pass to Query in your API route handler. These configurations are stored in the `queryConfig` parameter of the `MedusaRequest` object.
-
-As of [Medusa v2.2.0](https://github.com/medusajs/medusa/releases/tag/v2.2.0), `remoteQueryConfig` has been deprecated in favor of `queryConfig`. Their usage is still the same, only the property name has changed.
-
-For example, Create the file `src/api/customs/route.ts` with the following content:
-
-```ts title="src/api/customs/route.ts"
-import {
- MedusaRequest,
- MedusaResponse,
-} from "@medusajs/framework/http"
-import {
- ContainerRegistrationKeys,
-} from "@medusajs/framework/utils"
-
-export const GET = async (
- req: MedusaRequest,
- res: MedusaResponse
-) => {
- const query = req.scope.resolve(ContainerRegistrationKeys.QUERY)
-
- const { data: posts } = await query.graph({
- entity: "post",
- ...req.queryConfig,
- })
-
- res.json({ posts: posts })
-}
-```
-
-This adds a `GET` API route at `/customs`, which is the API route you added the middleware for.
-
-In the API route, you pass `req.queryConfig` to `query.graph`. `queryConfig` has properties like `fields` and `pagination` to configure the query based on the default values you specified in the middleware, and the query parameters passed in the request.
-
-### Test it Out
-
-To test it out, start your Medusa application and send a `GET` request to the `/customs` API route. A list of records are retrieved with the specified fields in the middleware.
-
-```json title="Returned Data"
-{
- "posts": [
- {
- "id": "123",
- "title": "test"
- }
- ]
-}
-```
-
-Try passing one of the Query configuration parameters, like `fields` or `limit`, and you'll see its impact on the returned result.
-
-Learn more about [specifing fields and relations](https://docs.medusajs.com/api/store#select-fields-and-relations) and [pagination](https://docs.medusajs.com/api/store#pagination) in the API reference.
-
-
-# Conditions in Workflows with When-Then
-
-In this chapter, you'll learn how to execute an action based on a condition in a workflow using when-then from the Workflows SDK.
-
-## Why If-Conditions Aren't Allowed in Workflows?
-
-Medusa creates an internal representation of the workflow definition you pass to `createWorkflow` to track and store its steps. At that point, variables in the workflow don't have any values. They only do when you execute the workflow.
-
-So, you can't use an if-condition that checks a variable's value, as the condition will be evaluated when Medusa creates the internal representation of the workflow, rather than during execution.
-
-Instead, use when-then from the Workflows SDK. It allows you to perform steps in a workflow only if a condition that you specify is satisfied.
-
-Restrictions for conditions is only applicable in a workflow's definition. You can still use if-conditions in your step's code.
-
-***
-
-## How to use When-Then?
-
-The Workflows SDK provides a `when` function that is used to check whether a condition is true. You chain a `then` function to `when` that specifies the steps to execute if the condition in `when` is satisfied.
-
-For example:
-
-```ts highlights={highlights}
-import {
- createWorkflow,
- WorkflowResponse,
- when,
-} from "@medusajs/framework/workflows-sdk"
-// step imports...
-
-const workflow = createWorkflow(
- "workflow",
- function (input: {
- is_active: boolean
- }) {
-
- const result = when(
- input,
- (input) => {
- return input.is_active
- }
- ).then(() => {
- const stepResult = isActiveStep()
- return stepResult
- })
-
- // executed without condition
- const anotherStepResult = anotherStep(result)
-
- return new WorkflowResponse(
- anotherStepResult
- )
- }
-)
-```
-
-In this code snippet, you execute the `isActiveStep` only if the `input.is_active`'s value is `true`.
-
-### When Parameters
-
-`when` accepts the following parameters:
-
-1. The first parameter is either an object or the workflow's input. This data is passed as a parameter to the function in `when`'s second parameter.
-2. The second parameter is a function that returns a boolean indicating whether to execute the action in `then`.
-
-### Then Parameters
-
-To specify the action to perform if the condition is satisfied, chain a `then` function to `when` and pass it a callback function.
-
-The callback function is only executed if `when`'s second parameter function returns a `true` value.
-
-***
-
-## Implementing If-Else with When-Then
-
-when-then doesn't support if-else conditions. Instead, use two `when-then` conditions in your workflow.
-
-For example:
-
-```ts highlights={ifElseHighlights}
-const workflow = createWorkflow(
- "workflow",
- function (input: {
- is_active: boolean
- }) {
-
- const isActiveResult = when(
- input,
- (input) => {
- return input.is_active
- }
- ).then(() => {
- return isActiveStep()
- })
-
- const notIsActiveResult = when(
- input,
- (input) => {
- return !input.is_active
- }
- ).then(() => {
- return notIsActiveStep()
- })
-
- // ...
- }
-)
-```
-
-In the above workflow, you use two `when-then` blocks. The first one performs a step if `input.is_active` is `true`, and the second performs a step if `input.is_active` is `false`, acting as an else condition.
-
-***
-
-## Specify Name for When-Then
-
-Internally, `when-then` blocks have a unique name similar to a step. When you return a step's result in a `when-then` block, the block's name is derived from the step's name. For example:
-
-```ts
-const isActiveResult = when(
- input,
- (input) => {
- return input.is_active
- }
-).then(() => {
- return isActiveStep()
-})
-```
-
-This `when-then` block's internal name will be `when-then-is-active`, where `is-active` is the step's name.
-
-However, if you need to return in your `when-then` block something other than a step's result, you need to specify a unique step name for that block. Otherwise, Medusa will generate a random name for it which can cause unexpected errors in production.
-
-You pass a name for `when-then` as a first parameter of `when`, whose signature can accept three parameters in this case. For example:
-
-```ts highlights={nameHighlights}
-const { isActive } = when(
- "check-is-active",
- input,
- (input) => {
- return input.is_active
- }
-).then(() => {
- const isActive = isActiveStep()
-
- return {
- isActive,
- }
-})
-```
-
-Since `then` returns a value different than the step's result, you pass to the `when` function the following parameters:
-
-1. A unique name to be assigned to the `when-then` block.
-2. Either an object or the workflow's input. This data is passed as a parameter to the function in `when`'s second parameter.
-3. A function that returns a boolean indicating whether to execute the action in `then`.
-
-The second and third parameters are the same as the parameters you previously passed to `when`.
-
-
-# Error Handling in Workflows
-
-In this chapter, you’ll learn about what happens when an error occurs in a workflow, how to disable error throwing in a workflow, and try-catch alternatives in workflow definitions.
-
-## Default Behavior of Errors in Workflows
-
-When an error occurs in a workflow, such as when a step throws an error, the workflow execution stops. Then, [the compensation function](https://docs.medusajs.com/learn/fundamentals/workflows/compensation-function/index.html.md) of every step in the workflow is called to undo the actions performed by their respective steps.
-
-The workflow's caller, such as an API route, subscriber, or scheduled job, will also fail and stop execution. Medusa then logs the error in the console. For API routes, an appropriate error is returned to the client based on the thrown error.
-
-Learn more about error handling in API routes in the [Errors chapter](https://docs.medusajs.com/learn/fundamentals/api-routes/errors/index.html.md).
-
-This is the default behavior of errors in workflows. However, you can configure workflows to not throw errors, or you can configure a step's internal error handling mechanism to change the default behavior.
-
-***
-
-## Disable Error Throwing in Workflow
-
-When an error is thrown in the workflow, that means the caller of the workflow, such as an API route, will fail and stop execution as well.
-
-While this is the common behavior, there are certain cases where you want to handle the error differently. For example, you may want to check the errors thrown by the workflow and return a custom error response to the client.
-
-The object parameter of a workflow's `run` method accepts a `throwOnError` property. When this property is set to `false`, the workflow will stop execution if an error occurs, but the Medusa's workflow engine will catch that error and return it to the caller instead of throwing it.
-
-For example:
-
-```ts title="src/api/workflows/route.ts" highlights={highlights} collapsibleLines="1-6" expandButtonLabel="Show Imports"
-import type {
- MedusaRequest,
- MedusaResponse,
-} from "@medusajs/framework/http"
-import myWorkflow from "../../../workflows/hello-world"
-
-export async function GET(
- req: MedusaRequest,
- res: MedusaResponse
-) {
- const { result, errors } = await myWorkflow(req.scope)
- .run({
- // ...
- throwOnError: false,
- })
-
- if (errors.length) {
- return res.send({
- message: "Something unexpected happened. Please try again.",
- })
- }
-
- res.send(result)
-}
-```
-
-You disable throwing errors in the workflow by setting the `throwOnError` property to `false` in the `run` method of the workflow.
-
-The object returned by the `run` method contains an `errors` property. This property is an array of errors that occured during the workflow's execution. You can check this array to see if any errors occurred and handle them accordingly.
-
-An error object has the following properties:
-
-- action: (\`string\`) The ID of the step that threw the error.
-- handlerType: (\`invoke\` \\| \`compensate\`) Where the error occurred. If the value is \`invoke\`, it means the error occurred in a step. Otherwise, the error occurred in the compensation function of a step.
-- error: (\[Error]\(https://nodejs.org/docs/latest-v20.x/api/errors.html#class-error)) The error object that was thrown.
-
-***
-
-## Try-Catch Alternatives in Workflow Definition
-
-If you want to use try-catch mechanism in a workflow to undo step actions, use a [compensation function](https://docs.medusajs.com/learn/fundamentals/workflows/compensation-function/index.html.md) instead.
-
-### Why You Can't Use Try-Catch in Workflow Definitions
-
-Medusa creates an internal representation of the workflow definition you pass to `createWorkflow` to track and store its steps.
-
-At that point, variables in the workflow don't have any values. They only do when you execute the workflow.
-
-So, try-catch blocks in the workflow definition function won't have an effect, as at that time the workflow is not executed and errors are not thrown.
-
-You can still use try-catch blocks in a workflow's step functions. For cases that require granular control over error handling in a workflow's definition, you can configure the internal error handling mechanism of a step.
-
-### Skip Workflow on Step Failure
-
-A step has a `skipOnPermanentFailure` configuration that allows you to configure what happens when an error occurs in the step. Its value can be a boolean or a string.
-
-By default, `skipOnPermanentFailure` is disabled. When it's enabled, the workflow's status is set to `skipped` instead of `failed`. This means:
-
-- Compensation functions of the workflow's steps are not called.
-- The workflow's caller continues executing. You can still [access the error](#disable-error-throwing-in-workflow) that occurred during the workflow's execution as mentioned in the [Disable Error Throwing](#disable-error-throwing-in-workflow) section.
-
-This is useful when you want to perform actions if no error occurs, but you don't care about compensating the workflow's steps or you don't want to stop the caller's execution.
-
-You can think of setting the `skipOnPermanentFailure` to `true` as the equivalent of the following `try-catch` block:
-
-```ts title="Outside a Workflow"
-try {
- actionThatThrowsError()
-
- moreActions()
-} catch (e) {
- // don't do anything
-}
-```
-
-You can do this in a workflow using the step's `skipOnPermanentFailure` configuration:
-
-```ts title="Workflow Equivalent" highlights={skipOnPermanentFailureEnabledHighlights}
-import {
- createWorkflow,
-} from "@medusajs/framework/workflows-sdk"
-import {
- actionThatThrowsError,
- moreActions,
-} from "./steps"
-
-export const myWorkflow = createWorkflow(
- "hello-world",
- function (input) {
- actionThatThrowsError().config({
- skipOnPermanentFailure: true,
- })
-
- // This action will not be executed if the previous step throws an error
- moreActions()
- }
-)
-```
-
-You set the configuration of a step by chaining the `config` method to the step's function call. The `config` method accepts an object similar to the one that can be passed to `createStep`.
-
-In this example, if the `actionThatThrowsError` step throws an error, the rest of the workflow will be skipped, and the `moreActions` step will not be executed.
-
-You can then access the error that occurred in that step as explained in the [Disable Error Throwing](#disable-error-throwing-in-workflow) section.
-
-### Continue Workflow Execution from a Specific Step
-
-In some cases, if an error occurs in a step, you may want to continue the workflow's execution from a specific step instead of stopping the workflow's execution or skipping the rest of the steps.
-
-The `skipOnPermanentFailure` configuration can accept a step's ID as a value. Then, the workflow will continue execution from that step if an error occurs in the step that has the `skipOnPermanentFailure` configuration.
-
-The compensation function of the step that has the `skipOnPermanentFailure` configuration will not be called when an error occurs.
-
-You can think of setting the `skipOnPermanentFailure` to a step's ID as the equivalent of the following `try-catch` block:
-
-```ts title="Outside a Workflow"
-try {
- actionThatThrowsError()
-
- moreActions()
-} catch (e) {
- // do nothing
-}
-
-continueExecutionFromStep()
-```
-
-You can do this in a workflow using the step's `skipOnPermanentFailure` configuration:
-
-```ts title="Workflow Equivalent" highlights={skipOnPermanentFailureStepHighlights}
-import {
- createWorkflow,
-} from "@medusajs/framework/workflows-sdk"
-import {
- actionThatThrowsError,
- moreActions,
- continueExecutionFromStep,
-} from "./steps"
-
-export const myWorkflow = createWorkflow(
- "hello-world",
- function (input) {
- actionThatThrowsError().config({
- // The `continue-execution-from-step` is the ID passed as a first
- // parameter to `createStep` of `continueExecutionFromStep`.
- skipOnPermanentFailure: "continue-execution-from-step",
- })
-
- // This action will not be executed if the previous step throws an error
- moreActions()
-
- // This action will be executed either way
- continueExecutionFromStep()
- }
-)
-```
-
-In this example, you configure the `actionThatThrowsError` step to continue the workflow's execution from the `continueExecutionFromStep` step if an error occurs in the `actionThatThrowsError` step.
-
-Notice that you pass the ID of the `continueExecutionFromStep` step as it's set in the `createStep` function.
-
-So, the `moreActions` step will not be executed if the `actionThatThrowsError` step throws an error, and the `continueExecutionFromStep` will be executed anyway.
-
-You can then access the error that occurred in that step as explained in the [Disable Error Throwing](#disable-error-throwing-in-workflow) section.
-
-If the specified step ID doesn't exist in the workflow, it will be equivalent to setting the `skipOnPermanentFailure` configuration to `true`. So, the workflow will be skipped, and the rest of the steps will not be executed.
-
-### Set Step as Failed, but Continue Workflow Execution
-
-In some cases, you may want to fail a step, but continue the rest of the workflow's execution.
-
-This is useful when you don't want a step's failure to stop the workflow's execution, but you want to mark that step as failed.
-
-The `continueOnPermanentFailure` configuration allows you to do that. When enabled, the workflow's execution will continue, but the step will be marked as failed if an error occurs in that step.
-
-The compensation function of the step that has the `continueOnPermanentFailure` configuration will not be called when an error occurs.
-
-You can think of setting the `continueOnPermanentFailure` to `true` as the equivalent of the following `try-catch` block:
-
-```ts title="Outside a Workflow"
-try {
- actionThatThrowsError()
-} catch (e) {
- // do nothing
-}
-
-moreActions()
-```
-
-You can do this in a workflow using the step's `continueOnPermanentFailure` configuration:
-
-```ts title="Workflow Equivalent" highlights={continueOnPermanentFailureHighlights}
-import {
- createWorkflow,
-} from "@medusajs/framework/workflows-sdk"
-import {
- actionThatThrowsError,
- moreActions,
-} from "./steps"
-
-export const myWorkflow = createWorkflow(
- "hello-world",
- function (input) {
- actionThatThrowsError().config({
- continueOnPermanentFailure: true,
- })
-
- // This action will be executed even if the previous step throws an error
- moreActions()
- }
-)
-```
-
-In this example, if the `actionThatThrowsError` step throws an error, the `moreActions` step will still be executed.
-
-You can then access the error that occurred in that step as explained in the [Disable Error Throwing](#disable-error-throwing-in-workflow) section.
-
-
# Workflow Constraints
This chapter lists constraints of defining a workflow or its steps.
@@ -16046,6 +15887,410 @@ const step1 = createStep(
```
+# Error Handling in Workflows
+
+In this chapter, you’ll learn about what happens when an error occurs in a workflow, how to disable error throwing in a workflow, and try-catch alternatives in workflow definitions.
+
+## Default Behavior of Errors in Workflows
+
+When an error occurs in a workflow, such as when a step throws an error, the workflow execution stops. Then, [the compensation function](https://docs.medusajs.com/learn/fundamentals/workflows/compensation-function/index.html.md) of every step in the workflow is called to undo the actions performed by their respective steps.
+
+The workflow's caller, such as an API route, subscriber, or scheduled job, will also fail and stop execution. Medusa then logs the error in the console. For API routes, an appropriate error is returned to the client based on the thrown error.
+
+Learn more about error handling in API routes in the [Errors chapter](https://docs.medusajs.com/learn/fundamentals/api-routes/errors/index.html.md).
+
+This is the default behavior of errors in workflows. However, you can configure workflows to not throw errors, or you can configure a step's internal error handling mechanism to change the default behavior.
+
+***
+
+## Disable Error Throwing in Workflow
+
+When an error is thrown in the workflow, that means the caller of the workflow, such as an API route, will fail and stop execution as well.
+
+While this is the common behavior, there are certain cases where you want to handle the error differently. For example, you may want to check the errors thrown by the workflow and return a custom error response to the client.
+
+The object parameter of a workflow's `run` method accepts a `throwOnError` property. When this property is set to `false`, the workflow will stop execution if an error occurs, but the Medusa's workflow engine will catch that error and return it to the caller instead of throwing it.
+
+For example:
+
+```ts title="src/api/workflows/route.ts" highlights={highlights} collapsibleLines="1-6" expandButtonLabel="Show Imports"
+import type {
+ MedusaRequest,
+ MedusaResponse,
+} from "@medusajs/framework/http"
+import myWorkflow from "../../../workflows/hello-world"
+
+export async function GET(
+ req: MedusaRequest,
+ res: MedusaResponse
+) {
+ const { result, errors } = await myWorkflow(req.scope)
+ .run({
+ // ...
+ throwOnError: false,
+ })
+
+ if (errors.length) {
+ return res.send({
+ message: "Something unexpected happened. Please try again.",
+ })
+ }
+
+ res.send(result)
+}
+```
+
+You disable throwing errors in the workflow by setting the `throwOnError` property to `false` in the `run` method of the workflow.
+
+The object returned by the `run` method contains an `errors` property. This property is an array of errors that occured during the workflow's execution. You can check this array to see if any errors occurred and handle them accordingly.
+
+An error object has the following properties:
+
+- action: (\`string\`) The ID of the step that threw the error.
+- handlerType: (\`invoke\` \\| \`compensate\`) Where the error occurred. If the value is \`invoke\`, it means the error occurred in a step. Otherwise, the error occurred in the compensation function of a step.
+- error: (\[Error]\(https://nodejs.org/docs/latest-v20.x/api/errors.html#class-error)) The error object that was thrown.
+
+***
+
+## Try-Catch Alternatives in Workflow Definition
+
+If you want to use try-catch mechanism in a workflow to undo step actions, use a [compensation function](https://docs.medusajs.com/learn/fundamentals/workflows/compensation-function/index.html.md) instead.
+
+### Why You Can't Use Try-Catch in Workflow Definitions
+
+Medusa creates an internal representation of the workflow definition you pass to `createWorkflow` to track and store its steps.
+
+At that point, variables in the workflow don't have any values. They only do when you execute the workflow.
+
+So, try-catch blocks in the workflow definition function won't have an effect, as at that time the workflow is not executed and errors are not thrown.
+
+You can still use try-catch blocks in a workflow's step functions. For cases that require granular control over error handling in a workflow's definition, you can configure the internal error handling mechanism of a step.
+
+### Skip Workflow on Step Failure
+
+A step has a `skipOnPermanentFailure` configuration that allows you to configure what happens when an error occurs in the step. Its value can be a boolean or a string.
+
+By default, `skipOnPermanentFailure` is disabled. When it's enabled, the workflow's status is set to `skipped` instead of `failed`. This means:
+
+- Compensation functions of the workflow's steps are not called.
+- The workflow's caller continues executing. You can still [access the error](#disable-error-throwing-in-workflow) that occurred during the workflow's execution as mentioned in the [Disable Error Throwing](#disable-error-throwing-in-workflow) section.
+
+This is useful when you want to perform actions if no error occurs, but you don't care about compensating the workflow's steps or you don't want to stop the caller's execution.
+
+You can think of setting the `skipOnPermanentFailure` to `true` as the equivalent of the following `try-catch` block:
+
+```ts title="Outside a Workflow"
+try {
+ actionThatThrowsError()
+
+ moreActions()
+} catch (e) {
+ // don't do anything
+}
+```
+
+You can do this in a workflow using the step's `skipOnPermanentFailure` configuration:
+
+```ts title="Workflow Equivalent" highlights={skipOnPermanentFailureEnabledHighlights}
+import {
+ createWorkflow,
+} from "@medusajs/framework/workflows-sdk"
+import {
+ actionThatThrowsError,
+ moreActions,
+} from "./steps"
+
+export const myWorkflow = createWorkflow(
+ "hello-world",
+ function (input) {
+ actionThatThrowsError().config({
+ skipOnPermanentFailure: true,
+ })
+
+ // This action will not be executed if the previous step throws an error
+ moreActions()
+ }
+)
+```
+
+You set the configuration of a step by chaining the `config` method to the step's function call. The `config` method accepts an object similar to the one that can be passed to `createStep`.
+
+In this example, if the `actionThatThrowsError` step throws an error, the rest of the workflow will be skipped, and the `moreActions` step will not be executed.
+
+You can then access the error that occurred in that step as explained in the [Disable Error Throwing](#disable-error-throwing-in-workflow) section.
+
+### Continue Workflow Execution from a Specific Step
+
+In some cases, if an error occurs in a step, you may want to continue the workflow's execution from a specific step instead of stopping the workflow's execution or skipping the rest of the steps.
+
+The `skipOnPermanentFailure` configuration can accept a step's ID as a value. Then, the workflow will continue execution from that step if an error occurs in the step that has the `skipOnPermanentFailure` configuration.
+
+The compensation function of the step that has the `skipOnPermanentFailure` configuration will not be called when an error occurs.
+
+You can think of setting the `skipOnPermanentFailure` to a step's ID as the equivalent of the following `try-catch` block:
+
+```ts title="Outside a Workflow"
+try {
+ actionThatThrowsError()
+
+ moreActions()
+} catch (e) {
+ // do nothing
+}
+
+continueExecutionFromStep()
+```
+
+You can do this in a workflow using the step's `skipOnPermanentFailure` configuration:
+
+```ts title="Workflow Equivalent" highlights={skipOnPermanentFailureStepHighlights}
+import {
+ createWorkflow,
+} from "@medusajs/framework/workflows-sdk"
+import {
+ actionThatThrowsError,
+ moreActions,
+ continueExecutionFromStep,
+} from "./steps"
+
+export const myWorkflow = createWorkflow(
+ "hello-world",
+ function (input) {
+ actionThatThrowsError().config({
+ // The `continue-execution-from-step` is the ID passed as a first
+ // parameter to `createStep` of `continueExecutionFromStep`.
+ skipOnPermanentFailure: "continue-execution-from-step",
+ })
+
+ // This action will not be executed if the previous step throws an error
+ moreActions()
+
+ // This action will be executed either way
+ continueExecutionFromStep()
+ }
+)
+```
+
+In this example, you configure the `actionThatThrowsError` step to continue the workflow's execution from the `continueExecutionFromStep` step if an error occurs in the `actionThatThrowsError` step.
+
+Notice that you pass the ID of the `continueExecutionFromStep` step as it's set in the `createStep` function.
+
+So, the `moreActions` step will not be executed if the `actionThatThrowsError` step throws an error, and the `continueExecutionFromStep` will be executed anyway.
+
+You can then access the error that occurred in that step as explained in the [Disable Error Throwing](#disable-error-throwing-in-workflow) section.
+
+If the specified step ID doesn't exist in the workflow, it will be equivalent to setting the `skipOnPermanentFailure` configuration to `true`. So, the workflow will be skipped, and the rest of the steps will not be executed.
+
+### Set Step as Failed, but Continue Workflow Execution
+
+In some cases, you may want to fail a step, but continue the rest of the workflow's execution.
+
+This is useful when you don't want a step's failure to stop the workflow's execution, but you want to mark that step as failed.
+
+The `continueOnPermanentFailure` configuration allows you to do that. When enabled, the workflow's execution will continue, but the step will be marked as failed if an error occurs in that step.
+
+The compensation function of the step that has the `continueOnPermanentFailure` configuration will not be called when an error occurs.
+
+You can think of setting the `continueOnPermanentFailure` to `true` as the equivalent of the following `try-catch` block:
+
+```ts title="Outside a Workflow"
+try {
+ actionThatThrowsError()
+} catch (e) {
+ // do nothing
+}
+
+moreActions()
+```
+
+You can do this in a workflow using the step's `continueOnPermanentFailure` configuration:
+
+```ts title="Workflow Equivalent" highlights={continueOnPermanentFailureHighlights}
+import {
+ createWorkflow,
+} from "@medusajs/framework/workflows-sdk"
+import {
+ actionThatThrowsError,
+ moreActions,
+} from "./steps"
+
+export const myWorkflow = createWorkflow(
+ "hello-world",
+ function (input) {
+ actionThatThrowsError().config({
+ continueOnPermanentFailure: true,
+ })
+
+ // This action will be executed even if the previous step throws an error
+ moreActions()
+ }
+)
+```
+
+In this example, if the `actionThatThrowsError` step throws an error, the `moreActions` step will still be executed.
+
+You can then access the error that occurred in that step as explained in the [Disable Error Throwing](#disable-error-throwing-in-workflow) section.
+
+
+# Conditions in Workflows with When-Then
+
+In this chapter, you'll learn how to execute an action based on a condition in a workflow using when-then from the Workflows SDK.
+
+## Why If-Conditions Aren't Allowed in Workflows?
+
+Medusa creates an internal representation of the workflow definition you pass to `createWorkflow` to track and store its steps. At that point, variables in the workflow don't have any values. They only do when you execute the workflow.
+
+So, you can't use an if-condition that checks a variable's value, as the condition will be evaluated when Medusa creates the internal representation of the workflow, rather than during execution.
+
+Instead, use when-then from the Workflows SDK. It allows you to perform steps in a workflow only if a condition that you specify is satisfied.
+
+Restrictions for conditions is only applicable in a workflow's definition. You can still use if-conditions in your step's code.
+
+***
+
+## How to use When-Then?
+
+The Workflows SDK provides a `when` function that is used to check whether a condition is true. You chain a `then` function to `when` that specifies the steps to execute if the condition in `when` is satisfied.
+
+For example:
+
+```ts highlights={highlights}
+import {
+ createWorkflow,
+ WorkflowResponse,
+ when,
+} from "@medusajs/framework/workflows-sdk"
+// step imports...
+
+const workflow = createWorkflow(
+ "workflow",
+ function (input: {
+ is_active: boolean
+ }) {
+
+ const result = when(
+ input,
+ (input) => {
+ return input.is_active
+ }
+ ).then(() => {
+ const stepResult = isActiveStep()
+ return stepResult
+ })
+
+ // executed without condition
+ const anotherStepResult = anotherStep(result)
+
+ return new WorkflowResponse(
+ anotherStepResult
+ )
+ }
+)
+```
+
+In this code snippet, you execute the `isActiveStep` only if the `input.is_active`'s value is `true`.
+
+### When Parameters
+
+`when` accepts the following parameters:
+
+1. The first parameter is either an object or the workflow's input. This data is passed as a parameter to the function in `when`'s second parameter.
+2. The second parameter is a function that returns a boolean indicating whether to execute the action in `then`.
+
+### Then Parameters
+
+To specify the action to perform if the condition is satisfied, chain a `then` function to `when` and pass it a callback function.
+
+The callback function is only executed if `when`'s second parameter function returns a `true` value.
+
+***
+
+## Implementing If-Else with When-Then
+
+when-then doesn't support if-else conditions. Instead, use two `when-then` conditions in your workflow.
+
+For example:
+
+```ts highlights={ifElseHighlights}
+const workflow = createWorkflow(
+ "workflow",
+ function (input: {
+ is_active: boolean
+ }) {
+
+ const isActiveResult = when(
+ input,
+ (input) => {
+ return input.is_active
+ }
+ ).then(() => {
+ return isActiveStep()
+ })
+
+ const notIsActiveResult = when(
+ input,
+ (input) => {
+ return !input.is_active
+ }
+ ).then(() => {
+ return notIsActiveStep()
+ })
+
+ // ...
+ }
+)
+```
+
+In the above workflow, you use two `when-then` blocks. The first one performs a step if `input.is_active` is `true`, and the second performs a step if `input.is_active` is `false`, acting as an else condition.
+
+***
+
+## Specify Name for When-Then
+
+Internally, `when-then` blocks have a unique name similar to a step. When you return a step's result in a `when-then` block, the block's name is derived from the step's name. For example:
+
+```ts
+const isActiveResult = when(
+ input,
+ (input) => {
+ return input.is_active
+ }
+).then(() => {
+ return isActiveStep()
+})
+```
+
+This `when-then` block's internal name will be `when-then-is-active`, where `is-active` is the step's name.
+
+However, if you need to return in your `when-then` block something other than a step's result, you need to specify a unique step name for that block. Otherwise, Medusa will generate a random name for it which can cause unexpected errors in production.
+
+You pass a name for `when-then` as a first parameter of `when`, whose signature can accept three parameters in this case. For example:
+
+```ts highlights={nameHighlights}
+const { isActive } = when(
+ "check-is-active",
+ input,
+ (input) => {
+ return input.is_active
+ }
+).then(() => {
+ const isActive = isActiveStep()
+
+ return {
+ isActive,
+ }
+})
+```
+
+Since `then` returns a value different than the step's result, you pass to the `when` function the following parameters:
+
+1. A unique name to be assigned to the `when-then` block.
+2. Either an object or the workflow's input. This data is passed as a parameter to the function in `when`'s second parameter.
+3. A function that returns a boolean indicating whether to execute the action in `then`.
+
+The second and third parameters are the same as the parameters you previously passed to `when`.
+
+
# Execute Another Workflow
In this chapter, you'll learn how to execute a workflow in another.
@@ -16176,75 +16421,6 @@ const workflow = createWorkflow(
In this example, you use when-then to run the `createProductsWorkflow` only if `should_create` (passed in the `input`) is enabled.
-# Expose a Workflow Hook
-
-In this chapter, you'll learn how to expose a hook in your workflow.
-
-## When to Expose a Hook
-
-Your workflow is reusable in other applications, and you allow performing an external action at some point in your workflow.
-
-Your workflow isn't reusable by other applications. Use a step that performs what a hook handler would instead.
-
-***
-
-## How to Expose a Hook in a Workflow?
-
-To expose a hook in your workflow, use `createHook` from the Workflows SDK.
-
-For example:
-
-```ts title="src/workflows/my-workflow/index.ts" highlights={hookHighlights}
-import {
- createStep,
- createHook,
- createWorkflow,
- WorkflowResponse,
-} from "@medusajs/framework/workflows-sdk"
-import { createProductStep } from "./steps/create-product"
-
-export const myWorkflow = createWorkflow(
- "my-workflow",
- function (input) {
- const product = createProductStep(input)
- const productCreatedHook = createHook(
- "productCreated",
- { productId: product.id }
- )
-
- return new WorkflowResponse(product, {
- hooks: [productCreatedHook],
- })
- }
-)
-```
-
-The `createHook` function accepts two parameters:
-
-1. The first is a string indicating the hook's name. You use this to consume the hook later.
-2. The second is the input to pass to the hook handler.
-
-The workflow must also pass an object having a `hooks` property as a second parameter to the `WorkflowResponse` constructor. Its value is an array of the workflow's hooks.
-
-### How to Consume the Hook?
-
-To consume the hook of the workflow, create the file `src/workflows/hooks/my-workflow.ts` with the following content:
-
-```ts title="src/workflows/hooks/my-workflow.ts" highlights={handlerHighlights}
-import { myWorkflow } from "../my-workflow"
-
-myWorkflow.hooks.productCreated(
- async ({ productId }, { container }) => {
- // TODO perform an action
- }
-)
-```
-
-The hook is available on the workflow's `hooks` property using its name `productCreated`.
-
-You invoke the hook, passing a step function (the hook handler) as a parameter.
-
-
# Long-Running Workflows
In this chapter, you’ll learn what a long-running workflow is and how to configure it.
@@ -16812,6 +16988,129 @@ if (workflowExecution.state === "failed") {
Other state values include `done`, `invoking`, and `compensating`.
+# Retry Failed Steps
+
+In this chapter, you’ll learn how to configure steps to allow retrial on failure.
+
+## What is a Step Retrial?
+
+A step retrial is a mechanism that allows a step to be retried automatically when it fails. This is useful for handling transient errors, such as network issues or temporary unavailability of a service.
+
+When a step fails, the workflow engine can automatically retry the step a specified number of times before marking the workflow as failed. This can help improve the reliability and resilience of your workflows.
+
+You can also configure the interval between retries, allowing you to wait for a certain period before attempting the step again. This is useful when the failure is due to a temporary issue that may resolve itself after some time.
+
+For example, if a step captures a payment, you may want to retry it the next day until the payment is successful or the maximum number of retries is reached.
+
+***
+
+## Configure a Step’s Retrial
+
+By default, when an error occurs in a step, the step and the workflow fail, and the execution stops.
+
+You can configure the step to retry on failure. The `createStep` function can accept a configuration object instead of the step’s name as a first parameter.
+
+For example:
+
+```ts title="src/workflows/hello-world.ts" highlights={[["10"]]} collapsibleLines="1-6" expandButtonLabel="Show Imports"
+import {
+ createStep,
+ createWorkflow,
+ WorkflowResponse,
+} from "@medusajs/framework/workflows-sdk"
+
+const step1 = createStep(
+ {
+ name: "step-1",
+ maxRetries: 2,
+ },
+ async () => {
+ console.log("Executing step 1")
+
+ throw new Error("Oops! Something happened.")
+ }
+)
+
+const myWorkflow = createWorkflow(
+ "hello-world",
+ function () {
+ const str1 = step1()
+
+ return new WorkflowResponse({
+ message: str1,
+ })
+})
+
+export default myWorkflow
+```
+
+The step’s configuration object accepts a `maxRetries` property, which is a number indicating the number of times a step can be retried when it fails.
+
+When you execute the above workflow, you’ll see the following result in the terminal:
+
+```bash
+Executing step 1
+Executing step 1
+Executing step 1
+error: Oops! Something happened.
+Error: Oops! Something happened.
+```
+
+The first line indicates the first time the step was executed, and the next two lines indicate the times the step was retried. After that, the step and workflow fail.
+
+***
+
+## Step Retry Intervals
+
+By default, a step is retried immediately after it fails. To specify a wait time before a step is retried, pass a `retryInterval` property to the step's configuration object. Its value is a number of seconds to wait before retrying the step.
+
+For example:
+
+```ts title="src/workflows/hello-world.ts" highlights={[["5"]]}
+const step1 = createStep(
+ {
+ name: "step-1",
+ maxRetries: 2,
+ retryInterval: 2, // 2 seconds
+ },
+ async () => {
+ // ...
+ }
+)
+```
+
+In this example, if the step fails, it will be retried after two seconds.
+
+### Maximum Retry Interval
+
+The `retryInterval` property's maximum value is [Number.MAX\_SAFE\_INTEGER](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MAX_SAFE_INTEGER). So, you can set a very long wait time before the step is retried, allowing you to retry steps after a long period.
+
+For example, to retry a step after a day:
+
+```ts title="src/workflows/hello-world.ts" highlights={[["5"]]}
+const step1 = createStep(
+ {
+ name: "step-1",
+ maxRetries: 2,
+ retryInterval: 86400, // 1 day
+ },
+ async () => {
+ // ...
+ }
+)
+```
+
+In this example, if the step fails, it will be retried after `86400` seconds (one day).
+
+### Interval Changes Workflow to Long-Running
+
+By setting `retryInterval` on a step, a workflow that uses that step becomes a [long-running workflow](https://docs.medusajs.com/learn/fundamentals/workflows/long-running-workflow/index.html.md) that runs asynchronously in the background. This is useful when creating workflows that may fail and should run for a long time until they succeed, such as waiting for a payment to be captured or a shipment to be delivered.
+
+However, since the long-running workflow runs in the background, you won't receive its result or errors immediately when you execute the workflow.
+
+Instead, you must subscribe to the workflow's execution using the Workflow Engine Module Service. Learn more about it in [this chapter](https://docs.medusajs.com/learn/fundamentals/workflows/long-running-workflow#access-long-running-workflow-status-and-result/index.html.md).
+
+
# Data Manipulation in Workflows with transform
In this chapter, you'll learn how to use `transform` from the Workflows SDK to manipulate data and variables in a workflow.
@@ -17017,36 +17316,6 @@ const myWorkflow = createWorkflow(
```
-# Scheduled Jobs Number of Executions
-
-In this chapter, you'll learn how to set a limit on the number of times a scheduled job is executed.
-
-## numberOfExecutions Option
-
-The export configuration object of the scheduled job accepts an optional property `numberOfExecutions`. Its value is a number indicating how many times the scheduled job can be executed during the Medusa application's runtime.
-
-For example:
-
-```ts highlights={highlights}
-export default async function myCustomJob() {
- console.log("I'll be executed three times only.")
-}
-
-export const config = {
- name: "hello-world",
- // execute every minute
- schedule: "* * * * *",
- numberOfExecutions: 3,
-}
-```
-
-The above scheduled job has the `numberOfExecutions` configuration set to `3`.
-
-So, it'll only execute 3 times, each every minute, then it won't be executed anymore.
-
-If you restart the Medusa application, the scheduled job will be executed again until reaching the number of executions specified.
-
-
# Workflow Hooks
In this chapter, you'll learn what a workflow hook is and how to consume them.
@@ -17171,215 +17440,6 @@ export async function POST(req: MedusaRequest, res: MedusaResponse) {
Your hook handler then receives that passed data in the `additional_data` object.
-# Workflow Timeout
-
-In this chapter, you’ll learn how to set a timeout for workflows and steps.
-
-## What is a Workflow Timeout?
-
-By default, a workflow doesn’t have a timeout. It continues execution until it’s finished or an error occurs.
-
-You can configure a workflow’s timeout to indicate how long the workflow can execute. If a workflow's execution time passes the configured timeout, it is failed and an error is thrown.
-
-### Timeout Doesn't Stop Step Execution
-
-Configuring a timeout doesn't stop the execution of a step in progress. The timeout only affects the status of the workflow and its result.
-
-***
-
-## Configure Workflow Timeout
-
-The `createWorkflow` function can accept a configuration object instead of the workflow’s name.
-
-In the configuration object, you pass a `timeout` property, whose value is a number indicating the timeout in seconds.
-
-For example:
-
-```ts title="src/workflows/hello-world.ts" highlights={[["16"]]} collapsibleLines="1-13" expandButtonLabel="Show More"
-import {
- createStep,
- createWorkflow,
- WorkflowResponse,
-} from "@medusajs/framework/workflows-sdk"
-
-const step1 = createStep(
- "step-1",
- async () => {
- // ...
- }
-)
-
-const myWorkflow = createWorkflow({
- name: "hello-world",
- timeout: 2, // 2 seconds
-}, function () {
- const str1 = step1()
-
- return new WorkflowResponse({
- message: str1,
- })
-})
-
-export default myWorkflow
-
-```
-
-This workflow's executions fail if they run longer than two seconds.
-
-A workflow’s timeout error is returned in the `errors` property of the workflow’s execution, as explained in [this chapter](https://docs.medusajs.com/learn/fundamentals/workflows/errors/index.html.md). The error’s name is `TransactionTimeoutError`.
-
-***
-
-## Configure Step Timeout
-
-Alternatively, you can configure the timeout for a step rather than the entire workflow.
-
-As mentioned in the previous section, the timeout doesn't stop the execution of the step. It only affects the step's status and output.
-
-The step’s configuration object accepts a `timeout` property, whose value is a number indicating the timeout in seconds.
-
-For example:
-
-```tsx
-const step1 = createStep(
- {
- name: "step-1",
- timeout: 2, // 2 seconds
- },
- async () => {
- // ...
- }
-)
-```
-
-This step's executions fail if they run longer than two seconds.
-
-A step’s timeout error is returned in the `errors` property of the workflow’s execution, as explained in [this chapter](https://docs.medusajs.com/learn/fundamentals/workflows/errors/index.html.md). The error’s name is `TransactionStepTimeoutError`.
-
-
-# Retry Failed Steps
-
-In this chapter, you’ll learn how to configure steps to allow retrial on failure.
-
-## What is a Step Retrial?
-
-A step retrial is a mechanism that allows a step to be retried automatically when it fails. This is useful for handling transient errors, such as network issues or temporary unavailability of a service.
-
-When a step fails, the workflow engine can automatically retry the step a specified number of times before marking the workflow as failed. This can help improve the reliability and resilience of your workflows.
-
-You can also configure the interval between retries, allowing you to wait for a certain period before attempting the step again. This is useful when the failure is due to a temporary issue that may resolve itself after some time.
-
-For example, if a step captures a payment, you may want to retry it the next day until the payment is successful or the maximum number of retries is reached.
-
-***
-
-## Configure a Step’s Retrial
-
-By default, when an error occurs in a step, the step and the workflow fail, and the execution stops.
-
-You can configure the step to retry on failure. The `createStep` function can accept a configuration object instead of the step’s name as a first parameter.
-
-For example:
-
-```ts title="src/workflows/hello-world.ts" highlights={[["10"]]} collapsibleLines="1-6" expandButtonLabel="Show Imports"
-import {
- createStep,
- createWorkflow,
- WorkflowResponse,
-} from "@medusajs/framework/workflows-sdk"
-
-const step1 = createStep(
- {
- name: "step-1",
- maxRetries: 2,
- },
- async () => {
- console.log("Executing step 1")
-
- throw new Error("Oops! Something happened.")
- }
-)
-
-const myWorkflow = createWorkflow(
- "hello-world",
- function () {
- const str1 = step1()
-
- return new WorkflowResponse({
- message: str1,
- })
-})
-
-export default myWorkflow
-```
-
-The step’s configuration object accepts a `maxRetries` property, which is a number indicating the number of times a step can be retried when it fails.
-
-When you execute the above workflow, you’ll see the following result in the terminal:
-
-```bash
-Executing step 1
-Executing step 1
-Executing step 1
-error: Oops! Something happened.
-Error: Oops! Something happened.
-```
-
-The first line indicates the first time the step was executed, and the next two lines indicate the times the step was retried. After that, the step and workflow fail.
-
-***
-
-## Step Retry Intervals
-
-By default, a step is retried immediately after it fails. To specify a wait time before a step is retried, pass a `retryInterval` property to the step's configuration object. Its value is a number of seconds to wait before retrying the step.
-
-For example:
-
-```ts title="src/workflows/hello-world.ts" highlights={[["5"]]}
-const step1 = createStep(
- {
- name: "step-1",
- maxRetries: 2,
- retryInterval: 2, // 2 seconds
- },
- async () => {
- // ...
- }
-)
-```
-
-In this example, if the step fails, it will be retried after two seconds.
-
-### Maximum Retry Interval
-
-The `retryInterval` property's maximum value is [Number.MAX\_SAFE\_INTEGER](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MAX_SAFE_INTEGER). So, you can set a very long wait time before the step is retried, allowing you to retry steps after a long period.
-
-For example, to retry a step after a day:
-
-```ts title="src/workflows/hello-world.ts" highlights={[["5"]]}
-const step1 = createStep(
- {
- name: "step-1",
- maxRetries: 2,
- retryInterval: 86400, // 1 day
- },
- async () => {
- // ...
- }
-)
-```
-
-In this example, if the step fails, it will be retried after `86400` seconds (one day).
-
-### Interval Changes Workflow to Long-Running
-
-By setting `retryInterval` on a step, a workflow that uses that step becomes a [long-running workflow](https://docs.medusajs.com/learn/fundamentals/workflows/long-running-workflow/index.html.md) that runs asynchronously in the background. This is useful when creating workflows that may fail and should run for a long time until they succeed, such as waiting for a payment to be captured or a shipment to be delivered.
-
-However, since the long-running workflow runs in the background, you won't receive its result or errors immediately when you execute the workflow.
-
-Instead, you must subscribe to the workflow's execution using the Workflow Engine Module Service. Learn more about it in [this chapter](https://docs.medusajs.com/learn/fundamentals/workflows/long-running-workflow#access-long-running-workflow-status-and-result/index.html.md).
-
-
# Docs Contribution Guidelines
Thank you for your interest in contributing to the documentation! You will be helping the open source community and other developers interested in learning more about Medusa and using it.
@@ -17738,135 +17798,90 @@ export const languages: Language[] = [
Our team will perform a general review on your PR and merge it if no issues are found. The translation will be available in the admin after the next release.
-# Example: Write Integration Tests for Workflows
+# Workflow Timeout
-In this chapter, you'll learn how to write integration tests for workflows using [medusaIntegrationTestRunner](https://docs.medusajs.com/learn/debugging-and-testing/testing-tools/integration-tests/index.html.md) from Medusa's Testing Framwork.
+In this chapter, you’ll learn how to set a timeout for workflows and steps.
-### Prerequisites
+## What is a Workflow Timeout?
-- [Testing Tools Setup](https://docs.medusajs.com/learn/debugging-and-testing/testing-tools/index.html.md)
+By default, a workflow doesn’t have a timeout. It continues execution until it’s finished or an error occurs.
-## Write Integration Test for Workflow
+You can configure a workflow’s timeout to indicate how long the workflow can execute. If a workflow's execution time passes the configured timeout, it is failed and an error is thrown.
-Consider you have the following workflow defined at `src/workflows/hello-world.ts`:
+### Timeout Doesn't Stop Step Execution
-```ts title="src/workflows/hello-world.ts"
-import {
+Configuring a timeout doesn't stop the execution of a step in progress. The timeout only affects the status of the workflow and its result.
+
+***
+
+## Configure Workflow Timeout
+
+The `createWorkflow` function can accept a configuration object instead of the workflow’s name.
+
+In the configuration object, you pass a `timeout` property, whose value is a number indicating the timeout in seconds.
+
+For example:
+
+```ts title="src/workflows/hello-world.ts" highlights={[["16"]]} collapsibleLines="1-13" expandButtonLabel="Show More"
+import {
+ createStep,
createWorkflow,
- createStep,
- StepResponse,
WorkflowResponse,
} from "@medusajs/framework/workflows-sdk"
-const step1 = createStep("step-1", () => {
- return new StepResponse("Hello, World!")
+const step1 = createStep(
+ "step-1",
+ async () => {
+ // ...
+ }
+)
+
+const myWorkflow = createWorkflow({
+ name: "hello-world",
+ timeout: 2, // 2 seconds
+}, function () {
+ const str1 = step1()
+
+ return new WorkflowResponse({
+ message: str1,
+ })
})
-export const helloWorldWorkflow = createWorkflow(
- "hello-world-workflow",
- () => {
- const message = step1()
+export default myWorkflow
- return new WorkflowResponse(message)
+```
+
+This workflow's executions fail if they run longer than two seconds.
+
+A workflow’s timeout error is returned in the `errors` property of the workflow’s execution, as explained in [this chapter](https://docs.medusajs.com/learn/fundamentals/workflows/errors/index.html.md). The error’s name is `TransactionTimeoutError`.
+
+***
+
+## Configure Step Timeout
+
+Alternatively, you can configure the timeout for a step rather than the entire workflow.
+
+As mentioned in the previous section, the timeout doesn't stop the execution of the step. It only affects the step's status and output.
+
+The step’s configuration object accepts a `timeout` property, whose value is a number indicating the timeout in seconds.
+
+For example:
+
+```tsx
+const step1 = createStep(
+ {
+ name: "step-1",
+ timeout: 2, // 2 seconds
+ },
+ async () => {
+ // ...
}
)
```
-To write a test for this workflow, create the file `integration-tests/http/workflow.spec.ts` with the following content:
+This step's executions fail if they run longer than two seconds.
-```ts title="integration-tests/http/workflow.spec.ts"
-import { medusaIntegrationTestRunner } from "@medusajs/test-utils"
-import { helloWorldWorkflow } from "../../src/workflows/hello-world"
-
-medusaIntegrationTestRunner({
- testSuite: ({ getContainer }) => {
- describe("Test hello-world workflow", () => {
- it("returns message", async () => {
- const { result } = await helloWorldWorkflow(getContainer())
- .run()
-
- expect(result).toEqual("Hello, World!")
- })
- })
- },
-})
-
-jest.setTimeout(60 * 1000)
-```
-
-You use the `medusaIntegrationTestRunner` to write an integration test for the workflow. The test pases if the workflow returns the string `"Hello, World!"`.
-
-### Jest Timeout
-
-Since your tests connect to the database and perform actions that require more time than the typical tests, make sure to increase the timeout in your test:
-
-```ts title="integration-tests/http/custom-routes.spec.ts"
-// in your test's file
-jest.setTimeout(60 * 1000)
-```
-
-***
-
-## Run Test
-
-Run the following command to run your tests:
-
-```bash npm2yarn
-npm run test:integration
-```
-
-If you don't have a `test:integration` script in `package.json`, refer to the [Medusa Testing Tools chapter](https://docs.medusajs.com/learn/debugging-and-testing/testing-tools#add-test-commands/index.html.md).
-
-This runs your Medusa application and runs the tests available under the `integrations/http` directory.
-
-***
-
-## Test That a Workflow Throws an Error
-
-You might want to test that a workflow throws an error in certain cases. To test this:
-
-- Disable the `throwOnError` option when executing the workflow.
-- Use the returned `errors` property to check what errors were thrown.
-
-For example, if you have a step that throws this error:
-
-```ts title="src/workflows/hello-world.ts"
-import { MedusaError } from "@medusajs/framework/utils"
-import { createStep } from "@medusajs/framework/workflows-sdk"
-
-const step1 = createStep("step-1", () => {
- throw new MedusaError(MedusaError.Types.NOT_FOUND, "Item doesn't exist")
-})
-```
-
-You can write the following test to ensure that the workflow throws that error:
-
-```ts title="integration-tests/http/workflow.spec.ts"
-import { medusaIntegrationTestRunner } from "@medusajs/test-utils"
-import { helloWorldWorkflow } from "../../src/workflows/hello-world"
-
-medusaIntegrationTestRunner({
- testSuite: ({ getContainer }) => {
- describe("Test hello-world workflow", () => {
- it("returns message", async () => {
- const { errors } = await helloWorldWorkflow(getContainer())
- .run({
- throwOnError: false,
- })
-
- expect(errors.length).toBeGreaterThan(0)
- expect(errors[0].error.message).toBe("Item doesn't exist")
- })
- })
- },
-})
-
-jest.setTimeout(60 * 1000)
-```
-
-The `errors` property contains an array of errors thrown during the execution of the workflow. Each error item has an `error` object, being the error thrown.
-
-If you threw a `MedusaError`, then you can check the error message in `errors[0].error.message`.
+A step’s timeout error is returned in the `errors` property of the workflow’s execution, as explained in [this chapter](https://docs.medusajs.com/learn/fundamentals/workflows/errors/index.html.md). The error’s name is `TransactionStepTimeoutError`.
# Example: Integration Tests for a Module
@@ -18508,6 +18523,137 @@ const response = await api.post(`/custom`, form, {
```
+# Example: Write Integration Tests for Workflows
+
+In this chapter, you'll learn how to write integration tests for workflows using [medusaIntegrationTestRunner](https://docs.medusajs.com/learn/debugging-and-testing/testing-tools/integration-tests/index.html.md) from Medusa's Testing Framwork.
+
+### Prerequisites
+
+- [Testing Tools Setup](https://docs.medusajs.com/learn/debugging-and-testing/testing-tools/index.html.md)
+
+## Write Integration Test for Workflow
+
+Consider you have the following workflow defined at `src/workflows/hello-world.ts`:
+
+```ts title="src/workflows/hello-world.ts"
+import {
+ createWorkflow,
+ createStep,
+ StepResponse,
+ WorkflowResponse,
+} from "@medusajs/framework/workflows-sdk"
+
+const step1 = createStep("step-1", () => {
+ return new StepResponse("Hello, World!")
+})
+
+export const helloWorldWorkflow = createWorkflow(
+ "hello-world-workflow",
+ () => {
+ const message = step1()
+
+ return new WorkflowResponse(message)
+ }
+)
+```
+
+To write a test for this workflow, create the file `integration-tests/http/workflow.spec.ts` with the following content:
+
+```ts title="integration-tests/http/workflow.spec.ts"
+import { medusaIntegrationTestRunner } from "@medusajs/test-utils"
+import { helloWorldWorkflow } from "../../src/workflows/hello-world"
+
+medusaIntegrationTestRunner({
+ testSuite: ({ getContainer }) => {
+ describe("Test hello-world workflow", () => {
+ it("returns message", async () => {
+ const { result } = await helloWorldWorkflow(getContainer())
+ .run()
+
+ expect(result).toEqual("Hello, World!")
+ })
+ })
+ },
+})
+
+jest.setTimeout(60 * 1000)
+```
+
+You use the `medusaIntegrationTestRunner` to write an integration test for the workflow. The test pases if the workflow returns the string `"Hello, World!"`.
+
+### Jest Timeout
+
+Since your tests connect to the database and perform actions that require more time than the typical tests, make sure to increase the timeout in your test:
+
+```ts title="integration-tests/http/custom-routes.spec.ts"
+// in your test's file
+jest.setTimeout(60 * 1000)
+```
+
+***
+
+## Run Test
+
+Run the following command to run your tests:
+
+```bash npm2yarn
+npm run test:integration
+```
+
+If you don't have a `test:integration` script in `package.json`, refer to the [Medusa Testing Tools chapter](https://docs.medusajs.com/learn/debugging-and-testing/testing-tools#add-test-commands/index.html.md).
+
+This runs your Medusa application and runs the tests available under the `integrations/http` directory.
+
+***
+
+## Test That a Workflow Throws an Error
+
+You might want to test that a workflow throws an error in certain cases. To test this:
+
+- Disable the `throwOnError` option when executing the workflow.
+- Use the returned `errors` property to check what errors were thrown.
+
+For example, if you have a step that throws this error:
+
+```ts title="src/workflows/hello-world.ts"
+import { MedusaError } from "@medusajs/framework/utils"
+import { createStep } from "@medusajs/framework/workflows-sdk"
+
+const step1 = createStep("step-1", () => {
+ throw new MedusaError(MedusaError.Types.NOT_FOUND, "Item doesn't exist")
+})
+```
+
+You can write the following test to ensure that the workflow throws that error:
+
+```ts title="integration-tests/http/workflow.spec.ts"
+import { medusaIntegrationTestRunner } from "@medusajs/test-utils"
+import { helloWorldWorkflow } from "../../src/workflows/hello-world"
+
+medusaIntegrationTestRunner({
+ testSuite: ({ getContainer }) => {
+ describe("Test hello-world workflow", () => {
+ it("returns message", async () => {
+ const { errors } = await helloWorldWorkflow(getContainer())
+ .run({
+ throwOnError: false,
+ })
+
+ expect(errors.length).toBeGreaterThan(0)
+ expect(errors[0].error.message).toBe("Item doesn't exist")
+ })
+ })
+ },
+})
+
+jest.setTimeout(60 * 1000)
+```
+
+The `errors` property contains an array of errors thrown during the execution of the workflow. Each error item has an `error` object, being the error thrown.
+
+If you threw a `MedusaError`, then you can check the error message in `errors[0].error.message`.
+
+
# Commerce Modules
In this section of the documentation, you'll find guides and references related to Medusa's Commerce Modules.
@@ -18548,6 +18694,136 @@ The Commerce Modules can be used in many use cases, including:
- Node.js Application: Use the Commerce Modules in any Node.js application by installing it with NPM.
+# Auth Module
+
+In this section of the documentation, you will find resources to learn more about the Auth Module and how to use it in your application.
+
+Medusa has auth related features available out-of-the-box through the Auth Module. A [module](https://docs.medusajs.com/docs/learn/fundamentals/modules/index.html.md) is a standalone package that provides features for a single domain. Each of Medusa's commerce features are placed in Commerce Modules, such as this Auth Module.
+
+Learn more about why modules are isolated in [this documentation](https://docs.medusajs.com/docs/learn/fundamentals/modules/isolation/index.html.md).
+
+## Auth Features
+
+- [Basic User Authentication](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/auth/authentication-route#1-basic-authentication-flow/index.html.md): Authenticate users using their email and password credentials.
+- [Third-Party and Social Authentication](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/auth/authentication-route#2-third-party-service-authenticate-flow/index.html.md): Authenticate users using third-party services and social platforms, such as [Google](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/auth/auth-providers/google/index.html.md) and [GitHub](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/auth/auth-providers/github/index.html.md).
+- [Authenticate Custom Actor Types](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/auth/create-actor-type/index.html.md): Create custom user or actor types, such as managers, authenticate them in your application, and guard routes based on the custom user types.
+- [Custom Authentication Providers](https://docs.medusajs.com/references/auth/provider/index.html.md): Integrate third-party services with custom authentication providors.
+
+***
+
+## How to Use the Auth Module
+
+In your Medusa application, you build flows around Commerce Modules. A flow is built as a [Workflow](https://docs.medusajs.com/docs/learn/fundamentals/workflows/index.html.md), which is a special function composed of a series of steps that guarantees data consistency and reliable roll-back mechanism.
+
+You can build custom workflows and steps. You can also re-use Medusa's workflows and steps, which are provided by the `@medusajs/medusa/core-flows` package.
+
+For example:
+
+```ts title="src/workflows/authenticate-user.ts" highlights={highlights}
+import {
+ createWorkflow,
+ WorkflowResponse,
+ createStep,
+ StepResponse,
+} from "@medusajs/framework/workflows-sdk"
+import { Modules, MedusaError } from "@medusajs/framework/utils"
+import { MedusaRequest } from "@medusajs/framework/http"
+import { AuthenticationInput } from "@medusajs/framework/types"
+
+type Input = {
+ req: MedusaRequest
+}
+
+const authenticateUserStep = createStep(
+ "authenticate-user",
+ async ({ req }: Input, { container }) => {
+ const authModuleService = container.resolve(Modules.AUTH)
+
+ const { success, authIdentity, error } = await authModuleService
+ .authenticate(
+ "emailpass",
+ {
+ url: req.url,
+ headers: req.headers,
+ query: req.query,
+ body: req.body,
+ authScope: "admin", // or custom actor type
+ protocol: req.protocol,
+ } as AuthenticationInput
+ )
+
+ if (!success) {
+ // incorrect authentication details
+ throw new MedusaError(
+ MedusaError.Types.UNAUTHORIZED,
+ error || "Incorrect authentication details"
+ )
+ }
+
+ return new StepResponse({ authIdentity }, authIdentity?.id)
+ },
+ async (authIdentityId, { container }) => {
+ if (!authIdentityId) {
+ return
+ }
+
+ const authModuleService = container.resolve(Modules.AUTH)
+
+ await authModuleService.deleteAuthIdentities([authIdentityId])
+ }
+)
+
+export const authenticateUserWorkflow = createWorkflow(
+ "authenticate-user",
+ (input: Input) => {
+ const { authIdentity } = authenticateUserStep(input)
+
+ return new WorkflowResponse({
+ authIdentity,
+ })
+ }
+)
+```
+
+You can then execute the workflow in your custom API routes, scheduled jobs, or subscribers:
+
+```ts title="API Route" highlights={[["11"], ["12"]]} collapsibleLines="1-6" expandButtonLabel="Show Imports"
+import type {
+ MedusaRequest,
+ MedusaResponse,
+} from "@medusajs/framework/http"
+import { authenticateUserWorkflow } from "../../workflows/authenticate-user"
+
+export async function GET(
+ req: MedusaRequest,
+ res: MedusaResponse
+) {
+ const { result } = await authenticateUserWorkflow(req.scope)
+ .run({
+ req,
+ })
+
+ res.send(result)
+}
+```
+
+Learn more about workflows in [this documentation](https://docs.medusajs.com/docs/learn/fundamentals/workflows/index.html.md).
+
+***
+
+## Configure Auth Module
+
+The Auth Module accepts options for further configurations. Refer to [this documentation](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/auth/module-options/index.html.md) for details on the module's options.
+
+***
+
+## Providers
+
+Medusa provides the following authentication providers out-of-the-box. You can use them to authenticate admin users, customers, or custom actor types.
+
+***
+
+
# API Key Module
In this section of the documentation, you will find resources to learn more about the API Key Module and how to use it in your application.
@@ -18688,6 +18964,304 @@ Learn more about workflows in [this documentation](https://docs.medusajs.com/doc
***
+# Currency Module
+
+In this section of the documentation, you will find resources to learn more about the Currency Module and how to use it in your application.
+
+Refer to the [Medusa Admin User Guide](https://docs.medusajs.com/user-guide/settings/store/index.html.md) to learn how to manage your store's currencies using the dashboard.
+
+Medusa has currency related features available out-of-the-box through the Currency Module. A [module](https://docs.medusajs.com/docs/learn/fundamentals/modules/index.html.md) is a standalone package that provides features for a single domain. Each of Medusa's commerce features are placed in Commerce Modules, such as this Currency Module.
+
+Learn more about why modules are isolated in [this documentation](https://docs.medusajs.com/docs/learn/fundamentals/modules/isolation/index.html.md).
+
+## Currency Features
+
+- [Currency Management and Retrieval](https://docs.medusajs.com/references/currency/listAndCountCurrencies/index.html.md): This module adds all common currencies to your application and allows you to retrieve them.
+- [Support Currencies in Modules](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/currency/links-to-other-modules/index.html.md): Other Commerce Modules use currency codes in their data models or operations. Use the Currency Module to retrieve a currency code and its details.
+
+***
+
+## How to Use the Currency Module
+
+In your Medusa application, you build flows around Commerce Modules. A flow is built as a [Workflow](https://docs.medusajs.com/docs/learn/fundamentals/workflows/index.html.md), which is a special function composed of a series of steps that guarantees data consistency and reliable roll-back mechanism.
+
+You can build custom workflows and steps. You can also re-use Medusa's workflows and steps, which are provided by the `@medusajs/medusa/core-flows` package.
+
+For example:
+
+```ts title="src/workflows/retrieve-price-with-currency.ts" highlights={highlights}
+import {
+ createWorkflow,
+ WorkflowResponse,
+ createStep,
+ StepResponse,
+ transform,
+} from "@medusajs/framework/workflows-sdk"
+import { Modules } from "@medusajs/framework/utils"
+
+const retrieveCurrencyStep = createStep(
+ "retrieve-currency",
+ async ({}, { container }) => {
+ const currencyModuleService = container.resolve(Modules.CURRENCY)
+
+ const currency = await currencyModuleService
+ .retrieveCurrency("usd")
+
+ return new StepResponse({ currency })
+ }
+)
+
+type Input = {
+ price: number
+}
+
+export const retrievePriceWithCurrency = createWorkflow(
+ "create-currency",
+ (input: Input) => {
+ const { currency } = retrieveCurrencyStep()
+
+ const formattedPrice = transform({
+ input,
+ currency,
+ }, (data) => {
+ return `${data.currency.symbol}${data.input.price}`
+ })
+
+ return new WorkflowResponse({
+ formattedPrice,
+ })
+ }
+)
+```
+
+You can then execute the workflow in your custom API routes, scheduled jobs, or subscribers:
+
+### API Route
+
+```ts title="src/api/workflow/route.ts" highlights={[["11"], ["12"], ["13"], ["14"]]} collapsibleLines="1-6" expandButtonLabel="Show Imports"
+import type {
+ MedusaRequest,
+ MedusaResponse,
+} from "@medusajs/framework/http"
+import { retrievePriceWithCurrency } from "../../workflows/retrieve-price-with-currency"
+
+export async function GET(
+ req: MedusaRequest,
+ res: MedusaResponse
+) {
+ const { result } = await retrievePriceWithCurrency(req.scope)
+ .run({
+ price: 10,
+ })
+
+ res.send(result)
+}
+```
+
+### Subscriber
+
+```ts title="src/subscribers/user-created.ts" highlights={[["11"], ["12"], ["13"], ["14"]]} collapsibleLines="1-6" expandButtonLabel="Show Imports"
+import {
+ type SubscriberConfig,
+ type SubscriberArgs,
+} from "@medusajs/framework"
+import { retrievePriceWithCurrency } from "../workflows/retrieve-price-with-currency"
+
+export default async function handleUserCreated({
+ event: { data },
+ container,
+}: SubscriberArgs<{ id: string }>) {
+ const { result } = await retrievePriceWithCurrency(container)
+ .run({
+ price: 10,
+ })
+
+ console.log(result)
+}
+
+export const config: SubscriberConfig = {
+ event: "user.created",
+}
+```
+
+### Scheduled Job
+
+```ts title="src/jobs/run-daily.ts" highlights={[["7"], ["8"], ["9"], ["10"]]}
+import { MedusaContainer } from "@medusajs/framework/types"
+import { retrievePriceWithCurrency } from "../workflows/retrieve-price-with-currency"
+
+export default async function myCustomJob(
+ container: MedusaContainer
+) {
+ const { result } = await retrievePriceWithCurrency(container)
+ .run({
+ price: 10,
+ })
+
+ console.log(result)
+}
+
+export const config = {
+ name: "run-once-a-day",
+ schedule: `0 0 * * *`,
+}
+```
+
+Learn more about workflows in [this documentation](https://docs.medusajs.com/docs/learn/fundamentals/workflows/index.html.md).
+
+***
+
+
+# Cart Module
+
+In this section of the documentation, you will find resources to learn more about the Cart Module and how to use it in your application.
+
+Medusa has cart related features available out-of-the-box through the Cart Module. A [module](https://docs.medusajs.com/docs/learn/fundamentals/modules/index.html.md) is a standalone package that provides features for a single domain. Each of Medusa's commerce features are placed in Commerce Modules, such as this Cart Module.
+
+Learn more about why modules are isolated in [this documentation](https://docs.medusajs.com/docs/learn/fundamentals/modules/isolation/index.html.md).
+
+## Cart Features
+
+- [Cart Management](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/cart/concepts/index.html.md): Store and manage carts, including their addresses, line items, shipping methods, and more.
+- [Apply Promotion Adjustments](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/cart/promotions/index.html.md): Apply promotions or discounts to line items and shipping methods by adding adjustment lines that are factored into their subtotals.
+- [Apply Tax Lines](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/cart/tax-lines/index.html.md): Apply tax lines to line items and shipping methods.
+- [Cart Scoping](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/cart/links-to-other-modules/index.html.md): When used in the Medusa application, Medusa creates links to other Commerce Modules, scoping a cart to a sales channel, region, and a customer.
+
+***
+
+## How to Use the Cart Module
+
+In your Medusa application, you build flows around Commerce Modules. A flow is built as a [Workflow](https://docs.medusajs.com/docs/learn/fundamentals/workflows/index.html.md), which is a special function composed of a series of steps that guarantees data consistency and reliable roll-back mechanism.
+
+You can build custom workflows and steps. You can also re-use Medusa's workflows and steps, which are provided by the `@medusajs/medusa/core-flows` package.
+
+For example:
+
+```ts title="src/workflows/create-cart.ts" highlights={highlights}
+import {
+ createWorkflow,
+ WorkflowResponse,
+ createStep,
+ StepResponse,
+} from "@medusajs/framework/workflows-sdk"
+import { Modules } from "@medusajs/framework/utils"
+
+const createCartStep = createStep(
+ "create-cart",
+ async ({}, { container }) => {
+ const cartModuleService = container.resolve(Modules.CART)
+
+ const cart = await cartModuleService.createCarts({
+ currency_code: "usd",
+ shipping_address: {
+ address_1: "1512 Barataria Blvd",
+ country_code: "us",
+ },
+ items: [
+ {
+ title: "Shirt",
+ unit_price: 1000,
+ quantity: 1,
+ },
+ ],
+ })
+
+ return new StepResponse({ cart }, cart.id)
+ },
+ async (cartId, { container }) => {
+ if (!cartId) {
+ return
+ }
+ const cartModuleService = container.resolve(Modules.CART)
+
+ await cartModuleService.deleteCarts([cartId])
+ }
+)
+
+export const createCartWorkflow = createWorkflow(
+ "create-cart",
+ () => {
+ const { cart } = createCartStep()
+
+ return new WorkflowResponse({
+ cart,
+ })
+ }
+)
+```
+
+You can then execute the workflow in your custom API routes, scheduled jobs, or subscribers:
+
+### API Route
+
+```ts title="src/api/workflow/route.ts" highlights={[["11"], ["12"]]} collapsibleLines="1-6" expandButtonLabel="Show Imports"
+import type {
+ MedusaRequest,
+ MedusaResponse,
+} from "@medusajs/framework/http"
+import { createCartWorkflow } from "../../workflows/create-cart"
+
+export async function GET(
+ req: MedusaRequest,
+ res: MedusaResponse
+) {
+ const { result } = await createCartWorkflow(req.scope)
+ .run()
+
+ res.send(result)
+}
+```
+
+### Subscriber
+
+```ts title="src/subscribers/user-created.ts" highlights={[["11"], ["12"]]} collapsibleLines="1-6" expandButtonLabel="Show Imports"
+import {
+ type SubscriberConfig,
+ type SubscriberArgs,
+} from "@medusajs/framework"
+import { createCartWorkflow } from "../workflows/create-cart"
+
+export default async function handleUserCreated({
+ event: { data },
+ container,
+}: SubscriberArgs<{ id: string }>) {
+ const { result } = await createCartWorkflow(container)
+ .run()
+
+ console.log(result)
+}
+
+export const config: SubscriberConfig = {
+ event: "user.created",
+}
+```
+
+### Scheduled Job
+
+```ts title="src/jobs/run-daily.ts" highlights={[["7"], ["8"]]}
+import { MedusaContainer } from "@medusajs/framework/types"
+import { createCartWorkflow } from "../workflows/create-cart"
+
+export default async function myCustomJob(
+ container: MedusaContainer
+) {
+ const { result } = await createCartWorkflow(container)
+ .run()
+
+ console.log(result)
+}
+
+export const config = {
+ name: "run-once-a-day",
+ schedule: `0 0 * * *`,
+}
+```
+
+Learn more about workflows in [this documentation](https://docs.medusajs.com/docs/learn/fundamentals/workflows/index.html.md).
+
+***
+
+
# Customer Module
In this section of the documentation, you will find resources to learn more about the Customer Module and how to use it in your application.
@@ -18996,154 +19570,6 @@ The Fulfillment Module accepts options for further configurations. Refer to [thi
***
-# Currency Module
-
-In this section of the documentation, you will find resources to learn more about the Currency Module and how to use it in your application.
-
-Refer to the [Medusa Admin User Guide](https://docs.medusajs.com/user-guide/settings/store/index.html.md) to learn how to manage your store's currencies using the dashboard.
-
-Medusa has currency related features available out-of-the-box through the Currency Module. A [module](https://docs.medusajs.com/docs/learn/fundamentals/modules/index.html.md) is a standalone package that provides features for a single domain. Each of Medusa's commerce features are placed in Commerce Modules, such as this Currency Module.
-
-Learn more about why modules are isolated in [this documentation](https://docs.medusajs.com/docs/learn/fundamentals/modules/isolation/index.html.md).
-
-## Currency Features
-
-- [Currency Management and Retrieval](https://docs.medusajs.com/references/currency/listAndCountCurrencies/index.html.md): This module adds all common currencies to your application and allows you to retrieve them.
-- [Support Currencies in Modules](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/currency/links-to-other-modules/index.html.md): Other Commerce Modules use currency codes in their data models or operations. Use the Currency Module to retrieve a currency code and its details.
-
-***
-
-## How to Use the Currency Module
-
-In your Medusa application, you build flows around Commerce Modules. A flow is built as a [Workflow](https://docs.medusajs.com/docs/learn/fundamentals/workflows/index.html.md), which is a special function composed of a series of steps that guarantees data consistency and reliable roll-back mechanism.
-
-You can build custom workflows and steps. You can also re-use Medusa's workflows and steps, which are provided by the `@medusajs/medusa/core-flows` package.
-
-For example:
-
-```ts title="src/workflows/retrieve-price-with-currency.ts" highlights={highlights}
-import {
- createWorkflow,
- WorkflowResponse,
- createStep,
- StepResponse,
- transform,
-} from "@medusajs/framework/workflows-sdk"
-import { Modules } from "@medusajs/framework/utils"
-
-const retrieveCurrencyStep = createStep(
- "retrieve-currency",
- async ({}, { container }) => {
- const currencyModuleService = container.resolve(Modules.CURRENCY)
-
- const currency = await currencyModuleService
- .retrieveCurrency("usd")
-
- return new StepResponse({ currency })
- }
-)
-
-type Input = {
- price: number
-}
-
-export const retrievePriceWithCurrency = createWorkflow(
- "create-currency",
- (input: Input) => {
- const { currency } = retrieveCurrencyStep()
-
- const formattedPrice = transform({
- input,
- currency,
- }, (data) => {
- return `${data.currency.symbol}${data.input.price}`
- })
-
- return new WorkflowResponse({
- formattedPrice,
- })
- }
-)
-```
-
-You can then execute the workflow in your custom API routes, scheduled jobs, or subscribers:
-
-### API Route
-
-```ts title="src/api/workflow/route.ts" highlights={[["11"], ["12"], ["13"], ["14"]]} collapsibleLines="1-6" expandButtonLabel="Show Imports"
-import type {
- MedusaRequest,
- MedusaResponse,
-} from "@medusajs/framework/http"
-import { retrievePriceWithCurrency } from "../../workflows/retrieve-price-with-currency"
-
-export async function GET(
- req: MedusaRequest,
- res: MedusaResponse
-) {
- const { result } = await retrievePriceWithCurrency(req.scope)
- .run({
- price: 10,
- })
-
- res.send(result)
-}
-```
-
-### Subscriber
-
-```ts title="src/subscribers/user-created.ts" highlights={[["11"], ["12"], ["13"], ["14"]]} collapsibleLines="1-6" expandButtonLabel="Show Imports"
-import {
- type SubscriberConfig,
- type SubscriberArgs,
-} from "@medusajs/framework"
-import { retrievePriceWithCurrency } from "../workflows/retrieve-price-with-currency"
-
-export default async function handleUserCreated({
- event: { data },
- container,
-}: SubscriberArgs<{ id: string }>) {
- const { result } = await retrievePriceWithCurrency(container)
- .run({
- price: 10,
- })
-
- console.log(result)
-}
-
-export const config: SubscriberConfig = {
- event: "user.created",
-}
-```
-
-### Scheduled Job
-
-```ts title="src/jobs/run-daily.ts" highlights={[["7"], ["8"], ["9"], ["10"]]}
-import { MedusaContainer } from "@medusajs/framework/types"
-import { retrievePriceWithCurrency } from "../workflows/retrieve-price-with-currency"
-
-export default async function myCustomJob(
- container: MedusaContainer
-) {
- const { result } = await retrievePriceWithCurrency(container)
- .run({
- price: 10,
- })
-
- console.log(result)
-}
-
-export const config = {
- name: "run-once-a-day",
- schedule: `0 0 * * *`,
-}
-```
-
-Learn more about workflows in [this documentation](https://docs.medusajs.com/docs/learn/fundamentals/workflows/index.html.md).
-
-***
-
-
# Inventory Module
In this section of the documentation, you will find resources to learn more about the Inventory Module and how to use it in your application.
@@ -19288,744 +19714,6 @@ Learn more about workflows in [this documentation](https://docs.medusajs.com/doc
***
-# Cart Module
-
-In this section of the documentation, you will find resources to learn more about the Cart Module and how to use it in your application.
-
-Medusa has cart related features available out-of-the-box through the Cart Module. A [module](https://docs.medusajs.com/docs/learn/fundamentals/modules/index.html.md) is a standalone package that provides features for a single domain. Each of Medusa's commerce features are placed in Commerce Modules, such as this Cart Module.
-
-Learn more about why modules are isolated in [this documentation](https://docs.medusajs.com/docs/learn/fundamentals/modules/isolation/index.html.md).
-
-## Cart Features
-
-- [Cart Management](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/cart/concepts/index.html.md): Store and manage carts, including their addresses, line items, shipping methods, and more.
-- [Apply Promotion Adjustments](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/cart/promotions/index.html.md): Apply promotions or discounts to line items and shipping methods by adding adjustment lines that are factored into their subtotals.
-- [Apply Tax Lines](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/cart/tax-lines/index.html.md): Apply tax lines to line items and shipping methods.
-- [Cart Scoping](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/cart/links-to-other-modules/index.html.md): When used in the Medusa application, Medusa creates links to other Commerce Modules, scoping a cart to a sales channel, region, and a customer.
-
-***
-
-## How to Use the Cart Module
-
-In your Medusa application, you build flows around Commerce Modules. A flow is built as a [Workflow](https://docs.medusajs.com/docs/learn/fundamentals/workflows/index.html.md), which is a special function composed of a series of steps that guarantees data consistency and reliable roll-back mechanism.
-
-You can build custom workflows and steps. You can also re-use Medusa's workflows and steps, which are provided by the `@medusajs/medusa/core-flows` package.
-
-For example:
-
-```ts title="src/workflows/create-cart.ts" highlights={highlights}
-import {
- createWorkflow,
- WorkflowResponse,
- createStep,
- StepResponse,
-} from "@medusajs/framework/workflows-sdk"
-import { Modules } from "@medusajs/framework/utils"
-
-const createCartStep = createStep(
- "create-cart",
- async ({}, { container }) => {
- const cartModuleService = container.resolve(Modules.CART)
-
- const cart = await cartModuleService.createCarts({
- currency_code: "usd",
- shipping_address: {
- address_1: "1512 Barataria Blvd",
- country_code: "us",
- },
- items: [
- {
- title: "Shirt",
- unit_price: 1000,
- quantity: 1,
- },
- ],
- })
-
- return new StepResponse({ cart }, cart.id)
- },
- async (cartId, { container }) => {
- if (!cartId) {
- return
- }
- const cartModuleService = container.resolve(Modules.CART)
-
- await cartModuleService.deleteCarts([cartId])
- }
-)
-
-export const createCartWorkflow = createWorkflow(
- "create-cart",
- () => {
- const { cart } = createCartStep()
-
- return new WorkflowResponse({
- cart,
- })
- }
-)
-```
-
-You can then execute the workflow in your custom API routes, scheduled jobs, or subscribers:
-
-### API Route
-
-```ts title="src/api/workflow/route.ts" highlights={[["11"], ["12"]]} collapsibleLines="1-6" expandButtonLabel="Show Imports"
-import type {
- MedusaRequest,
- MedusaResponse,
-} from "@medusajs/framework/http"
-import { createCartWorkflow } from "../../workflows/create-cart"
-
-export async function GET(
- req: MedusaRequest,
- res: MedusaResponse
-) {
- const { result } = await createCartWorkflow(req.scope)
- .run()
-
- res.send(result)
-}
-```
-
-### Subscriber
-
-```ts title="src/subscribers/user-created.ts" highlights={[["11"], ["12"]]} collapsibleLines="1-6" expandButtonLabel="Show Imports"
-import {
- type SubscriberConfig,
- type SubscriberArgs,
-} from "@medusajs/framework"
-import { createCartWorkflow } from "../workflows/create-cart"
-
-export default async function handleUserCreated({
- event: { data },
- container,
-}: SubscriberArgs<{ id: string }>) {
- const { result } = await createCartWorkflow(container)
- .run()
-
- console.log(result)
-}
-
-export const config: SubscriberConfig = {
- event: "user.created",
-}
-```
-
-### Scheduled Job
-
-```ts title="src/jobs/run-daily.ts" highlights={[["7"], ["8"]]}
-import { MedusaContainer } from "@medusajs/framework/types"
-import { createCartWorkflow } from "../workflows/create-cart"
-
-export default async function myCustomJob(
- container: MedusaContainer
-) {
- const { result } = await createCartWorkflow(container)
- .run()
-
- console.log(result)
-}
-
-export const config = {
- name: "run-once-a-day",
- schedule: `0 0 * * *`,
-}
-```
-
-Learn more about workflows in [this documentation](https://docs.medusajs.com/docs/learn/fundamentals/workflows/index.html.md).
-
-***
-
-
-# Auth Module
-
-In this section of the documentation, you will find resources to learn more about the Auth Module and how to use it in your application.
-
-Medusa has auth related features available out-of-the-box through the Auth Module. A [module](https://docs.medusajs.com/docs/learn/fundamentals/modules/index.html.md) is a standalone package that provides features for a single domain. Each of Medusa's commerce features are placed in Commerce Modules, such as this Auth Module.
-
-Learn more about why modules are isolated in [this documentation](https://docs.medusajs.com/docs/learn/fundamentals/modules/isolation/index.html.md).
-
-## Auth Features
-
-- [Basic User Authentication](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/auth/authentication-route#1-basic-authentication-flow/index.html.md): Authenticate users using their email and password credentials.
-- [Third-Party and Social Authentication](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/auth/authentication-route#2-third-party-service-authenticate-flow/index.html.md): Authenticate users using third-party services and social platforms, such as [Google](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/auth/auth-providers/google/index.html.md) and [GitHub](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/auth/auth-providers/github/index.html.md).
-- [Authenticate Custom Actor Types](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/auth/create-actor-type/index.html.md): Create custom user or actor types, such as managers, authenticate them in your application, and guard routes based on the custom user types.
-- [Custom Authentication Providers](https://docs.medusajs.com/references/auth/provider/index.html.md): Integrate third-party services with custom authentication providors.
-
-***
-
-## How to Use the Auth Module
-
-In your Medusa application, you build flows around Commerce Modules. A flow is built as a [Workflow](https://docs.medusajs.com/docs/learn/fundamentals/workflows/index.html.md), which is a special function composed of a series of steps that guarantees data consistency and reliable roll-back mechanism.
-
-You can build custom workflows and steps. You can also re-use Medusa's workflows and steps, which are provided by the `@medusajs/medusa/core-flows` package.
-
-For example:
-
-```ts title="src/workflows/authenticate-user.ts" highlights={highlights}
-import {
- createWorkflow,
- WorkflowResponse,
- createStep,
- StepResponse,
-} from "@medusajs/framework/workflows-sdk"
-import { Modules, MedusaError } from "@medusajs/framework/utils"
-import { MedusaRequest } from "@medusajs/framework/http"
-import { AuthenticationInput } from "@medusajs/framework/types"
-
-type Input = {
- req: MedusaRequest
-}
-
-const authenticateUserStep = createStep(
- "authenticate-user",
- async ({ req }: Input, { container }) => {
- const authModuleService = container.resolve(Modules.AUTH)
-
- const { success, authIdentity, error } = await authModuleService
- .authenticate(
- "emailpass",
- {
- url: req.url,
- headers: req.headers,
- query: req.query,
- body: req.body,
- authScope: "admin", // or custom actor type
- protocol: req.protocol,
- } as AuthenticationInput
- )
-
- if (!success) {
- // incorrect authentication details
- throw new MedusaError(
- MedusaError.Types.UNAUTHORIZED,
- error || "Incorrect authentication details"
- )
- }
-
- return new StepResponse({ authIdentity }, authIdentity?.id)
- },
- async (authIdentityId, { container }) => {
- if (!authIdentityId) {
- return
- }
-
- const authModuleService = container.resolve(Modules.AUTH)
-
- await authModuleService.deleteAuthIdentities([authIdentityId])
- }
-)
-
-export const authenticateUserWorkflow = createWorkflow(
- "authenticate-user",
- (input: Input) => {
- const { authIdentity } = authenticateUserStep(input)
-
- return new WorkflowResponse({
- authIdentity,
- })
- }
-)
-```
-
-You can then execute the workflow in your custom API routes, scheduled jobs, or subscribers:
-
-```ts title="API Route" highlights={[["11"], ["12"]]} collapsibleLines="1-6" expandButtonLabel="Show Imports"
-import type {
- MedusaRequest,
- MedusaResponse,
-} from "@medusajs/framework/http"
-import { authenticateUserWorkflow } from "../../workflows/authenticate-user"
-
-export async function GET(
- req: MedusaRequest,
- res: MedusaResponse
-) {
- const { result } = await authenticateUserWorkflow(req.scope)
- .run({
- req,
- })
-
- res.send(result)
-}
-```
-
-Learn more about workflows in [this documentation](https://docs.medusajs.com/docs/learn/fundamentals/workflows/index.html.md).
-
-***
-
-## Configure Auth Module
-
-The Auth Module accepts options for further configurations. Refer to [this documentation](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/auth/module-options/index.html.md) for details on the module's options.
-
-***
-
-## Providers
-
-Medusa provides the following authentication providers out-of-the-box. You can use them to authenticate admin users, customers, or custom actor types.
-
-***
-
-
-# Payment Module
-
-In this section of the documentation, you will find resources to learn more about the Payment Module and how to use it in your application.
-
-Refer to the [Medusa Admin User Guide](https://docs.medusajs.com/user-guide/orders/payments/index.html.md) to learn how to manage order payments using the dashboard.
-
-Medusa has payment related features available out-of-the-box through the Payment Module. A [module](https://docs.medusajs.com/docs/learn/fundamentals/modules/index.html.md) is a standalone package that provides features for a single domain. Each of Medusa's commerce features are placed in Commerce Modules, such as this Payment Module.
-
-Learn more about why modules are isolated in [this documentation](https://docs.medusajs.com/docs/learn/fundamentals/modules/isolation/index.html.md).
-
-## Payment Features
-
-- [Authorize, Capture, and Refund Payments](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/payment/payment/index.html.md): Authorize, capture, and refund payments for a single resource.
-- [Payment Collection Management](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/payment/payment-collection/index.html.md): Store and manage all payments of a single resources, such as a cart, in payment collections.
-- [Integrate Third-Party Payment Providers](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/payment/payment-provider/index.html.md): Use payment providers like [Stripe](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/payment/payment-provider/stripe/index.html.md) to handle and process payments, or integrate custom payment providers.
-- [Saved Payment Methods](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/payment/account-holder/index.html.md): Save payment methods for customers in third-party payment providers.
-- [Handle Webhook Events](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/payment/webhook-events/index.html.md): Handle webhook events from third-party providers and process the associated payment.
-
-***
-
-## How to Use the Payment Module
-
-In your Medusa application, you build flows around Commerce Modules. A flow is built as a [Workflow](https://docs.medusajs.com/docs/learn/fundamentals/workflows/index.html.md), which is a special function composed of a series of steps that guarantees data consistency and reliable roll-back mechanism.
-
-You can build custom workflows and steps. You can also re-use Medusa's workflows and steps, which are provided by the `@medusajs/medusa/core-flows` package.
-
-For example:
-
-```ts title="src/workflows/create-payment-collection.ts" highlights={highlights}
-import {
- createWorkflow,
- WorkflowResponse,
- createStep,
- StepResponse,
-} from "@medusajs/framework/workflows-sdk"
-import { Modules } from "@medusajs/framework/utils"
-
-const createPaymentCollectionStep = createStep(
- "create-payment-collection",
- async ({}, { container }) => {
- const paymentModuleService = container.resolve(Modules.PAYMENT)
-
- const paymentCollection = await paymentModuleService.createPaymentCollections({
- currency_code: "usd",
- amount: 5000,
- })
-
- return new StepResponse({ paymentCollection }, paymentCollection.id)
- },
- async (paymentCollectionId, { container }) => {
- if (!paymentCollectionId) {
- return
- }
- const paymentModuleService = container.resolve(Modules.PAYMENT)
-
- await paymentModuleService.deletePaymentCollections([paymentCollectionId])
- }
-)
-
-export const createPaymentCollectionWorkflow = createWorkflow(
- "create-payment-collection",
- () => {
- const { paymentCollection } = createPaymentCollectionStep()
-
- return new WorkflowResponse({
- paymentCollection,
- })
- }
-)
-```
-
-You can then execute the workflow in your custom API routes, scheduled jobs, or subscribers:
-
-### API Route
-
-```ts title="src/api/workflow/route.ts" highlights={[["11"], ["12"]]} collapsibleLines="1-6" expandButtonLabel="Show Imports"
-import type {
- MedusaRequest,
- MedusaResponse,
-} from "@medusajs/framework/http"
-import { createPaymentCollectionWorkflow } from "../../workflows/create-payment-collection"
-
-export async function GET(
- req: MedusaRequest,
- res: MedusaResponse
-) {
- const { result } = await createPaymentCollectionWorkflow(req.scope)
- .run()
-
- res.send(result)
-}
-```
-
-### Subscriber
-
-```ts title="src/subscribers/user-created.ts" highlights={[["11"], ["12"]]} collapsibleLines="1-6" expandButtonLabel="Show Imports"
-import {
- type SubscriberConfig,
- type SubscriberArgs,
-} from "@medusajs/framework"
-import { createPaymentCollectionWorkflow } from "../workflows/create-payment-collection"
-
-export default async function handleUserCreated({
- event: { data },
- container,
-}: SubscriberArgs<{ id: string }>) {
- const { result } = await createPaymentCollectionWorkflow(container)
- .run()
-
- console.log(result)
-}
-
-export const config: SubscriberConfig = {
- event: "user.created",
-}
-```
-
-### Scheduled Job
-
-```ts title="src/jobs/run-daily.ts" highlights={[["7"], ["8"]]}
-import { MedusaContainer } from "@medusajs/framework/types"
-import { createPaymentCollectionWorkflow } from "../workflows/create-payment-collection"
-
-export default async function myCustomJob(
- container: MedusaContainer
-) {
- const { result } = await createPaymentCollectionWorkflow(container)
- .run()
-
- console.log(result)
-}
-
-export const config = {
- name: "run-once-a-day",
- schedule: `0 0 * * *`,
-}
-```
-
-Learn more about workflows in [this documentation](https://docs.medusajs.com/docs/learn/fundamentals/workflows/index.html.md).
-
-***
-
-## Configure Payment Module
-
-The Payment Module accepts options for further configurations. Refer to [this documentation](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/payment/module-options/index.html.md) for details on the module's options.
-
-***
-
-## Providers
-
-Medusa provides the following payment providers out-of-the-box. You can use them to process payments for orders, returns, and other resources.
-
-***
-
-
-# Promotion Module
-
-In this section of the documentation, you will find resources to learn more about the Promotion Module and how to use it in your application.
-
-Refer to the [Medusa Admin User Guide](https://docs.medusajs.com/user-guide/promotions/index.html.md) to learn how to manage promotions using the dashboard.
-
-Medusa has promotion related features available out-of-the-box through the Promotion Module. A [module](https://docs.medusajs.com/docs/learn/fundamentals/modules/index.html.md) is a standalone package that provides features for a single domain. Each of Medusa's commerce features are placed in Commerce Modules, such as this Promotion Module.
-
-Learn more about why modules are isolated in [this documentation](https://docs.medusajs.com/docs/learn/fundamentals/modules/isolation/index.html.md).
-
-## Promotion Features
-
-- [Discount Functionalities](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/promotion/concepts/index.html.md): A promotion discounts an amount or percentage of a cart's items, shipping methods, or the entire order.
-- [Flexible Promotion Rules](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/promotion/concepts#flexible-rules/index.html.md): A promotion has rules that restricts when the promotion is applied.
-- [Campaign Management](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/promotion/campaign/index.html.md): A campaign combines promotions under the same conditions, such as start and end dates, and budget configurations.
-- [Apply Promotion on Carts and Orders](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/promotion/actions/index.html.md): Apply promotions on carts and orders to discount items, shipping methods, or the entire order.
-
-***
-
-## How to Use the Promotion Module
-
-In your Medusa application, you build flows around Commerce Modules. A flow is built as a [Workflow](https://docs.medusajs.com/docs/learn/fundamentals/workflows/index.html.md), which is a special function composed of a series of steps that guarantees data consistency and reliable roll-back mechanism.
-
-You can build custom workflows and steps. You can also re-use Medusa's workflows and steps, which are provided by the `@medusajs/medusa/core-flows` package.
-
-For example:
-
-```ts title="src/workflows/create-promotion.ts" highlights={highlights}
-import {
- createWorkflow,
- WorkflowResponse,
- createStep,
- StepResponse,
-} from "@medusajs/framework/workflows-sdk"
-import { Modules } from "@medusajs/framework/utils"
-
-const createPromotionStep = createStep(
- "create-promotion",
- async ({}, { container }) => {
- const promotionModuleService = container.resolve(Modules.PROMOTION)
-
- const promotion = await promotionModuleService.createPromotions({
- code: "10%OFF",
- type: "standard",
- application_method: {
- type: "percentage",
- target_type: "order",
- value: 10,
- currency_code: "usd",
- },
- })
-
- return new StepResponse({ promotion }, promotion.id)
- },
- async (promotionId, { container }) => {
- if (!promotionId) {
- return
- }
- const promotionModuleService = container.resolve(Modules.PROMOTION)
-
- await promotionModuleService.deletePromotions(promotionId)
- }
-)
-
-export const createPromotionWorkflow = createWorkflow(
- "create-promotion",
- () => {
- const { promotion } = createPromotionStep()
-
- return new WorkflowResponse({
- promotion,
- })
- }
-)
-```
-
-You can then execute the workflow in your custom API routes, scheduled jobs, or subscribers:
-
-### API Route
-
-```ts title="src/api/workflow/route.ts" highlights={[["11"], ["12"]]} collapsibleLines="1-6" expandButtonLabel="Show Imports"
-import type {
- MedusaRequest,
- MedusaResponse,
-} from "@medusajs/framework/http"
-import { createPromotionWorkflow } from "../../workflows/create-cart"
-
-export async function GET(
- req: MedusaRequest,
- res: MedusaResponse
-) {
- const { result } = await createPromotionWorkflow(req.scope)
- .run()
-
- res.send(result)
-}
-```
-
-### Subscriber
-
-```ts title="src/subscribers/user-created.ts" highlights={[["11"], ["12"]]} collapsibleLines="1-6" expandButtonLabel="Show Imports"
-import {
- type SubscriberConfig,
- type SubscriberArgs,
-} from "@medusajs/framework"
-import { createPromotionWorkflow } from "../workflows/create-cart"
-
-export default async function handleUserCreated({
- event: { data },
- container,
-}: SubscriberArgs<{ id: string }>) {
- const { result } = await createPromotionWorkflow(container)
- .run()
-
- console.log(result)
-}
-
-export const config: SubscriberConfig = {
- event: "user.created",
-}
-```
-
-### Scheduled Job
-
-```ts title="src/jobs/run-daily.ts" highlights={[["7"], ["8"]]}
-import { MedusaContainer } from "@medusajs/framework/types"
-import { createPromotionWorkflow } from "../workflows/create-cart"
-
-export default async function myCustomJob(
- container: MedusaContainer
-) {
- const { result } = await createPromotionWorkflow(container)
- .run()
-
- console.log(result)
-}
-
-export const config = {
- name: "run-once-a-day",
- schedule: `0 0 * * *`,
-}
-```
-
-Learn more about workflows in [this documentation](https://docs.medusajs.com/docs/learn/fundamentals/workflows/index.html.md).
-
-***
-
-
-# Product Module
-
-In this section of the documentation, you will find resources to learn more about the Product Module and how to use it in your application.
-
-Refer to the [Medusa Admin User Guide](https://docs.medusajs.com/user-guide/products/index.html.md) to learn how to manage products using the dashboard.
-
-Medusa has product related features available out-of-the-box through the Product Module. A [module](https://docs.medusajs.com/docs/learn/fundamentals/modules/index.html.md) is a standalone package that provides features for a single domain. Each of Medusa's commerce features are placed in Commerce Modules, such as this Product Module.
-
-Learn more about why modules are isolated in [this documentation](https://docs.medusajs.com/docs/learn/fundamentals/modules/isolation/index.html.md).
-
-## Product Features
-
-- [Products Management](https://docs.medusajs.com/references/product/models/Product/index.html.md): Store and manage products. Products have custom options, such as color or size, and each variant in the product sets the value for these options.
-- [Product Organization](https://docs.medusajs.com/references/product/models/index.html.md): The Product Module provides different data models used to organize products, including categories, collections, tags, and more.
-- [Bundled and Multi-Part Products](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/inventory/inventory-kit/index.html.md): Create and manage inventory kits for a single product, allowing you to implement use cases like bundled or multi-part products.
-- [Tiered Pricing and Price Rules](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/pricing/price-rules/index.html.md): Set prices for product variants with tiers and rules, allowing you to create complex pricing strategies.
-
-***
-
-## How to Use the Product Module
-
-In your Medusa application, you build flows around Commerce Modules. A flow is built as a [Workflow](https://docs.medusajs.com/docs/learn/fundamentals/workflows/index.html.md), which is a special function composed of a series of steps that guarantees data consistency and reliable roll-back mechanism.
-
-You can build custom workflows and steps. You can also re-use Medusa's workflows and steps, which are provided by the `@medusajs/medusa/core-flows` package.
-
-For example:
-
-```ts title="src/workflows/create-product.ts" highlights={highlights}
-import {
- createWorkflow,
- WorkflowResponse,
- createStep,
- StepResponse,
-} from "@medusajs/framework/workflows-sdk"
-import { Modules } from "@medusajs/framework/utils"
-
-const createProductStep = createStep(
- "create-product",
- async ({}, { container }) => {
- const productService = container.resolve(Modules.PRODUCT)
-
- const product = await productService.createProducts({
- title: "Medusa Shirt",
- options: [
- {
- title: "Color",
- values: ["Black", "White"],
- },
- ],
- variants: [
- {
- title: "Black Shirt",
- options: {
- Color: "Black",
- },
- },
- ],
- })
-
- return new StepResponse({ product }, product.id)
- },
- async (productId, { container }) => {
- if (!productId) {
- return
- }
- const productService = container.resolve(Modules.PRODUCT)
-
- await productService.deleteProducts([productId])
- }
-)
-
-export const createProductWorkflow = createWorkflow(
- "create-product",
- () => {
- const { product } = createProductStep()
-
- return new WorkflowResponse({
- product,
- })
- }
-)
-```
-
-You can then execute the workflow in your custom API routes, scheduled jobs, or subscribers:
-
-### API Route
-
-```ts title="src/api/workflow/route.ts" highlights={[["11"], ["12"]]} collapsibleLines="1-6" expandButtonLabel="Show Imports"
-import type {
- MedusaRequest,
- MedusaResponse,
-} from "@medusajs/framework/http"
-import { createProductWorkflow } from "../../workflows/create-product"
-
-export async function GET(
- req: MedusaRequest,
- res: MedusaResponse
-) {
- const { result } = await createProductWorkflow(req.scope)
- .run()
-
- res.send(result)
-}
-```
-
-### Subscriber
-
-```ts title="src/subscribers/user-created.ts" highlights={[["11"], ["12"]]} collapsibleLines="1-6" expandButtonLabel="Show Imports"
-import {
- type SubscriberConfig,
- type SubscriberArgs,
-} from "@medusajs/framework"
-import { createProductWorkflow } from "../workflows/create-product"
-
-export default async function handleUserCreated({
- event: { data },
- container,
-}: SubscriberArgs<{ id: string }>) {
- const { result } = await createProductWorkflow(container)
- .run()
-
- console.log(result)
-}
-
-export const config: SubscriberConfig = {
- event: "user.created",
-}
-```
-
-### Scheduled Job
-
-```ts title="src/jobs/run-daily.ts" highlights={[["7"], ["8"]]}
-import { MedusaContainer } from "@medusajs/framework/types"
-import { createProductWorkflow } from "../workflows/create-product"
-
-export default async function myCustomJob(
- container: MedusaContainer
-) {
- const { result } = await createProductWorkflow(container)
- .run()
-
- console.log(result)
-}
-
-export const config = {
- name: "run-once-a-day",
- schedule: `0 0 * * *`,
-}
-```
-
-Learn more about workflows in [this documentation](https://docs.medusajs.com/docs/learn/fundamentals/workflows/index.html.md).
-
-***
-
-
# Order Module
In this section of the documentation, you will find resources to learn more about the Order Module and how to use it in your application.
@@ -20336,6 +20024,464 @@ Learn more about workflows in [this documentation](https://docs.medusajs.com/doc
***
+# Payment Module
+
+In this section of the documentation, you will find resources to learn more about the Payment Module and how to use it in your application.
+
+Refer to the [Medusa Admin User Guide](https://docs.medusajs.com/user-guide/orders/payments/index.html.md) to learn how to manage order payments using the dashboard.
+
+Medusa has payment related features available out-of-the-box through the Payment Module. A [module](https://docs.medusajs.com/docs/learn/fundamentals/modules/index.html.md) is a standalone package that provides features for a single domain. Each of Medusa's commerce features are placed in Commerce Modules, such as this Payment Module.
+
+Learn more about why modules are isolated in [this documentation](https://docs.medusajs.com/docs/learn/fundamentals/modules/isolation/index.html.md).
+
+## Payment Features
+
+- [Authorize, Capture, and Refund Payments](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/payment/payment/index.html.md): Authorize, capture, and refund payments for a single resource.
+- [Payment Collection Management](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/payment/payment-collection/index.html.md): Store and manage all payments of a single resources, such as a cart, in payment collections.
+- [Integrate Third-Party Payment Providers](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/payment/payment-provider/index.html.md): Use payment providers like [Stripe](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/payment/payment-provider/stripe/index.html.md) to handle and process payments, or integrate custom payment providers.
+- [Saved Payment Methods](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/payment/account-holder/index.html.md): Save payment methods for customers in third-party payment providers.
+- [Handle Webhook Events](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/payment/webhook-events/index.html.md): Handle webhook events from third-party providers and process the associated payment.
+
+***
+
+## How to Use the Payment Module
+
+In your Medusa application, you build flows around Commerce Modules. A flow is built as a [Workflow](https://docs.medusajs.com/docs/learn/fundamentals/workflows/index.html.md), which is a special function composed of a series of steps that guarantees data consistency and reliable roll-back mechanism.
+
+You can build custom workflows and steps. You can also re-use Medusa's workflows and steps, which are provided by the `@medusajs/medusa/core-flows` package.
+
+For example:
+
+```ts title="src/workflows/create-payment-collection.ts" highlights={highlights}
+import {
+ createWorkflow,
+ WorkflowResponse,
+ createStep,
+ StepResponse,
+} from "@medusajs/framework/workflows-sdk"
+import { Modules } from "@medusajs/framework/utils"
+
+const createPaymentCollectionStep = createStep(
+ "create-payment-collection",
+ async ({}, { container }) => {
+ const paymentModuleService = container.resolve(Modules.PAYMENT)
+
+ const paymentCollection = await paymentModuleService.createPaymentCollections({
+ currency_code: "usd",
+ amount: 5000,
+ })
+
+ return new StepResponse({ paymentCollection }, paymentCollection.id)
+ },
+ async (paymentCollectionId, { container }) => {
+ if (!paymentCollectionId) {
+ return
+ }
+ const paymentModuleService = container.resolve(Modules.PAYMENT)
+
+ await paymentModuleService.deletePaymentCollections([paymentCollectionId])
+ }
+)
+
+export const createPaymentCollectionWorkflow = createWorkflow(
+ "create-payment-collection",
+ () => {
+ const { paymentCollection } = createPaymentCollectionStep()
+
+ return new WorkflowResponse({
+ paymentCollection,
+ })
+ }
+)
+```
+
+You can then execute the workflow in your custom API routes, scheduled jobs, or subscribers:
+
+### API Route
+
+```ts title="src/api/workflow/route.ts" highlights={[["11"], ["12"]]} collapsibleLines="1-6" expandButtonLabel="Show Imports"
+import type {
+ MedusaRequest,
+ MedusaResponse,
+} from "@medusajs/framework/http"
+import { createPaymentCollectionWorkflow } from "../../workflows/create-payment-collection"
+
+export async function GET(
+ req: MedusaRequest,
+ res: MedusaResponse
+) {
+ const { result } = await createPaymentCollectionWorkflow(req.scope)
+ .run()
+
+ res.send(result)
+}
+```
+
+### Subscriber
+
+```ts title="src/subscribers/user-created.ts" highlights={[["11"], ["12"]]} collapsibleLines="1-6" expandButtonLabel="Show Imports"
+import {
+ type SubscriberConfig,
+ type SubscriberArgs,
+} from "@medusajs/framework"
+import { createPaymentCollectionWorkflow } from "../workflows/create-payment-collection"
+
+export default async function handleUserCreated({
+ event: { data },
+ container,
+}: SubscriberArgs<{ id: string }>) {
+ const { result } = await createPaymentCollectionWorkflow(container)
+ .run()
+
+ console.log(result)
+}
+
+export const config: SubscriberConfig = {
+ event: "user.created",
+}
+```
+
+### Scheduled Job
+
+```ts title="src/jobs/run-daily.ts" highlights={[["7"], ["8"]]}
+import { MedusaContainer } from "@medusajs/framework/types"
+import { createPaymentCollectionWorkflow } from "../workflows/create-payment-collection"
+
+export default async function myCustomJob(
+ container: MedusaContainer
+) {
+ const { result } = await createPaymentCollectionWorkflow(container)
+ .run()
+
+ console.log(result)
+}
+
+export const config = {
+ name: "run-once-a-day",
+ schedule: `0 0 * * *`,
+}
+```
+
+Learn more about workflows in [this documentation](https://docs.medusajs.com/docs/learn/fundamentals/workflows/index.html.md).
+
+***
+
+## Configure Payment Module
+
+The Payment Module accepts options for further configurations. Refer to [this documentation](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/payment/module-options/index.html.md) for details on the module's options.
+
+***
+
+## Providers
+
+Medusa provides the following payment providers out-of-the-box. You can use them to process payments for orders, returns, and other resources.
+
+***
+
+
+# Product Module
+
+In this section of the documentation, you will find resources to learn more about the Product Module and how to use it in your application.
+
+Refer to the [Medusa Admin User Guide](https://docs.medusajs.com/user-guide/products/index.html.md) to learn how to manage products using the dashboard.
+
+Medusa has product related features available out-of-the-box through the Product Module. A [module](https://docs.medusajs.com/docs/learn/fundamentals/modules/index.html.md) is a standalone package that provides features for a single domain. Each of Medusa's commerce features are placed in Commerce Modules, such as this Product Module.
+
+Learn more about why modules are isolated in [this documentation](https://docs.medusajs.com/docs/learn/fundamentals/modules/isolation/index.html.md).
+
+## Product Features
+
+- [Products Management](https://docs.medusajs.com/references/product/models/Product/index.html.md): Store and manage products. Products have custom options, such as color or size, and each variant in the product sets the value for these options.
+- [Product Organization](https://docs.medusajs.com/references/product/models/index.html.md): The Product Module provides different data models used to organize products, including categories, collections, tags, and more.
+- [Bundled and Multi-Part Products](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/inventory/inventory-kit/index.html.md): Create and manage inventory kits for a single product, allowing you to implement use cases like bundled or multi-part products.
+- [Tiered Pricing and Price Rules](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/pricing/price-rules/index.html.md): Set prices for product variants with tiers and rules, allowing you to create complex pricing strategies.
+
+***
+
+## How to Use the Product Module
+
+In your Medusa application, you build flows around Commerce Modules. A flow is built as a [Workflow](https://docs.medusajs.com/docs/learn/fundamentals/workflows/index.html.md), which is a special function composed of a series of steps that guarantees data consistency and reliable roll-back mechanism.
+
+You can build custom workflows and steps. You can also re-use Medusa's workflows and steps, which are provided by the `@medusajs/medusa/core-flows` package.
+
+For example:
+
+```ts title="src/workflows/create-product.ts" highlights={highlights}
+import {
+ createWorkflow,
+ WorkflowResponse,
+ createStep,
+ StepResponse,
+} from "@medusajs/framework/workflows-sdk"
+import { Modules } from "@medusajs/framework/utils"
+
+const createProductStep = createStep(
+ "create-product",
+ async ({}, { container }) => {
+ const productService = container.resolve(Modules.PRODUCT)
+
+ const product = await productService.createProducts({
+ title: "Medusa Shirt",
+ options: [
+ {
+ title: "Color",
+ values: ["Black", "White"],
+ },
+ ],
+ variants: [
+ {
+ title: "Black Shirt",
+ options: {
+ Color: "Black",
+ },
+ },
+ ],
+ })
+
+ return new StepResponse({ product }, product.id)
+ },
+ async (productId, { container }) => {
+ if (!productId) {
+ return
+ }
+ const productService = container.resolve(Modules.PRODUCT)
+
+ await productService.deleteProducts([productId])
+ }
+)
+
+export const createProductWorkflow = createWorkflow(
+ "create-product",
+ () => {
+ const { product } = createProductStep()
+
+ return new WorkflowResponse({
+ product,
+ })
+ }
+)
+```
+
+You can then execute the workflow in your custom API routes, scheduled jobs, or subscribers:
+
+### API Route
+
+```ts title="src/api/workflow/route.ts" highlights={[["11"], ["12"]]} collapsibleLines="1-6" expandButtonLabel="Show Imports"
+import type {
+ MedusaRequest,
+ MedusaResponse,
+} from "@medusajs/framework/http"
+import { createProductWorkflow } from "../../workflows/create-product"
+
+export async function GET(
+ req: MedusaRequest,
+ res: MedusaResponse
+) {
+ const { result } = await createProductWorkflow(req.scope)
+ .run()
+
+ res.send(result)
+}
+```
+
+### Subscriber
+
+```ts title="src/subscribers/user-created.ts" highlights={[["11"], ["12"]]} collapsibleLines="1-6" expandButtonLabel="Show Imports"
+import {
+ type SubscriberConfig,
+ type SubscriberArgs,
+} from "@medusajs/framework"
+import { createProductWorkflow } from "../workflows/create-product"
+
+export default async function handleUserCreated({
+ event: { data },
+ container,
+}: SubscriberArgs<{ id: string }>) {
+ const { result } = await createProductWorkflow(container)
+ .run()
+
+ console.log(result)
+}
+
+export const config: SubscriberConfig = {
+ event: "user.created",
+}
+```
+
+### Scheduled Job
+
+```ts title="src/jobs/run-daily.ts" highlights={[["7"], ["8"]]}
+import { MedusaContainer } from "@medusajs/framework/types"
+import { createProductWorkflow } from "../workflows/create-product"
+
+export default async function myCustomJob(
+ container: MedusaContainer
+) {
+ const { result } = await createProductWorkflow(container)
+ .run()
+
+ console.log(result)
+}
+
+export const config = {
+ name: "run-once-a-day",
+ schedule: `0 0 * * *`,
+}
+```
+
+Learn more about workflows in [this documentation](https://docs.medusajs.com/docs/learn/fundamentals/workflows/index.html.md).
+
+***
+
+
+# Promotion Module
+
+In this section of the documentation, you will find resources to learn more about the Promotion Module and how to use it in your application.
+
+Refer to the [Medusa Admin User Guide](https://docs.medusajs.com/user-guide/promotions/index.html.md) to learn how to manage promotions using the dashboard.
+
+Medusa has promotion related features available out-of-the-box through the Promotion Module. A [module](https://docs.medusajs.com/docs/learn/fundamentals/modules/index.html.md) is a standalone package that provides features for a single domain. Each of Medusa's commerce features are placed in Commerce Modules, such as this Promotion Module.
+
+Learn more about why modules are isolated in [this documentation](https://docs.medusajs.com/docs/learn/fundamentals/modules/isolation/index.html.md).
+
+## Promotion Features
+
+- [Discount Functionalities](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/promotion/concepts/index.html.md): A promotion discounts an amount or percentage of a cart's items, shipping methods, or the entire order.
+- [Flexible Promotion Rules](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/promotion/concepts#flexible-rules/index.html.md): A promotion has rules that restricts when the promotion is applied.
+- [Campaign Management](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/promotion/campaign/index.html.md): A campaign combines promotions under the same conditions, such as start and end dates, and budget configurations.
+- [Apply Promotion on Carts and Orders](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/promotion/actions/index.html.md): Apply promotions on carts and orders to discount items, shipping methods, or the entire order.
+
+***
+
+## How to Use the Promotion Module
+
+In your Medusa application, you build flows around Commerce Modules. A flow is built as a [Workflow](https://docs.medusajs.com/docs/learn/fundamentals/workflows/index.html.md), which is a special function composed of a series of steps that guarantees data consistency and reliable roll-back mechanism.
+
+You can build custom workflows and steps. You can also re-use Medusa's workflows and steps, which are provided by the `@medusajs/medusa/core-flows` package.
+
+For example:
+
+```ts title="src/workflows/create-promotion.ts" highlights={highlights}
+import {
+ createWorkflow,
+ WorkflowResponse,
+ createStep,
+ StepResponse,
+} from "@medusajs/framework/workflows-sdk"
+import { Modules } from "@medusajs/framework/utils"
+
+const createPromotionStep = createStep(
+ "create-promotion",
+ async ({}, { container }) => {
+ const promotionModuleService = container.resolve(Modules.PROMOTION)
+
+ const promotion = await promotionModuleService.createPromotions({
+ code: "10%OFF",
+ type: "standard",
+ application_method: {
+ type: "percentage",
+ target_type: "order",
+ value: 10,
+ currency_code: "usd",
+ },
+ })
+
+ return new StepResponse({ promotion }, promotion.id)
+ },
+ async (promotionId, { container }) => {
+ if (!promotionId) {
+ return
+ }
+ const promotionModuleService = container.resolve(Modules.PROMOTION)
+
+ await promotionModuleService.deletePromotions(promotionId)
+ }
+)
+
+export const createPromotionWorkflow = createWorkflow(
+ "create-promotion",
+ () => {
+ const { promotion } = createPromotionStep()
+
+ return new WorkflowResponse({
+ promotion,
+ })
+ }
+)
+```
+
+You can then execute the workflow in your custom API routes, scheduled jobs, or subscribers:
+
+### API Route
+
+```ts title="src/api/workflow/route.ts" highlights={[["11"], ["12"]]} collapsibleLines="1-6" expandButtonLabel="Show Imports"
+import type {
+ MedusaRequest,
+ MedusaResponse,
+} from "@medusajs/framework/http"
+import { createPromotionWorkflow } from "../../workflows/create-cart"
+
+export async function GET(
+ req: MedusaRequest,
+ res: MedusaResponse
+) {
+ const { result } = await createPromotionWorkflow(req.scope)
+ .run()
+
+ res.send(result)
+}
+```
+
+### Subscriber
+
+```ts title="src/subscribers/user-created.ts" highlights={[["11"], ["12"]]} collapsibleLines="1-6" expandButtonLabel="Show Imports"
+import {
+ type SubscriberConfig,
+ type SubscriberArgs,
+} from "@medusajs/framework"
+import { createPromotionWorkflow } from "../workflows/create-cart"
+
+export default async function handleUserCreated({
+ event: { data },
+ container,
+}: SubscriberArgs<{ id: string }>) {
+ const { result } = await createPromotionWorkflow(container)
+ .run()
+
+ console.log(result)
+}
+
+export const config: SubscriberConfig = {
+ event: "user.created",
+}
+```
+
+### Scheduled Job
+
+```ts title="src/jobs/run-daily.ts" highlights={[["7"], ["8"]]}
+import { MedusaContainer } from "@medusajs/framework/types"
+import { createPromotionWorkflow } from "../workflows/create-cart"
+
+export default async function myCustomJob(
+ container: MedusaContainer
+) {
+ const { result } = await createPromotionWorkflow(container)
+ .run()
+
+ console.log(result)
+}
+
+export const config = {
+ name: "run-once-a-day",
+ schedule: `0 0 * * *`,
+}
+```
+
+Learn more about workflows in [this documentation](https://docs.medusajs.com/docs/learn/fundamentals/workflows/index.html.md).
+
+***
+
+
# Region Module
In this section of the documentation, you will find resources to learn more about the Region Module and how to use it in your application.
@@ -20479,428 +20625,6 @@ Learn more about workflows in [this documentation](https://docs.medusajs.com/doc
***
-# Store Module
-
-In this section of the documentation, you will find resources to learn more about the Store Module and how to use it in your application.
-
-Refer to the [Medusa Admin User Guide](https://docs.medusajs.com/user-guide/settings/store/index.html.md) to learn how to manage your store using the dashboard.
-
-Medusa has store related features available out-of-the-box through the Store Module. A [module](https://docs.medusajs.com/docs/learn/fundamentals/modules/index.html.md) is a standalone package that provides features for a single domain. Each of Medusa's commerce features are placed in Commerce Modules, such as this Store Module.
-
-Learn more about why modules are isolated in [this documentation](https://docs.medusajs.com/docs/learn/fundamentals/modules/isolation/index.html.md).
-
-## Store Features
-
-- [Store Management](https://docs.medusajs.com/references/store/models/Store/index.html.md): Create and manage stores in your application.
-- [Multi-Tenancy Support](https://docs.medusajs.com/references/store/models/Store/index.html.md): Create multiple stores, each having its own configurations.
-
-***
-
-## How to Use Store Module's Service
-
-In your Medusa application, you build flows around Commerce Modules. A flow is built as a [Workflow](https://docs.medusajs.com/docs/learn/fundamentals/workflows/index.html.md), which is a special function composed of a series of steps that guarantees data consistency and reliable roll-back mechanism.
-
-You can build custom workflows and steps. You can also re-use Medusa's workflows and steps, which are provided by the `@medusajs/medusa/core-flows` package.
-
-For example:
-
-```ts title="src/workflows/create-store.ts" highlights={highlights}
-import {
- createWorkflow,
- WorkflowResponse,
- createStep,
- StepResponse,
-} from "@medusajs/framework/workflows-sdk"
-import { Modules } from "@medusajs/framework/utils"
-
-const createStoreStep = createStep(
- "create-store",
- async ({}, { container }) => {
- const storeModuleService = container.resolve(Modules.STORE)
-
- const store = await storeModuleService.createStores({
- name: "My Store",
- supported_currencies: [{
- currency_code: "usd",
- is_default: true,
- }],
- })
-
- return new StepResponse({ store }, store.id)
- },
- async (storeId, { container }) => {
- if(!storeId) {
- return
- }
- const storeModuleService = container.resolve(Modules.STORE)
-
- await storeModuleService.deleteStores([storeId])
- }
-)
-
-export const createStoreWorkflow = createWorkflow(
- "create-store",
- () => {
- const { store } = createStoreStep()
-
- return new WorkflowResponse({ store })
- }
-)
-```
-
-You can then execute the workflow in your custom API routes, scheduled jobs, or subscribers:
-
-### API Route
-
-```ts title="src/api/workflow/route.ts" highlights={[["11"], ["12"]]} collapsibleLines="1-6" expandButtonLabel="Show Imports"
-import type {
- MedusaRequest,
- MedusaResponse,
-} from "@medusajs/framework/http"
-import { createStoreWorkflow } from "../../workflows/create-store"
-
-export async function GET(
- req: MedusaRequest,
- res: MedusaResponse
-) {
- const { result } = await createStoreWorkflow(req.scope)
- .run()
-
- res.send(result)
-}
-```
-
-### Subscriber
-
-```ts title="src/subscribers/user-created.ts" highlights={[["11"], ["12"]]} collapsibleLines="1-6" expandButtonLabel="Show Imports"
-import {
- type SubscriberConfig,
- type SubscriberArgs,
-} from "@medusajs/framework"
-import { createStoreWorkflow } from "../workflows/create-store"
-
-export default async function handleUserCreated({
- event: { data },
- container,
-}: SubscriberArgs<{ id: string }>) {
- const { result } = await createStoreWorkflow(container)
- .run()
-
- console.log(result)
-}
-
-export const config: SubscriberConfig = {
- event: "user.created",
-}
-```
-
-### Scheduled Job
-
-```ts title="src/jobs/run-daily.ts" highlights={[["7"], ["8"]]}
-import { MedusaContainer } from "@medusajs/framework/types"
-import { createStoreWorkflow } from "../workflows/create-store"
-
-export default async function myCustomJob(
- container: MedusaContainer
-) {
- const { result } = await createStoreWorkflow(container)
- .run()
-
- console.log(result)
-}
-
-export const config = {
- name: "run-once-a-day",
- schedule: `0 0 * * *`,
-}
-```
-
-Learn more about workflows in [this documentation](https://docs.medusajs.com/docs/learn/fundamentals/workflows/index.html.md).
-
-***
-
-
-# Tax Module
-
-In this section of the documentation, you will find resources to learn more about the Tax Module and how to use it in your application.
-
-Refer to the [Medusa Admin User Guide](https://docs.medusajs.com/user-guide/settings/tax-regions/index.html.md) to learn how to manage tax regions using the dashboard.
-
-Medusa has tax related features available out-of-the-box through the Tax Module. A [module](https://docs.medusajs.com/docs/learn/fundamentals/modules/index.html.md) is a standalone package that provides features for a single domain. Each of Medusa's commerce features are placed in Commerce Modules, such as this Tax Module.
-
-Learn more about why modules are isolated in [this documentation](https://docs.medusajs.com/docs/learn/fundamentals/modules/isolation/index.html.md).
-
-## Tax Features
-
-- [Tax Settings Per Region](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/tax/tax-region/index.html.md): Set different tax settings for each tax region.
-- [Tax Rates and Rules](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/tax/tax-rates-and-rules/index.html.md): Manage each region's default tax rates and override them with conditioned tax rates.
-- [Retrieve Tax Lines for carts and orders](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/tax/tax-calculation-with-provider/index.html.md): Calculate and retrieve the tax lines of a cart or order's line items and shipping methods with tax providers.
-
-***
-
-## How to Use Tax Module's Service
-
-In your Medusa application, you build flows around Commerce Modules. A flow is built as a [Workflow](https://docs.medusajs.com/docs/learn/fundamentals/workflows/index.html.md), which is a special function composed of a series of steps that guarantees data consistency and reliable roll-back mechanism.
-
-You can build custom workflows and steps. You can also re-use Medusa's workflows and steps, which are provided by the `@medusajs/medusa/core-flows` package.
-
-For example:
-
-```ts title="src/workflows/create-tax-region.ts" highlights={highlights}
-import {
- createWorkflow,
- WorkflowResponse,
- createStep,
- StepResponse,
-} from "@medusajs/framework/workflows-sdk"
-import { Modules } from "@medusajs/framework/utils"
-
-const createTaxRegionStep = createStep(
- "create-tax-region",
- async ({}, { container }) => {
- const taxModuleService = container.resolve(Modules.TAX)
-
- const taxRegion = await taxModuleService.createTaxRegions({
- country_code: "us",
- })
-
- return new StepResponse({ taxRegion }, taxRegion.id)
- },
- async (taxRegionId, { container }) => {
- if (!taxRegionId) {
- return
- }
- const taxModuleService = container.resolve(Modules.TAX)
-
- await taxModuleService.deleteTaxRegions([taxRegionId])
- }
-)
-
-export const createTaxRegionWorkflow = createWorkflow(
- "create-tax-region",
- () => {
- const { taxRegion } = createTaxRegionStep()
-
- return new WorkflowResponse({ taxRegion })
- }
-)
-```
-
-You can then execute the workflow in your custom API routes, scheduled jobs, or subscribers:
-
-### API Route
-
-```ts title="src/api/workflow/route.ts" highlights={[["11"], ["12"]]} collapsibleLines="1-6" expandButtonLabel="Show Imports"
-import type {
- MedusaRequest,
- MedusaResponse,
-} from "@medusajs/framework/http"
-import { createTaxRegionWorkflow } from "../../workflows/create-tax-region"
-
-export async function GET(
- req: MedusaRequest,
- res: MedusaResponse
-) {
- const { result } = await createTaxRegionWorkflow(req.scope)
- .run()
-
- res.send(result)
-}
-```
-
-### Subscriber
-
-```ts title="src/subscribers/user-created.ts" highlights={[["11"], ["12"]]} collapsibleLines="1-6" expandButtonLabel="Show Imports"
-import {
- type SubscriberConfig,
- type SubscriberArgs,
-} from "@medusajs/framework"
-import { createTaxRegionWorkflow } from "../workflows/create-tax-region"
-
-export default async function handleUserCreated({
- event: { data },
- container,
-}: SubscriberArgs<{ id: string }>) {
- const { result } = await createTaxRegionWorkflow(container)
- .run()
-
- console.log(result)
-}
-
-export const config: SubscriberConfig = {
- event: "user.created",
-}
-```
-
-### Scheduled Job
-
-```ts title="src/jobs/run-daily.ts" highlights={[["7"], ["8"]]}
-import { MedusaContainer } from "@medusajs/framework/types"
-import { createTaxRegionWorkflow } from "../workflows/create-tax-region"
-
-export default async function myCustomJob(
- container: MedusaContainer
-) {
- const { result } = await createTaxRegionWorkflow(container)
- .run()
-
- console.log(result)
-}
-
-export const config = {
- name: "run-once-a-day",
- schedule: `0 0 * * *`,
-}
-```
-
-Learn more about workflows in [this documentation](https://docs.medusajs.com/docs/learn/fundamentals/workflows/index.html.md).
-
-***
-
-## Configure Tax Module
-
-The Tax Module accepts options for further configurations. Refer to [this documentation](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/tax/module-options/index.html.md) for details on the module's options.
-
-***
-
-
-# Stock Location Module
-
-In this section of the documentation, you will find resources to learn more about the Stock Location Module and how to use it in your application.
-
-Refer to the [Medusa Admin User Guide](https://docs.medusajs.com/user-guide/settings/locations-and-shipping/index.html.md) to learn how to manage stock locations using the dashboard.
-
-Medusa has stock location related features available out-of-the-box through the Stock Location Module. A [module](https://docs.medusajs.com/docs/learn/fundamentals/modules/index.html.md) is a standalone package that provides features for a single domain. Each of Medusa's commerce features are placed in Commerce Modules, such as this Stock Location Module.
-
-Learn more about why modules are isolated in [this documentation](https://docs.medusajs.com/docs/learn/fundamentals/modules/isolation/index.html.md).
-
-## Stock Location Features
-
-- [Stock Location Management](https://docs.medusajs.com/references/stock-location-next/models/index.html.md): Store and manage stock locations. Medusa links stock locations with data models of other modules that require a location, such as the [Inventory Module's InventoryLevel](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/stock-location/links-to-other-modules/index.html.md).
-- [Address Management](https://docs.medusajs.com/references/stock-location-next/models/StockLocationAddress/index.html.md): Manage the address of each stock location.
-
-***
-
-## How to Use Stock Location Module's Service
-
-In your Medusa application, you build flows around Commerce Modules. A flow is built as a [Workflow](https://docs.medusajs.com/docs/learn/fundamentals/workflows/index.html.md), which is a special function composed of a series of steps that guarantees data consistency and reliable roll-back mechanism.
-
-You can build custom workflows and steps. You can also re-use Medusa's workflows and steps, which are provided by the `@medusajs/medusa/core-flows` package.
-
-For example:
-
-```ts title="src/workflows/create-stock-location.ts" highlights={highlights}
-import {
- createWorkflow,
- WorkflowResponse,
- createStep,
- StepResponse,
-} from "@medusajs/framework/workflows-sdk"
-import { Modules } from "@medusajs/framework/utils"
-
-const createStockLocationStep = createStep(
- "create-stock-location",
- async ({}, { container }) => {
- const stockLocationModuleService = container.resolve(Modules.STOCK_LOCATION)
-
- const stockLocation = await stockLocationModuleService.createStockLocations({
- name: "Warehouse 1",
- })
-
- return new StepResponse({ stockLocation }, stockLocation.id)
- },
- async (stockLocationId, { container }) => {
- if (!stockLocationId) {
- return
- }
- const stockLocationModuleService = container.resolve(Modules.STOCK_LOCATION)
-
- await stockLocationModuleService.deleteStockLocations([stockLocationId])
- }
-)
-
-export const createStockLocationWorkflow = createWorkflow(
- "create-stock-location",
- () => {
- const { stockLocation } = createStockLocationStep()
-
- return new WorkflowResponse({ stockLocation })
- }
-)
-```
-
-You can then execute the workflow in your custom API routes, scheduled jobs, or subscribers:
-
-### API Route
-
-```ts title="src/api/workflow/route.ts" highlights={[["11"], ["12"]]} collapsibleLines="1-6" expandButtonLabel="Show Imports"
-import type {
- MedusaRequest,
- MedusaResponse,
-} from "@medusajs/framework/http"
-import { createStockLocationWorkflow } from "../../workflows/create-stock-location"
-
-export async function GET(
- req: MedusaRequest,
- res: MedusaResponse
-) {
- const { result } = await createStockLocationWorkflow(req.scope)
- .run()
-
- res.send(result)
-}
-```
-
-### Subscriber
-
-```ts title="src/subscribers/user-created.ts" highlights={[["11"], ["12"]]} collapsibleLines="1-6" expandButtonLabel="Show Imports"
-import {
- type SubscriberConfig,
- type SubscriberArgs,
-} from "@medusajs/framework"
-import { createStockLocationWorkflow } from "../workflows/create-stock-location"
-
-export default async function handleUserCreated({
- event: { data },
- container,
-}: SubscriberArgs<{ id: string }>) {
- const { result } = await createStockLocationWorkflow(container)
- .run()
-
- console.log(result)
-}
-
-export const config: SubscriberConfig = {
- event: "user.created",
-}
-```
-
-### Scheduled Job
-
-```ts title="src/jobs/run-daily.ts" highlights={[["7"], ["8"]]}
-import { MedusaContainer } from "@medusajs/framework/types"
-import { createStockLocationWorkflow } from "../workflows/create-stock-location"
-
-export default async function myCustomJob(
- container: MedusaContainer
-) {
- const { result } = await createStockLocationWorkflow(container)
- .run()
-
- console.log(result)
-}
-
-export const config = {
- name: "run-once-a-day",
- schedule: `0 0 * * *`,
-}
-```
-
-Learn more about workflows in [this documentation](https://docs.medusajs.com/docs/learn/fundamentals/workflows/index.html.md).
-
-***
-
-
# Sales Channel Module
In this section of the documentation, you will find resources to learn more about the Sales Channel Module and how to use it in your application.
@@ -21061,6 +20785,143 @@ Learn more about workflows in [this documentation](https://docs.medusajs.com/doc
***
+# Stock Location Module
+
+In this section of the documentation, you will find resources to learn more about the Stock Location Module and how to use it in your application.
+
+Refer to the [Medusa Admin User Guide](https://docs.medusajs.com/user-guide/settings/locations-and-shipping/index.html.md) to learn how to manage stock locations using the dashboard.
+
+Medusa has stock location related features available out-of-the-box through the Stock Location Module. A [module](https://docs.medusajs.com/docs/learn/fundamentals/modules/index.html.md) is a standalone package that provides features for a single domain. Each of Medusa's commerce features are placed in Commerce Modules, such as this Stock Location Module.
+
+Learn more about why modules are isolated in [this documentation](https://docs.medusajs.com/docs/learn/fundamentals/modules/isolation/index.html.md).
+
+## Stock Location Features
+
+- [Stock Location Management](https://docs.medusajs.com/references/stock-location-next/models/index.html.md): Store and manage stock locations. Medusa links stock locations with data models of other modules that require a location, such as the [Inventory Module's InventoryLevel](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/stock-location/links-to-other-modules/index.html.md).
+- [Address Management](https://docs.medusajs.com/references/stock-location-next/models/StockLocationAddress/index.html.md): Manage the address of each stock location.
+
+***
+
+## How to Use Stock Location Module's Service
+
+In your Medusa application, you build flows around Commerce Modules. A flow is built as a [Workflow](https://docs.medusajs.com/docs/learn/fundamentals/workflows/index.html.md), which is a special function composed of a series of steps that guarantees data consistency and reliable roll-back mechanism.
+
+You can build custom workflows and steps. You can also re-use Medusa's workflows and steps, which are provided by the `@medusajs/medusa/core-flows` package.
+
+For example:
+
+```ts title="src/workflows/create-stock-location.ts" highlights={highlights}
+import {
+ createWorkflow,
+ WorkflowResponse,
+ createStep,
+ StepResponse,
+} from "@medusajs/framework/workflows-sdk"
+import { Modules } from "@medusajs/framework/utils"
+
+const createStockLocationStep = createStep(
+ "create-stock-location",
+ async ({}, { container }) => {
+ const stockLocationModuleService = container.resolve(Modules.STOCK_LOCATION)
+
+ const stockLocation = await stockLocationModuleService.createStockLocations({
+ name: "Warehouse 1",
+ })
+
+ return new StepResponse({ stockLocation }, stockLocation.id)
+ },
+ async (stockLocationId, { container }) => {
+ if (!stockLocationId) {
+ return
+ }
+ const stockLocationModuleService = container.resolve(Modules.STOCK_LOCATION)
+
+ await stockLocationModuleService.deleteStockLocations([stockLocationId])
+ }
+)
+
+export const createStockLocationWorkflow = createWorkflow(
+ "create-stock-location",
+ () => {
+ const { stockLocation } = createStockLocationStep()
+
+ return new WorkflowResponse({ stockLocation })
+ }
+)
+```
+
+You can then execute the workflow in your custom API routes, scheduled jobs, or subscribers:
+
+### API Route
+
+```ts title="src/api/workflow/route.ts" highlights={[["11"], ["12"]]} collapsibleLines="1-6" expandButtonLabel="Show Imports"
+import type {
+ MedusaRequest,
+ MedusaResponse,
+} from "@medusajs/framework/http"
+import { createStockLocationWorkflow } from "../../workflows/create-stock-location"
+
+export async function GET(
+ req: MedusaRequest,
+ res: MedusaResponse
+) {
+ const { result } = await createStockLocationWorkflow(req.scope)
+ .run()
+
+ res.send(result)
+}
+```
+
+### Subscriber
+
+```ts title="src/subscribers/user-created.ts" highlights={[["11"], ["12"]]} collapsibleLines="1-6" expandButtonLabel="Show Imports"
+import {
+ type SubscriberConfig,
+ type SubscriberArgs,
+} from "@medusajs/framework"
+import { createStockLocationWorkflow } from "../workflows/create-stock-location"
+
+export default async function handleUserCreated({
+ event: { data },
+ container,
+}: SubscriberArgs<{ id: string }>) {
+ const { result } = await createStockLocationWorkflow(container)
+ .run()
+
+ console.log(result)
+}
+
+export const config: SubscriberConfig = {
+ event: "user.created",
+}
+```
+
+### Scheduled Job
+
+```ts title="src/jobs/run-daily.ts" highlights={[["7"], ["8"]]}
+import { MedusaContainer } from "@medusajs/framework/types"
+import { createStockLocationWorkflow } from "../workflows/create-stock-location"
+
+export default async function myCustomJob(
+ container: MedusaContainer
+) {
+ const { result } = await createStockLocationWorkflow(container)
+ .run()
+
+ console.log(result)
+}
+
+export const config = {
+ name: "run-once-a-day",
+ schedule: `0 0 * * *`,
+}
+```
+
+Learn more about workflows in [this documentation](https://docs.medusajs.com/docs/learn/fundamentals/workflows/index.html.md).
+
+***
+
+
# User Module
In this section of the documentation, you will find resources to learn more about the User Module and how to use it in your application.
@@ -21208,6 +21069,1533 @@ The User Module accepts options for further configurations. Refer to [this docum
***
+# Tax Module
+
+In this section of the documentation, you will find resources to learn more about the Tax Module and how to use it in your application.
+
+Refer to the [Medusa Admin User Guide](https://docs.medusajs.com/user-guide/settings/tax-regions/index.html.md) to learn how to manage tax regions using the dashboard.
+
+Medusa has tax related features available out-of-the-box through the Tax Module. A [module](https://docs.medusajs.com/docs/learn/fundamentals/modules/index.html.md) is a standalone package that provides features for a single domain. Each of Medusa's commerce features are placed in Commerce Modules, such as this Tax Module.
+
+Learn more about why modules are isolated in [this documentation](https://docs.medusajs.com/docs/learn/fundamentals/modules/isolation/index.html.md).
+
+## Tax Features
+
+- [Tax Settings Per Region](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/tax/tax-region/index.html.md): Set different tax settings for each tax region.
+- [Tax Rates and Rules](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/tax/tax-rates-and-rules/index.html.md): Manage each region's default tax rates and override them with conditioned tax rates.
+- [Retrieve Tax Lines for carts and orders](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/tax/tax-calculation-with-provider/index.html.md): Calculate and retrieve the tax lines of a cart or order's line items and shipping methods with tax providers.
+
+***
+
+## How to Use Tax Module's Service
+
+In your Medusa application, you build flows around Commerce Modules. A flow is built as a [Workflow](https://docs.medusajs.com/docs/learn/fundamentals/workflows/index.html.md), which is a special function composed of a series of steps that guarantees data consistency and reliable roll-back mechanism.
+
+You can build custom workflows and steps. You can also re-use Medusa's workflows and steps, which are provided by the `@medusajs/medusa/core-flows` package.
+
+For example:
+
+```ts title="src/workflows/create-tax-region.ts" highlights={highlights}
+import {
+ createWorkflow,
+ WorkflowResponse,
+ createStep,
+ StepResponse,
+} from "@medusajs/framework/workflows-sdk"
+import { Modules } from "@medusajs/framework/utils"
+
+const createTaxRegionStep = createStep(
+ "create-tax-region",
+ async ({}, { container }) => {
+ const taxModuleService = container.resolve(Modules.TAX)
+
+ const taxRegion = await taxModuleService.createTaxRegions({
+ country_code: "us",
+ })
+
+ return new StepResponse({ taxRegion }, taxRegion.id)
+ },
+ async (taxRegionId, { container }) => {
+ if (!taxRegionId) {
+ return
+ }
+ const taxModuleService = container.resolve(Modules.TAX)
+
+ await taxModuleService.deleteTaxRegions([taxRegionId])
+ }
+)
+
+export const createTaxRegionWorkflow = createWorkflow(
+ "create-tax-region",
+ () => {
+ const { taxRegion } = createTaxRegionStep()
+
+ return new WorkflowResponse({ taxRegion })
+ }
+)
+```
+
+You can then execute the workflow in your custom API routes, scheduled jobs, or subscribers:
+
+### API Route
+
+```ts title="src/api/workflow/route.ts" highlights={[["11"], ["12"]]} collapsibleLines="1-6" expandButtonLabel="Show Imports"
+import type {
+ MedusaRequest,
+ MedusaResponse,
+} from "@medusajs/framework/http"
+import { createTaxRegionWorkflow } from "../../workflows/create-tax-region"
+
+export async function GET(
+ req: MedusaRequest,
+ res: MedusaResponse
+) {
+ const { result } = await createTaxRegionWorkflow(req.scope)
+ .run()
+
+ res.send(result)
+}
+```
+
+### Subscriber
+
+```ts title="src/subscribers/user-created.ts" highlights={[["11"], ["12"]]} collapsibleLines="1-6" expandButtonLabel="Show Imports"
+import {
+ type SubscriberConfig,
+ type SubscriberArgs,
+} from "@medusajs/framework"
+import { createTaxRegionWorkflow } from "../workflows/create-tax-region"
+
+export default async function handleUserCreated({
+ event: { data },
+ container,
+}: SubscriberArgs<{ id: string }>) {
+ const { result } = await createTaxRegionWorkflow(container)
+ .run()
+
+ console.log(result)
+}
+
+export const config: SubscriberConfig = {
+ event: "user.created",
+}
+```
+
+### Scheduled Job
+
+```ts title="src/jobs/run-daily.ts" highlights={[["7"], ["8"]]}
+import { MedusaContainer } from "@medusajs/framework/types"
+import { createTaxRegionWorkflow } from "../workflows/create-tax-region"
+
+export default async function myCustomJob(
+ container: MedusaContainer
+) {
+ const { result } = await createTaxRegionWorkflow(container)
+ .run()
+
+ console.log(result)
+}
+
+export const config = {
+ name: "run-once-a-day",
+ schedule: `0 0 * * *`,
+}
+```
+
+Learn more about workflows in [this documentation](https://docs.medusajs.com/docs/learn/fundamentals/workflows/index.html.md).
+
+***
+
+## Configure Tax Module
+
+The Tax Module accepts options for further configurations. Refer to [this documentation](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/tax/module-options/index.html.md) for details on the module's options.
+
+***
+
+
+# Store Module
+
+In this section of the documentation, you will find resources to learn more about the Store Module and how to use it in your application.
+
+Refer to the [Medusa Admin User Guide](https://docs.medusajs.com/user-guide/settings/store/index.html.md) to learn how to manage your store using the dashboard.
+
+Medusa has store related features available out-of-the-box through the Store Module. A [module](https://docs.medusajs.com/docs/learn/fundamentals/modules/index.html.md) is a standalone package that provides features for a single domain. Each of Medusa's commerce features are placed in Commerce Modules, such as this Store Module.
+
+Learn more about why modules are isolated in [this documentation](https://docs.medusajs.com/docs/learn/fundamentals/modules/isolation/index.html.md).
+
+## Store Features
+
+- [Store Management](https://docs.medusajs.com/references/store/models/Store/index.html.md): Create and manage stores in your application.
+- [Multi-Tenancy Support](https://docs.medusajs.com/references/store/models/Store/index.html.md): Create multiple stores, each having its own configurations.
+
+***
+
+## How to Use Store Module's Service
+
+In your Medusa application, you build flows around Commerce Modules. A flow is built as a [Workflow](https://docs.medusajs.com/docs/learn/fundamentals/workflows/index.html.md), which is a special function composed of a series of steps that guarantees data consistency and reliable roll-back mechanism.
+
+You can build custom workflows and steps. You can also re-use Medusa's workflows and steps, which are provided by the `@medusajs/medusa/core-flows` package.
+
+For example:
+
+```ts title="src/workflows/create-store.ts" highlights={highlights}
+import {
+ createWorkflow,
+ WorkflowResponse,
+ createStep,
+ StepResponse,
+} from "@medusajs/framework/workflows-sdk"
+import { Modules } from "@medusajs/framework/utils"
+
+const createStoreStep = createStep(
+ "create-store",
+ async ({}, { container }) => {
+ const storeModuleService = container.resolve(Modules.STORE)
+
+ const store = await storeModuleService.createStores({
+ name: "My Store",
+ supported_currencies: [{
+ currency_code: "usd",
+ is_default: true,
+ }],
+ })
+
+ return new StepResponse({ store }, store.id)
+ },
+ async (storeId, { container }) => {
+ if(!storeId) {
+ return
+ }
+ const storeModuleService = container.resolve(Modules.STORE)
+
+ await storeModuleService.deleteStores([storeId])
+ }
+)
+
+export const createStoreWorkflow = createWorkflow(
+ "create-store",
+ () => {
+ const { store } = createStoreStep()
+
+ return new WorkflowResponse({ store })
+ }
+)
+```
+
+You can then execute the workflow in your custom API routes, scheduled jobs, or subscribers:
+
+### API Route
+
+```ts title="src/api/workflow/route.ts" highlights={[["11"], ["12"]]} collapsibleLines="1-6" expandButtonLabel="Show Imports"
+import type {
+ MedusaRequest,
+ MedusaResponse,
+} from "@medusajs/framework/http"
+import { createStoreWorkflow } from "../../workflows/create-store"
+
+export async function GET(
+ req: MedusaRequest,
+ res: MedusaResponse
+) {
+ const { result } = await createStoreWorkflow(req.scope)
+ .run()
+
+ res.send(result)
+}
+```
+
+### Subscriber
+
+```ts title="src/subscribers/user-created.ts" highlights={[["11"], ["12"]]} collapsibleLines="1-6" expandButtonLabel="Show Imports"
+import {
+ type SubscriberConfig,
+ type SubscriberArgs,
+} from "@medusajs/framework"
+import { createStoreWorkflow } from "../workflows/create-store"
+
+export default async function handleUserCreated({
+ event: { data },
+ container,
+}: SubscriberArgs<{ id: string }>) {
+ const { result } = await createStoreWorkflow(container)
+ .run()
+
+ console.log(result)
+}
+
+export const config: SubscriberConfig = {
+ event: "user.created",
+}
+```
+
+### Scheduled Job
+
+```ts title="src/jobs/run-daily.ts" highlights={[["7"], ["8"]]}
+import { MedusaContainer } from "@medusajs/framework/types"
+import { createStoreWorkflow } from "../workflows/create-store"
+
+export default async function myCustomJob(
+ container: MedusaContainer
+) {
+ const { result } = await createStoreWorkflow(container)
+ .run()
+
+ console.log(result)
+}
+
+export const config = {
+ name: "run-once-a-day",
+ schedule: `0 0 * * *`,
+}
+```
+
+Learn more about workflows in [this documentation](https://docs.medusajs.com/docs/learn/fundamentals/workflows/index.html.md).
+
+***
+
+
+# Authentication Flows with the Auth Main Service
+
+In this document, you'll learn how to use the Auth Module's main service's methods to implement authentication flows and reset a user's password.
+
+## Authentication Methods
+
+### Register
+
+The [register method of the Auth Module's main service](https://docs.medusajs.com/references/auth/register/index.html.md) creates an auth identity that can be authenticated later.
+
+For example:
+
+```ts
+const data = await authModuleService.register(
+ "emailpass",
+ // passed to auth provider
+ {
+ // ...
+ }
+)
+```
+
+This method calls the `register` method of the provider specified in the first parameter and returns its data.
+
+### Authenticate
+
+To authenticate a user, you use the [authenticate method of the Auth Module's main service](https://docs.medusajs.com/references/auth/authenticate/index.html.md). For example:
+
+```ts
+const data = await authModuleService.authenticate(
+ "emailpass",
+ // passed to auth provider
+ {
+ // ...
+ }
+)
+```
+
+This method calls the `authenticate` method of the provider specified in the first parameter and returns its data.
+
+***
+
+## Auth Flow 1: Basic Authentication
+
+The basic authentication flow requires first using the `register` method, then the `authenticate` method:
+
+```ts
+const { success, authIdentity, error } = await authModuleService.register(
+ "emailpass",
+ // passed to auth provider
+ {
+ // ...
+ }
+)
+
+if (error) {
+ // registration failed
+ // TODO return an error
+ return
+}
+
+// later (can be another route for log-in)
+const { success, authIdentity, location } = await authModuleService.authenticate(
+ "emailpass",
+ // passed to auth provider
+ {
+ // ...
+ }
+)
+
+if (success && !location) {
+ // user is authenticated
+}
+```
+
+If `success` is true and `location` isn't set, the user is authenticated successfully, and their authentication details are available within the `authIdentity` object.
+
+The next section explains the flow if `location` is set.
+
+Check out the [AuthIdentity](https://docs.medusajs.com/references/auth/models/AuthIdentity/index.html.md) reference for the received properties in `authIdentity`.
+
+
+
+### Auth Identity with Same Identifier
+
+If an auth identity, such as a `customer`, tries to register with an email of another auth identity, the `register` method returns an error. This can happen either if another customer is using the same email, or an admin user has the same email.
+
+There are two ways to handle this:
+
+- Consider the customer authenticated if the `authenticate` method validates that the email and password are correct. This allows admin users, for example, to authenticate as customers.
+- Return an error message to the customer, informing them that the email is already in use.
+
+***
+
+## Auth Flow 2: Third-Party Service Authentication
+
+The third-party service authentication method requires using the `authenticate` method first:
+
+```ts
+const { success, authIdentity, location } = await authModuleService.authenticate(
+ "google",
+ // passed to auth provider
+ {
+ // ...
+ }
+)
+
+if (location) {
+ // return the location for the front-end to redirect to
+}
+
+if (!success) {
+ // authentication failed
+}
+
+// authentication successful
+```
+
+If the `authenticate` method returns a `location` property, the authentication process requires the user to perform an action with a third-party service. So, you return the `location` to the front-end or client to redirect to that URL.
+
+For example, when using the `google` provider, the `location` is the URL that the user is navigated to login.
+
+
+
+### Overriding Callback URL
+
+The Google and GitHub providers allow you to override their `callbackUrl` option during authentication. This is useful when you redirect the user after authentication to a URL based on its actor type. For example, you redirect admin users and customers to different pages.
+
+```ts
+const { success, authIdentity, location } = await authModuleService.authenticate(
+ "google",
+ // passed to auth provider
+ {
+ // ...
+ callback_url: "example.com",
+ }
+)
+```
+
+### validateCallback
+
+Providers handling this authentication flow must implement the `validateCallback` method. It implements the logic to validate the authentication with the third-party service.
+
+So, once the user performs the required action with the third-party service (for example, log-in with Google), the frontend must redirect to an API route that uses the [validateCallback method of the Auth Module's main service](https://docs.medusajs.com/references/auth/validateCallback/index.html.md).
+
+The method calls the specified provider’s `validateCallback` method passing it the authentication details it received in the second parameter:
+
+```ts
+const { success, authIdentity } = await authModuleService.validateCallback(
+ "google",
+ // passed to auth provider
+ {
+ // request data, such as
+ url,
+ headers,
+ query,
+ body,
+ protocol,
+ }
+)
+
+if (success) {
+ // authentication succeeded
+}
+```
+
+For providers like Google, the `query` object contains the query parameters from the original callback URL, such as the `code` and `state` parameters.
+
+If the returned `success` property is `true`, the authentication with the third-party provider was successful.
+
+
+
+***
+
+## Reset Password
+
+To update a user's password or other authentication details, use the `updateProvider` method of the Auth Module's main service. It calls the `update` method of the specified authentication provider.
+
+For example:
+
+```ts
+const { success } = await authModuleService.updateProvider(
+ "emailpass",
+ // passed to the auth provider
+ {
+ entity_id: "user@example.com",
+ password: "supersecret",
+ }
+)
+
+if (success) {
+ // password reset successfully
+}
+```
+
+The method accepts as a first parameter the ID of the provider, and as a second parameter the data necessary to reset the password.
+
+In the example above, you use the `emailpass` provider, so you have to pass an object having an `email` and `password` properties.
+
+If the returned `success` property is `true`, the password has reset successfully.
+
+
+# Auth Identity and Actor Types
+
+In this document, you’ll learn about concepts related to identity and actors in the Auth Module.
+
+## What is an Auth Identity?
+
+The [AuthIdentity data model](https://docs.medusajs.com/references/auth/models/AuthIdentity/index.html.md) represents a user registered by an [authentication provider](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/auth/auth-providers/index.html.md). When a user is registered using an authentication provider, the provider creates a record of `AuthIdentity`.
+
+Then, when the user logs-in in the future with the same authentication provider, the associated auth identity is used to validate their credentials.
+
+***
+
+## Actor Types
+
+An actor type is a type of user that can be authenticated. The Auth Module doesn't store or manage any user-like models, such as for customers or users. Instead, the user types are created and managed by other modules. For example, a customer is managed by the [Customer Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/customer/index.html.md).
+
+Then, when an auth identity is created for the actor type, the ID of the user is stored in the `app_metadata` property of the auth identity.
+
+For example, an auth identity of a customer has the following `app_metadata` property:
+
+```json
+{
+ "app_metadata": {
+ "customer_id": "cus_123"
+ }
+}
+```
+
+The ID of the user is stored in the key `{actor_type}_id` of the `app_metadata` property.
+
+***
+
+## Protect Routes by Actor Type
+
+When you protect routes with the `authenticate` middleware, you specify in its first parameter the actor type that must be authenticated to access the specified API routes.
+
+For example:
+
+```ts title="src/api/middlewares.ts" highlights={highlights}
+import {
+ defineMiddlewares,
+ authenticate,
+} from "@medusajs/framework/http"
+
+export default defineMiddlewares({
+ routes: [
+ {
+ matcher: "/custom/admin*",
+ middlewares: [
+ authenticate("user", ["session", "bearer", "api-key"]),
+ ],
+ },
+ ],
+})
+```
+
+By specifying `user` as the first parameter of `authenticate`, only authenticated users of actor type `user` (admin users) can access API routes starting with `/custom/admin`.
+
+***
+
+## Custom Actor Types
+
+You can define custom actor types that allows a custom user, managed by your custom module, to authenticate into Medusa.
+
+For example, if you have a custom module with a `Manager` data model, you can authenticate managers with the `manager` actor type.
+
+Learn how to create a custom actor type in [this guide](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/auth/create-actor-type/index.html.md).
+
+
+# Auth Providers
+
+In this document, you’ll learn how the Auth Module handles authentication using providers.
+
+## What's an Auth Module Provider?
+
+An auth module provider handles authenticating customers and users, either using custom logic or by integrating a third-party service.
+
+For example, the EmailPass Auth Module Provider authenticates a user using their email and password, whereas the Google Auth Module Provider authenticates users using their Google account.
+
+### Auth Providers List
+
+- [Emailpass](https://docs.medusajs.com/commerce-modules/auth/auth-providers/emailpass/index.html.md)
+- [Google](https://docs.medusajs.com/commerce-modules/auth/auth-providers/google/index.html.md)
+- [GitHub](https://docs.medusajs.com/commerce-modules/auth/auth-providers/github/index.html.md)
+
+***
+
+## Configure Allowed Auth Providers of Actor Types
+
+By default, users of all actor types can authenticate with all installed auth module providers.
+
+To restrict the auth providers used for actor types, use the [authMethodsPerActor option](https://docs.medusajs.com/docs/learn/configurations/medusa-config#httpauthMethodsPerActor/index.html.md) in Medusa's configurations:
+
+```ts title="medusa-config.ts"
+module.exports = defineConfig({
+ projectConfig: {
+ http: {
+ authMethodsPerActor: {
+ user: ["google"],
+ customer: ["emailpass"],
+ },
+ // ...
+ },
+ // ...
+ },
+})
+```
+
+When you specify the `authMethodsPerActor` configuration, it overrides the default. So, if you don't specify any providers for an actor type, users of that actor type can't authenticate with any provider.
+
+***
+
+## How to Create an Auth Module Provider
+
+Refer to [this guide](https://docs.medusajs.com/references/auth/provider/index.html.md) to learn how to create an auth module provider.
+
+
+# How to Use Authentication Routes
+
+In this document, you'll learn about the authentication routes and how to use them to create and log-in users, and reset their password.
+
+These routes are added by Medusa's HTTP layer, not the Auth Module.
+
+## Types of Authentication Flows
+
+### 1. Basic Authentication Flow
+
+This authentication flow doesn't require validation with third-party services.
+
+[How to register customer in storefront using basic authentication flow](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/storefront-development/customers/register/index.html.md).
+
+The steps are:
+
+
+
+1. Register the user with the [Register Route](#register-route).
+2. Use the authentication token to create the user with their respective API route.
+ - For example, for customers you would use the [Create Customer API route](https://docs.medusajs.com/api/store#customers_postcustomers).
+ - For admin users, you accept an invite using the [Accept Invite API route](https://docs.medusajs.com/api/admin#invites_postinvitesaccept)
+3. Authenticate the user with the [Auth Route](#login-route).
+
+After registration, you only use the [Auth Route](#login-route) for subsequent authentication.
+
+To handle errors related to existing identities, refer to [this section](#handling-existing-identities).
+
+### 2. Third-Party Service Authenticate Flow
+
+This authentication flow authenticates the user with a third-party service, such as Google.
+
+[How to authenticate customer with a third-party provider in the storefront.](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/storefront-development/customers/third-party-login/index.html.md).
+
+It requires the following steps:
+
+
+
+1. Authenticate the user with the [Auth Route](#login-route).
+2. The auth route returns a URL to authenticate with third-party service, such as login with Google. The frontend (such as a storefront), when it receives a `location` property in the response, must redirect to the returned location.
+3. Once the authentication with the third-party service finishes, it redirects back to the frontend with a `code` query parameter. So, make sure your third-party service is configured to redirect to your frontend page after successful authentication.
+4. The frontend sends a request to the [Validate Callback Route](#validate-callback-route) passing it the query parameters received from the third-party service, such as the `code` and `state` query parameters.
+5. If the callback validation is successful, the frontend receives the authentication token.
+6. Decode the received token in the frontend using tools like [react-jwt](https://www.npmjs.com/package/react-jwt).
+ - If the decoded data has an `actor_id` property, then the user is already registered. So, use this token for subsequent authenticated requests.
+ - If not, follow the rest of the steps.
+7. The frontend uses the authentication token to create the user with their respective API route.
+ - For example, for customers you would use the [Create Customer API route](https://docs.medusajs.com/api/store#customers_postcustomers).
+ - For admin users, you accept an invite using the [Accept Invite API route](https://docs.medusajs.com/api/admin#invites_postinvitesaccept)
+8. The frontend sends a request to the [Refresh Token Route](#refresh-token-route) to retrieve a new token with the user information populated.
+
+***
+
+## Register Route
+
+The Medusa application defines an API route at `/auth/{actor_type}/{provider}/register` that creates an auth identity for an actor type, such as a `customer`. It returns a JWT token that you pass to an API route that creates the user.
+
+```bash
+curl -X POST http://localhost:9000/auth/{actor_type}/{providers}/register
+-H 'Content-Type: application/json' \
+--data-raw '{
+ "email": "Whitney_Schultz@gmail.com"
+ // ...
+}'
+```
+
+This API route is useful for providers like `emailpass` that uses custom logic to authenticate a user. For authentication providers that authenticate with third-party services, such as Google, use the [Auth Route](#login-route) instead.
+
+For example, if you're registering a customer, you:
+
+1. Send a request to `/auth/customer/emailpass/register` to retrieve the registration JWT token.
+2. Send a request to the [Create Customer API route](https://docs.medusajs.com/api/store#customers_postcustomers) to create the customer, passing the [JWT token in the header](https://docs.medusajs.com/api/store#authentication).
+
+### Path Parameters
+
+Its path parameters are:
+
+- `{actor_type}`: the actor type of the user you're authenticating. For example, `customer`.
+- `{provider}`: the auth provider to handle the authentication. For example, `emailpass`.
+
+### Request Body Parameters
+
+This route accepts in the request body the data that the specified authentication provider requires to handle authentication.
+
+For example, the EmailPass provider requires an `email` and `password` fields in the request body.
+
+### Response Fields
+
+If the authentication is successful, you'll receive a `token` field in the response body object:
+
+```json
+{
+ "token": "..."
+}
+```
+
+Use that token in the header of subsequent requests to send authenticated requests.
+
+### Handling Existing Identities
+
+An auth identity with the same email may already exist in Medusa. This can happen if:
+
+- Another actor type is using that email. For example, an admin user is trying to register as a customer.
+- The same email belongs to a record of the same actor type. For example, another customer has the same email.
+
+In these scenarios, the Register Route will return an error instead of a token:
+
+```json
+{
+ "type": "unauthorized",
+ "message": "Identity with email already exists"
+}
+```
+
+To handle these scenarios, you can use the [Login Route](#login-route) to validate that the email and password match the existing identity. If so, you can allow the admin user, for example, to register as a customer.
+
+Otherwise, if the email and password don't match the existing identity, such as when the email belongs to another customer, the [Login Route](#login-route) returns an error:
+
+```json
+{
+ "type": "unauthorized",
+ "message": "Invalid email or password"
+}
+```
+
+You can show that error message to the customer.
+
+***
+
+## Login Route
+
+The Medusa application defines an API route at `/auth/{actor_type}/{provider}` that authenticates a user of an actor type. It returns a JWT token that can be passed in [the header of subsequent requests](https://docs.medusajs.com/api/store#authentication) to send authenticated requests.
+
+```bash
+curl -X POST http://localhost:9000/auth/{actor_type}/{providers}
+-H 'Content-Type: application/json' \
+--data-raw '{
+ "email": "Whitney_Schultz@gmail.com"
+ // ...
+}'
+```
+
+For example, if you're authenticating a customer, you send a request to `/auth/customer/emailpass`.
+
+### Path Parameters
+
+Its path parameters are:
+
+- `{actor_type}`: the actor type of the user you're authenticating. For example, `customer`.
+- `{provider}`: the auth provider to handle the authentication. For example, `emailpass`.
+
+### Request Body Parameters
+
+This route accepts in the request body the data that the specified authentication provider requires to handle authentication.
+
+For example, the EmailPass provider requires an `email` and `password` fields in the request body.
+
+#### Overriding Callback URL
+
+For the [GitHub](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/auth/auth-providers/github/index.html.md) and [Google](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/auth/auth-providers/google/index.html.md) providers, you can pass a `callback_url` body parameter that overrides the `callbackUrl` set in the provider's configurations.
+
+This is useful if you want to redirect the user to a different URL after authentication based on their actor type. For example, you can set different `callback_url` for admin users and customers.
+
+### Response Fields
+
+If the authentication is successful, you'll receive a `token` field in the response body object:
+
+```json
+{
+ "token": "..."
+}
+```
+
+Use that token in the header of subsequent requests to send authenticated requests.
+
+If the authentication requires more action with a third-party service, you'll receive a `location` property:
+
+```json
+{
+ "location": "https://..."
+}
+```
+
+Redirect to that URL in the frontend to continue the authentication process with the third-party service.
+
+[How to login Customers using the authentication route](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/storefront-development/customers/login/index.html.md).
+
+***
+
+## Validate Callback Route
+
+The Medusa application defines an API route at `/auth/{actor_type}/{provider}/callback` that's useful for validating the authentication callback or redirect from third-party services like Google.
+
+```bash
+curl -X POST http://localhost:9000/auth/{actor_type}/{providers}/callback?code=123&state=456
+```
+
+Refer to the [third-party authentication flow](#2-third-party-service-authenticate-flow) section to see how this route fits into the authentication flow.
+
+### Path Parameters
+
+Its path parameters are:
+
+- `{actor_type}`: the actor type of the user you're authenticating. For example, `customer`.
+- `{provider}`: the auth provider to handle the authentication. For example, `google`.
+
+### Query Parameters
+
+This route accepts all the query parameters that the third-party service sends to the frontend after the user completes the authentication process, such as the `code` and `state` query parameters.
+
+### Response Fields
+
+If the authentication is successful, you'll receive a `token` field in the response body object:
+
+```json
+{
+ "token": "..."
+}
+```
+
+In your frontend, decode the token using tools like [react-jwt](https://www.npmjs.com/package/react-jwt):
+
+- If the decoded data has an `actor_id` property, the user is already registered. So, use this token for subsequent authenticated requests.
+- If not, use the token in the header of a request that creates the user, such as the [Create Customer API route](https://docs.medusajs.com/api/store#customers_postcustomers).
+
+***
+
+## Refresh Token Route
+
+The Medusa application defines an API route at `/auth/token/refresh` that's useful after authenticating a user with a third-party service to populate the user's token with their new information.
+
+It requires the user's JWT token that they received from the authentication or callback routes.
+
+```bash
+curl -X POST http://localhost:9000/auth/token/refresh \
+-H 'Authorization: Bearer {token}'
+```
+
+### Response Fields
+
+If the token was refreshed successfully, you'll receive a `token` field in the response body object:
+
+```json
+{
+ "token": "..."
+}
+```
+
+Use that token in the header of subsequent requests to send authenticated requests.
+
+***
+
+## Reset Password Routes
+
+To reset a user's password:
+
+1. Generate a token using the [Generate Reset Password Token API route](#generate-reset-password-token-route).
+ - The API route emits the `auth.password_reset` event, passing the token in the payload.
+ - You can create a subscriber, as seen in [this guide](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/auth/reset-password/index.html.md), that listens to the event and send a notification to the user.
+2. Pass the token to the [Reset Password API route](#reset-password-route) to reset the password.
+ - The URL in the user's notification should direct them to a frontend URL, which sends a request to this route.
+
+[Storefront Development: How to Reset a Customer's Password.](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/storefront-development/customers/reset-password/index.html.md)
+
+### Generate Reset Password Token Route
+
+The Medusa application defines an API route at `/auth/{actor_type}/{auth_provider}/reset-password` that emits the `auth.password_reset` event, passing the token in the payload.
+
+```bash
+curl -X POST http://localhost:9000/auth/{actor_type}/{providers}/reset-password
+-H 'Content-Type: application/json' \
+--data-raw '{
+ "identifier": "Whitney_Schultz@gmail.com"
+}'
+```
+
+This API route is useful for providers like `emailpass` that store a user's password and use it for authentication.
+
+#### Path Parameters
+
+Its path parameters are:
+
+- `{actor_type}`: the actor type of the user you're authenticating. For example, `customer`.
+- `{provider}`: the auth provider to handle the authentication. For example, `emailpass`.
+
+#### Request Body Parameters
+
+This route accepts in the request body an object having the following property:
+
+- `identifier`: The user's identifier in the specified auth provider. For example, for the `emailpass` auth provider, you pass the user's email.
+
+#### Response Fields
+
+If the authentication is successful, the request returns a `201` response code.
+
+### Reset Password Route
+
+The Medusa application defines an API route at `/auth/{actor_type}/{auth_provider}/update` that accepts a token and, if valid, updates the user's password.
+
+```bash
+curl -X POST http://localhost:9000/auth/{actor_type}/{providers}/update
+-H 'Content-Type: application/json' \
+-H 'Authorization: Bearer {token}' \
+--data-raw '{
+ "email": "Whitney_Schultz@gmail.com",
+ "password": "supersecret"
+}'
+```
+
+This API route is useful for providers like `emailpass` that store a user's password and use it for logging them in.
+
+#### Path Parameters
+
+Its path parameters are:
+
+- `{actor_type}`: the actor type of the user you're authenticating. For example, `customer`.
+- `{provider}`: the auth provider to handle the authentication. For example, `emailpass`.
+
+#### Pass Token in Authorization Header
+
+Before [Medusa v2.6](https://github.com/medusajs/medusa/releases/tag/v2.6), you passed the token as a query parameter. Now, you must pass it in the `Authorization` header.
+
+In the request's authorization header, you must pass the token generated using the [Generate Reset Password Token route](#generate-reset-password-token-route). You pass it as a bearer token.
+
+### Request Body Parameters
+
+This route accepts in the request body an object that has the data necessary for the provider to update the user's password.
+
+For the `emailpass` provider, you must pass the following properties:
+
+- `email`: The user's email.
+- `password`: The new password.
+
+### Response Fields
+
+If the authentication is successful, the request returns an object with a `success` property set to `true`:
+
+```json
+{
+ "success": "true"
+}
+```
+
+
+# How to Create an Actor Type
+
+In this document, learn how to create an actor type and authenticate its associated data model.
+
+## 0. Create Module with Data Model
+
+Before creating an actor type, you must have a module with a data model representing the actor type.
+
+Learn how to create a module in [this guide](https://docs.medusajs.com/docs/learn/fundamentals/modules/index.html.md).
+
+The rest of this guide uses this `Manager` data model as an example:
+
+```ts title="src/modules/manager/models/manager.ts"
+import { model } from "@medusajs/framework/utils"
+
+const Manager = model.define("manager", {
+ id: model.id().primaryKey(),
+ firstName: model.text(),
+ lastName: model.text(),
+ email: model.text(),
+})
+
+export default Manager
+```
+
+***
+
+## 1. Create Workflow
+
+Start by creating a workflow that does two things:
+
+- Creates a record of the `Manager` data model.
+- Sets the `app_metadata` property of the associated `AuthIdentity` record based on the new actor type.
+
+For example, create the file `src/workflows/create-manager.ts`. with the following content:
+
+```ts title="src/workflows/create-manager.ts" highlights={workflowHighlights}
+import {
+ createWorkflow,
+ createStep,
+ StepResponse,
+ WorkflowResponse,
+} from "@medusajs/framework/workflows-sdk"
+import {
+ setAuthAppMetadataStep,
+} from "@medusajs/medusa/core-flows"
+import ManagerModuleService from "../modules/manager/service"
+
+type CreateManagerWorkflowInput = {
+ manager: {
+ first_name: string
+ last_name: string
+ email: string
+ }
+ authIdentityId: string
+}
+
+const createManagerStep = createStep(
+ "create-manager-step",
+ async ({
+ manager: managerData,
+ }: Pick,
+ { container }) => {
+ const managerModuleService: ManagerModuleService =
+ container.resolve("manager")
+
+ const manager = await managerModuleService.createManager(
+ managerData
+ )
+
+ return new StepResponse(manager)
+ }
+)
+
+const createManagerWorkflow = createWorkflow(
+ "create-manager",
+ function (input: CreateManagerWorkflowInput) {
+ const manager = createManagerStep({
+ manager: input.manager,
+ })
+
+ setAuthAppMetadataStep({
+ authIdentityId: input.authIdentityId,
+ actorType: "manager",
+ value: manager.id,
+ })
+
+ return new WorkflowResponse(manager)
+ }
+)
+
+export default createManagerWorkflow
+```
+
+This workflow accepts the manager’s data and the associated auth identity’s ID as inputs. The next sections explain how the auth identity ID is retrieved.
+
+The workflow has two steps:
+
+1. Create the manager using the `createManagerStep`.
+2. Set the `app_metadata` property of the associated auth identity using the `setAuthAppMetadataStep` from Medusa's core workflows. You specify the actor type `manager` in the `actorType` property of the step’s input.
+
+***
+
+## 2. Define the Create API Route
+
+Next, you’ll use the workflow defined in the previous section in an API route that creates a manager.
+
+So, create the file `src/api/manager/route.ts` with the following content:
+
+```ts title="src/api/manager/route.ts" highlights={createRouteHighlights}
+import type {
+ AuthenticatedMedusaRequest,
+ MedusaResponse,
+} from "@medusajs/framework/http"
+import { MedusaError } from "@medusajs/framework/utils"
+import createManagerWorkflow from "../../workflows/create-manager"
+
+type RequestBody = {
+ first_name: string
+ last_name: string
+ email: string
+}
+
+export async function POST(
+ req: AuthenticatedMedusaRequest,
+ res: MedusaResponse
+) {
+ // If `actor_id` is present, the request carries
+ // authentication for an existing manager
+ if (req.auth_context.actor_id) {
+ throw new MedusaError(
+ MedusaError.Types.INVALID_DATA,
+ "Request already authenticated as a manager."
+ )
+ }
+
+ const { result } = await createManagerWorkflow(req.scope)
+ .run({
+ input: {
+ manager: req.body,
+ authIdentityId: req.auth_context.auth_identity_id,
+ },
+ })
+
+ res.status(200).json({ manager: result })
+}
+```
+
+Since the manager must be associated with an `AuthIdentity` record, the request is expected to be authenticated, even if the manager isn’t created yet. This can be achieved by:
+
+1. Obtaining a token usng the [/auth route](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/auth/authentication-route/index.html.md).
+2. Passing the token in the bearer header of the request to this route.
+
+In the API route, you create the manager using the workflow from the previous section and return it in the response.
+
+***
+
+## 3. Apply the `authenticate` Middleware
+
+The last step is to apply the `authenticate` middleware on the API routes that require a manager’s authentication.
+
+To do that, create the file `src/api/middlewares.ts` with the following content:
+
+```ts title="src/api/middlewares.ts" highlights={middlewareHighlights}
+import {
+ defineMiddlewares,
+ authenticate,
+} from "@medusajs/framework/http"
+
+export default defineMiddlewares({
+ routes: [
+ {
+ matcher: "/manager",
+ method: "POST",
+ middlewares: [
+ authenticate("manager", ["session", "bearer"], {
+ allowUnregistered: true,
+ }),
+ ],
+ },
+ {
+ matcher: "/manager/me*",
+ middlewares: [
+ authenticate("manager", ["session", "bearer"]),
+ ],
+ },
+ ],
+})
+```
+
+This applies middlewares on two route patterns:
+
+1. The `authenticate` middleware is applied on the `/manager` API route for `POST` requests while allowing unregistered managers. This requires that a bearer token be passed in the request to access the manager’s auth identity but doesn’t require the manager to be registered.
+2. The `authenticate` middleware is applied on all routes starting with `/manager/me`, restricting these routes to authenticated managers only.
+
+### Retrieve Manager API Route
+
+For example, create the file `src/api/manager/me/route.ts` with the following content:
+
+```ts title="src/api/manager/me/route.ts"
+import {
+ AuthenticatedMedusaRequest,
+ MedusaResponse,
+} from "@medusajs/framework/http"
+import ManagerModuleService from "../../../modules/manager/service"
+
+export async function GET(
+ req: AuthenticatedMedusaRequest,
+ res: MedusaResponse
+): Promise {
+ const query = req.scope.resolve("query")
+ const managerId = req.auth_context?.actor_id
+
+ const { data: [manager] } = await query.graph({
+ entity: "manager",
+ fields: ["*"],
+ filters: {
+ id: managerId,
+ },
+ }, {
+ throwIfKeyNotFound: true,
+ })
+
+ res.json({ manager })
+}
+```
+
+This route is only accessible by authenticated managers. You access the manager’s ID using `req.auth_context.actor_id`.
+
+***
+
+## Test Custom Actor Type Authentication Flow
+
+To authenticate managers:
+
+1. Send a `POST` request to `/auth/manager/emailpass/register` to create an auth identity for the manager:
+
+```bash
+curl -X POST 'http://localhost:9000/auth/manager/emailpass/register' \
+-H 'Content-Type: application/json' \
+--data-raw '{
+ "email": "manager@gmail.com",
+ "password": "supersecret"
+}'
+```
+
+Copy the returned token to use it in the next request.
+
+2. Send a `POST` request to `/manager` to create a manager:
+
+```bash
+curl -X POST 'http://localhost:9000/manager' \
+-H 'Content-Type: application/json' \
+-H 'Authorization: Bearer {token}' \
+--data-raw '{
+ "first_name": "John",
+ "last_name": "Doe",
+ "email": "manager@gmail.com"
+}'
+```
+
+Replace `{token}` with the token returned in the previous step.
+
+3. Send a `POST` request to `/auth/manager/emailpass` again to retrieve an authenticated token for the manager:
+
+```bash
+curl -X POST 'http://localhost:9000/auth/manager/emailpass' \
+-H 'Content-Type: application/json' \
+--data-raw '{
+ "email": "manager@gmail.com",
+ "password": "supersecret"
+}'
+```
+
+4. You can now send authenticated requests as a manager. For example, send a `GET` request to `/manager/me` to retrieve the authenticated manager’s details:
+
+```bash
+curl 'http://localhost:9000/manager/me' \
+-H 'Authorization: Bearer {token}'
+```
+
+Whenever you want to log in as a manager, use the `/auth/manager/emailpass` API route, as explained in step 3.
+
+***
+
+## Delete User of Actor Type
+
+When you delete a user of the actor type, you must update its auth identity to remove the association to the user.
+
+For example, create the following workflow that deletes a manager and updates its auth identity, create the file `src/workflows/delete-manager.ts` with the following content:
+
+```ts title="src/workflows/delete-manager.ts" collapsibleLines="1-6" expandButtonLabel="Show Imports"
+import {
+ createStep,
+ StepResponse,
+} from "@medusajs/framework/workflows-sdk"
+import ManagerModuleService from "../modules/manager/service"
+
+export type DeleteManagerWorkflow = {
+ id: string
+}
+
+const deleteManagerStep = createStep(
+ "delete-manager-step",
+ async (
+ { id }: DeleteManagerWorkflow,
+ { container }) => {
+ const managerModuleService: ManagerModuleService =
+ container.resolve("manager")
+
+ const manager = await managerModuleService.retrieve(id)
+
+ await managerModuleService.deleteManagers(id)
+
+ return new StepResponse(undefined, { manager })
+ },
+ async ({ manager }, { container }) => {
+ const managerModuleService: ManagerModuleService =
+ container.resolve("manager")
+
+ await managerModuleService.createManagers(manager)
+ }
+ )
+```
+
+You add a step that deletes the manager using the `deleteManagers` method of the module's main service. In the compensation function, you create the manager again.
+
+Next, in the same file, add the workflow that deletes a manager:
+
+```ts title="src/workflows/delete-manager.ts" collapsibleLines="1-15" expandButtonLabel="Show Imports" highlights={deleteHighlights}
+// other imports
+import { MedusaError } from "@medusajs/framework/utils"
+import {
+ WorkflowData,
+ WorkflowResponse,
+ createWorkflow,
+ transform,
+} from "@medusajs/framework/workflows-sdk"
+import {
+ setAuthAppMetadataStep,
+ useQueryGraphStep,
+} from "@medusajs/medusa/core-flows"
+
+// ...
+
+export const deleteManagerWorkflow = createWorkflow(
+ "delete-manager",
+ (
+ input: WorkflowData
+ ): WorkflowResponse => {
+ deleteManagerStep(input)
+
+ const { data: authIdentities } = useQueryGraphStep({
+ entity: "auth_identity",
+ fields: ["id"],
+ filters: {
+ app_metadata: {
+ // the ID is of the format `{actor_type}_id`.
+ manager_id: input.id,
+ },
+ },
+ })
+
+ const authIdentity = transform(
+ { authIdentities },
+ ({ authIdentities }) => {
+ const authIdentity = authIdentities[0]
+
+ if (!authIdentity) {
+ throw new MedusaError(
+ MedusaError.Types.NOT_FOUND,
+ "Auth identity not found"
+ )
+ }
+
+ return authIdentity
+ }
+ )
+
+ setAuthAppMetadataStep({
+ authIdentityId: authIdentity.id,
+ actorType: "manager",
+ value: null,
+ })
+
+ return new WorkflowResponse(input.id)
+ }
+)
+```
+
+In the workflow, you:
+
+1. Use the `deleteManagerStep` defined earlier to delete the manager.
+2. Retrieve the auth identity of the manager using Query. To do that, you filter the `app_metadata` property of an auth identity, which holds the user's ID under `{actor_type_name}_id`. So, in this case, it's `manager_id`.
+3. Check that the auth identity exist, then, update the auth identity to remove the ID of the manager from it.
+
+You can use this workflow when deleting a manager, such as in an API route.
+
+
+# Auth Module Options
+
+In this document, you'll learn about the options of the Auth Module.
+
+## providers
+
+The `providers` option is an array of auth module providers.
+
+When the Medusa application starts, these providers are registered and can be used to handle authentication.
+
+By default, the `emailpass` provider is registered to authenticate customers and admin users.
+
+For example:
+
+```ts title="medusa-config.ts"
+import { Modules, ContainerRegistrationKeys } from "@medusajs/framework/utils"
+
+// ...
+
+module.exports = defineConfig({
+ // ...
+ modules: [
+ {
+ resolve: "@medusajs/medusa/auth",
+ dependencies: [Modules.CACHE, ContainerRegistrationKeys.LOGGER],
+ options: {
+ providers: [
+ {
+ resolve: "@medusajs/medusa/auth-emailpass",
+ id: "emailpass",
+ options: {
+ // provider options...
+ },
+ },
+ ],
+ },
+ },
+ ],
+})
+```
+
+The `providers` option is an array of objects that accept the following properties:
+
+- `resolve`: A string indicating the package name of the module provider or the path to it relative to the `src` directory.
+- `id`: A string indicating the provider's unique name or ID.
+- `options`: An optional object of the module provider's options.
+
+***
+
+## Auth CORS
+
+The Medusa application's authentication API routes are defined under the `/auth` prefix that requires setting the `authCors` property of the `http` configuration.
+
+By default, the Medusa application you created will have an `AUTH_CORS` environment variable, which is used as the value of `authCors`.
+
+Refer to [Medusa's configuration guide](https://docs.medusajs.com/docs/learn/configurations/medusa-config#httpauthCors/index.html.md) to learn more about the `authCors` configuration.
+
+***
+
+## authMethodsPerActor Configuration
+
+The Medusa application's configuration accept an `authMethodsPerActor` configuration which restricts the allowed auth providers used with an actor type.
+
+Learn more about the `authMethodsPerActor` configuration in [this guide](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/auth/auth-providers#configure-allowed-auth-providers-of-actor-types/index.html.md).
+
+
+# How to Handle Password Reset Token Event
+
+In this guide, you'll learn how to handle the `auth.password_reset` event, which is emitted when a request is sent to the [Generate Reset Password Token API route](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/auth/authentication-route#generate-reset-password-token-route/index.html.md).
+
+Refer to this [Medusa Admin User Guide](https://docs.medusajs.com/user-guide/reset-password/index.html.md) to learn how to reset your user admin password using the dashboard.
+
+You'll create a subscriber that listens to the event. When the event is emitted, the subscriber sends an email notification to the user.
+
+### Prerequisites
+
+- [A notification provider module, such as SendGrid](https://docs.medusajs.com/infrastructure-modules/notification/sendgrid/index.html.md)
+
+## 1. Create Subscriber
+
+The first step is to create a subscriber that listens to the `auth.password_reset` and sends the user a notification with instructions to reset their password.
+
+Create the file `src/subscribers/handle-reset.ts` with the following content:
+
+```ts title="src/subscribers/handle-reset.ts" highlights={highlights} collapsibleLines="1-6" expandMoreLabel="Show Imports"
+import {
+ SubscriberArgs,
+ type SubscriberConfig,
+} from "@medusajs/medusa"
+import { Modules } from "@medusajs/framework/utils"
+
+export default async function resetPasswordTokenHandler({
+ event: { data: {
+ entity_id: email,
+ token,
+ actor_type,
+ } },
+ container,
+}: SubscriberArgs<{ entity_id: string, token: string, actor_type: string }>) {
+ const notificationModuleService = container.resolve(
+ Modules.NOTIFICATION
+ )
+
+ const urlPrefix = actor_type === "customer" ?
+ "https://storefront.com" :
+ "https://admin.com/app"
+
+ await notificationModuleService.createNotifications({
+ to: email,
+ channel: "email",
+ template: "reset-password-template",
+ data: {
+ // a URL to a frontend application
+ url: `${urlPrefix}/reset-password?token=${token}&email=${email}`,
+ },
+ })
+}
+
+export const config: SubscriberConfig = {
+ event: "auth.password_reset",
+}
+```
+
+You subscribe to the `auth.password_reset` event. The event has a data payload object with the following properties:
+
+- `entity_id`: The identifier of the user. When using the `emailpass` provider, it's the user's email.
+- `token`: The token to reset the user's password.
+- `actor_type`: The user's actor type. For example, if the user is a customer, the `actor_type` is `customer`. If it's an admin user, the `actor_type` is `user`.
+
+This event's payload previously had an `actorType` field. It was renamed to `actor_type` after [Medusa v2.0.7](https://github.com/medusajs/medusa/releases/tag/v2.0.7).
+
+In the subscriber, you:
+
+- Decide the frontend URL based on whether the user is a customer or admin user by checking the value of `actor_type`.
+- Resolve the Notification Module and use its `createNotifications` method to send the notification.
+- You pass to the `createNotifications` method an object having the following properties:
+ - `to`: The identifier to send the notification to, which in this case is the email.
+ - `channel`: The channel to send the notification through, which in this case is email.
+ - `template`: The template ID in the third-party service.
+ - `data`: The data payload to pass to the template. You pass the URL to redirect the user to. You must pass the token and email in the URL so that the frontend can send them later to the Medusa application when reseting the password.
+
+***
+
+## 2. Test it Out: Generate Reset Password Token
+
+To test the subscriber out, send a request to the `/auth/{actor_type}/{auth_provider}/reset-password` API route, replacing `{actor_type}` and `{auth_provider}` with the user's actor type and provider used for authentication respectively.
+
+For example, to generate a reset password token for an admin user using the `emailpass` provider, send the following request:
+
+```bash
+curl --location 'http://localhost:9000/auth/user/emailpass/reset-password' \
+--header 'Content-Type: application/json' \
+--data-raw '{
+ "identifier": "admin-test@gmail.com"
+}'
+```
+
+In the request body, you must pass an `identifier` parameter. Its value is the user's identifier, which is the email in this case.
+
+If the token is generated successfully, the request returns a response with `201` status code. In the terminal, you'll find the following message indicating that the `auth.password_reset` event was emitted and your subscriber ran:
+
+```plain
+info: Processing auth.password_reset which has 1 subscribers
+```
+
+The notification is sent to the user with the frontend URL to enter a new password.
+
+***
+
+## Next Steps: Implementing Frontend
+
+In your frontend, you must have a page that accepts `token` and `email` query parameters.
+
+The page shows the user password fields to enter their new password, then submits the new password, token, and email to the [Reset Password Route](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/auth/authentication-route#reset-password-route/index.html.md).
+
+### Examples
+
+- [Storefront Guide: Reset Customer Password](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/storefront-development/customers/reset-password/index.html.md)
+
+
# API Key Concepts
In this document, you’ll learn about the different types of API keys, their expiration and verification.
@@ -21236,29 +22624,6 @@ The associated token is no longer usable or verifiable.
To verify a token received as an input or in a request, use the [authenticate method of the module’s main service](https://docs.medusajs.com/references/api-key/authenticate/index.html.md) which validates the token against all non-expired tokens.
-# Customer Accounts
-
-In this document, you’ll learn how registered and unregistered accounts are distinguished in the Medusa application.
-
-Refer to this [Medusa Admin User Guide](https://docs.medusajs.com/user-guide/customers/index.html.md) to learn how to manage customers using the dashboard.
-
-## `has_account` Property
-
-The [Customer data model](https://docs.medusajs.com/references/customer/models/Customer/index.html.md) has a `has_account` property, which is a boolean that indicates whether a customer is registered.
-
-When a guest customer places an order, a new `Customer` record is created with `has_account` set to `false`.
-
-When this or another guest customer registers an account with the same email, a new `Customer` record is created with `has_account` set to `true`.
-
-***
-
-## Email Uniqueness
-
-The above behavior means that two `Customer` records may exist with the same email. However, the main difference is the `has_account` property's value.
-
-So, there can only be one guest customer (having `has_account=false`) and one registered customer (having `has_account=true`) with the same email.
-
-
# Links between API Key Module and Other Modules
This document showcases the module links defined between the API Key Module and other Commerce Modules.
@@ -21357,1278 +22722,6 @@ createRemoteLinkStep({
```
-# Links between Customer Module and Other Modules
-
-This document showcases the module links defined between the Customer Module and other Commerce Modules.
-
-## Summary
-
-The Customer Module has the following links to other modules:
-
-Read-only links are used to query data across modules, but the relations aren't stored in a pivot table in the database.
-
-|First Data Model|Second Data Model|Type|Description|
-|---|---|---|---|
-|Customer|AccountHolder|Stored - many-to-many|Learn more|
-|Cart|Customer|Read-only - has one|Learn more|
-|Order|Customer|Read-only - has one|Learn more|
-
-***
-
-## Payment Module
-
-Medusa defines a link between the `Customer` and `AccountHolder` data models, allowing payment providers to save payment methods for a customer, if the payment provider supports it.
-
-This link is available starting from Medusa `v2.5.0`.
-
-### Retrieve with Query
-
-To retrieve the account holder associated with a customer with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `customer.*` in `fields`:
-
-### query.graph
-
-```ts
-const { data: customers } = await query.graph({
- entity: "customer",
- fields: [
- "account_holder_link.account_holder.*",
- ],
-})
-
-// customers[0].account_holder_link?.[0]?.account_holder
-```
-
-### useQueryGraphStep
-
-```ts
-import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
-
-// ...
-
-const { data: customers } = useQueryGraphStep({
- entity: "customer",
- fields: [
- "account_holder_link.account_holder.*",
- ],
-})
-
-// customers[0].account_holder_link?.[0]?.account_holder
-```
-
-### Manage with Link
-
-To manage the account holders of a customer, use [Link](https://docs.medusajs.com/docs/learn/fundamentals/module-links/link/index.html.md):
-
-### link.create
-
-```ts
-import { Modules } from "@medusajs/framework/utils"
-
-// ...
-
-await link.create({
- [Modules.CUSTOMER]: {
- customer_id: "cus_123",
- },
- [Modules.PAYMENT]: {
- account_holder_id: "acchld_123",
- },
-})
-```
-
-### createRemoteLinkStep
-
-```ts
-import { createRemoteLinkStep } from "@medusajs/medusa/core-flows"
-
-// ...
-
-createRemoteLinkStep({
- [Modules.CUSTOMER]: {
- customer_id: "cus_123",
- },
- [Modules.PAYMENT]: {
- account_holder_id: "acchld_123",
- },
-})
-```
-
-***
-
-## Cart Module
-
-Medusa defines a read-only link between the [Cart Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/cart/index.html.md)'s `Cart` data model and the `Customer` data model. Because the link is read-only from the `Cart`'s side, you can only retrieve the customer of a cart, and not the other way around.
-
-### Retrieve with Query
-
-To retrieve the customer of a cart with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `customer.*` in `fields`:
-
-### query.graph
-
-```ts
-const { data: carts } = await query.graph({
- entity: "cart",
- fields: [
- "customer.*",
- ],
-})
-
-// carts.customer
-```
-
-### useQueryGraphStep
-
-```ts
-import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
-
-// ...
-
-const { data: carts } = useQueryGraphStep({
- entity: "cart",
- fields: [
- "customer.*",
- ],
-})
-
-// carts.customer
-```
-
-***
-
-## Order Module
-
-Medusa defines a read-only link between the [Order Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/order/index.html.md)'s `Order` data model and the `Customer` data model. Because the link is read-only from the `Order`'s side, you can only retrieve the customer of an order, and not the other way around.
-
-### Retrieve with Query
-
-To retrieve the customer of an order with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `customer.*` in `fields`:
-
-### query.graph
-
-```ts
-const { data: orders } = await query.graph({
- entity: "order",
- fields: [
- "customer.*",
- ],
-})
-
-// orders.customer
-```
-
-### useQueryGraphStep
-
-```ts
-import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
-
-// ...
-
-const { data: orders } = useQueryGraphStep({
- entity: "order",
- fields: [
- "customer.*",
- ],
-})
-
-// orders.customer
-```
-
-
-# Fulfillment Concepts
-
-In this document, you’ll learn about some basic fulfillment concepts.
-
-## Fulfillment Set
-
-A fulfillment set is a general form or way of fulfillment. For example, shipping is a form of fulfillment, and pick-up is another form of fulfillment. Each of these can be created as fulfillment sets.
-
-A fulfillment set is represented by the [FulfillmentSet data model](https://docs.medusajs.com/references/fulfillment/models/FulfillmentSet/index.html.md). All other configurations, options, and management features are related to a fulfillment set, in one way or another.
-
-```ts
-const fulfillmentSets = await fulfillmentModuleService.createFulfillmentSets(
- [
- {
- name: "Shipping",
- type: "shipping",
- },
- {
- name: "Pick-up",
- type: "pick-up",
- },
- ]
-)
-```
-
-***
-
-## Service Zone
-
-A service zone is a collection of geographical zones or areas. It’s used to restrict available shipping options to a defined set of locations.
-
-A service zone is represented by the [ServiceZone data model](https://docs.medusajs.com/references/fulfillment/models/ServiceZone/index.html.md). It’s associated with a fulfillment set, as each service zone is specific to a form of fulfillment. For example, if a customer chooses to pick up items, you can restrict the available shipping options based on their location.
-
-
-
-A service zone can have multiple geographical zones, each represented by the [GeoZone data model](https://docs.medusajs.com/references/fulfillment/models/GeoZone/index.html.md). It holds location-related details to narrow down supported areas, such as country, city, or province code.
-
-The province code is always in lower-case and in [ISO 3166-2 format](https://en.wikipedia.org/wiki/ISO_3166-2).
-
-***
-
-## Shipping Profile
-
-A shipping profile defines a type of items that are shipped in a similar manner. For example, a `default` shipping profile is used for all item types, but the `digital` shipping profile is used for digital items that aren’t shipped and delivered conventionally.
-
-A shipping profile is represented by the [ShippingProfile data model](https://docs.medusajs.com/references/fulfillment/models/ShippingProfile/index.html.md). It only defines the profile’s details, but it’s associated with the shipping options available for the item type.
-
-
-# Fulfillment Module Provider
-
-In this document, you’ll learn what a fulfillment module provider is.
-
-Refer to this [Medusa Admin User Guide](https://docs.medusajs.com/user-guide/settings/locations-and-shipping/locations#manage-fulfillment-providers/index.html.md) to learn how to add a fulfillment provider to a location using the dashboard.
-
-## What’s a Fulfillment Module Provider?
-
-A fulfillment module provider handles fulfilling items, typically using a third-party integration.
-
-Fulfillment module providers registered in the Fulfillment Module's [options](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/fulfillment/module-options/index.html.md) are stored and represented by the [FulfillmentProvider data model](https://docs.medusajs.com/references/fulfillment/models/FulfillmentProvider/index.html.md).
-
-***
-
-## Configure Fulfillment Providers
-
-The Fulfillment Module accepts a `providers` option that allows you to register providers in your application.
-
-Learn more about the `providers` option in [this documentation](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/fulfillment/module-options/index.html.md).
-
-***
-
-## How to Create a Fulfillment Provider?
-
-Refer to [this guide](https://docs.medusajs.com/references/fulfillment/provider/index.html.md) to learn how to create a fulfillment module provider.
-
-
-# Links between Fulfillment Module and Other Modules
-
-This document showcases the module links defined between the Fulfillment Module and other Commerce Modules.
-
-## Summary
-
-The Fulfillment Module has the following links to other modules:
-
-|First Data Model|Second Data Model|Type|Description|
-|---|---|---|---|
-|Order|Fulfillment|Stored - one-to-many|Learn more|
-|Return|Fulfillment|Stored - one-to-many|Learn more|
-|PriceSet|ShippingOption|Stored - many-to-one|Learn more|
-|Product|ShippingProfile|Stored - many-to-one|Learn more|
-|StockLocation|FulfillmentProvider|Stored - one-to-many|Learn more|
-|StockLocation|FulfillmentSet|Stored - one-to-many|Learn more|
-
-***
-
-## Order Module
-
-The [Order Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/order/index.html.md) provides order-management functionalities.
-
-Medusa defines a link between the `Fulfillment` and `Order` data models. A fulfillment is created for an orders' items.
-
-
-
-A fulfillment is also created for a return's items. So, Medusa defines a link between the `Fulfillment` and `Return` data models.
-
-
-
-### Retrieve with Query
-
-To retrieve the order of a fulfillment with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `order.*` in `fields`:
-
-To retrieve the return, pass `return.*` in `fields`.
-
-### query.graph
-
-```ts
-const { data: fulfillments } = await query.graph({
- entity: "fulfillment",
- fields: [
- "order.*",
- ],
-})
-
-// fulfillments.order
-```
-
-### useQueryGraphStep
-
-```ts
-import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
-
-// ...
-
-const { data: fulfillments } = useQueryGraphStep({
- entity: "fulfillment",
- fields: [
- "order.*",
- ],
-})
-
-// fulfillments.order
-```
-
-### Manage with Link
-
-To manage the order of a cart, use [Link](https://docs.medusajs.com/docs/learn/fundamentals/module-links/link/index.html.md):
-
-### link.create
-
-```ts
-import { Modules } from "@medusajs/framework/utils"
-
-// ...
-
-await link.create({
- [Modules.ORDER]: {
- order_id: "order_123",
- },
- [Modules.FULFILLMENT]: {
- fulfillment_id: "ful_123",
- },
-})
-```
-
-### createRemoteLinkStep
-
-```ts
-import { Modules } from "@medusajs/framework/utils"
-import { createRemoteLinkStep } from "@medusajs/medusa/core-flows"
-
-// ...
-
-createRemoteLinkStep({
- [Modules.ORDER]: {
- order_id: "order_123",
- },
- [Modules.FULFILLMENT]: {
- fulfillment_id: "ful_123",
- },
-})
-```
-
-***
-
-## Pricing Module
-
-The Pricing Module provides features to store, manage, and retrieve the best prices in a specified context.
-
-Medusa defines a link between the `PriceSet` and `ShippingOption` data models. A shipping option's price is stored as a price set.
-
-
-
-### Retrieve with Query
-
-To retrieve the price set of a shipping option with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `price_set.*` in `fields`:
-
-### query.graph
-
-```ts
-const { data: shippingOptions } = await query.graph({
- entity: "shipping_option",
- fields: [
- "price_set_link.*",
- ],
-})
-
-// shippingOptions[0].price_set_link?.price_set_id
-```
-
-### useQueryGraphStep
-
-```ts
-import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
-
-// ...
-
-const { data: shippingOptions } = useQueryGraphStep({
- entity: "shipping_option",
- fields: [
- "price_set_link.*",
- ],
-})
-
-// shippingOptions[0].price_set_link?.price_set_id
-```
-
-### Manage with Link
-
-To manage the price set of a shipping option, use [Link](https://docs.medusajs.com/docs/learn/fundamentals/module-links/link/index.html.md):
-
-### link.create
-
-```ts
-import { Modules } from "@medusajs/framework/utils"
-
-// ...
-
-await link.create({
- [Modules.FULFILLMENT]: {
- shipping_option_id: "so_123",
- },
- [Modules.PRICING]: {
- price_set_id: "pset_123",
- },
-})
-```
-
-### createRemoteLinkStep
-
-```ts
-import { Modules } from "@medusajs/framework/utils"
-import { createRemoteLinkStep } from "@medusajs/medusa/core-flows"
-
-// ...
-
-createRemoteLinkStep({
- [Modules.FULFILLMENT]: {
- shipping_option_id: "so_123",
- },
- [Modules.PRICING]: {
- price_set_id: "pset_123",
- },
-})
-```
-
-***
-
-## Product Module
-
-Medusa defines a link between the `ShippingProfile` data model and the `Product` data model of the Product Module. Each product must belong to a shipping profile.
-
-This link is introduced in [Medusa v2.5.0](https://github.com/medusajs/medusa/releases/tag/v2.5.0).
-
-### Retrieve with Query
-
-To retrieve the products of a shipping profile with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `products.*` in `fields`:
-
-### query.graph
-
-```ts
-const { data: shippingProfiles } = await query.graph({
- entity: "shipping_profile",
- fields: [
- "products.*",
- ],
-})
-
-// shippingProfiles[0].products
-```
-
-### useQueryGraphStep
-
-```ts
-import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
-
-// ...
-
-const { data: shippingProfiles } = useQueryGraphStep({
- entity: "shipping_profile",
- fields: [
- "products.*",
- ],
-})
-
-// shippingProfiles[0].products
-```
-
-### Manage with Link
-
-To manage the shipping profile of a product, use [Link](https://docs.medusajs.com/docs/learn/fundamentals/module-links/link/index.html.md):
-
-### link.create
-
-```ts
-import { Modules } from "@medusajs/framework/utils"
-
-// ...
-
-await link.create({
- [Modules.PRODUCT]: {
- product_id: "prod_123",
- },
- [Modules.FULFILLMENT]: {
- shipping_profile_id: "sp_123",
- },
-})
-```
-
-### createRemoteLinkStep
-
-```ts
-import { Modules } from "@medusajs/framework/utils"
-import { createRemoteLinkStep } from "@medusajs/medusa/core-flows"
-
-// ...
-
-createRemoteLinkStep({
- [Modules.PRODUCT]: {
- product_id: "prod_123",
- },
- [Modules.FULFILLMENT]: {
- shipping_profile_id: "sp_123",
- },
-})
-```
-
-***
-
-## Stock Location Module
-
-The Stock Location Module provides features to manage stock locations in a store.
-
-Medusa defines a link between the `FulfillmentSet` and `StockLocation` data models. A fulfillment set can be conditioned to a specific stock location.
-
-
-
-Medusa also defines a link between the `FulfillmentProvider` and `StockLocation` data models to indicate the providers that can be used in a location.
-
-
-
-### Retrieve with Query
-
-To retrieve the stock location of a fulfillment set with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `location.*` in `fields`:
-
-To retrieve the stock location of a fulfillment provider, pass `locations.*` in `fields`.
-
-### query.graph
-
-```ts
-const { data: fulfillmentSets } = await query.graph({
- entity: "fulfillment_set",
- fields: [
- "location.*",
- ],
-})
-
-// fulfillmentSets[0].location
-```
-
-### useQueryGraphStep
-
-```ts
-import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
-
-// ...
-
-const { data: fulfillmentSets } = useQueryGraphStep({
- entity: "fulfillment_set",
- fields: [
- "location.*",
- ],
-})
-
-// fulfillmentSets[0].location
-```
-
-### Manage with Link
-
-To manage the stock location of a fulfillment set, use [Link](https://docs.medusajs.com/docs/learn/fundamentals/module-links/link/index.html.md):
-
-### link.create
-
-```ts
-import { Modules } from "@medusajs/framework/utils"
-
-// ...
-
-await link.create({
- [Modules.STOCK_LOCATION]: {
- stock_location_id: "sloc_123",
- },
- [Modules.FULFILLMENT]: {
- fulfillment_set_id: "fset_123",
- },
-})
-```
-
-### createRemoteLinkStep
-
-```ts
-import { Modules } from "@medusajs/framework/utils"
-import { createRemoteLinkStep } from "@medusajs/medusa/core-flows"
-
-// ...
-
-createRemoteLinkStep({
- [Modules.STOCK_LOCATION]: {
- stock_location_id: "sloc_123",
- },
- [Modules.FULFILLMENT]: {
- fulfillment_set_id: "fset_123",
- },
-})
-```
-
-
-# Fulfillment Module Options
-
-In this document, you'll learn about the options of the Fulfillment Module.
-
-## providers
-
-The `providers` option is an array of fulfillment module providers.
-
-When the Medusa application starts, these providers are registered and can be used to process fulfillments.
-
-For example:
-
-```ts title="medusa-config.ts"
-import { Modules } from "@medusajs/framework/utils"
-
-// ...
-
-module.exports = defineConfig({
- // ...
- modules: [
- {
- resolve: "@medusajs/medusa/fulfillment",
- options: {
- providers: [
- {
- resolve: `@medusajs/medusa/fulfillment-manual`,
- id: "manual",
- options: {
- // provider options...
- },
- },
- ],
- },
- },
- ],
-})
-```
-
-The `providers` option is an array of objects that accept the following properties:
-
-- `resolve`: A string indicating either the package name of the module provider or the path to it relative to the `src` directory.
-- `id`: A string indicating the provider's unique name or ID.
-- `options`: An optional object of the module provider's options.
-
-
-# Item Fulfillment
-
-In this document, you’ll learn about the concepts of item fulfillment.
-
-## Fulfillment Data Model
-
-A fulfillment is the shipping and delivery of one or more items to the customer. It’s represented by the [Fulfillment data model](https://docs.medusajs.com/references/fulfillment/models/Fulfillment/index.html.md).
-
-***
-
-## Fulfillment Processing by a Fulfillment Provider
-
-A fulfillment is associated with a fulfillment provider that handles all its processing, such as creating a shipment for the fulfillment’s items.
-
-The fulfillment is also associated with a shipping option of that provider, which determines how the item is shipped.
-
-
-
-***
-
-## data Property
-
-The `Fulfillment` data model has a `data` property that holds any necessary data for the third-party fulfillment provider to process the fulfillment.
-
-For example, the `data` property can hold the ID of the fulfillment in the third-party provider. The associated fulfillment provider then uses it whenever it retrieves the fulfillment’s details.
-
-***
-
-## Fulfillment Items
-
-A fulfillment is used to fulfill one or more items. Each item is represented by the `FulfillmentItem` data model.
-
-The fulfillment item holds details relevant to fulfilling the item, such as barcode, SKU, and quantity to fulfill.
-
-
-
-***
-
-## Fulfillment Label
-
-Once a shipment is created for the fulfillment, you can store its tracking number, URL, or other related details as a label, represented by the `FulfillmentLabel` data model.
-
-***
-
-## Fulfillment Status
-
-The `Fulfillment` data model has three properties to keep track of the current status of the fulfillment:
-
-- `packed_at`: The date the fulfillment was packed. If set, then the fulfillment has been packed.
-- `shipped_at`: The date the fulfillment was shipped. If set, then the fulfillment has been shipped.
-- `delivered_at`: The date the fulfillment was delivered. If set, then the fulfillment has been delivered.
-
-
-# Shipping Option
-
-In this document, you’ll learn about shipping options and their rules.
-
-## What’s a Shipping Option?
-
-A shipping option is a way of shipping an item. Each fulfillment provider provides a set of shipping options. For example, a provider may provide a shipping option for express shipping and another for standard shipping.
-
-When the customer places their order, they choose a shipping option to be used to fulfill their items.
-
-A shipping option is represented by the [ShippingOption data model](https://docs.medusajs.com/references/fulfillment/models/ShippingOption/index.html.md).
-
-***
-
-## Service Zone Restrictions
-
-A shipping option is restricted by a service zone, limiting the locations a shipping option be used in.
-
-For example, a fulfillment provider may have a shipping option that can be used in the United States, and another in Canada.
-
-
-
-Service zones can be more restrictive, such as restricting to certain cities or province codes.
-
-The province code is always in lower-case and in [ISO 3166-2 format](https://en.wikipedia.org/wiki/ISO_3166-2).
-
-
-
-***
-
-## Shipping Option Rules
-
-You can restrict shipping options by custom rules, such as the item’s weight or the customer’s group.
-
-You can also restrict a shipping option's price based on specific conditions. For example, you can make a shipping option's price free based on the cart's total. Learn more in the Pricing Module's [Price Rules](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/pricing/price-rules#how-to-set-rules-on-a-price/index.html.md) guide.
-
-These rules are represented by the [ShippingOptionRule data model](https://docs.medusajs.com/references/fulfillment/models/ShippingOptionRule/index.html.md). Its properties define the custom rule:
-
-- `attribute`: The name of a property or table that the rule applies to. For example, `customer_group`.
-- `operator`: The operator used in the condition. For example:
- - To allow multiple values, use the operator `in`, which validates that the provided values are in the rule’s values.
- - To create a negation condition that considers `value` against the rule, use `nin`, which validates that the provided values aren’t in the rule’s values.
- - Check out more operators in [this reference](https://docs.medusajs.com/references/fulfillment/types/fulfillment.RuleOperatorType/index.html.md).
-- `value`: One or more values.
-
-
-
-A shipping option can have multiple rules. For example, you can add rules to a shipping option so that it's available if the customer belongs to the VIP group and the total weight is less than 2000g.
-
-
-
-***
-
-## Shipping Profile and Types
-
-A shipping option belongs to a type. For example, a shipping option’s type may be `express`, while another `standard`. The type is represented by the [ShippingOptionType data model](https://docs.medusajs.com/references/fulfillment/models/ShippingOptionType/index.html.md).
-
-A shipping option also belongs to a shipping profile, as each shipping profile defines the type of items to be shipped in a similar manner.
-
-***
-
-## data Property
-
-When fulfilling an item, you might use a third-party fulfillment provider that requires additional custom data to be passed along from the checkout or order-creation process.
-
-The `ShippingOption` data model has a `data` property. It's an object that stores custom data relevant later when creating and processing a fulfillment.
-
-
-# Inventory Concepts
-
-In this document, you’ll learn about the main concepts in the Inventory Module, and how data is stored and related.
-
-## 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.
-
-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.
-
-
-
-### 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.
-
-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).
-
-***
-
-## 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.
-
-It has three quantity-related 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.
-
-### 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.
-
-***
-
-## 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.
-
-The reserved quantity is associated with a location, so it has a similar relation to that of the `InventoryLevel` with the Stock Location Module.
-
-
-# Inventory Module in Medusa Flows
-
-This document explains how the Inventory Module is used within the Medusa application's flows.
-
-## Product Variant Creation
-
-When a product variant is created and its `manage_inventory` property's value is `true`, the Medusa application creates an inventory item associated with that product variant.
-
-This flow is implemented within the [createProductVariantsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createProductVariantsWorkflow/index.html.md)
-
-
-
-***
-
-## Add to Cart
-
-When a product variant with `manage_inventory` set to `true` is added to cart, the Medusa application checks whether there's sufficient stocked quantity. If not, an error is thrown and the product variant won't be added to the cart.
-
-This flow is implemented within the [addToCartWorkflow](https://docs.medusajs.com/references/medusa-workflows/addToCartWorkflow/index.html.md)
-
-
-
-***
-
-## Order Placed
-
-When an order is placed, the Medusa application creates a reservation item for each product variant with `manage_inventory` set to `true`.
-
-This flow is implemented within the [completeCartWorkflow](https://docs.medusajs.com/references/medusa-workflows/completeCartWorkflow/index.html.md)
-
-
-
-***
-
-## Order Fulfillment
-
-When an item in an order is fulfilled and the associated variant has its `manage_inventory` property set to `true`, the Medusa application:
-
-- Subtracts the `reserved_quantity` from the `stocked_quantity` in the inventory level associated with the variant's inventory item.
-- Resets the `reserved_quantity` to `0`.
-- Deletes the associated reservation item.
-
-This flow is implemented within the [createOrderFulfillmentWorkflow](https://docs.medusajs.com/references/medusa-workflows/createOrderFulfillmentWorkflow/index.html.md)
-
-
-
-***
-
-## Order Return
-
-When an item in an order is returned and the associated variant has its `manage_inventory` property set to `true`, the Medusa application increments the `stocked_quantity` of the inventory item's level with the returned quantity.
-
-This flow is implemented within the [confirmReturnReceiveWorkflow](https://docs.medusajs.com/references/medusa-workflows/confirmReturnReceiveWorkflow/index.html.md)
-
-
-
-### Dismissed Returned Items
-
-If a returned item is considered damaged or is dismissed, its quantity doesn't increment the `stocked_quantity` of the inventory item's level.
-
-
-# Inventory Kits
-
-In this guide, you'll learn how inventory kits can be used in the Medusa application to support use cases like multi-part products, bundled products, and shared inventory across products.
-
-Refer to the following user guides to learn how to use the Medusa Admin dashboard to:
-
-- [Create Multi-Part Products](https://docs.medusajs.com/user-guide/products/create/multi-part/index.html.md).
-- [Create Bundled Products](https://docs.medusajs.com/user-guide/products/create/bundle/index.html.md).
-
-## What is an Inventory Kit?
-
-An inventory kit is a collection of inventory items that are linked to a single product variant. These inventory items can be used to represent different parts of a product, or to represent a bundle of products.
-
-The Medusa application links inventory items from the [Inventory Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/inventory/index.html.md) to product variants in the [Product Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/product/index.html.md). Each variant can have multiple inventory items, and these inventory items can be re-used or shared across variants.
-
-Using inventory kits, you can implement use cases like:
-
-- [Multi-part products](#multi-part-products): A product that consists of multiple parts, each with its own inventory item.
-- [Bundled products](#bundled-products): A product that is sold as a bundle, where each variant in the bundle product can re-use the inventory items of another product that should be sold as part of the bundle.
-
-***
-
-## Multi-Part Products
-
-Consider your store sells bicycles that consist of a frame, wheels, and seats, and you want to manage the inventory of these parts separately.
-
-To implement this in Medusa, you can:
-
-- Create inventory items for each of the different parts.
-- For each bicycle product, add a variant whose inventory kit consists of the inventory items of each of the parts.
-
-Then, whenever a customer purchases a bicycle, the inventory of each part is updated accordingly. You can also use the `required_quantity` of the variant's inventory items to set how much quantity is consumed of the part's inventory when a bicycle is sold. For example, the bicycle's wheels require 2 wheels inventory items to be sold when a bicycle is sold.
-
-
-
-### Create Multi-Part Product
-
-Using the [Medusa Admin](https://docs.medusajs.com/user-guide/products/create/multi-part/index.html.md), you can create a multi-part product by creating its inventory items first, then assigning these inventory items to the product's variant(s).
-
-Using [workflows](https://docs.medusajs.com/docs/learn/fundamentals/workflows/index.html.md), you can implement this by first creating the inventory items:
-
-```ts highlights={multiPartsHighlights1}
-import {
- createInventoryItemsWorkflow,
- useQueryGraphStep,
-} from "@medusajs/medusa/core-flows"
-import { createWorkflow } from "@medusajs/framework/workflows-sdk"
-
-export const createMultiPartProductsWorkflow = createWorkflow(
- "create-multi-part-products",
- () => {
- // Alternatively, you can create a stock location
- const { data: stockLocations } = useQueryGraphStep({
- entity: "stock_location",
- fields: ["*"],
- filters: {
- name: "European Warehouse",
- },
- })
-
- const inventoryItems = createInventoryItemsWorkflow.runAsStep({
- input: {
- items: [
- {
- sku: "FRAME",
- title: "Frame",
- location_levels: [
- {
- stocked_quantity: 100,
- location_id: stockLocations[0].id,
- },
- ],
- },
- {
- sku: "WHEEL",
- title: "Wheel",
- location_levels: [
- {
- stocked_quantity: 100,
- location_id: stockLocations[0].id,
- },
- ],
- },
- {
- sku: "SEAT",
- title: "Seat",
- location_levels: [
- {
- stocked_quantity: 100,
- location_id: stockLocations[0].id,
- },
- ],
- },
- ],
- },
- })
-
- // TODO create the product
- }
-)
-```
-
-You start by retrieving the stock location to create the inventory items in. Alternatively, you can [create a stock location](https://docs.medusajs.com/references/medusa-workflows/createStockLocationsWorkflow/index.html.md).
-
-Then, you create the inventory items that the product variant consists of.
-
-Next, create the product and pass the inventory item's IDs to the product's variant:
-
-```ts highlights={multiPartHighlights2}
-import {
- // ...
- transform,
-} from "@medusajs/framework/workflows-sdk"
-import {
- // ...
- createProductsWorkflow,
-} from "@medusajs/medusa/core-flows"
-
-export const createMultiPartProductsWorkflow = createWorkflow(
- "create-multi-part-products",
- () => {
- // ...
-
- const inventoryItemIds = transform({
- inventoryItems,
- }, (data) => {
- return data.inventoryItems.map((inventoryItem) => {
- return {
- inventory_item_id: inventoryItem.id,
- // can also specify required_quantity
- }
- })
- })
-
- const products = createProductsWorkflow.runAsStep({
- input: {
- products: [
- {
- title: "Bicycle",
- variants: [
- {
- title: "Bicycle - Small",
- prices: [
- {
- amount: 100,
- currency_code: "usd",
- },
- ],
- options: {
- "Default Option": "Default Variant",
- },
- inventory_items: inventoryItemIds,
- },
- ],
- options: [
- {
- title: "Default Option",
- values: ["Default Variant"],
- },
- ],
- shipping_profile_id: "sp_123",
- },
- ],
- },
- })
- }
-)
-```
-
-You prepare the inventory item IDs to pass to the variant using [transform](https://docs.medusajs.com/docs/learn/fundamentals/workflows/variable-manipulation/index.html.md) from the Workflows SDK, then pass these IDs to the created product's variant.
-
-You can now [execute the workflow](https://docs.medusajs.com/docs/learn/fundamentals/workflows#3-execute-the-workflow/index.html.md) in [API routes](https://docs.medusajs.com/docs/learn/fundamentals/api-routes/index.html.md), [scheduled jobs](https://docs.medusajs.com/docs/learn/fundamentals/scheduled-jobs/index.html.md), or [subscribers](https://docs.medusajs.com/docs/learn/fundamentals/events-and-subscribers/index.html.md).
-
-***
-
-## Bundled Products
-
-While inventory kits support bundled products, some features like custom pricing for a bundle or separate fulfillment for a bundle's items are not supported. To support those features, follow the [Bundled Products](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/recipes/bundled-products/examples/standard/index.html.md) tutorial to learn how to customize the Medusa application to add bundled products.
-
-Consider you have three products: shirt, pants, and shoes. You sell those products separately, but you also want to offer them as a bundle.
-
-
-
-You can do that by creating a product, where each variant re-uses the inventory items of each of the shirt, pants, and shoes products.
-
-Then, when the bundled product's variant is purchased, the inventory quantity of the associated inventory items are updated.
-
-
-
-### Create Bundled Product
-
-You can create a bundled product in the [Medusa Admin](https://docs.medusajs.com/user-guide/products/create/bundle/index.html.md) by creating the products part of the bundle first, each having its own inventory items. Then, you create the bundled product whose variant(s) have inventory kits composed of inventory items from each of the products part of the bundle.
-
-Using [workflows](https://docs.medusajs.com/docs/learn/fundamentals/workflows/index.html.md), you can implement this by first creating the products part of the bundle:
-
-```ts highlights={bundledHighlights1}
-import {
- createWorkflow,
-} from "@medusajs/framework/workflows-sdk"
-import {
- createProductsWorkflow,
-} from "@medusajs/medusa/core-flows"
-
-export const createBundledProducts = createWorkflow(
- "create-bundled-products",
- () => {
- const products = createProductsWorkflow.runAsStep({
- input: {
- products: [
- {
- title: "Shirt",
- shipping_profile_id: "sp_123",
- variants: [
- {
- title: "Shirt",
- prices: [
- {
- amount: 10,
- currency_code: "usd",
- },
- ],
- options: {
- "Default Option": "Default Variant",
- },
- manage_inventory: true,
- },
- ],
- options: [
- {
- title: "Default Option",
- values: ["Default Variant"],
- },
- ],
- },
- {
- title: "Pants",
- shipping_profile_id: "sp_123",
- variants: [
- {
- title: "Pants",
- prices: [
- {
- amount: 10,
- currency_code: "usd",
- },
- ],
- options: {
- "Default Option": "Default Variant",
- },
- manage_inventory: true,
- },
- ],
- options: [
- {
- title: "Default Option",
- values: ["Default Variant"],
- },
- ],
- },
- {
- title: "Shoes",
- shipping_profile_id: "sp_123",
- variants: [
- {
- title: "Shoes",
- prices: [
- {
- amount: 10,
- currency_code: "usd",
- },
- ],
- options: {
- "Default Option": "Default Variant",
- },
- manage_inventory: true,
- },
- ],
- options: [
- {
- title: "Default Option",
- values: ["Default Variant"],
- },
- ],
- },
- ],
- },
- })
-
- // TODO re-retrieve with inventory
- }
-)
-```
-
-You create three products and enable `manage_inventory` for their variants, which will create a default inventory item. You can also create the inventory item first for more control over the quantity as explained in [the previous section](#create-multi-part-product).
-
-Next, retrieve the products again but with variant information:
-
-```ts highlights={bundledHighlights2}
-import {
- // ...
- transform,
-} from "@medusajs/framework/workflows-sdk"
-import {
- useQueryGraphStep,
-} from "@medusajs/medusa/core-flows"
-
-export const createBundledProducts = createWorkflow(
- "create-bundled-products",
- () => {
- // ...
- const productIds = transform({
- products,
- }, (data) => data.products.map((product) => product.id))
-
- // @ts-ignore
- const { data: productsWithInventory } = useQueryGraphStep({
- entity: "product",
- fields: [
- "variants.*",
- "variants.inventory_items.*",
- ],
- filters: {
- id: productIds,
- },
- })
-
- const inventoryItemIds = transform({
- productsWithInventory,
- }, (data) => {
- return data.productsWithInventory.map((product) => {
- return {
- inventory_item_id: product.variants[0].inventory_items?.[0]?.inventory_item_id,
- }
- })
- })
-
- // create bundled product
- }
-)
-```
-
-Using [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), you retrieve the product again with the inventory items of each variant. Then, you prepare the inventory items to pass to the bundled product's variant.
-
-Finally, create the bundled product:
-
-```ts highlights={bundledProductHighlights3}
-export const createBundledProducts = createWorkflow(
- "create-bundled-products",
- () => {
- // ...
- const bundledProduct = createProductsWorkflow.runAsStep({
- input: {
- products: [
- {
- title: "Bundled Clothes",
- shipping_profile_id: "sp_123",
- variants: [
- {
- title: "Bundle",
- prices: [
- {
- amount: 30,
- currency_code: "usd",
- },
- ],
- options: {
- "Default Option": "Default Variant",
- },
- inventory_items: inventoryItemIds,
- },
- ],
- options: [
- {
- title: "Default Option",
- values: ["Default Variant"],
- },
- ],
- },
- ],
- },
- }).config({ name: "create-bundled-product" })
- }
-)
-```
-
-The bundled product has the same inventory items as those of the products part of the bundle.
-
-You can now [execute the workflow](https://docs.medusajs.com/docs/learn/fundamentals/workflows#3-execute-the-workflow/index.html.md) in [API routes](https://docs.medusajs.com/docs/learn/fundamentals/api-routes/index.html.md), [scheduled jobs](https://docs.medusajs.com/docs/learn/fundamentals/scheduled-jobs/index.html.md), or [subscribers](https://docs.medusajs.com/docs/learn/fundamentals/events-and-subscribers/index.html.md).
-
-
# Links between Currency Module and Other Modules
This document showcases the module links defined between the Currency Module and other Commerce Modules.
@@ -22686,147 +22779,6 @@ const { data: stores } = useQueryGraphStep({
```
-# Links between Inventory Module and Other Modules
-
-This document showcases the module links defined between the Inventory Module and other Commerce Modules.
-
-## Summary
-
-The Inventory Module has the following links to other modules:
-
-Read-only links are used to query data across modules, but the relations aren't stored in a pivot table in the database.
-
-|First Data Model|Second Data Model|Type|Description|
-|---|---|---|---|
-|ProductVariant|InventoryItem|Stored - many-to-many|Learn more|
-|InventoryLevel|StockLocation|Read-only - has many|Learn more|
-
-***
-
-## Product Module
-
-Each product variant has different inventory details. Medusa defines a link between the `ProductVariant` and `InventoryItem` data models.
-
-
-
-A product variant whose `manage_inventory` property is enabled has an associated inventory item. Through that inventory's items relations in the Inventory Module, you can manage and check the variant's inventory quantity.
-
-Learn more about product variant's inventory management in [this guide](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/product/variant-inventory/index.html.md).
-
-### Retrieve with Query
-
-To retrieve the product variants of an inventory item with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `variants.*` in `fields`:
-
-### query.graph
-
-```ts
-const { data: inventoryItems } = await query.graph({
- entity: "inventory_item",
- fields: [
- "variants.*",
- ],
-})
-
-// inventoryItems[0].variants
-```
-
-### useQueryGraphStep
-
-```ts
-import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
-
-// ...
-
-const { data: inventoryItems } = useQueryGraphStep({
- entity: "inventory_item",
- fields: [
- "variants.*",
- ],
-})
-
-// inventoryItems[0].variants
-```
-
-### Manage with Link
-
-To manage the variants of an inventory item, use [Link](https://docs.medusajs.com/docs/learn/fundamentals/module-links/link/index.html.md):
-
-### link.create
-
-```ts
-import { Modules } from "@medusajs/framework/utils"
-
-// ...
-
-await link.create({
- [Modules.PRODUCT]: {
- variant_id: "variant_123",
- },
- [Modules.INVENTORY]: {
- inventory_item_id: "iitem_123",
- },
-})
-```
-
-### createRemoteLinkStep
-
-```ts
-import { Modules } from "@medusajs/framework/utils"
-import { createRemoteLinkStep } from "@medusajs/medusa/core-flows"
-
-// ...
-
-createRemoteLinkStep({
- [Modules.PRODUCT]: {
- variant_id: "variant_123",
- },
- [Modules.INVENTORY]: {
- inventory_item_id: "iitem_123",
- },
-})
-```
-
-***
-
-## Stock Location Module
-
-Medusa defines a read-only link between the `InventoryLevel` data model and the [Stock Location Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/stock-location/index.html.md)'s `StockLocation` data model. This means you can retrieve the details of an inventory level's stock locations, but you don't manage the links in a pivot table in the database. The stock location of an inventory level is determined by the `location_id` property of the `InventoryLevel` data model.
-
-### Retrieve with Query
-
-To retrieve the stock locations of an inventory level with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `stock_locations.*` in `fields`:
-
-### query.graph
-
-```ts
-const { data: inventoryLevels } = await query.graph({
- entity: "inventory_level",
- fields: [
- "stock_locations.*",
- ],
-})
-
-// inventoryLevels[0].stock_locations
-```
-
-### useQueryGraphStep
-
-```ts
-import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
-
-// ...
-
-const { data: inventoryLevels } = useQueryGraphStep({
- entity: "inventory_level",
- fields: [
- "stock_locations.*",
- ],
-})
-
-// inventoryLevels[0].stock_locations
-```
-
-
# Cart Concepts
In this document, you’ll get an overview of the main concepts of a cart.
@@ -23496,1399 +23448,48 @@ await cartModuleService.setLineItemTaxLines(
```
-# Authentication Flows with the Auth Main Service
+# Customer Accounts
-In this document, you'll learn how to use the Auth Module's main service's methods to implement authentication flows and reset a user's password.
+In this document, you’ll learn how registered and unregistered accounts are distinguished in the Medusa application.
-## Authentication Methods
+Refer to this [Medusa Admin User Guide](https://docs.medusajs.com/user-guide/customers/index.html.md) to learn how to manage customers using the dashboard.
-### Register
+## `has_account` Property
-The [register method of the Auth Module's main service](https://docs.medusajs.com/references/auth/register/index.html.md) creates an auth identity that can be authenticated later.
+The [Customer data model](https://docs.medusajs.com/references/customer/models/Customer/index.html.md) has a `has_account` property, which is a boolean that indicates whether a customer is registered.
-For example:
+When a guest customer places an order, a new `Customer` record is created with `has_account` set to `false`.
-```ts
-const data = await authModuleService.register(
- "emailpass",
- // passed to auth provider
- {
- // ...
- }
-)
-```
-
-This method calls the `register` method of the provider specified in the first parameter and returns its data.
-
-### Authenticate
-
-To authenticate a user, you use the [authenticate method of the Auth Module's main service](https://docs.medusajs.com/references/auth/authenticate/index.html.md). For example:
-
-```ts
-const data = await authModuleService.authenticate(
- "emailpass",
- // passed to auth provider
- {
- // ...
- }
-)
-```
-
-This method calls the `authenticate` method of the provider specified in the first parameter and returns its data.
+When this or another guest customer registers an account with the same email, a new `Customer` record is created with `has_account` set to `true`.
***
-## Auth Flow 1: Basic Authentication
+## Email Uniqueness
-The basic authentication flow requires first using the `register` method, then the `authenticate` method:
+The above behavior means that two `Customer` records may exist with the same email. However, the main difference is the `has_account` property's value.
-```ts
-const { success, authIdentity, error } = await authModuleService.register(
- "emailpass",
- // passed to auth provider
- {
- // ...
- }
-)
+So, there can only be one guest customer (having `has_account=false`) and one registered customer (having `has_account=true`) with the same email.
-if (error) {
- // registration failed
- // TODO return an error
- return
-}
-// later (can be another route for log-in)
-const { success, authIdentity, location } = await authModuleService.authenticate(
- "emailpass",
- // passed to auth provider
- {
- // ...
- }
-)
+# Links between Customer Module and Other Modules
-if (success && !location) {
- // user is authenticated
-}
-```
-
-If `success` is true and `location` isn't set, the user is authenticated successfully, and their authentication details are available within the `authIdentity` object.
-
-The next section explains the flow if `location` is set.
-
-Check out the [AuthIdentity](https://docs.medusajs.com/references/auth/models/AuthIdentity/index.html.md) reference for the received properties in `authIdentity`.
-
-
-
-### Auth Identity with Same Identifier
-
-If an auth identity, such as a `customer`, tries to register with an email of another auth identity, the `register` method returns an error. This can happen either if another customer is using the same email, or an admin user has the same email.
-
-There are two ways to handle this:
-
-- Consider the customer authenticated if the `authenticate` method validates that the email and password are correct. This allows admin users, for example, to authenticate as customers.
-- Return an error message to the customer, informing them that the email is already in use.
-
-***
-
-## Auth Flow 2: Third-Party Service Authentication
-
-The third-party service authentication method requires using the `authenticate` method first:
-
-```ts
-const { success, authIdentity, location } = await authModuleService.authenticate(
- "google",
- // passed to auth provider
- {
- // ...
- }
-)
-
-if (location) {
- // return the location for the front-end to redirect to
-}
-
-if (!success) {
- // authentication failed
-}
-
-// authentication successful
-```
-
-If the `authenticate` method returns a `location` property, the authentication process requires the user to perform an action with a third-party service. So, you return the `location` to the front-end or client to redirect to that URL.
-
-For example, when using the `google` provider, the `location` is the URL that the user is navigated to login.
-
-
-
-### Overriding Callback URL
-
-The Google and GitHub providers allow you to override their `callbackUrl` option during authentication. This is useful when you redirect the user after authentication to a URL based on its actor type. For example, you redirect admin users and customers to different pages.
-
-```ts
-const { success, authIdentity, location } = await authModuleService.authenticate(
- "google",
- // passed to auth provider
- {
- // ...
- callback_url: "example.com",
- }
-)
-```
-
-### validateCallback
-
-Providers handling this authentication flow must implement the `validateCallback` method. It implements the logic to validate the authentication with the third-party service.
-
-So, once the user performs the required action with the third-party service (for example, log-in with Google), the frontend must redirect to an API route that uses the [validateCallback method of the Auth Module's main service](https://docs.medusajs.com/references/auth/validateCallback/index.html.md).
-
-The method calls the specified provider’s `validateCallback` method passing it the authentication details it received in the second parameter:
-
-```ts
-const { success, authIdentity } = await authModuleService.validateCallback(
- "google",
- // passed to auth provider
- {
- // request data, such as
- url,
- headers,
- query,
- body,
- protocol,
- }
-)
-
-if (success) {
- // authentication succeeded
-}
-```
-
-For providers like Google, the `query` object contains the query parameters from the original callback URL, such as the `code` and `state` parameters.
-
-If the returned `success` property is `true`, the authentication with the third-party provider was successful.
-
-
-
-***
-
-## Reset Password
-
-To update a user's password or other authentication details, use the `updateProvider` method of the Auth Module's main service. It calls the `update` method of the specified authentication provider.
-
-For example:
-
-```ts
-const { success } = await authModuleService.updateProvider(
- "emailpass",
- // passed to the auth provider
- {
- entity_id: "user@example.com",
- password: "supersecret",
- }
-)
-
-if (success) {
- // password reset successfully
-}
-```
-
-The method accepts as a first parameter the ID of the provider, and as a second parameter the data necessary to reset the password.
-
-In the example above, you use the `emailpass` provider, so you have to pass an object having an `email` and `password` properties.
-
-If the returned `success` property is `true`, the password has reset successfully.
-
-
-# Auth Identity and Actor Types
-
-In this document, you’ll learn about concepts related to identity and actors in the Auth Module.
-
-## What is an Auth Identity?
-
-The [AuthIdentity data model](https://docs.medusajs.com/references/auth/models/AuthIdentity/index.html.md) represents a user registered by an [authentication provider](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/auth/auth-providers/index.html.md). When a user is registered using an authentication provider, the provider creates a record of `AuthIdentity`.
-
-Then, when the user logs-in in the future with the same authentication provider, the associated auth identity is used to validate their credentials.
-
-***
-
-## Actor Types
-
-An actor type is a type of user that can be authenticated. The Auth Module doesn't store or manage any user-like models, such as for customers or users. Instead, the user types are created and managed by other modules. For example, a customer is managed by the [Customer Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/customer/index.html.md).
-
-Then, when an auth identity is created for the actor type, the ID of the user is stored in the `app_metadata` property of the auth identity.
-
-For example, an auth identity of a customer has the following `app_metadata` property:
-
-```json
-{
- "app_metadata": {
- "customer_id": "cus_123"
- }
-}
-```
-
-The ID of the user is stored in the key `{actor_type}_id` of the `app_metadata` property.
-
-***
-
-## Protect Routes by Actor Type
-
-When you protect routes with the `authenticate` middleware, you specify in its first parameter the actor type that must be authenticated to access the specified API routes.
-
-For example:
-
-```ts title="src/api/middlewares.ts" highlights={highlights}
-import {
- defineMiddlewares,
- authenticate,
-} from "@medusajs/framework/http"
-
-export default defineMiddlewares({
- routes: [
- {
- matcher: "/custom/admin*",
- middlewares: [
- authenticate("user", ["session", "bearer", "api-key"]),
- ],
- },
- ],
-})
-```
-
-By specifying `user` as the first parameter of `authenticate`, only authenticated users of actor type `user` (admin users) can access API routes starting with `/custom/admin`.
-
-***
-
-## Custom Actor Types
-
-You can define custom actor types that allows a custom user, managed by your custom module, to authenticate into Medusa.
-
-For example, if you have a custom module with a `Manager` data model, you can authenticate managers with the `manager` actor type.
-
-Learn how to create a custom actor type in [this guide](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/auth/create-actor-type/index.html.md).
-
-
-# How to Use Authentication Routes
-
-In this document, you'll learn about the authentication routes and how to use them to create and log-in users, and reset their password.
-
-These routes are added by Medusa's HTTP layer, not the Auth Module.
-
-## Types of Authentication Flows
-
-### 1. Basic Authentication Flow
-
-This authentication flow doesn't require validation with third-party services.
-
-[How to register customer in storefront using basic authentication flow](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/storefront-development/customers/register/index.html.md).
-
-The steps are:
-
-
-
-1. Register the user with the [Register Route](#register-route).
-2. Use the authentication token to create the user with their respective API route.
- - For example, for customers you would use the [Create Customer API route](https://docs.medusajs.com/api/store#customers_postcustomers).
- - For admin users, you accept an invite using the [Accept Invite API route](https://docs.medusajs.com/api/admin#invites_postinvitesaccept)
-3. Authenticate the user with the [Auth Route](#login-route).
-
-After registration, you only use the [Auth Route](#login-route) for subsequent authentication.
-
-To handle errors related to existing identities, refer to [this section](#handling-existing-identities).
-
-### 2. Third-Party Service Authenticate Flow
-
-This authentication flow authenticates the user with a third-party service, such as Google.
-
-[How to authenticate customer with a third-party provider in the storefront.](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/storefront-development/customers/third-party-login/index.html.md).
-
-It requires the following steps:
-
-
-
-1. Authenticate the user with the [Auth Route](#login-route).
-2. The auth route returns a URL to authenticate with third-party service, such as login with Google. The frontend (such as a storefront), when it receives a `location` property in the response, must redirect to the returned location.
-3. Once the authentication with the third-party service finishes, it redirects back to the frontend with a `code` query parameter. So, make sure your third-party service is configured to redirect to your frontend page after successful authentication.
-4. The frontend sends a request to the [Validate Callback Route](#validate-callback-route) passing it the query parameters received from the third-party service, such as the `code` and `state` query parameters.
-5. If the callback validation is successful, the frontend receives the authentication token.
-6. Decode the received token in the frontend using tools like [react-jwt](https://www.npmjs.com/package/react-jwt).
- - If the decoded data has an `actor_id` property, then the user is already registered. So, use this token for subsequent authenticated requests.
- - If not, follow the rest of the steps.
-7. The frontend uses the authentication token to create the user with their respective API route.
- - For example, for customers you would use the [Create Customer API route](https://docs.medusajs.com/api/store#customers_postcustomers).
- - For admin users, you accept an invite using the [Accept Invite API route](https://docs.medusajs.com/api/admin#invites_postinvitesaccept)
-8. The frontend sends a request to the [Refresh Token Route](#refresh-token-route) to retrieve a new token with the user information populated.
-
-***
-
-## Register Route
-
-The Medusa application defines an API route at `/auth/{actor_type}/{provider}/register` that creates an auth identity for an actor type, such as a `customer`. It returns a JWT token that you pass to an API route that creates the user.
-
-```bash
-curl -X POST http://localhost:9000/auth/{actor_type}/{providers}/register
--H 'Content-Type: application/json' \
---data-raw '{
- "email": "Whitney_Schultz@gmail.com"
- // ...
-}'
-```
-
-This API route is useful for providers like `emailpass` that uses custom logic to authenticate a user. For authentication providers that authenticate with third-party services, such as Google, use the [Auth Route](#login-route) instead.
-
-For example, if you're registering a customer, you:
-
-1. Send a request to `/auth/customer/emailpass/register` to retrieve the registration JWT token.
-2. Send a request to the [Create Customer API route](https://docs.medusajs.com/api/store#customers_postcustomers) to create the customer, passing the [JWT token in the header](https://docs.medusajs.com/api/store#authentication).
-
-### Path Parameters
-
-Its path parameters are:
-
-- `{actor_type}`: the actor type of the user you're authenticating. For example, `customer`.
-- `{provider}`: the auth provider to handle the authentication. For example, `emailpass`.
-
-### Request Body Parameters
-
-This route accepts in the request body the data that the specified authentication provider requires to handle authentication.
-
-For example, the EmailPass provider requires an `email` and `password` fields in the request body.
-
-### Response Fields
-
-If the authentication is successful, you'll receive a `token` field in the response body object:
-
-```json
-{
- "token": "..."
-}
-```
-
-Use that token in the header of subsequent requests to send authenticated requests.
-
-### Handling Existing Identities
-
-An auth identity with the same email may already exist in Medusa. This can happen if:
-
-- Another actor type is using that email. For example, an admin user is trying to register as a customer.
-- The same email belongs to a record of the same actor type. For example, another customer has the same email.
-
-In these scenarios, the Register Route will return an error instead of a token:
-
-```json
-{
- "type": "unauthorized",
- "message": "Identity with email already exists"
-}
-```
-
-To handle these scenarios, you can use the [Login Route](#login-route) to validate that the email and password match the existing identity. If so, you can allow the admin user, for example, to register as a customer.
-
-Otherwise, if the email and password don't match the existing identity, such as when the email belongs to another customer, the [Login Route](#login-route) returns an error:
-
-```json
-{
- "type": "unauthorized",
- "message": "Invalid email or password"
-}
-```
-
-You can show that error message to the customer.
-
-***
-
-## Login Route
-
-The Medusa application defines an API route at `/auth/{actor_type}/{provider}` that authenticates a user of an actor type. It returns a JWT token that can be passed in [the header of subsequent requests](https://docs.medusajs.com/api/store#authentication) to send authenticated requests.
-
-```bash
-curl -X POST http://localhost:9000/auth/{actor_type}/{providers}
--H 'Content-Type: application/json' \
---data-raw '{
- "email": "Whitney_Schultz@gmail.com"
- // ...
-}'
-```
-
-For example, if you're authenticating a customer, you send a request to `/auth/customer/emailpass`.
-
-### Path Parameters
-
-Its path parameters are:
-
-- `{actor_type}`: the actor type of the user you're authenticating. For example, `customer`.
-- `{provider}`: the auth provider to handle the authentication. For example, `emailpass`.
-
-### Request Body Parameters
-
-This route accepts in the request body the data that the specified authentication provider requires to handle authentication.
-
-For example, the EmailPass provider requires an `email` and `password` fields in the request body.
-
-#### Overriding Callback URL
-
-For the [GitHub](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/auth/auth-providers/github/index.html.md) and [Google](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/auth/auth-providers/google/index.html.md) providers, you can pass a `callback_url` body parameter that overrides the `callbackUrl` set in the provider's configurations.
-
-This is useful if you want to redirect the user to a different URL after authentication based on their actor type. For example, you can set different `callback_url` for admin users and customers.
-
-### Response Fields
-
-If the authentication is successful, you'll receive a `token` field in the response body object:
-
-```json
-{
- "token": "..."
-}
-```
-
-Use that token in the header of subsequent requests to send authenticated requests.
-
-If the authentication requires more action with a third-party service, you'll receive a `location` property:
-
-```json
-{
- "location": "https://..."
-}
-```
-
-Redirect to that URL in the frontend to continue the authentication process with the third-party service.
-
-[How to login Customers using the authentication route](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/storefront-development/customers/login/index.html.md).
-
-***
-
-## Validate Callback Route
-
-The Medusa application defines an API route at `/auth/{actor_type}/{provider}/callback` that's useful for validating the authentication callback or redirect from third-party services like Google.
-
-```bash
-curl -X POST http://localhost:9000/auth/{actor_type}/{providers}/callback?code=123&state=456
-```
-
-Refer to the [third-party authentication flow](#2-third-party-service-authenticate-flow) section to see how this route fits into the authentication flow.
-
-### Path Parameters
-
-Its path parameters are:
-
-- `{actor_type}`: the actor type of the user you're authenticating. For example, `customer`.
-- `{provider}`: the auth provider to handle the authentication. For example, `google`.
-
-### Query Parameters
-
-This route accepts all the query parameters that the third-party service sends to the frontend after the user completes the authentication process, such as the `code` and `state` query parameters.
-
-### Response Fields
-
-If the authentication is successful, you'll receive a `token` field in the response body object:
-
-```json
-{
- "token": "..."
-}
-```
-
-In your frontend, decode the token using tools like [react-jwt](https://www.npmjs.com/package/react-jwt):
-
-- If the decoded data has an `actor_id` property, the user is already registered. So, use this token for subsequent authenticated requests.
-- If not, use the token in the header of a request that creates the user, such as the [Create Customer API route](https://docs.medusajs.com/api/store#customers_postcustomers).
-
-***
-
-## Refresh Token Route
-
-The Medusa application defines an API route at `/auth/token/refresh` that's useful after authenticating a user with a third-party service to populate the user's token with their new information.
-
-It requires the user's JWT token that they received from the authentication or callback routes.
-
-```bash
-curl -X POST http://localhost:9000/auth/token/refresh \
--H 'Authorization: Bearer {token}'
-```
-
-### Response Fields
-
-If the token was refreshed successfully, you'll receive a `token` field in the response body object:
-
-```json
-{
- "token": "..."
-}
-```
-
-Use that token in the header of subsequent requests to send authenticated requests.
-
-***
-
-## Reset Password Routes
-
-To reset a user's password:
-
-1. Generate a token using the [Generate Reset Password Token API route](#generate-reset-password-token-route).
- - The API route emits the `auth.password_reset` event, passing the token in the payload.
- - You can create a subscriber, as seen in [this guide](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/auth/reset-password/index.html.md), that listens to the event and send a notification to the user.
-2. Pass the token to the [Reset Password API route](#reset-password-route) to reset the password.
- - The URL in the user's notification should direct them to a frontend URL, which sends a request to this route.
-
-[Storefront Development: How to Reset a Customer's Password.](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/storefront-development/customers/reset-password/index.html.md)
-
-### Generate Reset Password Token Route
-
-The Medusa application defines an API route at `/auth/{actor_type}/{auth_provider}/reset-password` that emits the `auth.password_reset` event, passing the token in the payload.
-
-```bash
-curl -X POST http://localhost:9000/auth/{actor_type}/{providers}/reset-password
--H 'Content-Type: application/json' \
---data-raw '{
- "identifier": "Whitney_Schultz@gmail.com"
-}'
-```
-
-This API route is useful for providers like `emailpass` that store a user's password and use it for authentication.
-
-#### Path Parameters
-
-Its path parameters are:
-
-- `{actor_type}`: the actor type of the user you're authenticating. For example, `customer`.
-- `{provider}`: the auth provider to handle the authentication. For example, `emailpass`.
-
-#### Request Body Parameters
-
-This route accepts in the request body an object having the following property:
-
-- `identifier`: The user's identifier in the specified auth provider. For example, for the `emailpass` auth provider, you pass the user's email.
-
-#### Response Fields
-
-If the authentication is successful, the request returns a `201` response code.
-
-### Reset Password Route
-
-The Medusa application defines an API route at `/auth/{actor_type}/{auth_provider}/update` that accepts a token and, if valid, updates the user's password.
-
-```bash
-curl -X POST http://localhost:9000/auth/{actor_type}/{providers}/update
--H 'Content-Type: application/json' \
--H 'Authorization: Bearer {token}' \
---data-raw '{
- "email": "Whitney_Schultz@gmail.com",
- "password": "supersecret"
-}'
-```
-
-This API route is useful for providers like `emailpass` that store a user's password and use it for logging them in.
-
-#### Path Parameters
-
-Its path parameters are:
-
-- `{actor_type}`: the actor type of the user you're authenticating. For example, `customer`.
-- `{provider}`: the auth provider to handle the authentication. For example, `emailpass`.
-
-#### Pass Token in Authorization Header
-
-Before [Medusa v2.6](https://github.com/medusajs/medusa/releases/tag/v2.6), you passed the token as a query parameter. Now, you must pass it in the `Authorization` header.
-
-In the request's authorization header, you must pass the token generated using the [Generate Reset Password Token route](#generate-reset-password-token-route). You pass it as a bearer token.
-
-### Request Body Parameters
-
-This route accepts in the request body an object that has the data necessary for the provider to update the user's password.
-
-For the `emailpass` provider, you must pass the following properties:
-
-- `email`: The user's email.
-- `password`: The new password.
-
-### Response Fields
-
-If the authentication is successful, the request returns an object with a `success` property set to `true`:
-
-```json
-{
- "success": "true"
-}
-```
-
-
-# How to Create an Actor Type
-
-In this document, learn how to create an actor type and authenticate its associated data model.
-
-## 0. Create Module with Data Model
-
-Before creating an actor type, you must have a module with a data model representing the actor type.
-
-Learn how to create a module in [this guide](https://docs.medusajs.com/docs/learn/fundamentals/modules/index.html.md).
-
-The rest of this guide uses this `Manager` data model as an example:
-
-```ts title="src/modules/manager/models/manager.ts"
-import { model } from "@medusajs/framework/utils"
-
-const Manager = model.define("manager", {
- id: model.id().primaryKey(),
- firstName: model.text(),
- lastName: model.text(),
- email: model.text(),
-})
-
-export default Manager
-```
-
-***
-
-## 1. Create Workflow
-
-Start by creating a workflow that does two things:
-
-- Creates a record of the `Manager` data model.
-- Sets the `app_metadata` property of the associated `AuthIdentity` record based on the new actor type.
-
-For example, create the file `src/workflows/create-manager.ts`. with the following content:
-
-```ts title="src/workflows/create-manager.ts" highlights={workflowHighlights}
-import {
- createWorkflow,
- createStep,
- StepResponse,
- WorkflowResponse,
-} from "@medusajs/framework/workflows-sdk"
-import {
- setAuthAppMetadataStep,
-} from "@medusajs/medusa/core-flows"
-import ManagerModuleService from "../modules/manager/service"
-
-type CreateManagerWorkflowInput = {
- manager: {
- first_name: string
- last_name: string
- email: string
- }
- authIdentityId: string
-}
-
-const createManagerStep = createStep(
- "create-manager-step",
- async ({
- manager: managerData,
- }: Pick,
- { container }) => {
- const managerModuleService: ManagerModuleService =
- container.resolve("managerModuleService")
-
- const manager = await managerModuleService.createManager(
- managerData
- )
-
- return new StepResponse(manager)
- }
-)
-
-const createManagerWorkflow = createWorkflow(
- "create-manager",
- function (input: CreateManagerWorkflowInput) {
- const manager = createManagerStep({
- manager: input.manager,
- })
-
- setAuthAppMetadataStep({
- authIdentityId: input.authIdentityId,
- actorType: "manager",
- value: manager.id,
- })
-
- return new WorkflowResponse(manager)
- }
-)
-
-export default createManagerWorkflow
-```
-
-This workflow accepts the manager’s data and the associated auth identity’s ID as inputs. The next sections explain how the auth identity ID is retrieved.
-
-The workflow has two steps:
-
-1. Create the manager using the `createManagerStep`.
-2. Set the `app_metadata` property of the associated auth identity using the `setAuthAppMetadataStep` from Medusa's core workflows. You specify the actor type `manager` in the `actorType` property of the step’s input.
-
-***
-
-## 2. Define the Create API Route
-
-Next, you’ll use the workflow defined in the previous section in an API route that creates a manager.
-
-So, create the file `src/api/manager/route.ts` with the following content:
-
-```ts title="src/api/manager/route.ts" highlights={createRouteHighlights}
-import type {
- AuthenticatedMedusaRequest,
- MedusaResponse,
-} from "@medusajs/framework/http"
-import { MedusaError } from "@medusajs/framework/utils"
-import createManagerWorkflow from "../../workflows/create-manager"
-
-type RequestBody = {
- first_name: string
- last_name: string
- email: string
-}
-
-export async function POST(
- req: AuthenticatedMedusaRequest,
- res: MedusaResponse
-) {
- // If `actor_id` is present, the request carries
- // authentication for an existing manager
- if (req.auth_context.actor_id) {
- throw new MedusaError(
- MedusaError.Types.INVALID_DATA,
- "Request already authenticated as a manager."
- )
- }
-
- const { result } = await createManagerWorkflow(req.scope)
- .run({
- input: {
- manager: req.body,
- authIdentityId: req.auth_context.auth_identity_id,
- },
- })
-
- res.status(200).json({ manager: result })
-}
-```
-
-Since the manager must be associated with an `AuthIdentity` record, the request is expected to be authenticated, even if the manager isn’t created yet. This can be achieved by:
-
-1. Obtaining a token usng the [/auth route](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/auth/authentication-route/index.html.md).
-2. Passing the token in the bearer header of the request to this route.
-
-In the API route, you create the manager using the workflow from the previous section and return it in the response.
-
-***
-
-## 3. Apply the `authenticate` Middleware
-
-The last step is to apply the `authenticate` middleware on the API routes that require a manager’s authentication.
-
-To do that, create the file `src/api/middlewares.ts` with the following content:
-
-```ts title="src/api/middlewares.ts" highlights={middlewareHighlights}
-import {
- defineMiddlewares,
- authenticate,
-} from "@medusajs/framework/http"
-
-export default defineMiddlewares({
- routes: [
- {
- matcher: "/manager",
- method: "POST",
- middlewares: [
- authenticate("manager", ["session", "bearer"], {
- allowUnregistered: true,
- }),
- ],
- },
- {
- matcher: "/manager/me*",
- middlewares: [
- authenticate("manager", ["session", "bearer"]),
- ],
- },
- ],
-})
-```
-
-This applies middlewares on two route patterns:
-
-1. The `authenticate` middleware is applied on the `/manager` API route for `POST` requests while allowing unregistered managers. This requires that a bearer token be passed in the request to access the manager’s auth identity but doesn’t require the manager to be registered.
-2. The `authenticate` middleware is applied on all routes starting with `/manager/me`, restricting these routes to authenticated managers only.
-
-### Retrieve Manager API Route
-
-For example, create the file `src/api/manager/me/route.ts` with the following content:
-
-```ts title="src/api/manager/me/route.ts"
-import {
- AuthenticatedMedusaRequest,
- MedusaResponse,
-} from "@medusajs/framework/http"
-import ManagerModuleService from "../../../modules/manager/service"
-
-export async function GET(
- req: AuthenticatedMedusaRequest,
- res: MedusaResponse
-): Promise {
- const managerModuleService: ManagerModuleService =
- req.scope.resolve("managerModuleService")
-
- const manager = await managerModuleService.retrieveManager(
- req.auth_context.actor_id
- )
-
- res.json({ manager })
-}
-```
-
-This route is only accessible by authenticated managers. You access the manager’s ID using `req.auth_context.actor_id`.
-
-***
-
-## Test Custom Actor Type Authentication Flow
-
-To authenticate managers:
-
-1. Send a `POST` request to `/auth/manager/emailpass/register` to create an auth identity for the manager:
-
-```bash
-curl -X POST 'http://localhost:9000/auth/manager/emailpass/register' \
--H 'Content-Type: application/json' \
---data-raw '{
- "email": "manager@gmail.com",
- "password": "supersecret"
-}'
-```
-
-Copy the returned token to use it in the next request.
-
-2. Send a `POST` request to `/manager` to create a manager:
-
-```bash
-curl -X POST 'http://localhost:9000/manager' \
--H 'Content-Type: application/json' \
--H 'Authorization: Bearer {token}' \
---data-raw '{
- "first_name": "John",
- "last_name": "Doe",
- "email": "manager@gmail.com"
-}'
-```
-
-Replace `{token}` with the token returned in the previous step.
-
-3. Send a `POST` request to `/auth/manager/emailpass` again to retrieve an authenticated token for the manager:
-
-```bash
-curl -X POST 'http://localhost:9000/auth/manager/emailpass' \
--H 'Content-Type: application/json' \
---data-raw '{
- "email": "manager@gmail.com",
- "password": "supersecret"
-}'
-```
-
-4. You can now send authenticated requests as a manager. For example, send a `GET` request to `/manager/me` to retrieve the authenticated manager’s details:
-
-```bash
-curl 'http://localhost:9000/manager/me' \
--H 'Authorization: Bearer {token}'
-```
-
-Whenever you want to log in as a manager, use the `/auth/manager/emailpass` API route, as explained in step 3.
-
-***
-
-## Delete User of Actor Type
-
-When you delete a user of the actor type, you must update its auth identity to remove the association to the user.
-
-For example, create the following workflow that deletes a manager and updates its auth identity, create the file `src/workflows/delete-manager.ts` with the following content:
-
-```ts title="src/workflows/delete-manager.ts" collapsibleLines="1-6" expandButtonLabel="Show Imports"
-import {
- createStep,
- StepResponse,
-} from "@medusajs/framework/workflows-sdk"
-import ManagerModuleService from "../modules/manager/service"
-
-export type DeleteManagerWorkflow = {
- id: string
-}
-
-const deleteManagerStep = createStep(
- "delete-manager-step",
- async (
- { id }: DeleteManagerWorkflow,
- { container }) => {
- const managerModuleService: ManagerModuleService =
- container.resolve("managerModuleService")
-
- const manager = await managerModuleService.retrieve(id)
-
- await managerModuleService.deleteManagers(id)
-
- return new StepResponse(undefined, { manager })
- },
- async ({ manager }, { container }) => {
- const managerModuleService: ManagerModuleService =
- container.resolve("managerModuleService")
-
- await managerModuleService.createManagers(manager)
- }
- )
-```
-
-You add a step that deletes the manager using the `deleteManagers` method of the module's main service. In the compensation function, you create the manager again.
-
-Next, in the same file, add the workflow that deletes a manager:
-
-```ts title="src/workflows/delete-manager.ts" collapsibleLines="1-15" expandButtonLabel="Show Imports" highlights={deleteHighlights}
-// other imports
-import { MedusaError } from "@medusajs/framework/utils"
-import {
- WorkflowData,
- WorkflowResponse,
- createWorkflow,
- transform,
-} from "@medusajs/framework/workflows-sdk"
-import {
- setAuthAppMetadataStep,
- useQueryGraphStep,
-} from "@medusajs/medusa/core-flows"
-
-// ...
-
-export const deleteManagerWorkflow = createWorkflow(
- "delete-manager",
- (
- input: WorkflowData
- ): WorkflowResponse => {
- deleteManagerStep(input)
-
- const { data: authIdentities } = useQueryGraphStep({
- entity: "auth_identity",
- fields: ["id"],
- filters: {
- app_metadata: {
- // the ID is of the format `{actor_type}_id`.
- manager_id: input.id,
- },
- },
- })
-
- const authIdentity = transform(
- { authIdentities },
- ({ authIdentities }) => {
- const authIdentity = authIdentities[0]
-
- if (!authIdentity) {
- throw new MedusaError(
- MedusaError.Types.NOT_FOUND,
- "Auth identity not found"
- )
- }
-
- return authIdentity
- }
- )
-
- setAuthAppMetadataStep({
- authIdentityId: authIdentity.id,
- actorType: "manager",
- value: null,
- })
-
- return new WorkflowResponse(input.id)
- }
-)
-```
-
-In the workflow, you:
-
-1. Use the `deleteManagerStep` defined earlier to delete the manager.
-2. Retrieve the auth identity of the manager using Query. To do that, you filter the `app_metadata` property of an auth identity, which holds the user's ID under `{actor_type_name}_id`. So, in this case, it's `manager_id`.
-3. Check that the auth identity exist, then, update the auth identity to remove the ID of the manager from it.
-
-You can use this workflow when deleting a manager, such as in an API route.
-
-
-# Auth Providers
-
-In this document, you’ll learn how the Auth Module handles authentication using providers.
-
-## What's an Auth Module Provider?
-
-An auth module provider handles authenticating customers and users, either using custom logic or by integrating a third-party service.
-
-For example, the EmailPass Auth Module Provider authenticates a user using their email and password, whereas the Google Auth Module Provider authenticates users using their Google account.
-
-### Auth Providers List
-
-- [Emailpass](https://docs.medusajs.com/commerce-modules/auth/auth-providers/emailpass/index.html.md)
-- [Google](https://docs.medusajs.com/commerce-modules/auth/auth-providers/google/index.html.md)
-- [GitHub](https://docs.medusajs.com/commerce-modules/auth/auth-providers/github/index.html.md)
-
-***
-
-## Configure Allowed Auth Providers of Actor Types
-
-By default, users of all actor types can authenticate with all installed auth module providers.
-
-To restrict the auth providers used for actor types, use the [authMethodsPerActor option](https://docs.medusajs.com/docs/learn/configurations/medusa-config#httpauthMethodsPerActor/index.html.md) in Medusa's configurations:
-
-```ts title="medusa-config.ts"
-module.exports = defineConfig({
- projectConfig: {
- http: {
- authMethodsPerActor: {
- user: ["google"],
- customer: ["emailpass"],
- },
- // ...
- },
- // ...
- },
-})
-```
-
-When you specify the `authMethodsPerActor` configuration, it overrides the default. So, if you don't specify any providers for an actor type, users of that actor type can't authenticate with any provider.
-
-***
-
-## How to Create an Auth Module Provider
-
-Refer to [this guide](https://docs.medusajs.com/references/auth/provider/index.html.md) to learn how to create an auth module provider.
-
-
-# Auth Module Options
-
-In this document, you'll learn about the options of the Auth Module.
-
-## providers
-
-The `providers` option is an array of auth module providers.
-
-When the Medusa application starts, these providers are registered and can be used to handle authentication.
-
-By default, the `emailpass` provider is registered to authenticate customers and admin users.
-
-For example:
-
-```ts title="medusa-config.ts"
-import { Modules, ContainerRegistrationKeys } from "@medusajs/framework/utils"
-
-// ...
-
-module.exports = defineConfig({
- // ...
- modules: [
- {
- resolve: "@medusajs/medusa/auth",
- dependencies: [Modules.CACHE, ContainerRegistrationKeys.LOGGER],
- options: {
- providers: [
- {
- resolve: "@medusajs/medusa/auth-emailpass",
- id: "emailpass",
- options: {
- // provider options...
- },
- },
- ],
- },
- },
- ],
-})
-```
-
-The `providers` option is an array of objects that accept the following properties:
-
-- `resolve`: A string indicating the package name of the module provider or the path to it relative to the `src` directory.
-- `id`: A string indicating the provider's unique name or ID.
-- `options`: An optional object of the module provider's options.
-
-***
-
-## Auth CORS
-
-The Medusa application's authentication API routes are defined under the `/auth` prefix that requires setting the `authCors` property of the `http` configuration.
-
-By default, the Medusa application you created will have an `AUTH_CORS` environment variable, which is used as the value of `authCors`.
-
-Refer to [Medusa's configuration guide](https://docs.medusajs.com/docs/learn/configurations/medusa-config#httpauthCors/index.html.md) to learn more about the `authCors` configuration.
-
-***
-
-## authMethodsPerActor Configuration
-
-The Medusa application's configuration accept an `authMethodsPerActor` configuration which restricts the allowed auth providers used with an actor type.
-
-Learn more about the `authMethodsPerActor` configuration in [this guide](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/auth/auth-providers#configure-allowed-auth-providers-of-actor-types/index.html.md).
-
-
-# How to Handle Password Reset Token Event
-
-In this guide, you'll learn how to handle the `auth.password_reset` event, which is emitted when a request is sent to the [Generate Reset Password Token API route](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/auth/authentication-route#generate-reset-password-token-route/index.html.md).
-
-Refer to this [Medusa Admin User Guide](https://docs.medusajs.com/user-guide/reset-password/index.html.md) to learn how to reset your user admin password using the dashboard.
-
-You'll create a subscriber that listens to the event. When the event is emitted, the subscriber sends an email notification to the user.
-
-### Prerequisites
-
-- [A notification provider module, such as SendGrid](https://docs.medusajs.com/infrastructure-modules/notification/sendgrid/index.html.md)
-
-## 1. Create Subscriber
-
-The first step is to create a subscriber that listens to the `auth.password_reset` and sends the user a notification with instructions to reset their password.
-
-Create the file `src/subscribers/handle-reset.ts` with the following content:
-
-```ts title="src/subscribers/handle-reset.ts" highlights={highlights} collapsibleLines="1-6" expandMoreLabel="Show Imports"
-import {
- SubscriberArgs,
- type SubscriberConfig,
-} from "@medusajs/medusa"
-import { Modules } from "@medusajs/framework/utils"
-
-export default async function resetPasswordTokenHandler({
- event: { data: {
- entity_id: email,
- token,
- actor_type,
- } },
- container,
-}: SubscriberArgs<{ entity_id: string, token: string, actor_type: string }>) {
- const notificationModuleService = container.resolve(
- Modules.NOTIFICATION
- )
-
- const urlPrefix = actor_type === "customer" ?
- "https://storefront.com" :
- "https://admin.com/app"
-
- await notificationModuleService.createNotifications({
- to: email,
- channel: "email",
- template: "reset-password-template",
- data: {
- // a URL to a frontend application
- url: `${urlPrefix}/reset-password?token=${token}&email=${email}`,
- },
- })
-}
-
-export const config: SubscriberConfig = {
- event: "auth.password_reset",
-}
-```
-
-You subscribe to the `auth.password_reset` event. The event has a data payload object with the following properties:
-
-- `entity_id`: The identifier of the user. When using the `emailpass` provider, it's the user's email.
-- `token`: The token to reset the user's password.
-- `actor_type`: The user's actor type. For example, if the user is a customer, the `actor_type` is `customer`. If it's an admin user, the `actor_type` is `user`.
-
-This event's payload previously had an `actorType` field. It was renamed to `actor_type` after [Medusa v2.0.7](https://github.com/medusajs/medusa/releases/tag/v2.0.7).
-
-In the subscriber, you:
-
-- Decide the frontend URL based on whether the user is a customer or admin user by checking the value of `actor_type`.
-- Resolve the Notification Module and use its `createNotifications` method to send the notification.
-- You pass to the `createNotifications` method an object having the following properties:
- - `to`: The identifier to send the notification to, which in this case is the email.
- - `channel`: The channel to send the notification through, which in this case is email.
- - `template`: The template ID in the third-party service.
- - `data`: The data payload to pass to the template. You pass the URL to redirect the user to. You must pass the token and email in the URL so that the frontend can send them later to the Medusa application when reseting the password.
-
-***
-
-## 2. Test it Out: Generate Reset Password Token
-
-To test the subscriber out, send a request to the `/auth/{actor_type}/{auth_provider}/reset-password` API route, replacing `{actor_type}` and `{auth_provider}` with the user's actor type and provider used for authentication respectively.
-
-For example, to generate a reset password token for an admin user using the `emailpass` provider, send the following request:
-
-```bash
-curl --location 'http://localhost:9000/auth/user/emailpass/reset-password' \
---header 'Content-Type: application/json' \
---data-raw '{
- "identifier": "admin-test@gmail.com"
-}'
-```
-
-In the request body, you must pass an `identifier` parameter. Its value is the user's identifier, which is the email in this case.
-
-If the token is generated successfully, the request returns a response with `201` status code. In the terminal, you'll find the following message indicating that the `auth.password_reset` event was emitted and your subscriber ran:
-
-```plain
-info: Processing auth.password_reset which has 1 subscribers
-```
-
-The notification is sent to the user with the frontend URL to enter a new password.
-
-***
-
-## Next Steps: Implementing Frontend
-
-In your frontend, you must have a page that accepts `token` and `email` query parameters.
-
-The page shows the user password fields to enter their new password, then submits the new password, token, and email to the [Reset Password Route](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/auth/authentication-route#reset-password-route/index.html.md).
-
-### Examples
-
-- [Storefront Guide: Reset Customer Password](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/storefront-development/customers/reset-password/index.html.md)
-
-
-# Payment Module Options
-
-In this document, you'll learn about the options of the Payment Module.
-
-## All Module Options
-
-|Option|Description|Required|Default|
-|---|---|---|---|---|---|---|
-|\`webhook\_delay\`|A number indicating the delay in milliseconds before processing a webhook event.|No|\`5000\`|
-|\`webhook\_retries\`|The number of times to retry the webhook event processing in case of an error.|No|\`3\`|
-|\`providers\`|An array of payment providers to install and register. Learn more |No|-|
-
-***
-
-## providers Option
-
-The `providers` option is an array of payment module providers.
-
-When the Medusa application starts, these providers are registered and can be used to process payments.
-
-For example:
-
-```ts title="medusa-config.ts"
-import { Modules } from "@medusajs/framework/utils"
-
-// ...
-
-module.exports = defineConfig({
- // ...
- modules: [
- {
- resolve: "@medusajs/medusa/payment",
- options: {
- providers: [
- {
- resolve: "@medusajs/medusa/payment-stripe",
- id: "stripe",
- options: {
- // ...
- },
- },
- ],
- },
- },
- ],
-})
-```
-
-The `providers` option is an array of objects that accept the following properties:
-
-- `resolve`: A string indicating the package name of the module provider or the path to it relative to the `src` directory.
-- `id`: A string indicating the provider's unique name or ID.
-- `options`: An optional object of the module provider's options.
-
-
-# Links between Payment Module and Other Modules
-
-This document showcases the module links defined between the Payment Module and other Commerce Modules.
+This document showcases the module links defined between the Customer Module and other Commerce Modules.
## Summary
-The Payment Module has the following links to other modules:
+The Customer Module has the following links to other modules:
+
+Read-only links are used to query data across modules, but the relations aren't stored in a pivot table in the database.
|First Data Model|Second Data Model|Type|Description|
|---|---|---|---|
-|Cart|PaymentCollection|Stored - one-to-one|Learn more|
|Customer|AccountHolder|Stored - many-to-many|Learn more|
-|Order|PaymentCollection|Stored - one-to-many|Learn more|
-|OrderClaim|PaymentCollection|Stored - one-to-many|Learn more|
-|OrderExchange|PaymentCollection|Stored - one-to-many|Learn more|
-|Region|PaymentProvider|Stored - many-to-many|Learn more|
+|Cart|Customer|Read-only - has one|Learn more|
+|Order|Customer|Read-only - has one|Learn more|
***
-## Cart Module
-
-The Cart Module provides cart-related features, but not payment processing.
-
-Medusa defines a link between the `Cart` and `PaymentCollection` data models. A cart has a payment collection which holds all the authorized payment sessions and payments made related to the cart.
-
-Learn more about this relation in [this documentation](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/payment/payment-collection#usage-with-the-cart-module/index.html.md).
-
-### Retrieve with Query
-
-To retrieve the cart associated with the payment collection with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `cart.*` in `fields`:
-
-### query.graph
-
-```ts
-const { data: paymentCollections } = await query.graph({
- entity: "payment_collection",
- fields: [
- "cart.*",
- ],
-})
-
-// paymentCollections[0].cart
-```
-
-### useQueryGraphStep
-
-```ts
-import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
-
-// ...
-
-const { data: paymentCollections } = useQueryGraphStep({
- entity: "payment_collection",
- fields: [
- "cart.*",
- ],
-})
-
-// paymentCollections[0].cart
-```
-
-### Manage with Link
-
-To manage the payment collection of a cart, use [Link](https://docs.medusajs.com/docs/learn/fundamentals/module-links/link/index.html.md):
-
-### link.create
-
-```ts
-import { Modules } from "@medusajs/framework/utils"
-
-// ...
-
-await link.create({
- [Modules.CART]: {
- cart_id: "cart_123",
- },
- [Modules.PAYMENT]: {
- payment_collection_id: "paycol_123",
- },
-})
-```
-
-### createRemoteLinkStep
-
-```ts
-import { createRemoteLinkStep } from "@medusajs/medusa/core-flows"
-
-// ...
-
-createRemoteLinkStep({
- [Modules.CART]: {
- cart_id: "cart_123",
- },
- [Modules.PAYMENT]: {
- payment_collection_id: "paycol_123",
- },
-})
-```
-
-***
-
-## Customer Module
+## Payment Module
Medusa defines a link between the `Customer` and `AccountHolder` data models, allowing payment providers to save payment methods for a customer, if the payment provider supports it.
@@ -24896,19 +23497,19 @@ This link is available starting from Medusa `v2.5.0`.
### Retrieve with Query
-To retrieve the customer associated with an account holder with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `customer.*` in `fields`:
+To retrieve the account holder associated with a customer with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `customer.*` in `fields`:
### query.graph
```ts
-const { data: accountHolders } = await query.graph({
- entity: "account_holder",
+const { data: customers } = await query.graph({
+ entity: "customer",
fields: [
- "customer.*",
+ "account_holder_link.account_holder.*",
],
})
-// accountHolders[0].customer
+// customers[0].account_holder_link?.[0]?.account_holder
```
### useQueryGraphStep
@@ -24918,14 +23519,14 @@ import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
// ...
-const { data: accountHolders } = useQueryGraphStep({
- entity: "account_holder",
+const { data: customers } = useQueryGraphStep({
+ entity: "customer",
fields: [
- "customer.*",
+ "account_holder_link.account_holder.*",
],
})
-// accountHolders[0].customer
+// customers[0].account_holder_link?.[0]?.account_holder
```
### Manage with Link
@@ -24968,29 +23569,65 @@ createRemoteLinkStep({
***
+## Cart Module
+
+Medusa defines a read-only link between the [Cart Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/cart/index.html.md)'s `Cart` data model and the `Customer` data model. Because the link is read-only from the `Cart`'s side, you can only retrieve the customer of a cart, and not the other way around.
+
+### Retrieve with Query
+
+To retrieve the customer of a cart with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `customer.*` in `fields`:
+
+### query.graph
+
+```ts
+const { data: carts } = await query.graph({
+ entity: "cart",
+ fields: [
+ "customer.*",
+ ],
+})
+
+// carts.customer
+```
+
+### useQueryGraphStep
+
+```ts
+import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
+
+// ...
+
+const { data: carts } = useQueryGraphStep({
+ entity: "cart",
+ fields: [
+ "customer.*",
+ ],
+})
+
+// carts.customer
+```
+
+***
+
## Order Module
-An order's payment details are stored in a payment collection. This also applies for claims and exchanges.
-
-So, Medusa defines links between the `PaymentCollection` data model and the `Order`, `OrderClaim`, and `OrderExchange` data models.
-
-
+Medusa defines a read-only link between the [Order Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/order/index.html.md)'s `Order` data model and the `Customer` data model. Because the link is read-only from the `Order`'s side, you can only retrieve the customer of an order, and not the other way around.
### Retrieve with Query
-To retrieve the order of a payment collection with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `order.*` in `fields`:
+To retrieve the customer of an order with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `customer.*` in `fields`:
### query.graph
```ts
-const { data: paymentCollections } = await query.graph({
- entity: "payment_collection",
+const { data: orders } = await query.graph({
+ entity: "order",
fields: [
- "order.*",
+ "customer.*",
],
})
-// paymentCollections[0].order
+// orders.customer
```
### useQueryGraphStep
@@ -25000,1007 +23637,193 @@ import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
// ...
-const { data: paymentCollections } = useQueryGraphStep({
- entity: "payment_collection",
+const { data: orders } = useQueryGraphStep({
+ entity: "order",
fields: [
- "order.*",
+ "customer.*",
],
})
-// paymentCollections[0].order
+// orders.customer
```
-### Manage with Link
-To manage the payment collections of an order, use [Link](https://docs.medusajs.com/docs/learn/fundamentals/module-links/link/index.html.md):
+# Fulfillment Module Provider
-### link.create
+In this document, you’ll learn what a fulfillment module provider is.
-```ts
-import { Modules } from "@medusajs/framework/utils"
+Refer to this [Medusa Admin User Guide](https://docs.medusajs.com/user-guide/settings/locations-and-shipping/locations#manage-fulfillment-providers/index.html.md) to learn how to add a fulfillment provider to a location using the dashboard.
-// ...
+## What’s a Fulfillment Module Provider?
-await link.create({
- [Modules.ORDER]: {
- order_id: "order_123",
- },
- [Modules.PAYMENT]: {
- payment_collection_id: "paycol_123",
- },
-})
-```
+A fulfillment module provider handles fulfilling items, typically using a third-party integration.
-### createRemoteLinkStep
-
-```ts
-import { Modules } from "@medusajs/framework/utils"
-import { createRemoteLinkStep } from "@medusajs/medusa/core-flows"
-
-// ...
-
-createRemoteLinkStep({
- [Modules.ORDER]: {
- order_id: "order_123",
- },
- [Modules.PAYMENT]: {
- payment_collection_id: "paycol_123",
- },
-})
-```
+Fulfillment module providers registered in the Fulfillment Module's [options](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/fulfillment/module-options/index.html.md) are stored and represented by the [FulfillmentProvider data model](https://docs.medusajs.com/references/fulfillment/models/FulfillmentProvider/index.html.md).
***
-## Region Module
+## Configure Fulfillment Providers
-You can specify for each region which payment providers are available. The Medusa application defines a link between the `PaymentProvider` and the `Region` data models.
+The Fulfillment Module accepts a `providers` option that allows you to register providers in your application.
-
-
-This increases the flexibility of your store. For example, you only show during checkout the payment providers associated with the cart's region.
-
-### Retrieve with Query
-
-To retrieve the regions of a payment provider with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `regions.*` in `fields`:
-
-### query.graph
-
-```ts
-const { data: paymentProviders } = await query.graph({
- entity: "payment_provider",
- fields: [
- "regions.*",
- ],
-})
-
-// paymentProviders[0].regions
-```
-
-### useQueryGraphStep
-
-```ts
-import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
-
-// ...
-
-const { data: paymentProviders } = useQueryGraphStep({
- entity: "payment_provider",
- fields: [
- "regions.*",
- ],
-})
-
-// paymentProviders[0].regions
-```
-
-### Manage with Link
-
-To manage the payment providers in a region, use [Link](https://docs.medusajs.com/docs/learn/fundamentals/module-links/link/index.html.md):
-
-### link.create
-
-```ts
-import { Modules } from "@medusajs/framework/utils"
-
-// ...
-
-await link.create({
- [Modules.REGION]: {
- region_id: "reg_123",
- },
- [Modules.PAYMENT]: {
- payment_provider_id: "pp_stripe_stripe",
- },
-})
-```
-
-### createRemoteLinkStep
-
-```ts
-import { Modules } from "@medusajs/framework/utils"
-import { createRemoteLinkStep } from "@medusajs/medusa/core-flows"
-
-// ...
-
-createRemoteLinkStep({
- [Modules.REGION]: {
- region_id: "reg_123",
- },
- [Modules.PAYMENT]: {
- payment_provider_id: "pp_stripe_stripe",
- },
-})
-```
-
-
-# Payment
-
-In this document, you’ll learn what a payment is and how it's created, captured, and refunded.
-
-## What's a Payment?
-
-When a payment session is authorized, a payment, represented by the [Payment data model](https://docs.medusajs.com/references/payment/models/Payment/index.html.md), is created. This payment can later be captured or refunded.
-
-A payment carries many of the data and relations of a payment session:
-
-- It belongs to the same payment collection.
-- It’s associated with the same payment provider, which handles further payment processing.
-- It stores the payment session’s `data` property in its `data` property, as it’s still useful for the payment provider’s processing.
+Learn more about the `providers` option in [this documentation](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/fulfillment/module-options/index.html.md).
***
-## Capture Payments
+## How to Create a Fulfillment Provider?
-When a payment is captured, a capture, represented by the [Capture data model](https://docs.medusajs.com/references/payment/models/Capture/index.html.md), is created. It holds details related to the capture, such as the amount, the capture date, and more.
-
-The payment can also be captured incrementally, each time a capture record is created for that amount.
-
-
-
-***
-
-## Refund Payments
-
-When a payment is refunded, a refund, represented by the [Refund data model](https://docs.medusajs.com/references/payment/models/Refund/index.html.md), is created. It holds details related to the refund, such as the amount, refund date, and more.
-
-A payment can be refunded multiple times, and each time a refund record is created.
-
-
+Refer to [this guide](https://docs.medusajs.com/references/fulfillment/provider/index.html.md) to learn how to create a fulfillment module provider.
-# Payment Collection
+# Fulfillment Concepts
-In this document, you’ll learn what a payment collection is and how the Medusa application uses it with the Cart Module.
+In this document, you’ll learn about some basic fulfillment concepts.
-## What's a Payment Collection?
+## Fulfillment Set
-A payment collection stores payment details related to a resource, such as a cart or an order. It’s represented by the [PaymentCollection data model](https://docs.medusajs.com/references/payment/models/PaymentCollection/index.html.md).
+A fulfillment set is a general form or way of fulfillment. For example, shipping is a form of fulfillment, and pick-up is another form of fulfillment. Each of these can be created as fulfillment sets.
-Every purchase or request for payment starts with a payment collection. The collection holds details necessary to complete the payment, including:
-
-- The [payment sessions](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/payment/payment-session/index.html.md) that represents the payment amount to authorize.
-- The [payments](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/payment/payment/index.html.md) that are created when a payment session is authorized. They can be captured and refunded.
-- The [payment providers](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/payment/payment-provider/index.html.md) that handle the processing of each payment session, including the authorization, capture, and refund.
-
-***
-
-## Multiple Payments
-
-The payment collection supports multiple payment sessions and payments.
-
-You can use this to accept payments in increments or split payments across payment providers.
-
-
-
-***
-
-## Usage with the Cart Module
-
-The Cart Module provides cart management features. However, it doesn’t provide any features related to accepting payment.
-
-During checkout, the Medusa application links a cart to a payment collection, which will be used for further payment processing.
-
-It also implements the payment flow during checkout as explained in [this documentation](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/payment/payment-flow/index.html.md).
-
-
-
-
-# Accept Payment Flow
-
-In this document, you’ll learn how to implement an accept-payment flow using workflows or the Payment Module's main service.
-
-It's highly recommended to use Medusa's workflows to implement this flow. Use the Payment Module's main service for more complex cases.
-
-For a guide on how to implement this flow in the storefront, check out [this guide](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/storefront-development/checkout/payment/index.html.md).
-
-## Flow Overview
-
-
-
-***
-
-## 1. Create a Payment Collection
-
-A payment collection holds all details related to a resource’s payment operations. So, you start off by creating a payment collection.
-
-For example:
-
-### Using Workflow
+A fulfillment set is represented by the [FulfillmentSet data model](https://docs.medusajs.com/references/fulfillment/models/FulfillmentSet/index.html.md). All other configurations, options, and management features are related to a fulfillment set, in one way or another.
```ts
-import { createPaymentCollectionForCartWorkflow } from "@medusajs/medusa/core-flows"
-
-// ...
-
-await createPaymentCollectionForCartWorkflow(req.scope)
- .run({
- input: {
- cart_id: "cart_123",
- },
- })
-```
-
-### Using Service
-
-```ts
-const paymentCollection =
- await paymentModuleService.createPaymentCollections({
- currency_code: "usd",
- amount: 5000,
- })
-```
-
-***
-
-## 2. Create Payment Sessions
-
-The payment collection has one or more payment sessions, each being a payment amount to be authorized by a payment provider.
-
-So, after creating the payment collection, create at least one payment session for a provider.
-
-For example:
-
-### Using Workflow
-
-```ts
-import { createPaymentSessionsWorkflow } from "@medusajs/medusa/core-flows"
-
-// ...
-
-const { result: paymentSesion } = await createPaymentSessionsWorkflow(req.scope)
- .run({
- input: {
- payment_collection_id: "paycol_123",
- provider_id: "stripe",
- },
- })
-```
-
-### Using Service
-
-```ts
-const paymentSession =
- await paymentModuleService.createPaymentSession(
- paymentCollection.id,
+const fulfillmentSets = await fulfillmentModuleService.createFulfillmentSets(
+ [
{
- provider_id: "stripe",
- currency_code: "usd",
- amount: 5000,
- data: {
- // any necessary data for the
- // payment provider
- },
- }
- )
+ name: "Shipping",
+ type: "shipping",
+ },
+ {
+ name: "Pick-up",
+ type: "pick-up",
+ },
+ ]
+)
```
***
-## 3. Authorize Payment Session
+## Service Zone
-Once the customer chooses a payment session, start the authorization process. This may involve some action performed by the third-party payment provider, such as entering a 3DS code.
+A service zone is a collection of geographical zones or areas. It’s used to restrict available shipping options to a defined set of locations.
-For example:
+A service zone is represented by the [ServiceZone data model](https://docs.medusajs.com/references/fulfillment/models/ServiceZone/index.html.md). It’s associated with a fulfillment set, as each service zone is specific to a form of fulfillment. For example, if a customer chooses to pick up items, you can restrict the available shipping options based on their location.
-### Using Step
+
-```ts
-import { authorizePaymentSessionStep } from "@medusajs/medusa/core-flows"
+A service zone can have multiple geographical zones, each represented by the [GeoZone data model](https://docs.medusajs.com/references/fulfillment/models/GeoZone/index.html.md). It holds location-related details to narrow down supported areas, such as country, city, or province code.
-// ...
-
-authorizePaymentSessionStep({
- id: "payses_123",
- context: {},
-})
-```
-
-### Using Service
-
-```ts
-const payment = authorizePaymentSessionStep({
- id: "payses_123",
- context: {},
-})
-```
-
-When the payment authorization is successful, a payment is created and returned.
-
-### Handling Additional Action
-
-If you used the `authorizePaymentSessionStep`, you don't need to implement this logic as it's implemented in the step.
-
-If the payment authorization isn’t successful, whether because it requires additional action or for another reason, the method updates the payment session with the new status and throws an error.
-
-In that case, you can catch that error and, if the session's `status` property is `requires_more`, handle the additional action, then retry the authorization.
-
-For example:
-
-```ts
-try {
- const payment =
- await paymentModuleService.authorizePaymentSession(
- paymentSession.id,
- {}
- )
-} catch (e) {
- // retrieve the payment session again
- const updatedPaymentSession = (
- await paymentModuleService.listPaymentSessions({
- id: [paymentSession.id],
- })
- )[0]
-
- if (updatedPaymentSession.status === "requires_more") {
- // TODO perform required action
- // TODO authorize payment again.
- }
-}
-```
+The province code is always in lower-case and in [ISO 3166-2 format](https://en.wikipedia.org/wiki/ISO_3166-2).
***
-## 4. Payment Flow Complete
+## Shipping Profile
-The payment flow is complete once the payment session is authorized and the payment is created.
+A shipping profile defines a type of items that are shipped in a similar manner. For example, a `default` shipping profile is used for all item types, but the `digital` shipping profile is used for digital items that aren’t shipped and delivered conventionally.
-You can then:
-
-- Capture the payment either using the [capturePaymentWorkflow](https://docs.medusajs.com/references/medusa-workflows/capturePaymentWorkflow/index.html.md) or [capturePayment method](https://docs.medusajs.com/references/payment/capturePayment/index.html.md).
-- Refund captured amounts using the [refundPaymentWorkflow](https://docs.medusajs.com/references/medusa-workflows/refundPaymentWorkflow/index.html.md) or [refundPayment method](https://docs.medusajs.com/references/payment/refundPayment/index.html.md).
-
-Some payment providers allow capturing the payment automatically once it’s authorized. In that case, you don’t need to do it manually.
+A shipping profile is represented by the [ShippingProfile data model](https://docs.medusajs.com/references/fulfillment/models/ShippingProfile/index.html.md). It only defines the profile’s details, but it’s associated with the shipping options available for the item type.
-# Account Holders and Saved Payment Methods
+# Item Fulfillment
-In this documentation, you'll learn about account holders, and how they're used to save payment methods in third-party payment providers.
+In this document, you’ll learn about the concepts of item fulfillment.
-Account holders are available starting from Medusa `v2.5.0`.
+## Fulfillment Data Model
-## What's an Account Holder?
-
-An account holder represents a customer that can have saved payment methods in a third-party service. It's represented by the `AccountHolder` data model.
-
-It holds fields retrieved from the third-party provider, such as:
-
-- `external_id`: The ID of the equivalent customer or account holder in the third-party provider.
-- `data`: Data returned by the payment provider when the account holder is created.
-
-A payment provider that supports saving payment methods for customers would create the equivalent of an account holder in the third-party provider. Then, whenever a payment method is saved, it would be saved under the account holder in the third-party provider.
-
-### Relation between Account Holder and Customer
-
-The Medusa application creates a link between the [Customer](https://docs.medusajs.com/references/customer/models/Customer/index.html.md) data model of the [Customer Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/customer/index.html.md) and the `AccountHolder` data model of the Payment Module.
-
-This link indicates that a customer can have more than one account holder, each representing saved payment methods in different payment providers.
-
-Learn more about this link in the [Link to Other Modules](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/payment/links-to-other-modules/index.html.md) guide.
+A fulfillment is the shipping and delivery of one or more items to the customer. It’s represented by the [Fulfillment data model](https://docs.medusajs.com/references/fulfillment/models/Fulfillment/index.html.md).
***
-## Save Payment Methods
+## Fulfillment Processing by a Fulfillment Provider
-If a payment provider supports saving payment methods for a customer, they must implement the following methods:
+A fulfillment is associated with a fulfillment provider that handles all its processing, such as creating a shipment for the fulfillment’s items.
-- `createAccountHolder`: Creates an account holder in the payment provider. The Payment Module uses this method before creating the account holder in Medusa, and uses the returned data to set fields like `external_id` and `data` in the created `AccountHolder` record.
-- `deleteAccountHolder`: Deletes an account holder in the payment provider. The Payment Module uses this method when an account holder is deleted in Medusa.
-- `savePaymentMethod`: Saves a payment method for an account holder in the payment provider.
-- `listPaymentMethods`: Lists saved payment methods in the third-party service for an account holder. This is useful when displaying the customer's saved payment methods in the storefront.
+The fulfillment is also associated with a shipping option of that provider, which determines how the item is shipped.
-Learn more about implementing these methods in the [Create Payment Provider guide](https://docs.medusajs.com/references/payment/provider/index.html.md).
-
-***
-
-## Account Holder in Medusa Payment Flows
-
-In the Medusa application, when a payment session is created for a registered customer, the Medusa application uses the Payment Module to create an account holder for the customer.
-
-Consequently, the Payment Module uses the payment provider to create an account holder in the third-party service, then creates the account holder in Medusa.
-
-This flow is only supported if the chosen payment provider has implemented the necessary [save payment methods](#save-payment-methods).
-
-
-# Payment Module Provider
-
-In this document, you’ll learn what a payment module provider is.
-
-Refer to this [Medusa Admin User Guide](https://docs.medusajs.com/user-guide/settings/regions/index.html.md) to learn how to manage the payment providers available in a region using the dashboard.
-
-## What's a Payment Module Provider?
-
-A payment module provider registers a payment provider that handles payment processing in the Medusa application. It integrates third-party payment providers, such as Stripe.
-
-To authorize a payment amount with a payment provider, a payment session is created and associated with that payment provider. The payment provider is then used to handle the authorization.
-
-After the payment session is authorized, the payment provider is associated with the resulting payment and handles its payment processing, such as to capture or refund payment.
-
-### List of Payment Module Providers
-
-- [Stripe](https://docs.medusajs.com/commerce-modules/payment/payment-provider/stripe/index.html.md)
-
-***
-
-## System Payment Provider
-
-The Payment Module provides a `system` payment provider that acts as a placeholder payment provider.
-
-It doesn’t handle payment processing and delegates that to the merchant. It acts similarly to a cash-on-delivery (COD) payment method.
-
-***
-
-## How are Payment Providers Created?
-
-A payment provider is a module whose main service extends the `AbstractPaymentProvider` imported from `@medusajs/framework/utils`.
-
-Refer to [this guide](https://docs.medusajs.com/references/payment/provider/index.html.md) on how to create a payment provider for the Payment Module.
-
-***
-
-## Configure Payment Providers
-
-The Payment Module accepts a `providers` option that allows you to register providers in your application.
-
-Learn more about this option in [this documentation](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/payment/module-options#providers/index.html.md).
-
-***
-
-## PaymentProvider Data Model
-
-When the Medusa application starts and registers the payment providers, it also creates a record of the `PaymentProvider` data model if none exists.
-
-This data model is used to reference a payment provider and determine whether it’s installed in the application.
-
-
-# Payment Session
-
-In this document, you’ll learn what a payment session is.
-
-## What's a Payment Session?
-
-A payment session, represented by the [PaymentSession data model](https://docs.medusajs.com/references/payment/models/PaymentSession/index.html.md), is a payment amount to be authorized. It’s associated with a payment provider that handles authorizing it.
-
-A payment collection can have multiple payment sessions. Using this feature, you can implement payment in installments or payments using multiple providers.
-
-
+
***
## data Property
-Payment providers may need additional data to process the payment later. The `PaymentSession` data model has a `data` property used to store that data.
+The `Fulfillment` data model has a `data` property that holds any necessary data for the third-party fulfillment provider to process the fulfillment.
-For example, the customer's ID in Stripe is stored in the `data` property.
+For example, the `data` property can hold the ID of the fulfillment in the third-party provider. The associated fulfillment provider then uses it whenever it retrieves the fulfillment’s details.
***
-## Payment Session Status
+## Fulfillment Items
-The `status` property of a payment session indicates its current status. Its value can be:
+A fulfillment is used to fulfill one or more items. Each item is represented by the `FulfillmentItem` data model.
-- `pending`: The payment session is awaiting authorization.
-- `requires_more`: The payment session requires an action before it’s authorized. For example, to enter a 3DS code.
-- `authorized`: The payment session is authorized.
-- `error`: An error occurred while authorizing the payment.
-- `canceled`: The authorization of the payment session has been canceled.
+The fulfillment item holds details relevant to fulfilling the item, such as barcode, SKU, and quantity to fulfill.
-
-# Webhook Events
-
-In this document, you’ll learn how the Payment Module supports listening to webhook events.
-
-## What's a Webhook Event?
-
-A webhook event is sent from a third-party payment provider to your application. It indicates a change in a payment’s status.
-
-This is useful in many cases such as when a payment is being processed asynchronously or when a request is interrupted and the payment provider is sending details on the process later.
+
***
-## getWebhookActionAndData Method
+## Fulfillment Label
-The Payment Module’s main service has a [getWebhookActionAndData method](https://docs.medusajs.com/references/payment/getWebhookActionAndData/index.html.md) used to handle incoming webhook events from third-party payment services. The method delegates the handling to the associated payment provider, which returns the event's details.
-
-Medusa implements a webhook listener route at the `/hooks/payment/[identifier]_[provider]` API route, where:
-
-- `[identifier]` is the `identifier` static property defined in the payment provider. For example, `stripe`.
-- `[provider]` is the ID of the provider. For example, `stripe`.
-
-For example, when integrating basic Stripe payments with the [Stripe Module Provider](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/payment/payment-provider/stripe/index.html.md), the webhook listener route is `/hooks/payment/stripe_stripe`. If you're integrating Stripe's Bancontact payments, the webhook listener route is `/hooks/payment/stripe-bancontact_stripe`.
-
-Use that webhook listener in your third-party payment provider's configurations.
-
-
-
-If the event's details indicate that the payment should be authorized, then the [authorizePaymentSession method of the main service](https://docs.medusajs.com/references/payment/authorizePaymentSession/index.html.md) is executed on the specified payment session.
-
-If the event's details indicate that the payment should be captured, then the [capturePayment method of the main service](https://docs.medusajs.com/references/payment/capturePayment/index.html.md) is executed on the payment of the specified payment session.
-
-### Actions After Webhook Payment Processing
-
-After the payment webhook actions are processed and the payment is authorized or captured, the Medusa application completes the cart associated with the payment's collection if it's not completed yet.
-
-
-# Promotion Actions
-
-In this document, you’ll learn about promotion actions and how they’re computed using the [computeActions method](https://docs.medusajs.com/references/promotion/computeActions/index.html.md).
-
-## computeActions Method
-
-The Promotion Module's main service has a [computeActions method](https://docs.medusajs.com/references/promotion/computeActions/index.html.md) that returns an array of actions to perform on a cart when one or more promotions are applied.
-
-Actions inform you what adjustment must be made to a cart item or shipping method. Each action is an object having the `action` property indicating the type of action.
+Once a shipment is created for the fulfillment, you can store its tracking number, URL, or other related details as a label, represented by the `FulfillmentLabel` data model.
***
-## Action Types
+## Fulfillment Status
-### `addItemAdjustment` Action
+The `Fulfillment` data model has three properties to keep track of the current status of the fulfillment:
-The `addItemAdjustment` action indicates that an adjustment must be made to an item. For example, removing $5 off its amount.
+- `packed_at`: The date the fulfillment was packed. If set, then the fulfillment has been packed.
+- `shipped_at`: The date the fulfillment was shipped. If set, then the fulfillment has been shipped.
+- `delivered_at`: The date the fulfillment was delivered. If set, then the fulfillment has been delivered.
-This action has the following format:
-```ts
-export interface AddItemAdjustmentAction {
- action: "addItemAdjustment"
- item_id: string
- amount: number
- code: string
- description?: string
-}
-```
+# Links between Fulfillment Module and Other Modules
-This action means that a new record should be created of the `LineItemAdjustment` data model in the Cart Module, or `OrderLineItemAdjustment` data model in the Order Module.
-
-Refer to [this reference](https://docs.medusajs.com/references/promotion/interfaces/promotion.AddItemAdjustmentAction/index.html.md) for details on the object’s properties.
-
-### `removeItemAdjustment` Action
-
-The `removeItemAdjustment` action indicates that an adjustment must be removed from a line item. For example, remove the $5 discount.
-
-The `computeActions` method accepts any previous item adjustments in the `items` property of the second parameter.
-
-This action has the following format:
-
-```ts
-export interface RemoveItemAdjustmentAction {
- action: "removeItemAdjustment"
- adjustment_id: string
- description?: string
- code: string
-}
-```
-
-This action means that a new record should be removed of the `LineItemAdjustment` (or `OrderLineItemAdjustment`) with the specified ID in the `adjustment_id` property.
-
-Refer to [this reference](https://docs.medusajs.com/references/promotion/interfaces/promotion.RemoveItemAdjustmentAction/index.html.md) for details on the object’s properties.
-
-### `addShippingMethodAdjustment` Action
-
-The `addShippingMethodAdjustment` action indicates that an adjustment must be made on a shipping method. For example, make the shipping method free.
-
-This action has the following format:
-
-```ts
-export interface AddShippingMethodAdjustment {
- action: "addShippingMethodAdjustment"
- shipping_method_id: string
- amount: number
- code: string
- description?: string
-}
-```
-
-This action means that a new record should be created of the `ShippingMethodAdjustment` data model in the Cart Module, or `OrderShippingMethodAdjustment` data model in the Order Module.
-
-Refer to [this reference](https://docs.medusajs.com/references/promotion/interfaces/promotion.AddShippingMethodAdjustment/index.html.md) for details on the object’s properties.
-
-### `removeShippingMethodAdjustment` Action
-
-The `removeShippingMethodAdjustment` action indicates that an adjustment must be removed from a shipping method. For example, remove the free shipping discount.
-
-The `computeActions` method accepts any previous shipping method adjustments in the `shipping_methods` property of the second parameter.
-
-This action has the following format:
-
-```ts
-export interface RemoveShippingMethodAdjustment {
- action: "removeShippingMethodAdjustment"
- adjustment_id: string
- code: string
-}
-```
-
-When the Medusa application receives this action type, it removes the `ShippingMethodAdjustment` (or `OrderShippingMethodAdjustment`) with the specified ID in the `adjustment_id` property.
-
-Refer to [this reference](https://docs.medusajs.com/references/promotion/interfaces/promotion.RemoveShippingMethodAdjustment/index.html.md) for details on the object’s properties.
-
-### `campaignBudgetExceeded` Action
-
-When the `campaignBudgetExceeded` action is returned, the promotions within a campaign can no longer be used as the campaign budget has been exceeded.
-
-This action has the following format:
-
-```ts
-export interface CampaignBudgetExceededAction {
- action: "campaignBudgetExceeded"
- code: string
-}
-```
-
-Refer to [this reference](https://docs.medusajs.com/references/promotion/interfaces/promotion.CampaignBudgetExceededAction/index.html.md) for details on the object’s properties.
-
-
-# Application Method
-
-In this document, you'll learn what an application method is.
-
-## What is an Application Method?
-
-The [ApplicationMethod data model](https://docs.medusajs.com/references/promotion/models/ApplicationMethod/index.html.md) defines how a promotion is applied:
-
-|Property|Purpose|
-|---|---|
-|\`type\`|Does the promotion discount a fixed amount or a percentage?|
-|\`target\_type\`|Is the promotion applied on a cart item, shipping method, or the entire order?|
-|\`allocation\`|Is the discounted amount applied on each item or split between the applicable items?|
-
-## Target Promotion Rules
-
-When the promotion is applied to a cart item or a shipping method, you can restrict which items/shipping methods the promotion is applied to.
-
-The `ApplicationMethod` data model has a collection of `PromotionRule` records to restrict which items or shipping methods the promotion applies to. The `target_rules` property represents this relation.
-
-
-
-In this example, the promotion is only applied on products in the cart having the SKU `SHIRT`.
-
-***
-
-## Buy Promotion Rules
-
-When the promotion’s type is `buyget`, you must specify the “buy X” condition. For example, a cart must have two shirts before the promotion can be applied.
-
-The application method has a collection of `PromotionRule` items to define the “buy X” rule. The `buy_rules` property represents this relation.
-
-
-
-In this example, the cart must have two products with the SKU `SHIRT` for the promotion to be applied.
-
-
-# Promotion Concepts
-
-In this guide, you’ll learn about the main promotion and rule concepts in the Promotion Module.
-
-Refer to this [Medusa Admin User Guide](https://docs.medusajs.com/user-guide/promotions/index.html.md) to learn how to manage promotions using the dashboard.
-
-## What is a Promotion?
-
-A promotion, represented by the [Promotion data model](https://docs.medusajs.com/references/promotion/models/Promotion/index.html.md), is a discount that can be applied on cart items, shipping methods, or entire orders.
-
-A promotion has two types:
-
-- `standard`: A standard promotion with rules.
-- `buyget`: “A buy X get Y” promotion with rules.
-
-|\`standard\`|\`buyget\`|
-|---|---|
-|A coupon code that gives customers 10% off their entire order.|Buy two shirts and get another for free.|
-|A coupon code that gives customers $15 off any shirt in their order.|Buy two shirts and get 10% off the entire order.|
-|A discount applied automatically for VIP customers that removes 10% off their shipping method’s amount.|Spend $100 and get free shipping.|
-
-The Medusa Admin UI may not provide a way to create each of these promotion examples. However, they are supported by the Promotion Module and Medusa's workflows and API routes.
-
-***
-
-## Promotion Rules
-
-A promotion can be restricted by a set of rules, each rule is represented by the [PromotionRule data model](https://docs.medusajs.com/references/promotion/models/PromotionRule/index.html.md).
-
-For example, you can create a promotion that only customers of the `VIP` customer group can use.
-
-
-
-A `PromotionRule`'s `attribute` property indicates the property's name to which this rule is applied. For example, `customer_group_id`.
-
-The expected value for the attribute is stored in the `PromotionRuleValue` data model. So, a rule can have multiple values.
-
-When testing whether a promotion can be applied to a cart, the rule's `attribute` property and its values are tested on the cart itself.
-
-For example, the cart's customer must be part of the customer group(s) indicated in the promotion rule's value.
-
-### Flexible Rules
-
-The `PromotionRule`'s `operator` property adds more flexibility to the rule’s condition rather than simple equality (`eq`).
-
-For example, to restrict the promotion to only `VIP` and `B2B` customer groups:
-
-- Add a `PromotionRule` record with its `attribute` property set to `customer_group_id` and `operator` property to `in`.
-- Add two `PromotionRuleValue` records associated with the rule: one with the value `VIP` and the other `B2B`.
-
-
-
-In this case, a customer’s group must be in the `VIP` and `B2B` set of values to use the promotion.
-
-***
-
-## How to Apply Rules on a Promotion?
-
-### Using Workflows
-
-If you're managing promotions using [Medusa's workflows](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/medusa-workflows-reference/index.html.md) or the API routes that use them, you can specify rules for the promotion or its [application method](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/promotion/application-method/index.html.md).
-
-For example, if you're creating a promotion using the [createPromotionsWorkflow](https://docs.medusajs.com/resources/references/medusa-workflows/createPromotionsWorkflow/index.html.md):
-
-```ts
-const { result } = await createPromotionsWorkflow(container)
- .run({
- input: {
- promotionsData: [{
- code: "10OFF",
- type: "standard",
- status: "active",
- application_method: {
- type: "percentage",
- target_type: "items",
- allocation: "across",
- value: 10,
- currency_code: "usd",
- },
- rules: [
- {
- attribute: "customer.group.id",
- operator: "eq",
- values: [
- "cusgrp_123",
- ],
- },
- ],
- }],
- },
- })
-```
-
-In this example, the promotion is restricted to customers with the `cusgrp_123` customer group.
-
-### Using Promotion Module's Service
-
-For most use cases, it's recommended to use [workflows](#using-workflows) instead of directly using the module's service.
-
-If you're managing promotions using the Promotion Module's service, you can specify rules for the promotion or its [application method](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/promotion/application-method/index.html.md) in its methods.
-
-For example, if you're creating a promotion with the [createPromotions](https://docs.medusajs.com/resources/references/promotion/createPromotions/index.html.md) method:
-
-```ts
-const promotions = await promotionModuleService.createPromotions([
- {
- code: "50OFF",
- type: "standard",
- status: "active",
- application_method: {
- type: "percentage",
- target_type: "items",
- value: 50,
- },
- rules: [
- {
- attribute: "customer.group.id",
- operator: "eq",
- values: [
- "cusgrp_123",
- ],
- },
- ],
- },
-])
-```
-
-In this example, the promotion is restricted to customers with the `cusgrp_123` customer group.
-
-### How is the Promotion Rule Applied?
-
-A promotion is applied on a resource if its attributes match the promotion's rules.
-
-For example, consider you have the following promotion with a rule that restricts the promotion to a specific customer:
-
-```json
-{
- "code": "10OFF",
- "type": "standard",
- "status": "active",
- "application_method": {
- "type": "percentage",
- "target_type": "items",
- "allocation": "across",
- "value": 10,
- "currency_code": "usd"
- },
- "rules": [
- {
- "attribute": "customer_id",
- "operator": "eq",
- "values": [
- "cus_123"
- ]
- }
- ]
-}
-```
-
-When you try to apply this promotion on a cart, the cart's `customer_id` is compared to the promotion rule's value based on the specified operator. So, the promotion will only be applied if the cart's `customer_id` is equal to `cus_123`.
-
-
-# Campaign
-
-In this document, you'll learn about campaigns.
-
-Refer to this [Medusa Admin User Guide](https://docs.medusajs.com/user-guide/promotions/campaigns/index.html.md) to learn how to manage campaigns using the dashboard.
-
-## What is a Campaign?
-
-A [Campaign](https://docs.medusajs.com/references/promotion/models/Campaign/index.html.md) combines promotions under the same conditions, such as start and end dates.
-
-
-
-***
-
-## Campaign Limits
-
-Each campaign has a budget represented by the [CampaignBudget data model](https://docs.medusajs.com/references/promotion/models/CampaignBudget/index.html.md). The budget limits how many times the promotion can be used.
-
-There are two types of budgets:
-
-- `spend`: An amount that, when crossed, the promotion becomes unusable. For example, if the amount limit is set to `$100`, and the total amount of usage of this promotion crosses that threshold, the promotion can no longer be applied.
-- `usage`: The number of times that a promotion can be used. For example, if the usage limit is set to `10`, the promotion can be used only 10 times by customers. After that, it can no longer be applied.
-
-
-
-
-# Links between Promotion Module and Other Modules
-
-This document showcases the module links defined between the Promotion Module and other Commerce Modules.
+This document showcases the module links defined between the Fulfillment Module and other Commerce Modules.
## Summary
-The Promotion Module has the following links to other modules:
-
-Read-only links are used to query data across modules, but the relations aren't stored in a pivot table in the database.
+The Fulfillment Module has the following links to other modules:
|First Data Model|Second Data Model|Type|Description|
|---|---|---|---|
-|Cart|Promotion|Stored - many-to-many|Learn more|
-|LineItemAdjustment|Promotion|Read-only - has one|Learn more|
-|Order|Promotion|Stored - many-to-many|Learn more|
-
-***
-
-## Cart Module
-
-A promotion can be applied on line items and shipping methods of a cart. Medusa defines a link between the `Cart` and `Promotion` data models.
-
-
-
-Medusa also defines a read-only link between the [Cart Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/cart/index.html.md)'s `LineItemAdjustment` data model and the `Promotion` data model. Because the link is read-only from the `LineItemAdjustment`'s side, you can only retrieve the promotion applied on a line item, and not the other way around.
-
-### Retrieve with Query
-
-To retrieve the carts that a promotion is applied on with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `carts.*` in `fields`:
-
-To retrieve the promotion of a line item adjustment, pass `promotion.*` in `fields`.
-
-### query.graph
-
-```ts
-const { data: promotions } = await query.graph({
- entity: "promotion",
- fields: [
- "carts.*",
- ],
-})
-
-// promotions[0].carts
-```
-
-### useQueryGraphStep
-
-```ts
-import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
-
-// ...
-
-const { data: promotions } = useQueryGraphStep({
- entity: "promotion",
- fields: [
- "carts.*",
- ],
-})
-
-// promotions[0].carts
-```
-
-### Manage with Link
-
-To manage the promotions of a cart, use [Link](https://docs.medusajs.com/docs/learn/fundamentals/module-links/link/index.html.md):
-
-### link.create
-
-```ts
-import { Modules } from "@medusajs/framework/utils"
-
-// ...
-
-await link.create({
- [Modules.CART]: {
- cart_id: "cart_123",
- },
- [Modules.PROMOTION]: {
- promotion_id: "promo_123",
- },
-})
-```
-
-### createRemoteLinkStep
-
-```ts
-import { Modules } from "@medusajs/framework/utils"
-import { createRemoteLinkStep } from "@medusajs/medusa/core-flows"
-
-// ...
-
-createRemoteLinkStep({
- [Modules.CART]: {
- cart_id: "cart_123",
- },
- [Modules.PROMOTION]: {
- promotion_id: "promo_123",
- },
-})
-```
+|Order|Fulfillment|Stored - one-to-many|Learn more|
+|Return|Fulfillment|Stored - one-to-many|Learn more|
+|PriceSet|ShippingOption|Stored - many-to-one|Learn more|
+|Product|ShippingProfile|Stored - many-to-one|Learn more|
+|StockLocation|FulfillmentProvider|Stored - one-to-many|Learn more|
+|StockLocation|FulfillmentSet|Stored - one-to-many|Learn more|
***
## Order Module
-An order is associated with the promotion applied on it. Medusa defines a link between the `Order` and `Promotion` data models.
+The [Order Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/order/index.html.md) provides order-management functionalities.
-
+Medusa defines a link between the `Fulfillment` and `Order` data models. A fulfillment is created for an orders' items.
+
+
+
+A fulfillment is also created for a return's items. So, Medusa defines a link between the `Fulfillment` and `Return` data models.
+
+
### Retrieve with Query
-To retrieve the orders a promotion is applied on with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `orders.*` in `fields`:
+To retrieve the order of a fulfillment with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `order.*` in `fields`:
+
+To retrieve the return, pass `return.*` in `fields`.
### query.graph
```ts
-const { data: promotions } = await query.graph({
- entity: "promotion",
+const { data: fulfillments } = await query.graph({
+ entity: "fulfillment",
fields: [
- "orders.*",
+ "order.*",
],
})
-// promotions[0].orders
+// fulfillments.order
```
### useQueryGraphStep
@@ -26010,19 +23833,19 @@ import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
// ...
-const { data: promotions } = useQueryGraphStep({
- entity: "promotion",
+const { data: fulfillments } = useQueryGraphStep({
+ entity: "fulfillment",
fields: [
- "orders.*",
+ "order.*",
],
})
-// promotions[0].orders
+// fulfillments.order
```
### Manage with Link
-To manage the promotion of an order, use [Link](https://docs.medusajs.com/docs/learn/fundamentals/module-links/link/index.html.md):
+To manage the order of a cart, use [Link](https://docs.medusajs.com/docs/learn/fundamentals/module-links/link/index.html.md):
### link.create
@@ -26035,8 +23858,8 @@ await link.create({
[Modules.ORDER]: {
order_id: "order_123",
},
- [Modules.PROMOTION]: {
- promotion_id: "promo_123",
+ [Modules.FULFILLMENT]: {
+ fulfillment_id: "ful_123",
},
})
```
@@ -26053,58 +23876,37 @@ createRemoteLinkStep({
[Modules.ORDER]: {
order_id: "order_123",
},
- [Modules.PROMOTION]: {
- promotion_id: "promo_123",
+ [Modules.FULFILLMENT]: {
+ fulfillment_id: "ful_123",
},
})
```
-
-# Links between Product Module and Other Modules
-
-This document showcases the module links defined between the Product Module and other Commerce Modules.
-
-## Summary
-
-The Product Module has the following links to other modules:
-
-Read-only links are used to query data across modules, but the relations aren't stored in a pivot table in the database.
-
-|First Data Model|Second Data Model|Type|Description|
-|---|---|---|---|
-|LineItem|Product|Read-only - has one|Learn more|
-|Product|ShippingProfile|Stored - many-to-one|Learn more|
-|ProductVariant|InventoryItem|Stored - many-to-many|Learn more|
-|OrderLineItem|Product|Read-only - has one|Learn more|
-|ProductVariant|PriceSet|Stored - one-to-one|Learn more|
-|Product|SalesChannel|Stored - many-to-many|Learn more|
-
***
-## Cart Module
+## Pricing Module
-Medusa defines read-only links between:
+The Pricing Module provides features to store, manage, and retrieve the best prices in a specified context.
-- The [Cart Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/cart/index.html.md)'s `LineItem` data model and the `Product` data model. Because the link is read-only from the `LineItem`'s side, you can only retrieve the product of a line item, and not the other way around.
-- The `ProductVariant` data model and the [Cart Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/cart/index.html.md)'s `LineItem` data model. Because the link is read-only from the `LineItem`'s side, you can only retrieve the variant of a line item, and not the other way around.
+Medusa defines a link between the `PriceSet` and `ShippingOption` data models. A shipping option's price is stored as a price set.
+
+
### Retrieve with Query
-To retrieve the variant of a line item with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `variant.*` in `fields`:
-
-To retrieve the product, pass `product.*` in `fields`.
+To retrieve the price set of a shipping option with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `price_set.*` in `fields`:
### query.graph
```ts
-const { data: lineItems } = await query.graph({
- entity: "line_item",
+const { data: shippingOptions } = await query.graph({
+ entity: "shipping_option",
fields: [
- "variant.*",
+ "price_set_link.*",
],
})
-// lineItems[0].variant
+// shippingOptions[0].price_set_link?.price_set_id
```
### useQueryGraphStep
@@ -26114,39 +23916,78 @@ import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
// ...
-const { data: lineItems } = useQueryGraphStep({
- entity: "line_item",
+const { data: shippingOptions } = useQueryGraphStep({
+ entity: "shipping_option",
fields: [
- "variant.*",
+ "price_set_link.*",
],
})
-// lineItems[0].variant
+// shippingOptions[0].price_set_link?.price_set_id
+```
+
+### Manage with Link
+
+To manage the price set of a shipping option, use [Link](https://docs.medusajs.com/docs/learn/fundamentals/module-links/link/index.html.md):
+
+### link.create
+
+```ts
+import { Modules } from "@medusajs/framework/utils"
+
+// ...
+
+await link.create({
+ [Modules.FULFILLMENT]: {
+ shipping_option_id: "so_123",
+ },
+ [Modules.PRICING]: {
+ price_set_id: "pset_123",
+ },
+})
+```
+
+### createRemoteLinkStep
+
+```ts
+import { Modules } from "@medusajs/framework/utils"
+import { createRemoteLinkStep } from "@medusajs/medusa/core-flows"
+
+// ...
+
+createRemoteLinkStep({
+ [Modules.FULFILLMENT]: {
+ shipping_option_id: "so_123",
+ },
+ [Modules.PRICING]: {
+ price_set_id: "pset_123",
+ },
+})
```
***
-## Fulfillment Module
+## Product Module
-Medusa defines a link between the `Product` data model and the `ShippingProfile` data model of the Fulfillment Module. Each product must belong to a shipping profile.
+Medusa defines a link between the `ShippingProfile` data model and the `Product` data model of the Product Module. Each product must belong to a shipping profile.
This link is introduced in [Medusa v2.5.0](https://github.com/medusajs/medusa/releases/tag/v2.5.0).
### Retrieve with Query
-To retrieve the shipping profile of a product with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `shipping_profile.*` in `fields`:
+To retrieve the products of a shipping profile with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `products.*` in `fields`:
### query.graph
```ts
-const { data: products } = await query.graph({
- entity: "product",
+const { data: shippingProfiles } = await query.graph({
+ entity: "shipping_profile",
fields: [
- "shipping_profile.*",
+ "products.*",
],
})
-// products[0].shipping_profile
+// shippingProfiles[0].products
```
### useQueryGraphStep
@@ -26156,14 +23997,14 @@ import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
// ...
-const { data: products } = useQueryGraphStep({
- entity: "product",
+const { data: shippingProfiles } = useQueryGraphStep({
+ entity: "shipping_profile",
fields: [
- "shipping_profile.*",
+ "products.*",
],
})
-// products[0].shipping_profile
+// shippingProfiles[0].products
```
### Manage with Link
@@ -26207,33 +24048,682 @@ createRemoteLinkStep({
***
-## Inventory Module
+## Stock Location Module
-The Inventory Module provides inventory-management features for any stock-kept item.
+The Stock Location Module provides features to manage stock locations in a store.
-Medusa defines a link between the `ProductVariant` and `InventoryItem` data models. Each product variant has different inventory details.
+Medusa defines a link between the `FulfillmentSet` and `StockLocation` data models. A fulfillment set can be conditioned to a specific stock location.
-
+
-When the `manage_inventory` property of a product variant is enabled, you can manage the variant's inventory in different locations through this relation.
+Medusa also defines a link between the `FulfillmentProvider` and `StockLocation` data models to indicate the providers that can be used in a location.
+
+
+
+### Retrieve with Query
+
+To retrieve the stock location of a fulfillment set with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `location.*` in `fields`:
+
+To retrieve the stock location of a fulfillment provider, pass `locations.*` in `fields`.
+
+### query.graph
+
+```ts
+const { data: fulfillmentSets } = await query.graph({
+ entity: "fulfillment_set",
+ fields: [
+ "location.*",
+ ],
+})
+
+// fulfillmentSets[0].location
+```
+
+### useQueryGraphStep
+
+```ts
+import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
+
+// ...
+
+const { data: fulfillmentSets } = useQueryGraphStep({
+ entity: "fulfillment_set",
+ fields: [
+ "location.*",
+ ],
+})
+
+// fulfillmentSets[0].location
+```
+
+### Manage with Link
+
+To manage the stock location of a fulfillment set, use [Link](https://docs.medusajs.com/docs/learn/fundamentals/module-links/link/index.html.md):
+
+### link.create
+
+```ts
+import { Modules } from "@medusajs/framework/utils"
+
+// ...
+
+await link.create({
+ [Modules.STOCK_LOCATION]: {
+ stock_location_id: "sloc_123",
+ },
+ [Modules.FULFILLMENT]: {
+ fulfillment_set_id: "fset_123",
+ },
+})
+```
+
+### createRemoteLinkStep
+
+```ts
+import { Modules } from "@medusajs/framework/utils"
+import { createRemoteLinkStep } from "@medusajs/medusa/core-flows"
+
+// ...
+
+createRemoteLinkStep({
+ [Modules.STOCK_LOCATION]: {
+ stock_location_id: "sloc_123",
+ },
+ [Modules.FULFILLMENT]: {
+ fulfillment_set_id: "fset_123",
+ },
+})
+```
+
+
+# Fulfillment Module Options
+
+In this document, you'll learn about the options of the Fulfillment Module.
+
+## providers
+
+The `providers` option is an array of fulfillment module providers.
+
+When the Medusa application starts, these providers are registered and can be used to process fulfillments.
+
+For example:
+
+```ts title="medusa-config.ts"
+import { Modules } from "@medusajs/framework/utils"
+
+// ...
+
+module.exports = defineConfig({
+ // ...
+ modules: [
+ {
+ resolve: "@medusajs/medusa/fulfillment",
+ options: {
+ providers: [
+ {
+ resolve: `@medusajs/medusa/fulfillment-manual`,
+ id: "manual",
+ options: {
+ // provider options...
+ },
+ },
+ ],
+ },
+ },
+ ],
+})
+```
+
+The `providers` option is an array of objects that accept the following properties:
+
+- `resolve`: A string indicating either the package name of the module provider or the path to it relative to the `src` directory.
+- `id`: A string indicating the provider's unique name or ID.
+- `options`: An optional object of the module provider's options.
+
+
+# Shipping Option
+
+In this document, you’ll learn about shipping options and their rules.
+
+## What’s a Shipping Option?
+
+A shipping option is a way of shipping an item. Each fulfillment provider provides a set of shipping options. For example, a provider may provide a shipping option for express shipping and another for standard shipping.
+
+When the customer places their order, they choose a shipping option to be used to fulfill their items.
+
+A shipping option is represented by the [ShippingOption data model](https://docs.medusajs.com/references/fulfillment/models/ShippingOption/index.html.md).
+
+***
+
+## Service Zone Restrictions
+
+A shipping option is restricted by a service zone, limiting the locations a shipping option be used in.
+
+For example, a fulfillment provider may have a shipping option that can be used in the United States, and another in Canada.
+
+
+
+Service zones can be more restrictive, such as restricting to certain cities or province codes.
+
+The province code is always in lower-case and in [ISO 3166-2 format](https://en.wikipedia.org/wiki/ISO_3166-2).
+
+
+
+***
+
+## Shipping Option Rules
+
+You can restrict shipping options by custom rules, such as the item’s weight or the customer’s group.
+
+You can also restrict a shipping option's price based on specific conditions. For example, you can make a shipping option's price free based on the cart's total. Learn more in the Pricing Module's [Price Rules](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/pricing/price-rules#how-to-set-rules-on-a-price/index.html.md) guide.
+
+These rules are represented by the [ShippingOptionRule data model](https://docs.medusajs.com/references/fulfillment/models/ShippingOptionRule/index.html.md). Its properties define the custom rule:
+
+- `attribute`: The name of a property or table that the rule applies to. For example, `customer_group`.
+- `operator`: The operator used in the condition. For example:
+ - To allow multiple values, use the operator `in`, which validates that the provided values are in the rule’s values.
+ - To create a negation condition that considers `value` against the rule, use `nin`, which validates that the provided values aren’t in the rule’s values.
+ - Check out more operators in [this reference](https://docs.medusajs.com/references/fulfillment/types/fulfillment.RuleOperatorType/index.html.md).
+- `value`: One or more values.
+
+
+
+A shipping option can have multiple rules. For example, you can add rules to a shipping option so that it's available if the customer belongs to the VIP group and the total weight is less than 2000g.
+
+
+
+***
+
+## Shipping Profile and Types
+
+A shipping option belongs to a type. For example, a shipping option’s type may be `express`, while another `standard`. The type is represented by the [ShippingOptionType data model](https://docs.medusajs.com/references/fulfillment/models/ShippingOptionType/index.html.md).
+
+A shipping option also belongs to a shipping profile, as each shipping profile defines the type of items to be shipped in a similar manner.
+
+***
+
+## data Property
+
+When fulfilling an item, you might use a third-party fulfillment provider that requires additional custom data to be passed along from the checkout or order-creation process.
+
+The `ShippingOption` data model has a `data` property. It's an object that stores custom data relevant later when creating and processing a fulfillment.
+
+
+# Inventory Concepts
+
+In this document, you’ll learn about the main concepts in the Inventory Module, and how data is stored and related.
+
+## 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.
+
+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.
+
+
+
+### 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.
+
+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).
+
+***
+
+## 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.
+
+It has three quantity-related 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.
+
+### 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.
+
+***
+
+## 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.
+
+The reserved quantity is associated with a location, so it has a similar relation to that of the `InventoryLevel` with the Stock Location Module.
+
+
+# Inventory Kits
+
+In this guide, you'll learn how inventory kits can be used in the Medusa application to support use cases like multi-part products, bundled products, and shared inventory across products.
+
+Refer to the following user guides to learn how to use the Medusa Admin dashboard to:
+
+- [Create Multi-Part Products](https://docs.medusajs.com/user-guide/products/create/multi-part/index.html.md).
+- [Create Bundled Products](https://docs.medusajs.com/user-guide/products/create/bundle/index.html.md).
+
+## What is an Inventory Kit?
+
+An inventory kit is a collection of inventory items that are linked to a single product variant. These inventory items can be used to represent different parts of a product, or to represent a bundle of products.
+
+The Medusa application links inventory items from the [Inventory Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/inventory/index.html.md) to product variants in the [Product Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/product/index.html.md). Each variant can have multiple inventory items, and these inventory items can be re-used or shared across variants.
+
+Using inventory kits, you can implement use cases like:
+
+- [Multi-part products](#multi-part-products): A product that consists of multiple parts, each with its own inventory item.
+- [Bundled products](#bundled-products): A product that is sold as a bundle, where each variant in the bundle product can re-use the inventory items of another product that should be sold as part of the bundle.
+
+***
+
+## Multi-Part Products
+
+Consider your store sells bicycles that consist of a frame, wheels, and seats, and you want to manage the inventory of these parts separately.
+
+To implement this in Medusa, you can:
+
+- Create inventory items for each of the different parts.
+- For each bicycle product, add a variant whose inventory kit consists of the inventory items of each of the parts.
+
+Then, whenever a customer purchases a bicycle, the inventory of each part is updated accordingly. You can also use the `required_quantity` of the variant's inventory items to set how much quantity is consumed of the part's inventory when a bicycle is sold. For example, the bicycle's wheels require 2 wheels inventory items to be sold when a bicycle is sold.
+
+
+
+### Create Multi-Part Product
+
+Using the [Medusa Admin](https://docs.medusajs.com/user-guide/products/create/multi-part/index.html.md), you can create a multi-part product by creating its inventory items first, then assigning these inventory items to the product's variant(s).
+
+Using [workflows](https://docs.medusajs.com/docs/learn/fundamentals/workflows/index.html.md), you can implement this by first creating the inventory items:
+
+```ts highlights={multiPartsHighlights1}
+import {
+ createInventoryItemsWorkflow,
+ useQueryGraphStep,
+} from "@medusajs/medusa/core-flows"
+import { createWorkflow } from "@medusajs/framework/workflows-sdk"
+
+export const createMultiPartProductsWorkflow = createWorkflow(
+ "create-multi-part-products",
+ () => {
+ // Alternatively, you can create a stock location
+ const { data: stockLocations } = useQueryGraphStep({
+ entity: "stock_location",
+ fields: ["*"],
+ filters: {
+ name: "European Warehouse",
+ },
+ })
+
+ const inventoryItems = createInventoryItemsWorkflow.runAsStep({
+ input: {
+ items: [
+ {
+ sku: "FRAME",
+ title: "Frame",
+ location_levels: [
+ {
+ stocked_quantity: 100,
+ location_id: stockLocations[0].id,
+ },
+ ],
+ },
+ {
+ sku: "WHEEL",
+ title: "Wheel",
+ location_levels: [
+ {
+ stocked_quantity: 100,
+ location_id: stockLocations[0].id,
+ },
+ ],
+ },
+ {
+ sku: "SEAT",
+ title: "Seat",
+ location_levels: [
+ {
+ stocked_quantity: 100,
+ location_id: stockLocations[0].id,
+ },
+ ],
+ },
+ ],
+ },
+ })
+
+ // TODO create the product
+ }
+)
+```
+
+You start by retrieving the stock location to create the inventory items in. Alternatively, you can [create a stock location](https://docs.medusajs.com/references/medusa-workflows/createStockLocationsWorkflow/index.html.md).
+
+Then, you create the inventory items that the product variant consists of.
+
+Next, create the product and pass the inventory item's IDs to the product's variant:
+
+```ts highlights={multiPartHighlights2}
+import {
+ // ...
+ transform,
+} from "@medusajs/framework/workflows-sdk"
+import {
+ // ...
+ createProductsWorkflow,
+} from "@medusajs/medusa/core-flows"
+
+export const createMultiPartProductsWorkflow = createWorkflow(
+ "create-multi-part-products",
+ () => {
+ // ...
+
+ const inventoryItemIds = transform({
+ inventoryItems,
+ }, (data) => {
+ return data.inventoryItems.map((inventoryItem) => {
+ return {
+ inventory_item_id: inventoryItem.id,
+ // can also specify required_quantity
+ }
+ })
+ })
+
+ const products = createProductsWorkflow.runAsStep({
+ input: {
+ products: [
+ {
+ title: "Bicycle",
+ variants: [
+ {
+ title: "Bicycle - Small",
+ prices: [
+ {
+ amount: 100,
+ currency_code: "usd",
+ },
+ ],
+ options: {
+ "Default Option": "Default Variant",
+ },
+ inventory_items: inventoryItemIds,
+ },
+ ],
+ options: [
+ {
+ title: "Default Option",
+ values: ["Default Variant"],
+ },
+ ],
+ shipping_profile_id: "sp_123",
+ },
+ ],
+ },
+ })
+ }
+)
+```
+
+You prepare the inventory item IDs to pass to the variant using [transform](https://docs.medusajs.com/docs/learn/fundamentals/workflows/variable-manipulation/index.html.md) from the Workflows SDK, then pass these IDs to the created product's variant.
+
+You can now [execute the workflow](https://docs.medusajs.com/docs/learn/fundamentals/workflows#3-execute-the-workflow/index.html.md) in [API routes](https://docs.medusajs.com/docs/learn/fundamentals/api-routes/index.html.md), [scheduled jobs](https://docs.medusajs.com/docs/learn/fundamentals/scheduled-jobs/index.html.md), or [subscribers](https://docs.medusajs.com/docs/learn/fundamentals/events-and-subscribers/index.html.md).
+
+***
+
+## Bundled Products
+
+While inventory kits support bundled products, some features like custom pricing for a bundle or separate fulfillment for a bundle's items are not supported. To support those features, follow the [Bundled Products](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/recipes/bundled-products/examples/standard/index.html.md) tutorial to learn how to customize the Medusa application to add bundled products.
+
+Consider you have three products: shirt, pants, and shoes. You sell those products separately, but you also want to offer them as a bundle.
+
+
+
+You can do that by creating a product, where each variant re-uses the inventory items of each of the shirt, pants, and shoes products.
+
+Then, when the bundled product's variant is purchased, the inventory quantity of the associated inventory items are updated.
+
+
+
+### Create Bundled Product
+
+You can create a bundled product in the [Medusa Admin](https://docs.medusajs.com/user-guide/products/create/bundle/index.html.md) by creating the products part of the bundle first, each having its own inventory items. Then, you create the bundled product whose variant(s) have inventory kits composed of inventory items from each of the products part of the bundle.
+
+Using [workflows](https://docs.medusajs.com/docs/learn/fundamentals/workflows/index.html.md), you can implement this by first creating the products part of the bundle:
+
+```ts highlights={bundledHighlights1}
+import {
+ createWorkflow,
+} from "@medusajs/framework/workflows-sdk"
+import {
+ createProductsWorkflow,
+} from "@medusajs/medusa/core-flows"
+
+export const createBundledProducts = createWorkflow(
+ "create-bundled-products",
+ () => {
+ const products = createProductsWorkflow.runAsStep({
+ input: {
+ products: [
+ {
+ title: "Shirt",
+ shipping_profile_id: "sp_123",
+ variants: [
+ {
+ title: "Shirt",
+ prices: [
+ {
+ amount: 10,
+ currency_code: "usd",
+ },
+ ],
+ options: {
+ "Default Option": "Default Variant",
+ },
+ manage_inventory: true,
+ },
+ ],
+ options: [
+ {
+ title: "Default Option",
+ values: ["Default Variant"],
+ },
+ ],
+ },
+ {
+ title: "Pants",
+ shipping_profile_id: "sp_123",
+ variants: [
+ {
+ title: "Pants",
+ prices: [
+ {
+ amount: 10,
+ currency_code: "usd",
+ },
+ ],
+ options: {
+ "Default Option": "Default Variant",
+ },
+ manage_inventory: true,
+ },
+ ],
+ options: [
+ {
+ title: "Default Option",
+ values: ["Default Variant"],
+ },
+ ],
+ },
+ {
+ title: "Shoes",
+ shipping_profile_id: "sp_123",
+ variants: [
+ {
+ title: "Shoes",
+ prices: [
+ {
+ amount: 10,
+ currency_code: "usd",
+ },
+ ],
+ options: {
+ "Default Option": "Default Variant",
+ },
+ manage_inventory: true,
+ },
+ ],
+ options: [
+ {
+ title: "Default Option",
+ values: ["Default Variant"],
+ },
+ ],
+ },
+ ],
+ },
+ })
+
+ // TODO re-retrieve with inventory
+ }
+)
+```
+
+You create three products and enable `manage_inventory` for their variants, which will create a default inventory item. You can also create the inventory item first for more control over the quantity as explained in [the previous section](#create-multi-part-product).
+
+Next, retrieve the products again but with variant information:
+
+```ts highlights={bundledHighlights2}
+import {
+ // ...
+ transform,
+} from "@medusajs/framework/workflows-sdk"
+import {
+ useQueryGraphStep,
+} from "@medusajs/medusa/core-flows"
+
+export const createBundledProducts = createWorkflow(
+ "create-bundled-products",
+ () => {
+ // ...
+ const productIds = transform({
+ products,
+ }, (data) => data.products.map((product) => product.id))
+
+ // @ts-ignore
+ const { data: productsWithInventory } = useQueryGraphStep({
+ entity: "product",
+ fields: [
+ "variants.*",
+ "variants.inventory_items.*",
+ ],
+ filters: {
+ id: productIds,
+ },
+ })
+
+ const inventoryItemIds = transform({
+ productsWithInventory,
+ }, (data) => {
+ return data.productsWithInventory.map((product) => {
+ return {
+ inventory_item_id: product.variants[0].inventory_items?.[0]?.inventory_item_id,
+ }
+ })
+ })
+
+ // create bundled product
+ }
+)
+```
+
+Using [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), you retrieve the product again with the inventory items of each variant. Then, you prepare the inventory items to pass to the bundled product's variant.
+
+Finally, create the bundled product:
+
+```ts highlights={bundledProductHighlights3}
+export const createBundledProducts = createWorkflow(
+ "create-bundled-products",
+ () => {
+ // ...
+ const bundledProduct = createProductsWorkflow.runAsStep({
+ input: {
+ products: [
+ {
+ title: "Bundled Clothes",
+ shipping_profile_id: "sp_123",
+ variants: [
+ {
+ title: "Bundle",
+ prices: [
+ {
+ amount: 30,
+ currency_code: "usd",
+ },
+ ],
+ options: {
+ "Default Option": "Default Variant",
+ },
+ inventory_items: inventoryItemIds,
+ },
+ ],
+ options: [
+ {
+ title: "Default Option",
+ values: ["Default Variant"],
+ },
+ ],
+ },
+ ],
+ },
+ }).config({ name: "create-bundled-product" })
+ }
+)
+```
+
+The bundled product has the same inventory items as those of the products part of the bundle.
+
+You can now [execute the workflow](https://docs.medusajs.com/docs/learn/fundamentals/workflows#3-execute-the-workflow/index.html.md) in [API routes](https://docs.medusajs.com/docs/learn/fundamentals/api-routes/index.html.md), [scheduled jobs](https://docs.medusajs.com/docs/learn/fundamentals/scheduled-jobs/index.html.md), or [subscribers](https://docs.medusajs.com/docs/learn/fundamentals/events-and-subscribers/index.html.md).
+
+
+# Links between Inventory Module and Other Modules
+
+This document showcases the module links defined between the Inventory Module and other Commerce Modules.
+
+## Summary
+
+The Inventory Module has the following links to other modules:
+
+Read-only links are used to query data across modules, but the relations aren't stored in a pivot table in the database.
+
+|First Data Model|Second Data Model|Type|Description|
+|---|---|---|---|
+|ProductVariant|InventoryItem|Stored - many-to-many|Learn more|
+|InventoryLevel|StockLocation|Read-only - has many|Learn more|
+
+***
+
+## Product Module
+
+Each product variant has different inventory details. Medusa defines a link between the `ProductVariant` and `InventoryItem` data models.
+
+
+
+A product variant whose `manage_inventory` property is enabled has an associated inventory item. Through that inventory's items relations in the Inventory Module, you can manage and check the variant's inventory quantity.
Learn more about product variant's inventory management in [this guide](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/product/variant-inventory/index.html.md).
### Retrieve with Query
-To retrieve the inventory items of a product variant with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `inventory_items.*` in `fields`:
+To retrieve the product variants of an inventory item with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `variants.*` in `fields`:
### query.graph
```ts
-const { data: variants } = await query.graph({
- entity: "variant",
+const { data: inventoryItems } = await query.graph({
+ entity: "inventory_item",
fields: [
- "inventory_items.*",
+ "variants.*",
],
})
-// variants[0].inventory_items
+// inventoryItems[0].variants
```
### useQueryGraphStep
@@ -26243,19 +24733,19 @@ import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
// ...
-const { data: variants } = useQueryGraphStep({
- entity: "variant",
+const { data: inventoryItems } = useQueryGraphStep({
+ entity: "inventory_item",
fields: [
- "inventory_items.*",
+ "variants.*",
],
})
-// variants[0].inventory_items
+// inventoryItems[0].variants
```
### Manage with Link
-To manage the inventory items of a variant, use [Link](https://docs.medusajs.com/docs/learn/fundamentals/module-links/link/index.html.md):
+To manage the variants of an inventory item, use [Link](https://docs.medusajs.com/docs/learn/fundamentals/module-links/link/index.html.md):
### link.create
@@ -26294,30 +24784,25 @@ createRemoteLinkStep({
***
-## Order Module
+## Stock Location Module
-Medusa defines read-only links between:
-
-- the [Order Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/order/index.html.md)'s `OrderLineItem` data model and the `Product` data model. Because the link is read-only from the `OrderLineItem`'s side, you can only retrieve the product of an order line item, and not the other way around.
-- the [Order Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/order/index.html.md)'s `OrderLineItem` data model and the `ProductVariant` data model. Because the link is read-only from the `OrderLineItem`'s side, you can only retrieve the variant of an order line item, and not the other way around.
+Medusa defines a read-only link between the `InventoryLevel` data model and the [Stock Location Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/stock-location/index.html.md)'s `StockLocation` data model. This means you can retrieve the details of an inventory level's stock locations, but you don't manage the links in a pivot table in the database. The stock location of an inventory level is determined by the `location_id` property of the `InventoryLevel` data model.
### Retrieve with Query
-To retrieve the variant of a line item with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `variant.*` in `fields`:
-
-To retrieve the product, pass `product.*` in `fields`.
+To retrieve the stock locations of an inventory level with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `stock_locations.*` in `fields`:
### query.graph
```ts
-const { data: lineItems } = await query.graph({
- entity: "order_line_item",
+const { data: inventoryLevels } = await query.graph({
+ entity: "inventory_level",
fields: [
- "variant.*",
+ "stock_locations.*",
],
})
-// lineItems[0].variant
+// inventoryLevels[0].stock_locations
```
### useQueryGraphStep
@@ -26327,301 +24812,76 @@ import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
// ...
-const { data: lineItems } = useQueryGraphStep({
- entity: "order_line_item",
+const { data: inventoryLevels } = useQueryGraphStep({
+ entity: "inventory_level",
fields: [
- "variant.*",
+ "stock_locations.*",
],
})
-// lineItems[0].variant
+// inventoryLevels[0].stock_locations
```
+
+# Inventory Module in Medusa Flows
+
+This document explains how the Inventory Module is used within the Medusa application's flows.
+
+## Product Variant Creation
+
+When a product variant is created and its `manage_inventory` property's value is `true`, the Medusa application creates an inventory item associated with that product variant.
+
+This flow is implemented within the [createProductVariantsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createProductVariantsWorkflow/index.html.md)
+
+
+
***
-## Pricing Module
+## Add to Cart
-The Product Module doesn't provide pricing-related features.
+When a product variant with `manage_inventory` set to `true` is added to cart, the Medusa application checks whether there's sufficient stocked quantity. If not, an error is thrown and the product variant won't be added to the cart.
-Instead, Medusa defines a link between the `ProductVariant` and the `PriceSet` data models. A product variant’s prices are stored belonging to a price set.
+This flow is implemented within the [addToCartWorkflow](https://docs.medusajs.com/references/medusa-workflows/addToCartWorkflow/index.html.md)
-
-
-So, to add prices for a product variant, create a price set and add the prices to it.
-
-### Retrieve with Query
-
-To retrieve the price set of a variant with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `price_set.*` in `fields`:
-
-### query.graph
-
-```ts
-const { data: variants } = await query.graph({
- entity: "variant",
- fields: [
- "price_set.*",
- ],
-})
-
-// variants[0].price_set
-```
-
-### useQueryGraphStep
-
-```ts
-import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
-
-// ...
-
-const { data: variants } = useQueryGraphStep({
- entity: "variant",
- fields: [
- "price_set.*",
- ],
-})
-
-// variants[0].price_set
-```
-
-### Manage with Link
-
-To manage the price set of a variant, use [Link](https://docs.medusajs.com/docs/learn/fundamentals/module-links/link/index.html.md):
-
-### link.create
-
-```ts
-import { Modules } from "@medusajs/framework/utils"
-
-// ...
-
-await link.create({
- [Modules.PRODUCT]: {
- variant_id: "variant_123",
- },
- [Modules.PRICING]: {
- price_set_id: "pset_123",
- },
-})
-```
-
-### createRemoteLinkStep
-
-```ts
-import { Modules } from "@medusajs/framework/utils"
-import { createRemoteLinkStep } from "@medusajs/medusa/core-flows"
-
-// ...
-
-createRemoteLinkStep({
- [Modules.PRODUCT]: {
- variant_id: "variant_123",
- },
- [Modules.PRICING]: {
- price_set_id: "pset_123",
- },
-})
-```
+
***
-## Sales Channel Module
+## Order Placed
-The Sales Channel Module provides functionalities to manage multiple selling channels in your store.
+When an order is placed, the Medusa application creates a reservation item for each product variant with `manage_inventory` set to `true`.
-Medusa defines a link between the `Product` and `SalesChannel` data models. A product can have different availability in different sales channels.
+This flow is implemented within the [completeCartWorkflow](https://docs.medusajs.com/references/medusa-workflows/completeCartWorkflow/index.html.md)
-
-
-### Retrieve with Query
-
-To retrieve the sales channels of a product with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `sales_channels.*` in `fields`:
-
-### query.graph
-
-```ts
-const { data: products } = await query.graph({
- entity: "product",
- fields: [
- "sales_channels.*",
- ],
-})
-
-// products[0].sales_channels
-```
-
-### useQueryGraphStep
-
-```ts
-import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
-
-// ...
-
-const { data: products } = useQueryGraphStep({
- entity: "product",
- fields: [
- "sales_channels.*",
- ],
-})
-
-// products[0].sales_channels
-```
-
-### Manage with Link
-
-To manage the sales channels of a product, use [Link](https://docs.medusajs.com/docs/learn/fundamentals/module-links/link/index.html.md):
-
-### link.create
-
-```ts
-import { Modules } from "@medusajs/framework/utils"
-
-// ...
-
-await link.create({
- [Modules.PRODUCT]: {
- product_id: "prod_123",
- },
- [Modules.SALES_CHANNEL]: {
- sales_channel_id: "sc_123",
- },
-})
-```
-
-### createRemoteLinkStep
-
-```ts
-import { Modules } from "@medusajs/framework/utils"
-import { createRemoteLinkStep } from "@medusajs/medusa/core-flows"
-
-// ...
-
-createRemoteLinkStep({
- [Modules.PRODUCT]: {
- product_id: "prod_123",
- },
- [Modules.SALES_CHANNEL]: {
- sales_channel_id: "sc_123",
- },
-})
-```
-
-
-# Configure Selling Products
-
-In this guide, you'll learn how to set up and configure your products based on their shipping and inventory requirements, the product type, how you want to sell them, or your commerce ecosystem.
-
-The concepts in this guide are applicable starting from Medusa v2.5.1.
-
-## Scenario
-
-Businesses can have different selling requirements:
-
-1. They may sell physical or digital items.
-2. They may sell items that don't require shipping or inventory management, such as selling digital products, services, or booking appointments.
-3. They may sell items whose inventory is managed by an external system, such as an ERP.
-
-Medusa supports these different selling requirements by allowing you to configure shipping and inventory requirements for products and their variants. This guide explains how these configurations work, then provides examples of setting up different use cases.
+
***
-## Configuring Shipping Requirements
+## Order Fulfillment
-The Medusa application defines a link between the `Product` data model and a [ShippingProfile](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/fulfillment/concepts#shipping-profile/index.html.md) in the [Fulfillment Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/fulfillment/index.html.md), allowing you to associate a product with a shipping profile.
+When an item in an order is fulfilled and the associated variant has its `manage_inventory` property set to `true`, the Medusa application:
-When a product is associated with a shipping profile, its variants require shipping and fulfillment when purchased. This is useful for physical products or digital products that require custom fulfillment.
+- Subtracts the `reserved_quantity` from the `stocked_quantity` in the inventory level associated with the variant's inventory item.
+- Resets the `reserved_quantity` to `0`.
+- Deletes the associated reservation item.
-If a product doesn't have an associated shipping profile, its variants don't require shipping and fulfillment when purchased. This is useful for digital products, for example, that don't require shipping.
+This flow is implemented within the [createOrderFulfillmentWorkflow](https://docs.medusajs.com/references/medusa-workflows/createOrderFulfillmentWorkflow/index.html.md)
-### Overriding Shipping Requirements for Variants
-
-A product variant whose inventory is managed by Medusa (its `manage_inventory` property is enabled) has an [inventory item](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/inventory/concepts#inventoryitem/index.html.md). The inventory item has a `requires_shipping` property that can be used to override its shipping requirement. This is useful if the product has an associated shipping profile but you want to disable shipping for a specific variant, or vice versa.
-
-Learn more about product variant's inventory in [this guide](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/product/variant-inventory/index.html.md).
-
-When a product variant is purchased, the Medusa application decides whether the purchased item requires shipping in the following order:
-
-1. The product variant has an inventory item. In this case, the Medusa application uses the inventory item's `requires_shipping` property to determine if the item requires shipping.
-2. If the product variant doesn't have an inventory item, the Medusa application checks whether the product has an associated shipping profile to determine if the item requires shipping.
+
***
-## Use Case Examples
+## Order Return
-By combining configurations of shipment requirements and inventory management, you can set up your products to support your use case:
+When an item in an order is returned and the associated variant has its `manage_inventory` property set to `true`, the Medusa application increments the `stocked_quantity` of the inventory item's level with the returned quantity.
-|Use Case|Configurations|Example|
-|---|---|---|---|---|
-|Item that's shipped on purchase, and its variant inventory is managed by the Medusa application.||Any stock-kept item (clothing, for example), whose inventory is managed in the Medusa application.|
-|Item that's shipped on purchase, but its variant inventory is managed externally (not by Medusa) or it has infinite stock.||Any stock-kept item (clothing, for example), whose inventory is managed in an ERP or has infinite stock.|
-|Item that's not shipped on purchase, but its variant inventory is managed by Medusa.||Digital products, such as licenses, that don't require shipping but have a limited quantity.|
-|Item that doesn't require shipping and its variant inventory isn't managed by Medusa.|||
+This flow is implemented within the [confirmReturnReceiveWorkflow](https://docs.medusajs.com/references/medusa-workflows/confirmReturnReceiveWorkflow/index.html.md)
+
-# Product Variant Inventory
+### Dismissed Returned Items
-# Product Variant Inventory
-
-In this guide, you'll learn about the inventory management features related to product variants.
-
-Refer to this [Medusa Admin User Guide](https://docs.medusajs.com/user-guide/products/variants#manage-product-variant-inventory/index.html.md) to learn how to manage inventory of product variants.
-
-## Configure Inventory Management of Product Variants
-
-A product variant, represented by the [ProductVariant](https://docs.medusajs.com/references/product/models/ProductVariant/index.html.md) data model, has a `manage_inventory` field that's disabled by default. This field indicates whether you'll manage the inventory quantity of the product variant in the Medusa application. You can also keep `manage_inventory` disabled if you manage the product's inventory in an external system, such as an ERP.
-
-The Product Module doesn't provide inventory-management features. Instead, the Medusa application uses the [Inventory Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/inventory/index.html.md) to manage inventory for products and variants. When `manage_inventory` is disabled, the Medusa application always considers the product variant to be in stock. This is useful if your product's variants aren't items that can be stocked, such as digital products, or they don't have a limited stock quantity.
-
-When `manage_inventory` is enabled, the Medusa application tracks the inventory of the product variant using the [Inventory Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/inventory/index.html.md). For example, when a customer purchases a product variant, the Medusa application decrements the stocked quantity of the product variant.
-
-***
-
-## How the Medusa Application Manages Inventory
-
-When a product variant has `manage_inventory` enabled, the Medusa application creates an inventory item using the [Inventory Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/inventory/index.html.md) and links it to the product variant.
-
-
-
-The inventory item has one or more locations, called inventory levels, that represent the stock quantity of the product variant at a specific location. This allows you to manage inventory across multiple warehouses, such as a warehouse in the US and another in Europe.
-
-
-
-Learn more about inventory concepts in the [Inventory Module's documentation](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/inventory/concepts/index.html.md).
-
-The Medusa application represents and manages stock locations using the [Stock Location Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/stock-location/index.html.md). It creates a read-only link between the `InventoryLevel` and `StockLocation` data models so that it can retrieve the stock location of an inventory level.
-
-
-
-Learn more about the Stock Location Module in the [Stock Location Module's documentation](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/stock-location/concepts/index.html.md).
-
-### Product Inventory in Storefronts
-
-When a storefront sends a request to the Medusa application, it must always pass a [publishable API key](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/sales-channel/publishable-api-keys/index.html.md) in the request header. This API key specifies the sales channels, available through the [Sales Channel Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/sales-channel/index.html.md), of the storefront.
-
-The Medusa application links sales channels to stock locations, indicating the locations available for a specific sales channel. So, all inventory-related operations are scoped by the sales channel and its associated stock locations.
-
-For example, the availability of a product variant is determined by the `stocked_quantity` of its inventory level at the stock location linked to the storefront's sales channel.
-
-
-
-***
-
-## Variant Back Orders
-
-Product variants have an `allow_backorder` field that's disabled by default. When enabled, the Medusa application allows customers to purchase the product variant even when it's out of stock. Use this when your product variant is available through on-demand or pre-order purchase.
-
-You can also allow customers to subscribe to restock notifications of a product variant as explained in [this guide](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/recipes/commerce-automation/restock-notification/index.html.md).
-
-***
-
-## Additional Resources
-
-The following guides provide more details on inventory management in the Medusa application:
-
-- [Inventory Kits in the Inventory Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/inventory/inventory-kit/index.html.md): Learn how you can implement bundled or multi-part products through the Inventory Module.
-- [Retrieve Product Variant Inventory Quantity](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/product/guides/variant-inventory/index.html.md): Learn how to retrieve the available inventory quantity of a product variant.
-- [Configure Selling Products](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/product/selling-products/index.html.md): Learn how to use inventory management to support different use cases when selling products.
-- [Inventory in Flows](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/inventory/inventory-in-flows/index.html.md): Learn how Medusa utilizes inventory management in different flows.
-- [Storefront guide: how to retrieve a product variant's inventory details](https://docs.medusajs.com/resources/storefront-development/products/inventory/index.html.md).
+If a returned item is considered damaged or is dismissed, its quantity doesn't increment the `stocked_quantity` of the inventory item's level.
# Order Concepts
@@ -26730,6 +24990,60 @@ Once the Order Edit is confirmed, any additional payment or refund required can
This is determined by the comparison between the `OrderSummary` and the order's transactions, as mentioned in [this guide](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/order/transactions#checking-outstanding-amount/index.html.md).
+# Order Claim
+
+In this document, 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.
+
+The [OrderClaim data model](https://docs.medusajs.com/references/order/models/OrderClaim/index.html.md) represents a claim.
+
+***
+
+## Claim Type
+
+The `Claim` data model has a `type` property whose value indicates the type of the claim:
+
+- `refund`: the items are returned, and the customer is refunded.
+- `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.
+
+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).
+
+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).
+
+***
+
+## 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).
+
+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).
+
+***
+
+## Claim Refund
+
+If the claim’s type is `refund`, the amount to be refunded 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
+
+When a claim is confirmed, the order’s version is incremented.
+
+
# Order Exchange
In this document, you’ll learn about order exchanges.
@@ -27376,60 +25690,6 @@ When the order is changed, such as an item is exchanged, this changes the versio
When the order is retrieved, only the related data having the same version is retrieved.
-# Order Claim
-
-In this document, 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.
-
-The [OrderClaim data model](https://docs.medusajs.com/references/order/models/OrderClaim/index.html.md) represents a claim.
-
-***
-
-## Claim Type
-
-The `Claim` data model has a `type` property whose value indicates the type of the claim:
-
-- `refund`: the items are returned, and the customer is refunded.
-- `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.
-
-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).
-
-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).
-
-***
-
-## 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).
-
-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).
-
-***
-
-## Claim Refund
-
-If the claim’s type is `refund`, the amount to be refunded 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
-
-When a claim is confirmed, the order’s version is incremented.
-
-
# Promotions Adjustments in Orders
In this document, you’ll learn how a promotion is applied to an order’s items and shipping methods using adjustment lines.
@@ -27642,29 +25902,6 @@ The following diagram is a simplified showcase of how a subtotal is calculated f
For example, if a line item's amount is `5000`, the tax rate is `10`, and `is_tax_inclusive` is enabled, the tax amount is 10% of `5000`, which is `500`. The item's unit price becomes `4500`.
-# Pricing Concepts
-
-In this document, you’ll learn about the main concepts in the Pricing Module.
-
-## Price Set
-
-A [PriceSet](https://docs.medusajs.com/references/pricing/models/PriceSet/index.html.md) represents a collection of prices that are linked to a resource (for example, a product or a shipping option).
-
-Each of these prices are represented by the [Price data module](https://docs.medusajs.com/references/pricing/models/Price/index.html.md).
-
-
-
-***
-
-## Price List
-
-A [PriceList](https://docs.medusajs.com/references/pricing/models/PriceList/index.html.md) is a group of prices only enabled if their conditions and rules are satisfied.
-
-A price list has optional `start_date` and `end_date` properties that indicate the date range in which a price list can be applied.
-
-Its associated prices are represented by the `Price` data model.
-
-
# Transactions
In this document, you’ll learn about an order’s transactions and its use.
@@ -27713,6 +25950,439 @@ The `OrderTransaction` data model has two properties that determine which data m
- `reference_id`: indicates the ID of the record in the table. For example, `pay_123`.
+# Pricing Concepts
+
+In this document, you’ll learn about the main concepts in the Pricing Module.
+
+## Price Set
+
+A [PriceSet](https://docs.medusajs.com/references/pricing/models/PriceSet/index.html.md) represents a collection of prices that are linked to a resource (for example, a product or a shipping option).
+
+Each of these prices are represented by the [Price data module](https://docs.medusajs.com/references/pricing/models/Price/index.html.md).
+
+
+
+***
+
+## Price List
+
+A [PriceList](https://docs.medusajs.com/references/pricing/models/PriceList/index.html.md) is a group of prices only enabled if their conditions and rules are satisfied.
+
+A price list has optional `start_date` and `end_date` properties that indicate the date range in which a price list can be applied.
+
+Its associated prices are represented by the `Price` data model.
+
+
+# Links between Pricing Module and Other Modules
+
+This document showcases the module links defined between the Pricing Module and other Commerce Modules.
+
+## Summary
+
+The Pricing Module has the following links to other modules:
+
+|First Data Model|Second Data Model|Type|Description|
+|---|---|---|---|
+|ShippingOption|PriceSet|Stored - one-to-one|Learn more|
+|ProductVariant|PriceSet|Stored - one-to-one|Learn more|
+
+***
+
+## Fulfillment Module
+
+The Fulfillment Module provides fulfillment-related functionalities, including shipping options that the customer chooses from when they place their order. However, it doesn't provide pricing-related functionalities for these options.
+
+Medusa defines a link between the `PriceSet` and `ShippingOption` data models. A shipping option's price is stored as a price set.
+
+
+
+### Retrieve with Query
+
+To retrieve the shipping option of a price set with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `shipping_option.*` in `fields`:
+
+### query.graph
+
+```ts
+const { data: priceSets } = await query.graph({
+ entity: "price_set",
+ fields: [
+ "shipping_option.*",
+ ],
+})
+
+// priceSets[0].shipping_option
+```
+
+### useQueryGraphStep
+
+```ts
+import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
+
+// ...
+
+const { data: priceSets } = useQueryGraphStep({
+ entity: "price_set",
+ fields: [
+ "shipping_option.*",
+ ],
+})
+
+// priceSets[0].shipping_option
+```
+
+### Manage with Link
+
+To manage the price set of a shipping option, use [Link](https://docs.medusajs.com/docs/learn/fundamentals/module-links/link/index.html.md):
+
+### link.create
+
+```ts
+import { Modules } from "@medusajs/framework/utils"
+
+// ...
+
+await link.create({
+ [Modules.FULFILLMENT]: {
+ shipping_option_id: "so_123",
+ },
+ [Modules.PRICING]: {
+ price_set_id: "pset_123",
+ },
+})
+```
+
+### createRemoteLinkStep
+
+```ts
+import { Modules } from "@medusajs/framework/utils"
+import { createRemoteLinkStep } from "@medusajs/medusa/core-flows"
+
+// ...
+
+createRemoteLinkStep({
+ [Modules.FULFILLMENT]: {
+ shipping_option_id: "so_123",
+ },
+ [Modules.PRICING]: {
+ price_set_id: "pset_123",
+ },
+})
+```
+
+***
+
+## Product Module
+
+The Product Module doesn't store or manage the prices of product variants.
+
+Medusa defines a link between the `ProductVariant` and the `PriceSet`. A product variant’s prices are stored as prices belonging to a price set.
+
+
+
+So, when you want to add prices for a product variant, you create a price set and add the prices to it.
+
+You can then benefit from adding rules to prices or using the `calculatePrices` method to retrieve the price of a product variant within a specified context.
+
+### Retrieve with Query
+
+To retrieve the variant of a price set with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `variant.*` in `fields`:
+
+### query.graph
+
+```ts
+const { data: priceSets } = await query.graph({
+ entity: "price_set",
+ fields: [
+ "variant.*",
+ ],
+})
+
+// priceSets[0].variant
+```
+
+### useQueryGraphStep
+
+```ts
+import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
+
+// ...
+
+const { data: priceSets } = useQueryGraphStep({
+ entity: "price_set",
+ fields: [
+ "variant.*",
+ ],
+})
+
+// priceSets[0].variant
+```
+
+### Manage with Link
+
+To manage the price set of a variant, use [Link](https://docs.medusajs.com/docs/learn/fundamentals/module-links/link/index.html.md):
+
+### link.create
+
+```ts
+import { Modules } from "@medusajs/framework/utils"
+
+// ...
+
+await link.create({
+ [Modules.PRODUCT]: {
+ variant_id: "variant_123",
+ },
+ [Modules.PRICING]: {
+ price_set_id: "pset_123",
+ },
+})
+```
+
+### createRemoteLinkStep
+
+```ts
+import { Modules } from "@medusajs/framework/utils"
+import { createRemoteLinkStep } from "@medusajs/medusa/core-flows"
+
+// ...
+
+createRemoteLinkStep({
+ [Modules.PRODUCT]: {
+ variant_id: "variant_123",
+ },
+ [Modules.PRICING]: {
+ price_set_id: "pset_123",
+ },
+})
+```
+
+
+# Prices Calculation
+
+In this document, you'll learn how prices are calculated when you use the [calculatePrices method](https://docs.medusajs.com/references/pricing/calculatePrices/index.html.md) of the Pricing Module's main service.
+
+## calculatePrices Method
+
+The [calculatePrices method](https://docs.medusajs.com/references/pricing/calculatePrices/index.html.md) accepts as parameters the ID of one or more price sets and a context.
+
+It returns a price object with the best matching price for each price set.
+
+### Calculation Context
+
+The calculation context is an optional object passed as a second parameter to the `calculatePrices` method. It accepts rules to restrict the selected prices in the price set.
+
+For example:
+
+```ts
+const price = await pricingModuleService.calculatePrices(
+ { id: [priceSetId] },
+ {
+ context: {
+ currency_code: currencyCode,
+ region_id: "reg_123",
+ },
+ }
+)
+```
+
+In this example, you retrieve the prices in a price set for the specified currency code and region ID.
+
+### Returned Price Object
+
+For each price set, the `calculatePrices` method selects two prices:
+
+- A calculated price: Either a price that belongs to a price list and best matches the specified context, or the same as the original price.
+- An original price, which is either:
+ - The same price as the calculated price if the price list it belongs to is of type `override`;
+ - Or a price that doesn't belong to a price list and best matches the specified context.
+
+Both prices are returned in an object that has the following properties:
+
+- id: (\`string\`) The ID of the price set from which the price was selected.
+- is\_calculated\_price\_price\_list: (\`boolean\`) Whether the calculated price belongs to a price list.
+- calculated\_amount: (\`number\`) The amount of the calculated price, or \`null\` if there isn't a calculated price. This is the amount shown to the customer.
+- is\_original\_price\_price\_list: (\`boolean\`) Whether the original price belongs to a price list.
+- original\_amount: (\`number\`) The amount of the original price, or \`null\` if there isn't an original price. This amount is useful to compare with the \`calculated\_amount\`, such as to check for discounted value.
+- currency\_code: (\`string\`) The currency code of the calculated price, or \`null\` if there isn't a calculated price.
+- is\_calculated\_price\_tax\_inclusive: (\`boolean\`) Whether the calculated price is tax inclusive. Learn more about tax-inclusivity in \[this document]\(../tax-inclusive-pricing/page.mdx)
+- is\_original\_price\_tax\_inclusive: (\`boolean\`) Whether the original price is tax inclusive. Learn more about tax-inclusivity in \[this document]\(../tax-inclusive-pricing/page.mdx)
+- calculated\_price: (\`object\`) The calculated price's price details.
+
+ - id: (\`string\`) The ID of the price.
+
+ - price\_list\_id: (\`string\`) The ID of the associated price list.
+
+ - price\_list\_type: (\`string\`) The price list's type. For example, \`sale\`.
+
+ - min\_quantity: (\`number\`) The price's min quantity condition.
+
+ - max\_quantity: (\`number\`) The price's max quantity condition.
+- original\_price: (\`object\`) The original price's price details.
+
+ - id: (\`string\`) The ID of the price.
+
+ - price\_list\_id: (\`string\`) The ID of the associated price list.
+
+ - price\_list\_type: (\`string\`) The price list's type. For example, \`sale\`.
+
+ - min\_quantity: (\`number\`) The price's min quantity condition.
+
+ - max\_quantity: (\`number\`) The price's max quantity condition.
+
+***
+
+## Examples
+
+Consider the following price set:
+
+```ts
+const priceSet = await pricingModuleService.createPriceSets({
+ prices: [
+ // default price
+ {
+ amount: 500,
+ currency_code: "EUR",
+ rules: {},
+ },
+ // prices with rules
+ {
+ amount: 400,
+ currency_code: "EUR",
+ rules: {
+ region_id: "reg_123",
+ },
+ },
+ {
+ amount: 450,
+ currency_code: "EUR",
+ rules: {
+ city: "krakow",
+ },
+ },
+ {
+ amount: 500,
+ currency_code: "EUR",
+ rules: {
+ city: "warsaw",
+ region_id: "reg_123",
+ },
+ },
+ {
+ amount: 200,
+ currency_code: "EUR",
+ min_quantity: 100,
+ },
+ ],
+})
+```
+
+### Default Price Selection
+
+### Code
+
+```ts
+const price = await pricingModuleService.calculatePrices(
+ { id: [priceSet.id] },
+ {
+ context: {
+ currency_code: "EUR"
+ }
+ }
+)
+```
+
+### Result
+
+### Calculate Prices with Rules
+
+### Code
+
+```ts
+const price = await pricingModuleService.calculatePrices(
+ { id: [priceSet.id] },
+ {
+ context: {
+ currency_code: "EUR",
+ region_id: "reg_123",
+ city: "krakow"
+ }
+ }
+)
+```
+
+### Result
+
+### Tiered Pricing Selection
+
+### Code
+
+```ts
+const price = await pricingModuleService.calculatePrices(
+ { id: [priceSet.id] },
+ {
+ context: {
+ cart: {
+ items: [
+ {
+ id: "item_1",
+ quantity: 200,
+ // assuming the price set belongs to this variant
+ variant_id: "variant_1",
+ // ...
+ }
+ ],
+ // ...
+ }
+ }
+ }
+)
+```
+
+### Result
+
+### Price Selection with Price List
+
+### Code
+
+```ts
+const priceList = pricingModuleService.createPriceLists([{
+ title: "Summer Price List",
+ description: "Price list for summer sale",
+ starts_at: Date.parse("01/10/2023").toString(),
+ ends_at: Date.parse("31/10/2023").toString(),
+ rules: {
+ region_id: ['PL']
+ },
+ type: "sale",
+ prices: [
+ {
+ amount: 400,
+ currency_code: "EUR",
+ price_set_id: priceSet.id,
+ },
+ {
+ amount: 450,
+ currency_code: "EUR",
+ price_set_id: priceSet.id,
+ },
+ ],
+}]);
+
+const price = await pricingModuleService.calculatePrices(
+ { id: [priceSet.id] },
+ {
+ context: {
+ currency_code: "EUR",
+ region_id: "PL",
+ city: "krakow"
+ }
+ }
+)
+```
+
+### Result
+
+
# Price Tiers and Rules
In this Pricing Module guide, you'll learn about tired prices, price rules for price sets and price lists, and how to add rules to a price.
@@ -27791,10 +26461,10 @@ const { result } = await createProductsWorkflow(container)
},
],
// ...
- }]
+ }],
}],
// ...
- }
+ },
})
```
@@ -27982,416 +26652,6 @@ In this example, the price is only applied if a cart's customer belongs to the c
These same rules apply to product variant prices as well, or any other resource that has a price.
-# Prices Calculation
-
-In this document, you'll learn how prices are calculated when you use the [calculatePrices method](https://docs.medusajs.com/references/pricing/calculatePrices/index.html.md) of the Pricing Module's main service.
-
-## calculatePrices Method
-
-The [calculatePrices method](https://docs.medusajs.com/references/pricing/calculatePrices/index.html.md) accepts as parameters the ID of one or more price sets and a context.
-
-It returns a price object with the best matching price for each price set.
-
-### Calculation Context
-
-The calculation context is an optional object passed as a second parameter to the `calculatePrices` method. It accepts rules to restrict the selected prices in the price set.
-
-For example:
-
-```ts
-const price = await pricingModuleService.calculatePrices(
- { id: [priceSetId] },
- {
- context: {
- currency_code: currencyCode,
- region_id: "reg_123",
- },
- }
-)
-```
-
-In this example, you retrieve the prices in a price set for the specified currency code and region ID.
-
-### Returned Price Object
-
-For each price set, the `calculatePrices` method selects two prices:
-
-- A calculated price: Either a price that belongs to a price list and best matches the specified context, or the same as the original price.
-- An original price, which is either:
- - The same price as the calculated price if the price list it belongs to is of type `override`;
- - Or a price that doesn't belong to a price list and best matches the specified context.
-
-Both prices are returned in an object that has the following properties:
-
-- id: (\`string\`) The ID of the price set from which the price was selected.
-- is\_calculated\_price\_price\_list: (\`boolean\`) Whether the calculated price belongs to a price list.
-- calculated\_amount: (\`number\`) The amount of the calculated price, or \`null\` if there isn't a calculated price. This is the amount shown to the customer.
-- is\_original\_price\_price\_list: (\`boolean\`) Whether the original price belongs to a price list.
-- original\_amount: (\`number\`) The amount of the original price, or \`null\` if there isn't an original price. This amount is useful to compare with the \`calculated\_amount\`, such as to check for discounted value.
-- currency\_code: (\`string\`) The currency code of the calculated price, or \`null\` if there isn't a calculated price.
-- is\_calculated\_price\_tax\_inclusive: (\`boolean\`) Whether the calculated price is tax inclusive. Learn more about tax-inclusivity in \[this document]\(../tax-inclusive-pricing/page.mdx)
-- is\_original\_price\_tax\_inclusive: (\`boolean\`) Whether the original price is tax inclusive. Learn more about tax-inclusivity in \[this document]\(../tax-inclusive-pricing/page.mdx)
-- calculated\_price: (\`object\`) The calculated price's price details.
-
- - id: (\`string\`) The ID of the price.
-
- - price\_list\_id: (\`string\`) The ID of the associated price list.
-
- - price\_list\_type: (\`string\`) The price list's type. For example, \`sale\`.
-
- - min\_quantity: (\`number\`) The price's min quantity condition.
-
- - max\_quantity: (\`number\`) The price's max quantity condition.
-- original\_price: (\`object\`) The original price's price details.
-
- - id: (\`string\`) The ID of the price.
-
- - price\_list\_id: (\`string\`) The ID of the associated price list.
-
- - price\_list\_type: (\`string\`) The price list's type. For example, \`sale\`.
-
- - min\_quantity: (\`number\`) The price's min quantity condition.
-
- - max\_quantity: (\`number\`) The price's max quantity condition.
-
-***
-
-## Examples
-
-Consider the following price set:
-
-```ts
-const priceSet = await pricingModuleService.createPriceSets({
- prices: [
- // default price
- {
- amount: 500,
- currency_code: "EUR",
- rules: {},
- },
- // prices with rules
- {
- amount: 400,
- currency_code: "EUR",
- rules: {
- region_id: "reg_123",
- },
- },
- {
- amount: 450,
- currency_code: "EUR",
- rules: {
- city: "krakow",
- },
- },
- {
- amount: 500,
- currency_code: "EUR",
- rules: {
- city: "warsaw",
- region_id: "reg_123",
- },
- },
- {
- amount: 200,
- currency_code: "EUR",
- min_quantity: 100,
- }
- ],
-})
-```
-
-### Default Price Selection
-
-### Code
-
-```ts
-const price = await pricingModuleService.calculatePrices(
- { id: [priceSet.id] },
- {
- context: {
- currency_code: "EUR"
- }
- }
-)
-```
-
-### Result
-
-### Calculate Prices with Rules
-
-### Code
-
-```ts
-const price = await pricingModuleService.calculatePrices(
- { id: [priceSet.id] },
- {
- context: {
- currency_code: "EUR",
- region_id: "reg_123",
- city: "krakow"
- }
- }
-)
-```
-
-### Result
-
-### Tiered Pricing Selection
-
-### Code
-
-```ts
-const price = await pricingModuleService.calculatePrices(
- { id: [priceSet.id] },
- {
- context: {
- cart: {
- items: [
- {
- id: "item_1",
- quantity: 200,
- // assuming the price set belongs to this variant
- variant_id: "variant_1",
- // ...
- }
- ],
- // ...
- }
- }
- }
-)
-```
-
-### Result
-
-### Price Selection with Price List
-
-### Code
-
-```ts
-const priceList = pricingModuleService.createPriceLists([{
- title: "Summer Price List",
- description: "Price list for summer sale",
- starts_at: Date.parse("01/10/2023").toString(),
- ends_at: Date.parse("31/10/2023").toString(),
- rules: {
- region_id: ['PL']
- },
- type: "sale",
- prices: [
- {
- amount: 400,
- currency_code: "EUR",
- price_set_id: priceSet.id,
- },
- {
- amount: 450,
- currency_code: "EUR",
- price_set_id: priceSet.id,
- },
- ],
-}]);
-
-const price = await pricingModuleService.calculatePrices(
- { id: [priceSet.id] },
- {
- context: {
- currency_code: "EUR",
- region_id: "PL",
- city: "krakow"
- }
- }
-)
-```
-
-### Result
-
-
-# Links between Pricing Module and Other Modules
-
-This document showcases the module links defined between the Pricing Module and other Commerce Modules.
-
-## Summary
-
-The Pricing Module has the following links to other modules:
-
-|First Data Model|Second Data Model|Type|Description|
-|---|---|---|---|
-|ShippingOption|PriceSet|Stored - one-to-one|Learn more|
-|ProductVariant|PriceSet|Stored - one-to-one|Learn more|
-
-***
-
-## Fulfillment Module
-
-The Fulfillment Module provides fulfillment-related functionalities, including shipping options that the customer chooses from when they place their order. However, it doesn't provide pricing-related functionalities for these options.
-
-Medusa defines a link between the `PriceSet` and `ShippingOption` data models. A shipping option's price is stored as a price set.
-
-
-
-### Retrieve with Query
-
-To retrieve the shipping option of a price set with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `shipping_option.*` in `fields`:
-
-### query.graph
-
-```ts
-const { data: priceSets } = await query.graph({
- entity: "price_set",
- fields: [
- "shipping_option.*",
- ],
-})
-
-// priceSets[0].shipping_option
-```
-
-### useQueryGraphStep
-
-```ts
-import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
-
-// ...
-
-const { data: priceSets } = useQueryGraphStep({
- entity: "price_set",
- fields: [
- "shipping_option.*",
- ],
-})
-
-// priceSets[0].shipping_option
-```
-
-### Manage with Link
-
-To manage the price set of a shipping option, use [Link](https://docs.medusajs.com/docs/learn/fundamentals/module-links/link/index.html.md):
-
-### link.create
-
-```ts
-import { Modules } from "@medusajs/framework/utils"
-
-// ...
-
-await link.create({
- [Modules.FULFILLMENT]: {
- shipping_option_id: "so_123",
- },
- [Modules.PRICING]: {
- price_set_id: "pset_123",
- },
-})
-```
-
-### createRemoteLinkStep
-
-```ts
-import { Modules } from "@medusajs/framework/utils"
-import { createRemoteLinkStep } from "@medusajs/medusa/core-flows"
-
-// ...
-
-createRemoteLinkStep({
- [Modules.FULFILLMENT]: {
- shipping_option_id: "so_123",
- },
- [Modules.PRICING]: {
- price_set_id: "pset_123",
- },
-})
-```
-
-***
-
-## Product Module
-
-The Product Module doesn't store or manage the prices of product variants.
-
-Medusa defines a link between the `ProductVariant` and the `PriceSet`. A product variant’s prices are stored as prices belonging to a price set.
-
-
-
-So, when you want to add prices for a product variant, you create a price set and add the prices to it.
-
-You can then benefit from adding rules to prices or using the `calculatePrices` method to retrieve the price of a product variant within a specified context.
-
-### Retrieve with Query
-
-To retrieve the variant of a price set with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `variant.*` in `fields`:
-
-### query.graph
-
-```ts
-const { data: priceSets } = await query.graph({
- entity: "price_set",
- fields: [
- "variant.*",
- ],
-})
-
-// priceSets[0].variant
-```
-
-### useQueryGraphStep
-
-```ts
-import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
-
-// ...
-
-const { data: priceSets } = useQueryGraphStep({
- entity: "price_set",
- fields: [
- "variant.*",
- ],
-})
-
-// priceSets[0].variant
-```
-
-### Manage with Link
-
-To manage the price set of a variant, use [Link](https://docs.medusajs.com/docs/learn/fundamentals/module-links/link/index.html.md):
-
-### link.create
-
-```ts
-import { Modules } from "@medusajs/framework/utils"
-
-// ...
-
-await link.create({
- [Modules.PRODUCT]: {
- variant_id: "variant_123",
- },
- [Modules.PRICING]: {
- price_set_id: "pset_123",
- },
-})
-```
-
-### createRemoteLinkStep
-
-```ts
-import { Modules } from "@medusajs/framework/utils"
-import { createRemoteLinkStep } from "@medusajs/medusa/core-flows"
-
-// ...
-
-createRemoteLinkStep({
- [Modules.PRODUCT]: {
- variant_id: "variant_123",
- },
- [Modules.PRICING]: {
- price_set_id: "pset_123",
- },
-})
-```
-
-
# Tax-Inclusive Pricing
In this document, you’ll learn about tax-inclusive pricing and how it's used when calculating prices.
@@ -28460,6 +26720,1898 @@ A region’s price preference’s `is_tax_inclusive`'s value takes higher preced
- and the region has a price preference
+# Account Holders and Saved Payment Methods
+
+In this documentation, you'll learn about account holders, and how they're used to save payment methods in third-party payment providers.
+
+Account holders are available starting from Medusa `v2.5.0`.
+
+## What's an Account Holder?
+
+An account holder represents a customer that can have saved payment methods in a third-party service. It's represented by the `AccountHolder` data model.
+
+It holds fields retrieved from the third-party provider, such as:
+
+- `external_id`: The ID of the equivalent customer or account holder in the third-party provider.
+- `data`: Data returned by the payment provider when the account holder is created.
+
+A payment provider that supports saving payment methods for customers would create the equivalent of an account holder in the third-party provider. Then, whenever a payment method is saved, it would be saved under the account holder in the third-party provider.
+
+### Relation between Account Holder and Customer
+
+The Medusa application creates a link between the [Customer](https://docs.medusajs.com/references/customer/models/Customer/index.html.md) data model of the [Customer Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/customer/index.html.md) and the `AccountHolder` data model of the Payment Module.
+
+This link indicates that a customer can have more than one account holder, each representing saved payment methods in different payment providers.
+
+Learn more about this link in the [Link to Other Modules](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/payment/links-to-other-modules/index.html.md) guide.
+
+***
+
+## Save Payment Methods
+
+If a payment provider supports saving payment methods for a customer, they must implement the following methods:
+
+- `createAccountHolder`: Creates an account holder in the payment provider. The Payment Module uses this method before creating the account holder in Medusa, and uses the returned data to set fields like `external_id` and `data` in the created `AccountHolder` record.
+- `deleteAccountHolder`: Deletes an account holder in the payment provider. The Payment Module uses this method when an account holder is deleted in Medusa.
+- `savePaymentMethod`: Saves a payment method for an account holder in the payment provider.
+- `listPaymentMethods`: Lists saved payment methods in the third-party service for an account holder. This is useful when displaying the customer's saved payment methods in the storefront.
+
+Learn more about implementing these methods in the [Create Payment Provider guide](https://docs.medusajs.com/references/payment/provider/index.html.md).
+
+***
+
+## Account Holder in Medusa Payment Flows
+
+In the Medusa application, when a payment session is created for a registered customer, the Medusa application uses the Payment Module to create an account holder for the customer.
+
+Consequently, the Payment Module uses the payment provider to create an account holder in the third-party service, then creates the account holder in Medusa.
+
+This flow is only supported if the chosen payment provider has implemented the necessary [save payment methods](#save-payment-methods).
+
+
+# Payment Module Options
+
+In this document, you'll learn about the options of the Payment Module.
+
+## All Module Options
+
+|Option|Description|Required|Default|
+|---|---|---|---|---|---|---|
+|\`webhook\_delay\`|A number indicating the delay in milliseconds before processing a webhook event.|No|\`5000\`|
+|\`webhook\_retries\`|The number of times to retry the webhook event processing in case of an error.|No|\`3\`|
+|\`providers\`|An array of payment providers to install and register. Learn more |No|-|
+
+***
+
+## providers Option
+
+The `providers` option is an array of payment module providers.
+
+When the Medusa application starts, these providers are registered and can be used to process payments.
+
+For example:
+
+```ts title="medusa-config.ts"
+import { Modules } from "@medusajs/framework/utils"
+
+// ...
+
+module.exports = defineConfig({
+ // ...
+ modules: [
+ {
+ resolve: "@medusajs/medusa/payment",
+ options: {
+ providers: [
+ {
+ resolve: "@medusajs/medusa/payment-stripe",
+ id: "stripe",
+ options: {
+ // ...
+ },
+ },
+ ],
+ },
+ },
+ ],
+})
+```
+
+The `providers` option is an array of objects that accept the following properties:
+
+- `resolve`: A string indicating the package name of the module provider or the path to it relative to the `src` directory.
+- `id`: A string indicating the provider's unique name or ID.
+- `options`: An optional object of the module provider's options.
+
+
+# Links between Payment Module and Other Modules
+
+This document showcases the module links defined between the Payment Module and other Commerce Modules.
+
+## Summary
+
+The Payment Module has the following links to other modules:
+
+|First Data Model|Second Data Model|Type|Description|
+|---|---|---|---|
+|Cart|PaymentCollection|Stored - one-to-one|Learn more|
+|Customer|AccountHolder|Stored - many-to-many|Learn more|
+|Order|PaymentCollection|Stored - one-to-many|Learn more|
+|OrderClaim|PaymentCollection|Stored - one-to-many|Learn more|
+|OrderExchange|PaymentCollection|Stored - one-to-many|Learn more|
+|Region|PaymentProvider|Stored - many-to-many|Learn more|
+
+***
+
+## Cart Module
+
+The Cart Module provides cart-related features, but not payment processing.
+
+Medusa defines a link between the `Cart` and `PaymentCollection` data models. A cart has a payment collection which holds all the authorized payment sessions and payments made related to the cart.
+
+Learn more about this relation in [this documentation](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/payment/payment-collection#usage-with-the-cart-module/index.html.md).
+
+### Retrieve with Query
+
+To retrieve the cart associated with the payment collection with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `cart.*` in `fields`:
+
+### query.graph
+
+```ts
+const { data: paymentCollections } = await query.graph({
+ entity: "payment_collection",
+ fields: [
+ "cart.*",
+ ],
+})
+
+// paymentCollections[0].cart
+```
+
+### useQueryGraphStep
+
+```ts
+import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
+
+// ...
+
+const { data: paymentCollections } = useQueryGraphStep({
+ entity: "payment_collection",
+ fields: [
+ "cart.*",
+ ],
+})
+
+// paymentCollections[0].cart
+```
+
+### Manage with Link
+
+To manage the payment collection of a cart, use [Link](https://docs.medusajs.com/docs/learn/fundamentals/module-links/link/index.html.md):
+
+### link.create
+
+```ts
+import { Modules } from "@medusajs/framework/utils"
+
+// ...
+
+await link.create({
+ [Modules.CART]: {
+ cart_id: "cart_123",
+ },
+ [Modules.PAYMENT]: {
+ payment_collection_id: "paycol_123",
+ },
+})
+```
+
+### createRemoteLinkStep
+
+```ts
+import { createRemoteLinkStep } from "@medusajs/medusa/core-flows"
+
+// ...
+
+createRemoteLinkStep({
+ [Modules.CART]: {
+ cart_id: "cart_123",
+ },
+ [Modules.PAYMENT]: {
+ payment_collection_id: "paycol_123",
+ },
+})
+```
+
+***
+
+## Customer Module
+
+Medusa defines a link between the `Customer` and `AccountHolder` data models, allowing payment providers to save payment methods for a customer, if the payment provider supports it.
+
+This link is available starting from Medusa `v2.5.0`.
+
+### Retrieve with Query
+
+To retrieve the customer associated with an account holder with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `customer.*` in `fields`:
+
+### query.graph
+
+```ts
+const { data: accountHolders } = await query.graph({
+ entity: "account_holder",
+ fields: [
+ "customer.*",
+ ],
+})
+
+// accountHolders[0].customer
+```
+
+### useQueryGraphStep
+
+```ts
+import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
+
+// ...
+
+const { data: accountHolders } = useQueryGraphStep({
+ entity: "account_holder",
+ fields: [
+ "customer.*",
+ ],
+})
+
+// accountHolders[0].customer
+```
+
+### Manage with Link
+
+To manage the account holders of a customer, use [Link](https://docs.medusajs.com/docs/learn/fundamentals/module-links/link/index.html.md):
+
+### link.create
+
+```ts
+import { Modules } from "@medusajs/framework/utils"
+
+// ...
+
+await link.create({
+ [Modules.CUSTOMER]: {
+ customer_id: "cus_123",
+ },
+ [Modules.PAYMENT]: {
+ account_holder_id: "acchld_123",
+ },
+})
+```
+
+### createRemoteLinkStep
+
+```ts
+import { createRemoteLinkStep } from "@medusajs/medusa/core-flows"
+
+// ...
+
+createRemoteLinkStep({
+ [Modules.CUSTOMER]: {
+ customer_id: "cus_123",
+ },
+ [Modules.PAYMENT]: {
+ account_holder_id: "acchld_123",
+ },
+})
+```
+
+***
+
+## Order Module
+
+An order's payment details are stored in a payment collection. This also applies for claims and exchanges.
+
+So, Medusa defines links between the `PaymentCollection` data model and the `Order`, `OrderClaim`, and `OrderExchange` data models.
+
+
+
+### Retrieve with Query
+
+To retrieve the order of a payment collection with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `order.*` in `fields`:
+
+### query.graph
+
+```ts
+const { data: paymentCollections } = await query.graph({
+ entity: "payment_collection",
+ fields: [
+ "order.*",
+ ],
+})
+
+// paymentCollections[0].order
+```
+
+### useQueryGraphStep
+
+```ts
+import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
+
+// ...
+
+const { data: paymentCollections } = useQueryGraphStep({
+ entity: "payment_collection",
+ fields: [
+ "order.*",
+ ],
+})
+
+// paymentCollections[0].order
+```
+
+### Manage with Link
+
+To manage the payment collections of an order, use [Link](https://docs.medusajs.com/docs/learn/fundamentals/module-links/link/index.html.md):
+
+### link.create
+
+```ts
+import { Modules } from "@medusajs/framework/utils"
+
+// ...
+
+await link.create({
+ [Modules.ORDER]: {
+ order_id: "order_123",
+ },
+ [Modules.PAYMENT]: {
+ payment_collection_id: "paycol_123",
+ },
+})
+```
+
+### createRemoteLinkStep
+
+```ts
+import { Modules } from "@medusajs/framework/utils"
+import { createRemoteLinkStep } from "@medusajs/medusa/core-flows"
+
+// ...
+
+createRemoteLinkStep({
+ [Modules.ORDER]: {
+ order_id: "order_123",
+ },
+ [Modules.PAYMENT]: {
+ payment_collection_id: "paycol_123",
+ },
+})
+```
+
+***
+
+## Region Module
+
+You can specify for each region which payment providers are available. The Medusa application defines a link between the `PaymentProvider` and the `Region` data models.
+
+
+
+This increases the flexibility of your store. For example, you only show during checkout the payment providers associated with the cart's region.
+
+### Retrieve with Query
+
+To retrieve the regions of a payment provider with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `regions.*` in `fields`:
+
+### query.graph
+
+```ts
+const { data: paymentProviders } = await query.graph({
+ entity: "payment_provider",
+ fields: [
+ "regions.*",
+ ],
+})
+
+// paymentProviders[0].regions
+```
+
+### useQueryGraphStep
+
+```ts
+import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
+
+// ...
+
+const { data: paymentProviders } = useQueryGraphStep({
+ entity: "payment_provider",
+ fields: [
+ "regions.*",
+ ],
+})
+
+// paymentProviders[0].regions
+```
+
+### Manage with Link
+
+To manage the payment providers in a region, use [Link](https://docs.medusajs.com/docs/learn/fundamentals/module-links/link/index.html.md):
+
+### link.create
+
+```ts
+import { Modules } from "@medusajs/framework/utils"
+
+// ...
+
+await link.create({
+ [Modules.REGION]: {
+ region_id: "reg_123",
+ },
+ [Modules.PAYMENT]: {
+ payment_provider_id: "pp_stripe_stripe",
+ },
+})
+```
+
+### createRemoteLinkStep
+
+```ts
+import { Modules } from "@medusajs/framework/utils"
+import { createRemoteLinkStep } from "@medusajs/medusa/core-flows"
+
+// ...
+
+createRemoteLinkStep({
+ [Modules.REGION]: {
+ region_id: "reg_123",
+ },
+ [Modules.PAYMENT]: {
+ payment_provider_id: "pp_stripe_stripe",
+ },
+})
+```
+
+
+# Payment
+
+In this document, you’ll learn what a payment is and how it's created, captured, and refunded.
+
+## What's a Payment?
+
+When a payment session is authorized, a payment, represented by the [Payment data model](https://docs.medusajs.com/references/payment/models/Payment/index.html.md), is created. This payment can later be captured or refunded.
+
+A payment carries many of the data and relations of a payment session:
+
+- It belongs to the same payment collection.
+- It’s associated with the same payment provider, which handles further payment processing.
+- It stores the payment session’s `data` property in its `data` property, as it’s still useful for the payment provider’s processing.
+
+***
+
+## Capture Payments
+
+When a payment is captured, a capture, represented by the [Capture data model](https://docs.medusajs.com/references/payment/models/Capture/index.html.md), is created. It holds details related to the capture, such as the amount, the capture date, and more.
+
+The payment can also be captured incrementally, each time a capture record is created for that amount.
+
+
+
+***
+
+## Refund Payments
+
+When a payment is refunded, a refund, represented by the [Refund data model](https://docs.medusajs.com/references/payment/models/Refund/index.html.md), is created. It holds details related to the refund, such as the amount, refund date, and more.
+
+A payment can be refunded multiple times, and each time a refund record is created.
+
+
+
+
+# Payment Collection
+
+In this document, you’ll learn what a payment collection is and how the Medusa application uses it with the Cart Module.
+
+## What's a Payment Collection?
+
+A payment collection stores payment details related to a resource, such as a cart or an order. It’s represented by the [PaymentCollection data model](https://docs.medusajs.com/references/payment/models/PaymentCollection/index.html.md).
+
+Every purchase or request for payment starts with a payment collection. The collection holds details necessary to complete the payment, including:
+
+- The [payment sessions](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/payment/payment-session/index.html.md) that represents the payment amount to authorize.
+- The [payments](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/payment/payment/index.html.md) that are created when a payment session is authorized. They can be captured and refunded.
+- The [payment providers](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/payment/payment-provider/index.html.md) that handle the processing of each payment session, including the authorization, capture, and refund.
+
+***
+
+## Multiple Payments
+
+The payment collection supports multiple payment sessions and payments.
+
+You can use this to accept payments in increments or split payments across payment providers.
+
+
+
+***
+
+## Usage with the Cart Module
+
+The Cart Module provides cart management features. However, it doesn’t provide any features related to accepting payment.
+
+During checkout, the Medusa application links a cart to a payment collection, which will be used for further payment processing.
+
+It also implements the payment flow during checkout as explained in [this documentation](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/payment/payment-flow/index.html.md).
+
+
+
+
+# Accept Payment Flow
+
+In this document, you’ll learn how to implement an accept-payment flow using workflows or the Payment Module's main service.
+
+It's highly recommended to use Medusa's workflows to implement this flow. Use the Payment Module's main service for more complex cases.
+
+For a guide on how to implement this flow in the storefront, check out [this guide](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/storefront-development/checkout/payment/index.html.md).
+
+## Flow Overview
+
+
+
+***
+
+## 1. Create a Payment Collection
+
+A payment collection holds all details related to a resource’s payment operations. So, you start off by creating a payment collection.
+
+For example:
+
+### Using Workflow
+
+```ts
+import { createPaymentCollectionForCartWorkflow } from "@medusajs/medusa/core-flows"
+
+// ...
+
+await createPaymentCollectionForCartWorkflow(req.scope)
+ .run({
+ input: {
+ cart_id: "cart_123",
+ },
+ })
+```
+
+### Using Service
+
+```ts
+const paymentCollection =
+ await paymentModuleService.createPaymentCollections({
+ currency_code: "usd",
+ amount: 5000,
+ })
+```
+
+***
+
+## 2. Create Payment Sessions
+
+The payment collection has one or more payment sessions, each being a payment amount to be authorized by a payment provider.
+
+So, after creating the payment collection, create at least one payment session for a provider.
+
+For example:
+
+### Using Workflow
+
+```ts
+import { createPaymentSessionsWorkflow } from "@medusajs/medusa/core-flows"
+
+// ...
+
+const { result: paymentSesion } = await createPaymentSessionsWorkflow(req.scope)
+ .run({
+ input: {
+ payment_collection_id: "paycol_123",
+ provider_id: "stripe",
+ },
+ })
+```
+
+### Using Service
+
+```ts
+const paymentSession =
+ await paymentModuleService.createPaymentSession(
+ paymentCollection.id,
+ {
+ provider_id: "stripe",
+ currency_code: "usd",
+ amount: 5000,
+ data: {
+ // any necessary data for the
+ // payment provider
+ },
+ }
+ )
+```
+
+***
+
+## 3. Authorize Payment Session
+
+Once the customer chooses a payment session, start the authorization process. This may involve some action performed by the third-party payment provider, such as entering a 3DS code.
+
+For example:
+
+### Using Step
+
+```ts
+import { authorizePaymentSessionStep } from "@medusajs/medusa/core-flows"
+
+// ...
+
+authorizePaymentSessionStep({
+ id: "payses_123",
+ context: {},
+})
+```
+
+### Using Service
+
+```ts
+const payment = authorizePaymentSessionStep({
+ id: "payses_123",
+ context: {},
+})
+```
+
+When the payment authorization is successful, a payment is created and returned.
+
+### Handling Additional Action
+
+If you used the `authorizePaymentSessionStep`, you don't need to implement this logic as it's implemented in the step.
+
+If the payment authorization isn’t successful, whether because it requires additional action or for another reason, the method updates the payment session with the new status and throws an error.
+
+In that case, you can catch that error and, if the session's `status` property is `requires_more`, handle the additional action, then retry the authorization.
+
+For example:
+
+```ts
+try {
+ const payment =
+ await paymentModuleService.authorizePaymentSession(
+ paymentSession.id,
+ {}
+ )
+} catch (e) {
+ // retrieve the payment session again
+ const updatedPaymentSession = (
+ await paymentModuleService.listPaymentSessions({
+ id: [paymentSession.id],
+ })
+ )[0]
+
+ if (updatedPaymentSession.status === "requires_more") {
+ // TODO perform required action
+ // TODO authorize payment again.
+ }
+}
+```
+
+***
+
+## 4. Payment Flow Complete
+
+The payment flow is complete once the payment session is authorized and the payment is created.
+
+You can then:
+
+- Capture the payment either using the [capturePaymentWorkflow](https://docs.medusajs.com/references/medusa-workflows/capturePaymentWorkflow/index.html.md) or [capturePayment method](https://docs.medusajs.com/references/payment/capturePayment/index.html.md).
+- Refund captured amounts using the [refundPaymentWorkflow](https://docs.medusajs.com/references/medusa-workflows/refundPaymentWorkflow/index.html.md) or [refundPayment method](https://docs.medusajs.com/references/payment/refundPayment/index.html.md).
+
+Some payment providers allow capturing the payment automatically once it’s authorized. In that case, you don’t need to do it manually.
+
+
+# Payment Session
+
+In this document, you’ll learn what a payment session is.
+
+## What's a Payment Session?
+
+A payment session, represented by the [PaymentSession data model](https://docs.medusajs.com/references/payment/models/PaymentSession/index.html.md), is a payment amount to be authorized. It’s associated with a payment provider that handles authorizing it.
+
+A payment collection can have multiple payment sessions. Using this feature, you can implement payment in installments or payments using multiple providers.
+
+
+
+***
+
+## data Property
+
+Payment providers may need additional data to process the payment later. The `PaymentSession` data model has a `data` property used to store that data.
+
+For example, the customer's ID in Stripe is stored in the `data` property.
+
+***
+
+## Payment Session Status
+
+The `status` property of a payment session indicates its current status. Its value can be:
+
+- `pending`: The payment session is awaiting authorization.
+- `requires_more`: The payment session requires an action before it’s authorized. For example, to enter a 3DS code.
+- `authorized`: The payment session is authorized.
+- `error`: An error occurred while authorizing the payment.
+- `canceled`: The authorization of the payment session has been canceled.
+
+
+# Payment Module Provider
+
+In this document, you’ll learn what a payment module provider is.
+
+Refer to this [Medusa Admin User Guide](https://docs.medusajs.com/user-guide/settings/regions/index.html.md) to learn how to manage the payment providers available in a region using the dashboard.
+
+## What's a Payment Module Provider?
+
+A payment module provider registers a payment provider that handles payment processing in the Medusa application. It integrates third-party payment providers, such as Stripe.
+
+To authorize a payment amount with a payment provider, a payment session is created and associated with that payment provider. The payment provider is then used to handle the authorization.
+
+After the payment session is authorized, the payment provider is associated with the resulting payment and handles its payment processing, such as to capture or refund payment.
+
+### List of Payment Module Providers
+
+- [Stripe](https://docs.medusajs.com/commerce-modules/payment/payment-provider/stripe/index.html.md)
+
+***
+
+## System Payment Provider
+
+The Payment Module provides a `system` payment provider that acts as a placeholder payment provider.
+
+It doesn’t handle payment processing and delegates that to the merchant. It acts similarly to a cash-on-delivery (COD) payment method.
+
+***
+
+## How are Payment Providers Created?
+
+A payment provider is a module whose main service extends the `AbstractPaymentProvider` imported from `@medusajs/framework/utils`.
+
+Refer to [this guide](https://docs.medusajs.com/references/payment/provider/index.html.md) on how to create a payment provider for the Payment Module.
+
+***
+
+## Configure Payment Providers
+
+The Payment Module accepts a `providers` option that allows you to register providers in your application.
+
+Learn more about this option in [this documentation](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/payment/module-options#providers/index.html.md).
+
+***
+
+## PaymentProvider Data Model
+
+When the Medusa application starts and registers the payment providers, it also creates a record of the `PaymentProvider` data model if none exists.
+
+This data model is used to reference a payment provider and determine whether it’s installed in the application.
+
+
+# Webhook Events
+
+In this document, you’ll learn how the Payment Module supports listening to webhook events.
+
+## What's a Webhook Event?
+
+A webhook event is sent from a third-party payment provider to your application. It indicates a change in a payment’s status.
+
+This is useful in many cases such as when a payment is being processed asynchronously or when a request is interrupted and the payment provider is sending details on the process later.
+
+***
+
+## getWebhookActionAndData Method
+
+The Payment Module’s main service has a [getWebhookActionAndData method](https://docs.medusajs.com/references/payment/getWebhookActionAndData/index.html.md) used to handle incoming webhook events from third-party payment services. The method delegates the handling to the associated payment provider, which returns the event's details.
+
+Medusa implements a webhook listener route at the `/hooks/payment/[identifier]_[provider]` API route, where:
+
+- `[identifier]` is the `identifier` static property defined in the payment provider. For example, `stripe`.
+- `[provider]` is the ID of the provider. For example, `stripe`.
+
+For example, when integrating basic Stripe payments with the [Stripe Module Provider](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/payment/payment-provider/stripe/index.html.md), the webhook listener route is `/hooks/payment/stripe_stripe`. If you're integrating Stripe's Bancontact payments, the webhook listener route is `/hooks/payment/stripe-bancontact_stripe`.
+
+Use that webhook listener in your third-party payment provider's configurations.
+
+
+
+If the event's details indicate that the payment should be authorized, then the [authorizePaymentSession method of the main service](https://docs.medusajs.com/references/payment/authorizePaymentSession/index.html.md) is executed on the specified payment session.
+
+If the event's details indicate that the payment should be captured, then the [capturePayment method of the main service](https://docs.medusajs.com/references/payment/capturePayment/index.html.md) is executed on the payment of the specified payment session.
+
+### Actions After Webhook Payment Processing
+
+After the payment webhook actions are processed and the payment is authorized or captured, the Medusa application completes the cart associated with the payment's collection if it's not completed yet.
+
+
+# Configure Selling Products
+
+In this guide, you'll learn how to set up and configure your products based on their shipping and inventory requirements, the product type, how you want to sell them, or your commerce ecosystem.
+
+The concepts in this guide are applicable starting from Medusa v2.5.1.
+
+## Scenario
+
+Businesses can have different selling requirements:
+
+1. They may sell physical or digital items.
+2. They may sell items that don't require shipping or inventory management, such as selling digital products, services, or booking appointments.
+3. They may sell items whose inventory is managed by an external system, such as an ERP.
+
+Medusa supports these different selling requirements by allowing you to configure shipping and inventory requirements for products and their variants. This guide explains how these configurations work, then provides examples of setting up different use cases.
+
+***
+
+## Configuring Shipping Requirements
+
+The Medusa application defines a link between the `Product` data model and a [ShippingProfile](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/fulfillment/concepts#shipping-profile/index.html.md) in the [Fulfillment Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/fulfillment/index.html.md), allowing you to associate a product with a shipping profile.
+
+When a product is associated with a shipping profile, its variants require shipping and fulfillment when purchased. This is useful for physical products or digital products that require custom fulfillment.
+
+If a product doesn't have an associated shipping profile, its variants don't require shipping and fulfillment when purchased. This is useful for digital products, for example, that don't require shipping.
+
+### Overriding Shipping Requirements for Variants
+
+A product variant whose inventory is managed by Medusa (its `manage_inventory` property is enabled) has an [inventory item](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/inventory/concepts#inventoryitem/index.html.md). The inventory item has a `requires_shipping` property that can be used to override its shipping requirement. This is useful if the product has an associated shipping profile but you want to disable shipping for a specific variant, or vice versa.
+
+Learn more about product variant's inventory in [this guide](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/product/variant-inventory/index.html.md).
+
+When a product variant is purchased, the Medusa application decides whether the purchased item requires shipping in the following order:
+
+1. The product variant has an inventory item. In this case, the Medusa application uses the inventory item's `requires_shipping` property to determine if the item requires shipping.
+2. If the product variant doesn't have an inventory item, the Medusa application checks whether the product has an associated shipping profile to determine if the item requires shipping.
+
+***
+
+## Use Case Examples
+
+By combining configurations of shipment requirements and inventory management, you can set up your products to support your use case:
+
+|Use Case|Configurations|Example|
+|---|---|---|---|---|
+|Item that's shipped on purchase, and its variant inventory is managed by the Medusa application.||Any stock-kept item (clothing, for example), whose inventory is managed in the Medusa application.|
+|Item that's shipped on purchase, but its variant inventory is managed externally (not by Medusa) or it has infinite stock.||Any stock-kept item (clothing, for example), whose inventory is managed in an ERP or has infinite stock.|
+|Item that's not shipped on purchase, but its variant inventory is managed by Medusa.||Digital products, such as licenses, that don't require shipping but have a limited quantity.|
+|Item that doesn't require shipping and its variant inventory isn't managed by Medusa.|||
+
+
+# Links between Product Module and Other Modules
+
+This document showcases the module links defined between the Product Module and other Commerce Modules.
+
+## Summary
+
+The Product Module has the following links to other modules:
+
+Read-only links are used to query data across modules, but the relations aren't stored in a pivot table in the database.
+
+|First Data Model|Second Data Model|Type|Description|
+|---|---|---|---|
+|LineItem|Product|Read-only - has one|Learn more|
+|Product|ShippingProfile|Stored - many-to-one|Learn more|
+|ProductVariant|InventoryItem|Stored - many-to-many|Learn more|
+|OrderLineItem|Product|Read-only - has one|Learn more|
+|ProductVariant|PriceSet|Stored - one-to-one|Learn more|
+|Product|SalesChannel|Stored - many-to-many|Learn more|
+
+***
+
+## Cart Module
+
+Medusa defines read-only links between:
+
+- The [Cart Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/cart/index.html.md)'s `LineItem` data model and the `Product` data model. Because the link is read-only from the `LineItem`'s side, you can only retrieve the product of a line item, and not the other way around.
+- The `ProductVariant` data model and the [Cart Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/cart/index.html.md)'s `LineItem` data model. Because the link is read-only from the `LineItem`'s side, you can only retrieve the variant of a line item, and not the other way around.
+
+### Retrieve with Query
+
+To retrieve the variant of a line item with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `variant.*` in `fields`:
+
+To retrieve the product, pass `product.*` in `fields`.
+
+### query.graph
+
+```ts
+const { data: lineItems } = await query.graph({
+ entity: "line_item",
+ fields: [
+ "variant.*",
+ ],
+})
+
+// lineItems[0].variant
+```
+
+### useQueryGraphStep
+
+```ts
+import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
+
+// ...
+
+const { data: lineItems } = useQueryGraphStep({
+ entity: "line_item",
+ fields: [
+ "variant.*",
+ ],
+})
+
+// lineItems[0].variant
+```
+
+***
+
+## Fulfillment Module
+
+Medusa defines a link between the `Product` data model and the `ShippingProfile` data model of the Fulfillment Module. Each product must belong to a shipping profile.
+
+This link is introduced in [Medusa v2.5.0](https://github.com/medusajs/medusa/releases/tag/v2.5.0).
+
+### Retrieve with Query
+
+To retrieve the shipping profile of a product with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `shipping_profile.*` in `fields`:
+
+### query.graph
+
+```ts
+const { data: products } = await query.graph({
+ entity: "product",
+ fields: [
+ "shipping_profile.*",
+ ],
+})
+
+// products[0].shipping_profile
+```
+
+### useQueryGraphStep
+
+```ts
+import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
+
+// ...
+
+const { data: products } = useQueryGraphStep({
+ entity: "product",
+ fields: [
+ "shipping_profile.*",
+ ],
+})
+
+// products[0].shipping_profile
+```
+
+### Manage with Link
+
+To manage the shipping profile of a product, use [Link](https://docs.medusajs.com/docs/learn/fundamentals/module-links/link/index.html.md):
+
+### link.create
+
+```ts
+import { Modules } from "@medusajs/framework/utils"
+
+// ...
+
+await link.create({
+ [Modules.PRODUCT]: {
+ product_id: "prod_123",
+ },
+ [Modules.FULFILLMENT]: {
+ shipping_profile_id: "sp_123",
+ },
+})
+```
+
+### createRemoteLinkStep
+
+```ts
+import { Modules } from "@medusajs/framework/utils"
+import { createRemoteLinkStep } from "@medusajs/medusa/core-flows"
+
+// ...
+
+createRemoteLinkStep({
+ [Modules.PRODUCT]: {
+ product_id: "prod_123",
+ },
+ [Modules.FULFILLMENT]: {
+ shipping_profile_id: "sp_123",
+ },
+})
+```
+
+***
+
+## Inventory Module
+
+The Inventory Module provides inventory-management features for any stock-kept item.
+
+Medusa defines a link between the `ProductVariant` and `InventoryItem` data models. Each product variant has different inventory details.
+
+
+
+When the `manage_inventory` property of a product variant is enabled, you can manage the variant's inventory in different locations through this relation.
+
+Learn more about product variant's inventory management in [this guide](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/product/variant-inventory/index.html.md).
+
+### Retrieve with Query
+
+To retrieve the inventory items of a product variant with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `inventory_items.*` in `fields`:
+
+### query.graph
+
+```ts
+const { data: variants } = await query.graph({
+ entity: "variant",
+ fields: [
+ "inventory_items.*",
+ ],
+})
+
+// variants[0].inventory_items
+```
+
+### useQueryGraphStep
+
+```ts
+import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
+
+// ...
+
+const { data: variants } = useQueryGraphStep({
+ entity: "variant",
+ fields: [
+ "inventory_items.*",
+ ],
+})
+
+// variants[0].inventory_items
+```
+
+### Manage with Link
+
+To manage the inventory items of a variant, use [Link](https://docs.medusajs.com/docs/learn/fundamentals/module-links/link/index.html.md):
+
+### link.create
+
+```ts
+import { Modules } from "@medusajs/framework/utils"
+
+// ...
+
+await link.create({
+ [Modules.PRODUCT]: {
+ variant_id: "variant_123",
+ },
+ [Modules.INVENTORY]: {
+ inventory_item_id: "iitem_123",
+ },
+})
+```
+
+### createRemoteLinkStep
+
+```ts
+import { Modules } from "@medusajs/framework/utils"
+import { createRemoteLinkStep } from "@medusajs/medusa/core-flows"
+
+// ...
+
+createRemoteLinkStep({
+ [Modules.PRODUCT]: {
+ variant_id: "variant_123",
+ },
+ [Modules.INVENTORY]: {
+ inventory_item_id: "iitem_123",
+ },
+})
+```
+
+***
+
+## Order Module
+
+Medusa defines read-only links between:
+
+- the [Order Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/order/index.html.md)'s `OrderLineItem` data model and the `Product` data model. Because the link is read-only from the `OrderLineItem`'s side, you can only retrieve the product of an order line item, and not the other way around.
+- the [Order Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/order/index.html.md)'s `OrderLineItem` data model and the `ProductVariant` data model. Because the link is read-only from the `OrderLineItem`'s side, you can only retrieve the variant of an order line item, and not the other way around.
+
+### Retrieve with Query
+
+To retrieve the variant of a line item with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `variant.*` in `fields`:
+
+To retrieve the product, pass `product.*` in `fields`.
+
+### query.graph
+
+```ts
+const { data: lineItems } = await query.graph({
+ entity: "order_line_item",
+ fields: [
+ "variant.*",
+ ],
+})
+
+// lineItems[0].variant
+```
+
+### useQueryGraphStep
+
+```ts
+import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
+
+// ...
+
+const { data: lineItems } = useQueryGraphStep({
+ entity: "order_line_item",
+ fields: [
+ "variant.*",
+ ],
+})
+
+// lineItems[0].variant
+```
+
+***
+
+## Pricing Module
+
+The Product Module doesn't provide pricing-related features.
+
+Instead, Medusa defines a link between the `ProductVariant` and the `PriceSet` data models. A product variant’s prices are stored belonging to a price set.
+
+
+
+So, to add prices for a product variant, create a price set and add the prices to it.
+
+### Retrieve with Query
+
+To retrieve the price set of a variant with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `price_set.*` in `fields`:
+
+### query.graph
+
+```ts
+const { data: variants } = await query.graph({
+ entity: "variant",
+ fields: [
+ "price_set.*",
+ ],
+})
+
+// variants[0].price_set
+```
+
+### useQueryGraphStep
+
+```ts
+import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
+
+// ...
+
+const { data: variants } = useQueryGraphStep({
+ entity: "variant",
+ fields: [
+ "price_set.*",
+ ],
+})
+
+// variants[0].price_set
+```
+
+### Manage with Link
+
+To manage the price set of a variant, use [Link](https://docs.medusajs.com/docs/learn/fundamentals/module-links/link/index.html.md):
+
+### link.create
+
+```ts
+import { Modules } from "@medusajs/framework/utils"
+
+// ...
+
+await link.create({
+ [Modules.PRODUCT]: {
+ variant_id: "variant_123",
+ },
+ [Modules.PRICING]: {
+ price_set_id: "pset_123",
+ },
+})
+```
+
+### createRemoteLinkStep
+
+```ts
+import { Modules } from "@medusajs/framework/utils"
+import { createRemoteLinkStep } from "@medusajs/medusa/core-flows"
+
+// ...
+
+createRemoteLinkStep({
+ [Modules.PRODUCT]: {
+ variant_id: "variant_123",
+ },
+ [Modules.PRICING]: {
+ price_set_id: "pset_123",
+ },
+})
+```
+
+***
+
+## Sales Channel Module
+
+The Sales Channel Module provides functionalities to manage multiple selling channels in your store.
+
+Medusa defines a link between the `Product` and `SalesChannel` data models. A product can have different availability in different sales channels.
+
+
+
+### Retrieve with Query
+
+To retrieve the sales channels of a product with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `sales_channels.*` in `fields`:
+
+### query.graph
+
+```ts
+const { data: products } = await query.graph({
+ entity: "product",
+ fields: [
+ "sales_channels.*",
+ ],
+})
+
+// products[0].sales_channels
+```
+
+### useQueryGraphStep
+
+```ts
+import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
+
+// ...
+
+const { data: products } = useQueryGraphStep({
+ entity: "product",
+ fields: [
+ "sales_channels.*",
+ ],
+})
+
+// products[0].sales_channels
+```
+
+### Manage with Link
+
+To manage the sales channels of a product, use [Link](https://docs.medusajs.com/docs/learn/fundamentals/module-links/link/index.html.md):
+
+### link.create
+
+```ts
+import { Modules } from "@medusajs/framework/utils"
+
+// ...
+
+await link.create({
+ [Modules.PRODUCT]: {
+ product_id: "prod_123",
+ },
+ [Modules.SALES_CHANNEL]: {
+ sales_channel_id: "sc_123",
+ },
+})
+```
+
+### createRemoteLinkStep
+
+```ts
+import { Modules } from "@medusajs/framework/utils"
+import { createRemoteLinkStep } from "@medusajs/medusa/core-flows"
+
+// ...
+
+createRemoteLinkStep({
+ [Modules.PRODUCT]: {
+ product_id: "prod_123",
+ },
+ [Modules.SALES_CHANNEL]: {
+ sales_channel_id: "sc_123",
+ },
+})
+```
+
+
+# Product Variant Inventory
+
+# Product Variant Inventory
+
+In this guide, you'll learn about the inventory management features related to product variants.
+
+Refer to this [Medusa Admin User Guide](https://docs.medusajs.com/user-guide/products/variants#manage-product-variant-inventory/index.html.md) to learn how to manage inventory of product variants.
+
+## Configure Inventory Management of Product Variants
+
+A product variant, represented by the [ProductVariant](https://docs.medusajs.com/references/product/models/ProductVariant/index.html.md) data model, has a `manage_inventory` field that's disabled by default. This field indicates whether you'll manage the inventory quantity of the product variant in the Medusa application. You can also keep `manage_inventory` disabled if you manage the product's inventory in an external system, such as an ERP.
+
+The Product Module doesn't provide inventory-management features. Instead, the Medusa application uses the [Inventory Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/inventory/index.html.md) to manage inventory for products and variants. When `manage_inventory` is disabled, the Medusa application always considers the product variant to be in stock. This is useful if your product's variants aren't items that can be stocked, such as digital products, or they don't have a limited stock quantity.
+
+When `manage_inventory` is enabled, the Medusa application tracks the inventory of the product variant using the [Inventory Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/inventory/index.html.md). For example, when a customer purchases a product variant, the Medusa application decrements the stocked quantity of the product variant.
+
+***
+
+## How the Medusa Application Manages Inventory
+
+When a product variant has `manage_inventory` enabled, the Medusa application creates an inventory item using the [Inventory Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/inventory/index.html.md) and links it to the product variant.
+
+
+
+The inventory item has one or more locations, called inventory levels, that represent the stock quantity of the product variant at a specific location. This allows you to manage inventory across multiple warehouses, such as a warehouse in the US and another in Europe.
+
+
+
+Learn more about inventory concepts in the [Inventory Module's documentation](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/inventory/concepts/index.html.md).
+
+The Medusa application represents and manages stock locations using the [Stock Location Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/stock-location/index.html.md). It creates a read-only link between the `InventoryLevel` and `StockLocation` data models so that it can retrieve the stock location of an inventory level.
+
+
+
+Learn more about the Stock Location Module in the [Stock Location Module's documentation](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/stock-location/concepts/index.html.md).
+
+### Product Inventory in Storefronts
+
+When a storefront sends a request to the Medusa application, it must always pass a [publishable API key](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/sales-channel/publishable-api-keys/index.html.md) in the request header. This API key specifies the sales channels, available through the [Sales Channel Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/sales-channel/index.html.md), of the storefront.
+
+The Medusa application links sales channels to stock locations, indicating the locations available for a specific sales channel. So, all inventory-related operations are scoped by the sales channel and its associated stock locations.
+
+For example, the availability of a product variant is determined by the `stocked_quantity` of its inventory level at the stock location linked to the storefront's sales channel.
+
+
+
+***
+
+## Variant Back Orders
+
+Product variants have an `allow_backorder` field that's disabled by default. When enabled, the Medusa application allows customers to purchase the product variant even when it's out of stock. Use this when your product variant is available through on-demand or pre-order purchase.
+
+You can also allow customers to subscribe to restock notifications of a product variant as explained in [this guide](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/recipes/commerce-automation/restock-notification/index.html.md).
+
+***
+
+## Additional Resources
+
+The following guides provide more details on inventory management in the Medusa application:
+
+- [Inventory Kits in the Inventory Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/inventory/inventory-kit/index.html.md): Learn how you can implement bundled or multi-part products through the Inventory Module.
+- [Retrieve Product Variant Inventory Quantity](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/product/guides/variant-inventory/index.html.md): Learn how to retrieve the available inventory quantity of a product variant.
+- [Configure Selling Products](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/product/selling-products/index.html.md): Learn how to use inventory management to support different use cases when selling products.
+- [Inventory in Flows](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/inventory/inventory-in-flows/index.html.md): Learn how Medusa utilizes inventory management in different flows.
+- [Storefront guide: how to retrieve a product variant's inventory details](https://docs.medusajs.com/resources/storefront-development/products/inventory/index.html.md).
+
+
+# Promotion Actions
+
+In this document, you’ll learn about promotion actions and how they’re computed using the [computeActions method](https://docs.medusajs.com/references/promotion/computeActions/index.html.md).
+
+## computeActions Method
+
+The Promotion Module's main service has a [computeActions method](https://docs.medusajs.com/references/promotion/computeActions/index.html.md) that returns an array of actions to perform on a cart when one or more promotions are applied.
+
+Actions inform you what adjustment must be made to a cart item or shipping method. Each action is an object having the `action` property indicating the type of action.
+
+***
+
+## Action Types
+
+### `addItemAdjustment` Action
+
+The `addItemAdjustment` action indicates that an adjustment must be made to an item. For example, removing $5 off its amount.
+
+This action has the following format:
+
+```ts
+export interface AddItemAdjustmentAction {
+ action: "addItemAdjustment"
+ item_id: string
+ amount: number
+ code: string
+ description?: string
+}
+```
+
+This action means that a new record should be created of the `LineItemAdjustment` data model in the Cart Module, or `OrderLineItemAdjustment` data model in the Order Module.
+
+Refer to [this reference](https://docs.medusajs.com/references/promotion/interfaces/promotion.AddItemAdjustmentAction/index.html.md) for details on the object’s properties.
+
+### `removeItemAdjustment` Action
+
+The `removeItemAdjustment` action indicates that an adjustment must be removed from a line item. For example, remove the $5 discount.
+
+The `computeActions` method accepts any previous item adjustments in the `items` property of the second parameter.
+
+This action has the following format:
+
+```ts
+export interface RemoveItemAdjustmentAction {
+ action: "removeItemAdjustment"
+ adjustment_id: string
+ description?: string
+ code: string
+}
+```
+
+This action means that a new record should be removed of the `LineItemAdjustment` (or `OrderLineItemAdjustment`) with the specified ID in the `adjustment_id` property.
+
+Refer to [this reference](https://docs.medusajs.com/references/promotion/interfaces/promotion.RemoveItemAdjustmentAction/index.html.md) for details on the object’s properties.
+
+### `addShippingMethodAdjustment` Action
+
+The `addShippingMethodAdjustment` action indicates that an adjustment must be made on a shipping method. For example, make the shipping method free.
+
+This action has the following format:
+
+```ts
+export interface AddShippingMethodAdjustment {
+ action: "addShippingMethodAdjustment"
+ shipping_method_id: string
+ amount: number
+ code: string
+ description?: string
+}
+```
+
+This action means that a new record should be created of the `ShippingMethodAdjustment` data model in the Cart Module, or `OrderShippingMethodAdjustment` data model in the Order Module.
+
+Refer to [this reference](https://docs.medusajs.com/references/promotion/interfaces/promotion.AddShippingMethodAdjustment/index.html.md) for details on the object’s properties.
+
+### `removeShippingMethodAdjustment` Action
+
+The `removeShippingMethodAdjustment` action indicates that an adjustment must be removed from a shipping method. For example, remove the free shipping discount.
+
+The `computeActions` method accepts any previous shipping method adjustments in the `shipping_methods` property of the second parameter.
+
+This action has the following format:
+
+```ts
+export interface RemoveShippingMethodAdjustment {
+ action: "removeShippingMethodAdjustment"
+ adjustment_id: string
+ code: string
+}
+```
+
+When the Medusa application receives this action type, it removes the `ShippingMethodAdjustment` (or `OrderShippingMethodAdjustment`) with the specified ID in the `adjustment_id` property.
+
+Refer to [this reference](https://docs.medusajs.com/references/promotion/interfaces/promotion.RemoveShippingMethodAdjustment/index.html.md) for details on the object’s properties.
+
+### `campaignBudgetExceeded` Action
+
+When the `campaignBudgetExceeded` action is returned, the promotions within a campaign can no longer be used as the campaign budget has been exceeded.
+
+This action has the following format:
+
+```ts
+export interface CampaignBudgetExceededAction {
+ action: "campaignBudgetExceeded"
+ code: string
+}
+```
+
+Refer to [this reference](https://docs.medusajs.com/references/promotion/interfaces/promotion.CampaignBudgetExceededAction/index.html.md) for details on the object’s properties.
+
+
+# Application Method
+
+In this document, you'll learn what an application method is.
+
+## What is an Application Method?
+
+The [ApplicationMethod data model](https://docs.medusajs.com/references/promotion/models/ApplicationMethod/index.html.md) defines how a promotion is applied:
+
+|Property|Purpose|
+|---|---|
+|\`type\`|Does the promotion discount a fixed amount or a percentage?|
+|\`target\_type\`|Is the promotion applied on a cart item, shipping method, or the entire order?|
+|\`allocation\`|Is the discounted amount applied on each item or split between the applicable items?|
+
+## Target Promotion Rules
+
+When the promotion is applied to a cart item or a shipping method, you can restrict which items/shipping methods the promotion is applied to.
+
+The `ApplicationMethod` data model has a collection of `PromotionRule` records to restrict which items or shipping methods the promotion applies to. The `target_rules` property represents this relation.
+
+
+
+In this example, the promotion is only applied on products in the cart having the SKU `SHIRT`.
+
+***
+
+## Buy Promotion Rules
+
+When the promotion’s type is `buyget`, you must specify the “buy X” condition. For example, a cart must have two shirts before the promotion can be applied.
+
+The application method has a collection of `PromotionRule` items to define the “buy X” rule. The `buy_rules` property represents this relation.
+
+
+
+In this example, the cart must have two products with the SKU `SHIRT` for the promotion to be applied.
+
+
+# Promotion Concepts
+
+In this guide, you’ll learn about the main promotion and rule concepts in the Promotion Module.
+
+Refer to this [Medusa Admin User Guide](https://docs.medusajs.com/user-guide/promotions/index.html.md) to learn how to manage promotions using the dashboard.
+
+## What is a Promotion?
+
+A promotion, represented by the [Promotion data model](https://docs.medusajs.com/references/promotion/models/Promotion/index.html.md), is a discount that can be applied on cart items, shipping methods, or entire orders.
+
+A promotion has two types:
+
+- `standard`: A standard promotion with rules.
+- `buyget`: “A buy X get Y” promotion with rules.
+
+|\`standard\`|\`buyget\`|
+|---|---|
+|A coupon code that gives customers 10% off their entire order.|Buy two shirts and get another for free.|
+|A coupon code that gives customers $15 off any shirt in their order.|Buy two shirts and get 10% off the entire order.|
+|A discount applied automatically for VIP customers that removes 10% off their shipping method’s amount.|Spend $100 and get free shipping.|
+
+The Medusa Admin UI may not provide a way to create each of these promotion examples. However, they are supported by the Promotion Module and Medusa's workflows and API routes.
+
+***
+
+## Promotion Rules
+
+A promotion can be restricted by a set of rules, each rule is represented by the [PromotionRule data model](https://docs.medusajs.com/references/promotion/models/PromotionRule/index.html.md).
+
+For example, you can create a promotion that only customers of the `VIP` customer group can use.
+
+
+
+A `PromotionRule`'s `attribute` property indicates the property's name to which this rule is applied. For example, `customer_group_id`.
+
+The expected value for the attribute is stored in the `PromotionRuleValue` data model. So, a rule can have multiple values.
+
+When testing whether a promotion can be applied to a cart, the rule's `attribute` property and its values are tested on the cart itself.
+
+For example, the cart's customer must be part of the customer group(s) indicated in the promotion rule's value.
+
+### Flexible Rules
+
+The `PromotionRule`'s `operator` property adds more flexibility to the rule’s condition rather than simple equality (`eq`).
+
+For example, to restrict the promotion to only `VIP` and `B2B` customer groups:
+
+- Add a `PromotionRule` record with its `attribute` property set to `customer_group_id` and `operator` property to `in`.
+- Add two `PromotionRuleValue` records associated with the rule: one with the value `VIP` and the other `B2B`.
+
+
+
+In this case, a customer’s group must be in the `VIP` and `B2B` set of values to use the promotion.
+
+***
+
+## How to Apply Rules on a Promotion?
+
+### Using Workflows
+
+If you're managing promotions using [Medusa's workflows](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/medusa-workflows-reference/index.html.md) or the API routes that use them, you can specify rules for the promotion or its [application method](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/promotion/application-method/index.html.md).
+
+For example, if you're creating a promotion using the [createPromotionsWorkflow](https://docs.medusajs.com/resources/references/medusa-workflows/createPromotionsWorkflow/index.html.md):
+
+```ts
+const { result } = await createPromotionsWorkflow(container)
+ .run({
+ input: {
+ promotionsData: [{
+ code: "10OFF",
+ type: "standard",
+ status: "active",
+ application_method: {
+ type: "percentage",
+ target_type: "items",
+ allocation: "across",
+ value: 10,
+ currency_code: "usd",
+ },
+ rules: [
+ {
+ attribute: "customer.group.id",
+ operator: "eq",
+ values: [
+ "cusgrp_123",
+ ],
+ },
+ ],
+ }],
+ },
+ })
+```
+
+In this example, the promotion is restricted to customers with the `cusgrp_123` customer group.
+
+### Using Promotion Module's Service
+
+For most use cases, it's recommended to use [workflows](#using-workflows) instead of directly using the module's service.
+
+If you're managing promotions using the Promotion Module's service, you can specify rules for the promotion or its [application method](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/promotion/application-method/index.html.md) in its methods.
+
+For example, if you're creating a promotion with the [createPromotions](https://docs.medusajs.com/resources/references/promotion/createPromotions/index.html.md) method:
+
+```ts
+const promotions = await promotionModuleService.createPromotions([
+ {
+ code: "50OFF",
+ type: "standard",
+ status: "active",
+ application_method: {
+ type: "percentage",
+ target_type: "items",
+ value: 50,
+ },
+ rules: [
+ {
+ attribute: "customer.group.id",
+ operator: "eq",
+ values: [
+ "cusgrp_123",
+ ],
+ },
+ ],
+ },
+])
+```
+
+In this example, the promotion is restricted to customers with the `cusgrp_123` customer group.
+
+### How is the Promotion Rule Applied?
+
+A promotion is applied on a resource if its attributes match the promotion's rules.
+
+For example, consider you have the following promotion with a rule that restricts the promotion to a specific customer:
+
+```json
+{
+ "code": "10OFF",
+ "type": "standard",
+ "status": "active",
+ "application_method": {
+ "type": "percentage",
+ "target_type": "items",
+ "allocation": "across",
+ "value": 10,
+ "currency_code": "usd"
+ },
+ "rules": [
+ {
+ "attribute": "customer_id",
+ "operator": "eq",
+ "values": [
+ "cus_123"
+ ]
+ }
+ ]
+}
+```
+
+When you try to apply this promotion on a cart, the cart's `customer_id` is compared to the promotion rule's value based on the specified operator. So, the promotion will only be applied if the cart's `customer_id` is equal to `cus_123`.
+
+
+# Links between Promotion Module and Other Modules
+
+This document showcases the module links defined between the Promotion Module and other Commerce Modules.
+
+## Summary
+
+The Promotion Module has the following links to other modules:
+
+Read-only links are used to query data across modules, but the relations aren't stored in a pivot table in the database.
+
+|First Data Model|Second Data Model|Type|Description|
+|---|---|---|---|
+|Cart|Promotion|Stored - many-to-many|Learn more|
+|LineItemAdjustment|Promotion|Read-only - has one|Learn more|
+|Order|Promotion|Stored - many-to-many|Learn more|
+
+***
+
+## Cart Module
+
+A promotion can be applied on line items and shipping methods of a cart. Medusa defines a link between the `Cart` and `Promotion` data models.
+
+
+
+Medusa also defines a read-only link between the [Cart Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/cart/index.html.md)'s `LineItemAdjustment` data model and the `Promotion` data model. Because the link is read-only from the `LineItemAdjustment`'s side, you can only retrieve the promotion applied on a line item, and not the other way around.
+
+### Retrieve with Query
+
+To retrieve the carts that a promotion is applied on with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `carts.*` in `fields`:
+
+To retrieve the promotion of a line item adjustment, pass `promotion.*` in `fields`.
+
+### query.graph
+
+```ts
+const { data: promotions } = await query.graph({
+ entity: "promotion",
+ fields: [
+ "carts.*",
+ ],
+})
+
+// promotions[0].carts
+```
+
+### useQueryGraphStep
+
+```ts
+import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
+
+// ...
+
+const { data: promotions } = useQueryGraphStep({
+ entity: "promotion",
+ fields: [
+ "carts.*",
+ ],
+})
+
+// promotions[0].carts
+```
+
+### Manage with Link
+
+To manage the promotions of a cart, use [Link](https://docs.medusajs.com/docs/learn/fundamentals/module-links/link/index.html.md):
+
+### link.create
+
+```ts
+import { Modules } from "@medusajs/framework/utils"
+
+// ...
+
+await link.create({
+ [Modules.CART]: {
+ cart_id: "cart_123",
+ },
+ [Modules.PROMOTION]: {
+ promotion_id: "promo_123",
+ },
+})
+```
+
+### createRemoteLinkStep
+
+```ts
+import { Modules } from "@medusajs/framework/utils"
+import { createRemoteLinkStep } from "@medusajs/medusa/core-flows"
+
+// ...
+
+createRemoteLinkStep({
+ [Modules.CART]: {
+ cart_id: "cart_123",
+ },
+ [Modules.PROMOTION]: {
+ promotion_id: "promo_123",
+ },
+})
+```
+
+***
+
+## Order Module
+
+An order is associated with the promotion applied on it. Medusa defines a link between the `Order` and `Promotion` data models.
+
+
+
+### Retrieve with Query
+
+To retrieve the orders a promotion is applied on with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `orders.*` in `fields`:
+
+### query.graph
+
+```ts
+const { data: promotions } = await query.graph({
+ entity: "promotion",
+ fields: [
+ "orders.*",
+ ],
+})
+
+// promotions[0].orders
+```
+
+### useQueryGraphStep
+
+```ts
+import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
+
+// ...
+
+const { data: promotions } = useQueryGraphStep({
+ entity: "promotion",
+ fields: [
+ "orders.*",
+ ],
+})
+
+// promotions[0].orders
+```
+
+### Manage with Link
+
+To manage the promotion of an order, use [Link](https://docs.medusajs.com/docs/learn/fundamentals/module-links/link/index.html.md):
+
+### link.create
+
+```ts
+import { Modules } from "@medusajs/framework/utils"
+
+// ...
+
+await link.create({
+ [Modules.ORDER]: {
+ order_id: "order_123",
+ },
+ [Modules.PROMOTION]: {
+ promotion_id: "promo_123",
+ },
+})
+```
+
+### createRemoteLinkStep
+
+```ts
+import { Modules } from "@medusajs/framework/utils"
+import { createRemoteLinkStep } from "@medusajs/medusa/core-flows"
+
+// ...
+
+createRemoteLinkStep({
+ [Modules.ORDER]: {
+ order_id: "order_123",
+ },
+ [Modules.PROMOTION]: {
+ promotion_id: "promo_123",
+ },
+})
+```
+
+
+# Campaign
+
+In this document, you'll learn about campaigns.
+
+Refer to this [Medusa Admin User Guide](https://docs.medusajs.com/user-guide/promotions/campaigns/index.html.md) to learn how to manage campaigns using the dashboard.
+
+## What is a Campaign?
+
+A [Campaign](https://docs.medusajs.com/references/promotion/models/Campaign/index.html.md) combines promotions under the same conditions, such as start and end dates.
+
+
+
+***
+
+## Campaign Limits
+
+Each campaign has a budget represented by the [CampaignBudget data model](https://docs.medusajs.com/references/promotion/models/CampaignBudget/index.html.md). The budget limits how many times the promotion can be used.
+
+There are two types of budgets:
+
+- `spend`: An amount that, when crossed, the promotion becomes unusable. For example, if the amount limit is set to `$100`, and the total amount of usage of this promotion crosses that threshold, the promotion can no longer be applied.
+- `usage`: The number of times that a promotion can be used. For example, if the usage limit is set to `10`, the promotion can be used only 10 times by customers. After that, it can no longer be applied.
+
+
+
+
# Links between Region Module and Other Modules
This document showcases the module links defined between the Region Module and other Commerce Modules.
@@ -28640,483 +28792,6 @@ createRemoteLinkStep({
```
-# Links between Store Module and Other Modules
-
-This document showcases the module links defined between the Store Module and other Commerce Modules.
-
-## Summary
-
-The Store Module has the following links to other modules:
-
-Read-only links are used to query data across modules, but the relations aren't stored in a pivot table in the database.
-
-|First Data Model|Second Data Model|Type|Description|
-|---|---|---|---|
-|StoreCurrency|Currency|Read-only - has many|Learn more|
-
-***
-
-## Currency Module
-
-The Store Module has a `Currency` data model that stores the supported currencies of a store. However, these currencies don't hold all the details of a currency, such as its name or symbol.
-
-Instead, Medusa defines a read-only link between the [Currency Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/currency/index.html.md)'s `Currency` data model and the Store Module's `StoreCurrency` data model. This means you can retrieve the details of a store's supported currencies, but you don't manage the links in a pivot table in the database. The currencies of a store are determined by the `currency_code` of the [Currency](https://docs.medusajs.com/references/store/models/Currency/index.html.md) data model in the Store Module (not in the Currency Module).
-
-### Retrieve with Query
-
-To retrieve the details of a store's currencies with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `supported_currencies.currency.*` in `fields`:
-
-### query.graph
-
-```ts
-const { data: stores } = await query.graph({
- entity: "store",
- fields: [
- "supported_currencies.currency.*",
- ],
-})
-
-// stores[0].supported_currencies
-```
-
-### useQueryGraphStep
-
-```ts
-import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
-
-// ...
-
-const { data: stores } = useQueryGraphStep({
- entity: "store",
- fields: [
- "supported_currencies.currency.*",
- ],
-})
-
-// stores[0].supported_currencies
-```
-
-
-# Tax Calculation with the Tax Provider
-
-In this document, you’ll learn how tax lines are calculated and what a tax provider is.
-
-## Tax Lines Calculation
-
-Tax lines are calculated and retrieved using the [getTaxLines method of the Tax Module’s main service](https://docs.medusajs.com/references/tax/getTaxLines/index.html.md). It accepts an array of line items and shipping methods, and the context of the calculation.
-
-For example:
-
-```ts
-const taxLines = await taxModuleService.getTaxLines(
- [
- {
- id: "cali_123",
- product_id: "prod_123",
- unit_price: 1000,
- quantity: 1,
- },
- {
- id: "casm_123",
- shipping_option_id: "so_123",
- unit_price: 2000,
- },
- ],
- {
- address: {
- country_code: "us",
- },
- }
-)
-```
-
-The context object is used to determine which tax regions and rates to use in the calculation. It includes properties related to the address and customer.
-
-The example above retrieves the tax lines based on the tax region for the United States.
-
-The method returns tax lines for the line item and shipping methods. For example:
-
-```json
-[
- {
- "line_item_id": "cali_123",
- "rate_id": "txr_1",
- "rate": 10,
- "code": "XXX",
- "name": "Tax Rate 1"
- },
- {
- "shipping_line_id": "casm_123",
- "rate_id": "txr_2",
- "rate": 5,
- "code": "YYY",
- "name": "Tax Rate 2"
- }
-]
-```
-
-***
-
-## Using the Tax Provider in the Calculation
-
-The tax lines retrieved by the `getTaxLines` method are actually retrieved from the tax region’s provider.
-
-A tax module provider whose main service implements the logic to shape tax lines. Each tax region has a tax provider.
-
-The Tax Module provides a `system` tax provider that only transforms calculated item and shipping tax rates into the required return type.
-
-{/* ---
-
-TODO add once tax provider guide is updated + add module providers match other modules.
-
-## Create Tax Provider
-
-Refer to [this guide](/modules/tax/provider) to learn more about creating a tax provider. */}
-
-
-# Tax Module Options
-
-In this document, you'll learn about the options of the Tax Module.
-
-## providers
-
-The `providers` option is an array of either tax module providers or path to a file that defines a tax provider.
-
-When the Medusa application starts, these providers are registered and can be used to retrieve tax lines.
-
-```ts title="medusa-config.ts"
-import { Modules } from "@medusajs/framework/utils"
-
-// ...
-
-module.exports = defineConfig({
- // ...
- modules: [
- {
- resolve: "@medusajs/tax",
- options: {
- providers: [
- {
- resolve: "./path/to/my-provider",
- id: "my-provider",
- options: {
- // ...
- },
- },
- ],
- },
- },
- ],
-})
-```
-
-The objects in the array accept the following properties:
-
-- `resolve`: A string indicating the package name of the module provider or the path to it.
-- `id`: A string indicating the provider's unique name or ID.
-- `options`: An optional object of the module provider's options.
-
-
-# Tax Rates and Rules
-
-In this document, you’ll learn about tax rates and rules.
-
-Refer to this [Medusa Admin User Guide](https://docs.medusajs.com/user-guide/settings/tax-regions#manage-tax-rate-overrides/index.html.md) to learn how to manage tax rates using the dashboard.
-
-## What are Tax Rates?
-
-A tax rate is a percentage amount used to calculate the tax amount for each taxable item’s price, such as line items or shipping methods, in a cart. The sum of all calculated tax amounts are then added to the cart’s total as a tax total.
-
-Each tax region has a default tax rate. This tax rate is applied to all taxable items of a cart in that region.
-
-### Combinable Tax Rates
-
-Tax regions can have parent tax regions. To inherit the tax rates of the parent tax region, set the `is_combinable` of the child’s tax rates to `true`.
-
-Then, when tax rates are retrieved for a taxable item in the child region, both the child and the parent tax regions’ applicable rates are returned.
-
-***
-
-## Override Tax Rates with Rules
-
-You can create tax rates that override the default for specific conditions or rules.
-
-For example, you can have a default tax rate is 10%, but for products of type “Shirt” is %15.
-
-A tax region can have multiple tax rates, and each tax rate can have multiple tax rules. The [TaxRateRule data model](https://docs.medusajs.com/references/tax/models/TaxRateRule/index.html.md) represents a tax rate’s rule.
-
-
-
-These two properties of the data model identify the rule’s target:
-
-- `reference`: the name of the table in the database that this rule points to. For example, `product_type`.
-- `reference_id`: the ID of the data model’s record that this points to. For example, a product type’s ID.
-
-So, to override the default tax rate for product types “Shirt”, you create a tax rate and associate with it a tax rule whose `reference` is `product_type` and `reference_id` the ID of the “Shirt” product type.
-
-
-# Tax Region
-
-In this document, you’ll learn about tax regions and how to use them with the Region Module.
-
-Refer to this [Medusa Admin User Guide](https://docs.medusajs.com/user-guide/settings/tax-regions/index.html.md) to learn how to manage tax regions using the dashboard.
-
-## What is a Tax Region?
-
-A tax region, represented by the [TaxRegion data model](https://docs.medusajs.com/references/tax/models/TaxRegion/index.html.md), stores tax settings related to a region that your store serves.
-
-Tax regions can inherit settings and rules from a parent tax region.
-
-Each tax region has tax rules and a tax provider.
-
-
-# Stock Location Concepts
-
-In this document, you’ll learn about the main concepts in the Stock Location Module.
-
-## Stock Location
-
-A stock location, represented by the `StockLocation` data model, represents a location where stock items are kept. For example, a warehouse.
-
-Medusa uses stock locations to provide inventory details, from the Inventory Module, per location.
-
-***
-
-## StockLocationAddress
-
-The `StockLocationAddress` data model belongs to the `StockLocation` data model. It provides more detailed information of the location, such as country code or street address.
-
-
-# Links between Stock Location Module and Other Modules
-
-This document showcases the module links defined between the Stock Location Module and other Commerce Modules.
-
-## Summary
-
-The Stock Location Module has the following links to other modules:
-
-Read-only links are used to query data across modules, but the relations aren't stored in a pivot table in the database.
-
-|First Data Model|Second Data Model|Type|Description|
-|---|---|---|---|
-|FulfillmentSet|StockLocation|Stored - many-to-one|Learn more|
-|FulfillmentProvider|StockLocation|Stored - many-to-many|Learn more|
-|InventoryLevel|StockLocation|Read-only - has many|Learn more|
-|SalesChannel|StockLocation|Stored - many-to-many|Learn more|
-
-***
-
-## Fulfillment Module
-
-A fulfillment set can be conditioned to a specific stock location.
-
-Medusa defines a link between the `FulfillmentSet` and `StockLocation` data models.
-
-
-
-Medusa also defines a link between the `FulfillmentProvider` and `StockLocation` data models to indicate the providers that can be used in a location.
-
-
-
-### Retrieve with Query
-
-To retrieve the fulfillment sets of a stock location with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `fulfillment_sets.*` in `fields`:
-
-To retrieve the fulfillment providers, pass `fulfillment_providers.*` in `fields`.
-
-### query.graph
-
-```ts
-const { data: stockLocations } = await query.graph({
- entity: "stock_location",
- fields: [
- "fulfillment_sets.*",
- ],
-})
-
-// stockLocations[0].fulfillment_sets
-```
-
-### useQueryGraphStep
-
-```ts
-import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
-
-// ...
-
-const { data: stockLocations } = useQueryGraphStep({
- entity: "stock_location",
- fields: [
- "fulfillment_sets.*",
- ],
-})
-
-// stockLocations[0].fulfillment_sets
-```
-
-### Manage with Link
-
-To manage the stock location of a fulfillment set, use [Link](https://docs.medusajs.com/docs/learn/fundamentals/module-links/link/index.html.md):
-
-### link.create
-
-```ts
-import { Modules } from "@medusajs/framework/utils"
-
-// ...
-
-await link.create({
- [Modules.STOCK_LOCATION]: {
- stock_location_id: "sloc_123",
- },
- [Modules.FULFILLMENT]: {
- fulfillment_set_id: "fset_123",
- },
-})
-```
-
-### createRemoteLinkStep
-
-```ts
-import { Modules } from "@medusajs/framework/utils"
-import { createRemoteLinkStep } from "@medusajs/medusa/core-flows"
-
-// ...
-
-createRemoteLinkStep({
- [Modules.STOCK_LOCATION]: {
- stock_location_id: "sloc_123",
- },
- [Modules.FULFILLMENT]: {
- fulfillment_set_id: "fset_123",
- },
-})
-```
-
-***
-
-## Inventory Module
-
-Medusa defines a read-only link between the [Inventory Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/inventory/index.html.md)'s `InventoryLevel` data model and the `StockLocation` data model. Because the link is read-only from the `InventoryLevel`'s side, you can only retrieve the stock location of an inventory level, and not the other way around.
-
-### Retrieve with Query
-
-To retrieve the stock locations of an inventory level with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `stock_locations.*` in `fields`:
-
-### query.graph
-
-```ts
-const { data: inventoryLevels } = await query.graph({
- entity: "inventory_level",
- fields: [
- "stock_locations.*",
- ],
-})
-
-// inventoryLevels[0].stock_locations
-```
-
-### useQueryGraphStep
-
-```ts
-import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
-
-// ...
-
-const { data: inventoryLevels } = useQueryGraphStep({
- entity: "inventory_level",
- fields: [
- "stock_locations.*",
- ],
-})
-
-// inventoryLevels[0].stock_locations
-```
-
-***
-
-## Sales Channel Module
-
-A stock location is associated with a sales channel. This scopes inventory quantities in a stock location by the associated sales channel.
-
-Medusa defines a link between the `SalesChannel` and `StockLocation` data models.
-
-
-
-### Retrieve with Query
-
-To retrieve the sales channels of a stock location with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `sales_channels.*` in `fields`:
-
-### query.graph
-
-```ts
-const { data: stockLocations } = await query.graph({
- entity: "stock_location",
- fields: [
- "sales_channels.*",
- ],
-})
-
-// stockLocations[0].sales_channels
-```
-
-### useQueryGraphStep
-
-```ts
-import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
-
-// ...
-
-const { data: stockLocations } = useQueryGraphStep({
- entity: "stock_location",
- fields: [
- "sales_channels.*",
- ],
-})
-
-// stockLocations[0].sales_channels
-```
-
-### Manage with Link
-
-To manage the stock locations of a sales channel, use [Link](https://docs.medusajs.com/docs/learn/fundamentals/module-links/link/index.html.md):
-
-### link.create
-
-```ts
-import { Modules } from "@medusajs/framework/utils"
-
-// ...
-
-await link.create({
- [Modules.SALES_CHANNEL]: {
- sales_channel_id: "sc_123",
- },
- [Modules.STOCK_LOCATION]: {
- sales_channel_id: "sloc_123",
- },
-})
-```
-
-### createRemoteLinkStep
-
-```ts
-import { Modules } from "@medusajs/framework/utils"
-import { createRemoteLinkStep } from "@medusajs/medusa/core-flows"
-
-// ...
-
-createRemoteLinkStep({
- [Modules.SALES_CHANNEL]: {
- sales_channel_id: "sc_123",
- },
- [Modules.STOCK_LOCATION]: {
- sales_channel_id: "sloc_123",
- },
-})
-```
-
-
# Publishable API Keys with Sales Channels
In this document, you’ll learn what publishable API keys are and how to use them with sales channels.
@@ -29520,6 +29195,253 @@ createRemoteLinkStep({
```
+# Stock Location Concepts
+
+In this document, you’ll learn about the main concepts in the Stock Location Module.
+
+## Stock Location
+
+A stock location, represented by the `StockLocation` data model, represents a location where stock items are kept. For example, a warehouse.
+
+Medusa uses stock locations to provide inventory details, from the Inventory Module, per location.
+
+***
+
+## StockLocationAddress
+
+The `StockLocationAddress` data model belongs to the `StockLocation` data model. It provides more detailed information of the location, such as country code or street address.
+
+
+# Links between Stock Location Module and Other Modules
+
+This document showcases the module links defined between the Stock Location Module and other Commerce Modules.
+
+## Summary
+
+The Stock Location Module has the following links to other modules:
+
+Read-only links are used to query data across modules, but the relations aren't stored in a pivot table in the database.
+
+|First Data Model|Second Data Model|Type|Description|
+|---|---|---|---|
+|FulfillmentSet|StockLocation|Stored - many-to-one|Learn more|
+|FulfillmentProvider|StockLocation|Stored - many-to-many|Learn more|
+|InventoryLevel|StockLocation|Read-only - has many|Learn more|
+|SalesChannel|StockLocation|Stored - many-to-many|Learn more|
+
+***
+
+## Fulfillment Module
+
+A fulfillment set can be conditioned to a specific stock location.
+
+Medusa defines a link between the `FulfillmentSet` and `StockLocation` data models.
+
+
+
+Medusa also defines a link between the `FulfillmentProvider` and `StockLocation` data models to indicate the providers that can be used in a location.
+
+
+
+### Retrieve with Query
+
+To retrieve the fulfillment sets of a stock location with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `fulfillment_sets.*` in `fields`:
+
+To retrieve the fulfillment providers, pass `fulfillment_providers.*` in `fields`.
+
+### query.graph
+
+```ts
+const { data: stockLocations } = await query.graph({
+ entity: "stock_location",
+ fields: [
+ "fulfillment_sets.*",
+ ],
+})
+
+// stockLocations[0].fulfillment_sets
+```
+
+### useQueryGraphStep
+
+```ts
+import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
+
+// ...
+
+const { data: stockLocations } = useQueryGraphStep({
+ entity: "stock_location",
+ fields: [
+ "fulfillment_sets.*",
+ ],
+})
+
+// stockLocations[0].fulfillment_sets
+```
+
+### Manage with Link
+
+To manage the stock location of a fulfillment set, use [Link](https://docs.medusajs.com/docs/learn/fundamentals/module-links/link/index.html.md):
+
+### link.create
+
+```ts
+import { Modules } from "@medusajs/framework/utils"
+
+// ...
+
+await link.create({
+ [Modules.STOCK_LOCATION]: {
+ stock_location_id: "sloc_123",
+ },
+ [Modules.FULFILLMENT]: {
+ fulfillment_set_id: "fset_123",
+ },
+})
+```
+
+### createRemoteLinkStep
+
+```ts
+import { Modules } from "@medusajs/framework/utils"
+import { createRemoteLinkStep } from "@medusajs/medusa/core-flows"
+
+// ...
+
+createRemoteLinkStep({
+ [Modules.STOCK_LOCATION]: {
+ stock_location_id: "sloc_123",
+ },
+ [Modules.FULFILLMENT]: {
+ fulfillment_set_id: "fset_123",
+ },
+})
+```
+
+***
+
+## Inventory Module
+
+Medusa defines a read-only link between the [Inventory Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/inventory/index.html.md)'s `InventoryLevel` data model and the `StockLocation` data model. Because the link is read-only from the `InventoryLevel`'s side, you can only retrieve the stock location of an inventory level, and not the other way around.
+
+### Retrieve with Query
+
+To retrieve the stock locations of an inventory level with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `stock_locations.*` in `fields`:
+
+### query.graph
+
+```ts
+const { data: inventoryLevels } = await query.graph({
+ entity: "inventory_level",
+ fields: [
+ "stock_locations.*",
+ ],
+})
+
+// inventoryLevels[0].stock_locations
+```
+
+### useQueryGraphStep
+
+```ts
+import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
+
+// ...
+
+const { data: inventoryLevels } = useQueryGraphStep({
+ entity: "inventory_level",
+ fields: [
+ "stock_locations.*",
+ ],
+})
+
+// inventoryLevels[0].stock_locations
+```
+
+***
+
+## Sales Channel Module
+
+A stock location is associated with a sales channel. This scopes inventory quantities in a stock location by the associated sales channel.
+
+Medusa defines a link between the `SalesChannel` and `StockLocation` data models.
+
+
+
+### Retrieve with Query
+
+To retrieve the sales channels of a stock location with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `sales_channels.*` in `fields`:
+
+### query.graph
+
+```ts
+const { data: stockLocations } = await query.graph({
+ entity: "stock_location",
+ fields: [
+ "sales_channels.*",
+ ],
+})
+
+// stockLocations[0].sales_channels
+```
+
+### useQueryGraphStep
+
+```ts
+import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
+
+// ...
+
+const { data: stockLocations } = useQueryGraphStep({
+ entity: "stock_location",
+ fields: [
+ "sales_channels.*",
+ ],
+})
+
+// stockLocations[0].sales_channels
+```
+
+### Manage with Link
+
+To manage the stock locations of a sales channel, use [Link](https://docs.medusajs.com/docs/learn/fundamentals/module-links/link/index.html.md):
+
+### link.create
+
+```ts
+import { Modules } from "@medusajs/framework/utils"
+
+// ...
+
+await link.create({
+ [Modules.SALES_CHANNEL]: {
+ sales_channel_id: "sc_123",
+ },
+ [Modules.STOCK_LOCATION]: {
+ sales_channel_id: "sloc_123",
+ },
+})
+```
+
+### createRemoteLinkStep
+
+```ts
+import { Modules } from "@medusajs/framework/utils"
+import { createRemoteLinkStep } from "@medusajs/medusa/core-flows"
+
+// ...
+
+createRemoteLinkStep({
+ [Modules.SALES_CHANNEL]: {
+ sales_channel_id: "sc_123",
+ },
+ [Modules.STOCK_LOCATION]: {
+ sales_channel_id: "sloc_123",
+ },
+})
+```
+
+
# User Creation Flows
In this document, learn the different ways to create a user using the User Module.
@@ -29637,6 +29559,298 @@ JWT_SECRET=supersecret
```
+# Tax Module Options
+
+In this document, you'll learn about the options of the Tax Module.
+
+## providers
+
+The `providers` option is an array of either tax module providers or path to a file that defines a tax provider.
+
+When the Medusa application starts, these providers are registered and can be used to retrieve tax lines.
+
+```ts title="medusa-config.ts"
+import { Modules } from "@medusajs/framework/utils"
+
+// ...
+
+module.exports = defineConfig({
+ // ...
+ modules: [
+ {
+ resolve: "@medusajs/tax",
+ options: {
+ providers: [
+ {
+ resolve: "./path/to/my-provider",
+ id: "my-provider",
+ options: {
+ // ...
+ },
+ },
+ ],
+ },
+ },
+ ],
+})
+```
+
+The objects in the array accept the following properties:
+
+- `resolve`: A string indicating the package name of the module provider or the path to it.
+- `id`: A string indicating the provider's unique name or ID.
+- `options`: An optional object of the module provider's options.
+
+
+# Tax Calculation with the Tax Provider
+
+In this document, you’ll learn how tax lines are calculated and what a tax provider is.
+
+## Tax Lines Calculation
+
+Tax lines are calculated and retrieved using the [getTaxLines method of the Tax Module’s main service](https://docs.medusajs.com/references/tax/getTaxLines/index.html.md). It accepts an array of line items and shipping methods, and the context of the calculation.
+
+For example:
+
+```ts
+const taxLines = await taxModuleService.getTaxLines(
+ [
+ {
+ id: "cali_123",
+ product_id: "prod_123",
+ unit_price: 1000,
+ quantity: 1,
+ },
+ {
+ id: "casm_123",
+ shipping_option_id: "so_123",
+ unit_price: 2000,
+ },
+ ],
+ {
+ address: {
+ country_code: "us",
+ },
+ }
+)
+```
+
+The context object is used to determine which tax regions and rates to use in the calculation. It includes properties related to the address and customer.
+
+The example above retrieves the tax lines based on the tax region for the United States.
+
+The method returns tax lines for the line item and shipping methods. For example:
+
+```json
+[
+ {
+ "line_item_id": "cali_123",
+ "rate_id": "txr_1",
+ "rate": 10,
+ "code": "XXX",
+ "name": "Tax Rate 1"
+ },
+ {
+ "shipping_line_id": "casm_123",
+ "rate_id": "txr_2",
+ "rate": 5,
+ "code": "YYY",
+ "name": "Tax Rate 2"
+ }
+]
+```
+
+***
+
+## Using the Tax Provider in the Calculation
+
+The tax lines retrieved by the `getTaxLines` method are actually retrieved from the tax region’s provider.
+
+A tax module provider whose main service implements the logic to shape tax lines. Each tax region has a tax provider.
+
+The Tax Module provides a `system` tax provider that only transforms calculated item and shipping tax rates into the required return type.
+
+{/* ---
+
+TODO add once tax provider guide is updated + add module providers match other modules.
+
+## Create Tax Provider
+
+Refer to [this guide](/modules/tax/provider) to learn more about creating a tax provider. */}
+
+
+# Tax Rates and Rules
+
+In this document, you’ll learn about tax rates and rules.
+
+Refer to this [Medusa Admin User Guide](https://docs.medusajs.com/user-guide/settings/tax-regions#manage-tax-rate-overrides/index.html.md) to learn how to manage tax rates using the dashboard.
+
+## What are Tax Rates?
+
+A tax rate is a percentage amount used to calculate the tax amount for each taxable item’s price, such as line items or shipping methods, in a cart. The sum of all calculated tax amounts are then added to the cart’s total as a tax total.
+
+Each tax region has a default tax rate. This tax rate is applied to all taxable items of a cart in that region.
+
+### Combinable Tax Rates
+
+Tax regions can have parent tax regions. To inherit the tax rates of the parent tax region, set the `is_combinable` of the child’s tax rates to `true`.
+
+Then, when tax rates are retrieved for a taxable item in the child region, both the child and the parent tax regions’ applicable rates are returned.
+
+***
+
+## Override Tax Rates with Rules
+
+You can create tax rates that override the default for specific conditions or rules.
+
+For example, you can have a default tax rate is 10%, but for products of type “Shirt” is %15.
+
+A tax region can have multiple tax rates, and each tax rate can have multiple tax rules. The [TaxRateRule data model](https://docs.medusajs.com/references/tax/models/TaxRateRule/index.html.md) represents a tax rate’s rule.
+
+
+
+These two properties of the data model identify the rule’s target:
+
+- `reference`: the name of the table in the database that this rule points to. For example, `product_type`.
+- `reference_id`: the ID of the data model’s record that this points to. For example, a product type’s ID.
+
+So, to override the default tax rate for product types “Shirt”, you create a tax rate and associate with it a tax rule whose `reference` is `product_type` and `reference_id` the ID of the “Shirt” product type.
+
+
+# Tax Region
+
+In this document, you’ll learn about tax regions and how to use them with the Region Module.
+
+Refer to this [Medusa Admin User Guide](https://docs.medusajs.com/user-guide/settings/tax-regions/index.html.md) to learn how to manage tax regions using the dashboard.
+
+## What is a Tax Region?
+
+A tax region, represented by the [TaxRegion data model](https://docs.medusajs.com/references/tax/models/TaxRegion/index.html.md), stores tax settings related to a region that your store serves.
+
+Tax regions can inherit settings and rules from a parent tax region.
+
+Each tax region has tax rules and a tax provider.
+
+
+# Links between Store Module and Other Modules
+
+This document showcases the module links defined between the Store Module and other Commerce Modules.
+
+## Summary
+
+The Store Module has the following links to other modules:
+
+Read-only links are used to query data across modules, but the relations aren't stored in a pivot table in the database.
+
+|First Data Model|Second Data Model|Type|Description|
+|---|---|---|---|
+|StoreCurrency|Currency|Read-only - has many|Learn more|
+
+***
+
+## Currency Module
+
+The Store Module has a `Currency` data model that stores the supported currencies of a store. However, these currencies don't hold all the details of a currency, such as its name or symbol.
+
+Instead, Medusa defines a read-only link between the [Currency Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/currency/index.html.md)'s `Currency` data model and the Store Module's `StoreCurrency` data model. This means you can retrieve the details of a store's supported currencies, but you don't manage the links in a pivot table in the database. The currencies of a store are determined by the `currency_code` of the [Currency](https://docs.medusajs.com/references/store/models/Currency/index.html.md) data model in the Store Module (not in the Currency Module).
+
+### Retrieve with Query
+
+To retrieve the details of a store's currencies with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `supported_currencies.currency.*` in `fields`:
+
+### query.graph
+
+```ts
+const { data: stores } = await query.graph({
+ entity: "store",
+ fields: [
+ "supported_currencies.currency.*",
+ ],
+})
+
+// stores[0].supported_currencies
+```
+
+### useQueryGraphStep
+
+```ts
+import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
+
+// ...
+
+const { data: stores } = useQueryGraphStep({
+ entity: "store",
+ fields: [
+ "supported_currencies.currency.*",
+ ],
+})
+
+// stores[0].supported_currencies
+```
+
+
+# Emailpass Auth Module Provider
+
+In this document, you’ll learn about the Emailpass auth module provider and how to install and use it in the Auth Module.
+
+Using the Emailpass auth module provider, you allow users to register and login with an email and password.
+
+***
+
+## Register the Emailpass Auth Module Provider
+
+The Emailpass auth provider is registered by default with the Auth Module.
+
+If you want to pass options to the provider, add the provider to the `providers` option of the Auth Module:
+
+```ts title="medusa-config.ts"
+import { Modules, ContainerRegistrationKeys } from "@medusajs/framework/utils"
+
+// ...
+
+module.exports = defineConfig({
+ // ...
+ modules: [
+ {
+ resolve: "@medusajs/medusa/auth",
+ dependencies: [Modules.CACHE, ContainerRegistrationKeys.LOGGER],
+ options: {
+ providers: [
+ // other providers...
+ {
+ resolve: "@medusajs/medusa/auth-emailpass",
+ id: "emailpass",
+ options: {
+ // options...
+ },
+ },
+ ],
+ },
+ },
+ ],
+})
+```
+
+### Module Options
+
+|Configuration|Description|Required|Default|
+|---|---|---|---|---|---|---|
+|\`hashConfig\`|An object of configurations to use when hashing the user's
+password. Refer to |No|\`\`\`ts
+const hashConfig = \{
+ logN: 15,
+ r: 8,
+ p: 1
+}
+\`\`\`|
+
+***
+
+## Related Guides
+
+- [How to register a customer using email and password](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/storefront-development/customers/register/index.html.md)
+
+
# GitHub Auth Module Provider
In this document, you’ll learn about the GitHub Auth Module Provider and how to install and use it in the Auth Module.
@@ -29806,68 +30020,6 @@ The [Authenticate or Login API Route](https://docs.medusajs.com/Users/shahednass
- [How to implement Google social login in the storefront](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/storefront-development/customers/third-party-login/index.html.md).
-# Emailpass Auth Module Provider
-
-In this document, you’ll learn about the Emailpass auth module provider and how to install and use it in the Auth Module.
-
-Using the Emailpass auth module provider, you allow users to register and login with an email and password.
-
-***
-
-## Register the Emailpass Auth Module Provider
-
-The Emailpass auth provider is registered by default with the Auth Module.
-
-If you want to pass options to the provider, add the provider to the `providers` option of the Auth Module:
-
-```ts title="medusa-config.ts"
-import { Modules, ContainerRegistrationKeys } from "@medusajs/framework/utils"
-
-// ...
-
-module.exports = defineConfig({
- // ...
- modules: [
- {
- resolve: "@medusajs/medusa/auth",
- dependencies: [Modules.CACHE, ContainerRegistrationKeys.LOGGER],
- options: {
- providers: [
- // other providers...
- {
- resolve: "@medusajs/medusa/auth-emailpass",
- id: "emailpass",
- options: {
- // options...
- },
- },
- ],
- },
- },
- ],
-})
-```
-
-### Module Options
-
-|Configuration|Description|Required|Default|
-|---|---|---|---|---|---|---|
-|\`hashConfig\`|An object of configurations to use when hashing the user's
-password. Refer to |No|\`\`\`ts
-const hashConfig = \{
- logN: 15,
- r: 8,
- p: 1
-}
-\`\`\`|
-
-***
-
-## Related Guides
-
-- [How to register a customer using email and password](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/storefront-development/customers/register/index.html.md)
-
-
# Stripe Module Provider
In this document, you’ll learn about the Stripe Module Provider and how to configure it in the Payment Module.
@@ -30001,6 +30153,86 @@ When you set up the webhook in Stripe, choose the following events to listen to:
- [Customize Stripe Integration in Next.js Starter](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/nextjs-starter/guides/customize-stripe/index.html.md).
+# Get Product Variant Prices using Query
+
+In this document, you'll learn how to retrieve product variant prices in the Medusa application using [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md).
+
+The Product Module doesn't provide pricing functionalities. The Medusa application links the Product Module's `ProductVariant` data model to the Pricing Module's `PriceSet` data model.
+
+So, to retrieve data across the linked records of the two modules, you use Query.
+
+## Retrieve All Product Variant Prices
+
+To retrieve all product variant prices, retrieve the product using Query and include among its fields `variants.prices.*`.
+
+For example:
+
+```ts highlights={[["6"]]}
+const { data: products } = await query.graph({
+ entity: "product",
+ fields: [
+ "*",
+ "variants.*",
+ "variants.prices.*",
+ ],
+ filters: {
+ id: [
+ "prod_123",
+ ],
+ },
+})
+```
+
+Each variant in the retrieved products has a `prices` array property with all the product variant prices. Each price object has the properties of the [Pricing Module's Price data model](https://docs.medusajs.com/references/pricing/models/Price/index.html.md).
+
+***
+
+## Retrieve Calculated Price for a Context
+
+The Pricing Module can calculate prices of a variant based on a [context](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/pricing/price-calculation#calculation-context/index.html.md), such as the region ID or the currency code.
+
+Learn more about prices calculation in [this Pricing Module documentation](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/pricing/price-calculation/index.html.md).
+
+To retrieve calculated prices of variants based on a context, retrieve the products using Query and:
+
+- Pass `variants.calculated_price.*` in the `fields` property.
+- Pass a `context` property in the object parameter. Its value is an object of objects that sets the context for the retrieved fields.
+
+For example:
+
+```ts highlights={[["10"], ["15"], ["16"], ["17"], ["18"], ["19"], ["20"], ["21"], ["22"]]}
+import { QueryContext } from "@medusajs/framework/utils"
+
+// ...
+
+const { data: products } = await query.graph({
+ entity: "product",
+ fields: [
+ "*",
+ "variants.*",
+ "variants.calculated_price.*",
+ ],
+ filters: {
+ id: "prod_123",
+ },
+ context: {
+ variants: {
+ calculated_price: QueryContext({
+ region_id: "reg_01J3MRPDNXXXDSCC76Y6YCZARS",
+ currency_code: "eur",
+ }),
+ },
+ },
+})
+```
+
+For the context of the product variant's calculated price, you pass an object to `context` with the property `variants`, whose value is another object with the property `calculated_price`.
+
+`calculated_price`'s value is created using `QueryContext` from the Modules SDK, passing it a [calculation context object](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/pricing/price-calculation#calculation-context/index.html.md).
+
+Each variant in the retrieved products has a `calculated_price` object. Learn more about its properties in [this Pricing Module guide](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/pricing/price-calculation#returned-price-object/index.html.md).
+
+
# Get Product Variant Inventory Quantity
In this guide, you'll learn how to retrieve the available inventory quantity of a product variant in your Medusa application customizations. That includes API routes, workflows, subscribers, scheduled jobs, and any resource that can access the [Medusa container](https://docs.medusajs.com/docs/learn/fundamentals/medusa-container/index.html.md).
@@ -30339,176 +30571,92 @@ For each product variant, you:
- `priceWithoutTax`: The variant's price without taxes applied.
-# Get Product Variant Prices using Query
-
-In this document, you'll learn how to retrieve product variant prices in the Medusa application using [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md).
-
-The Product Module doesn't provide pricing functionalities. The Medusa application links the Product Module's `ProductVariant` data model to the Pricing Module's `PriceSet` data model.
-
-So, to retrieve data across the linked records of the two modules, you use Query.
-
-## Retrieve All Product Variant Prices
-
-To retrieve all product variant prices, retrieve the product using Query and include among its fields `variants.prices.*`.
-
-For example:
-
-```ts highlights={[["6"]]}
-const { data: products } = await query.graph({
- entity: "product",
- fields: [
- "*",
- "variants.*",
- "variants.prices.*",
- ],
- filters: {
- id: [
- "prod_123",
- ],
- },
-})
-```
-
-Each variant in the retrieved products has a `prices` array property with all the product variant prices. Each price object has the properties of the [Pricing Module's Price data model](https://docs.medusajs.com/references/pricing/models/Price/index.html.md).
-
-***
-
-## Retrieve Calculated Price for a Context
-
-The Pricing Module can calculate prices of a variant based on a [context](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/pricing/price-calculation#calculation-context/index.html.md), such as the region ID or the currency code.
-
-Learn more about prices calculation in [this Pricing Module documentation](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/pricing/price-calculation/index.html.md).
-
-To retrieve calculated prices of variants based on a context, retrieve the products using Query and:
-
-- Pass `variants.calculated_price.*` in the `fields` property.
-- Pass a `context` property in the object parameter. Its value is an object of objects that sets the context for the retrieved fields.
-
-For example:
-
-```ts highlights={[["10"], ["15"], ["16"], ["17"], ["18"], ["19"], ["20"], ["21"], ["22"]]}
-import { QueryContext } from "@medusajs/framework/utils"
-
-// ...
-
-const { data: products } = await query.graph({
- entity: "product",
- fields: [
- "*",
- "variants.*",
- "variants.calculated_price.*",
- ],
- filters: {
- id: "prod_123",
- },
- context: {
- variants: {
- calculated_price: QueryContext({
- region_id: "reg_01J3MRPDNXXXDSCC76Y6YCZARS",
- currency_code: "eur",
- }),
- },
- },
-})
-```
-
-For the context of the product variant's calculated price, you pass an object to `context` with the property `variants`, whose value is another object with the property `calculated_price`.
-
-`calculated_price`'s value is created using `QueryContext` from the Modules SDK, passing it a [calculation context object](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/pricing/price-calculation#calculation-context/index.html.md).
-
-Each variant in the retrieved products has a `calculated_price` object. Learn more about its properties in [this Pricing Module guide](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/pricing/price-calculation#returned-price-object/index.html.md).
-
-
## Workflows
- [generateResetPasswordTokenWorkflow](https://docs.medusajs.com/references/medusa-workflows/generateResetPasswordTokenWorkflow/index.html.md)
-- [batchLinksWorkflow](https://docs.medusajs.com/references/medusa-workflows/batchLinksWorkflow/index.html.md)
-- [createLinksWorkflow](https://docs.medusajs.com/references/medusa-workflows/createLinksWorkflow/index.html.md)
-- [updateLinksWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateLinksWorkflow/index.html.md)
-- [dismissLinksWorkflow](https://docs.medusajs.com/references/medusa-workflows/dismissLinksWorkflow/index.html.md)
-- [addToCartWorkflow](https://docs.medusajs.com/references/medusa-workflows/addToCartWorkflow/index.html.md)
-- [addShippingMethodToCartWorkflow](https://docs.medusajs.com/references/medusa-workflows/addShippingMethodToCartWorkflow/index.html.md)
-- [createCartCreditLinesWorkflow](https://docs.medusajs.com/references/medusa-workflows/createCartCreditLinesWorkflow/index.html.md)
-- [completeCartWorkflow](https://docs.medusajs.com/references/medusa-workflows/completeCartWorkflow/index.html.md)
-- [createCartWorkflow](https://docs.medusajs.com/references/medusa-workflows/createCartWorkflow/index.html.md)
-- [createPaymentCollectionForCartWorkflow](https://docs.medusajs.com/references/medusa-workflows/createPaymentCollectionForCartWorkflow/index.html.md)
-- [confirmVariantInventoryWorkflow](https://docs.medusajs.com/references/medusa-workflows/confirmVariantInventoryWorkflow/index.html.md)
-- [deleteCartCreditLinesWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteCartCreditLinesWorkflow/index.html.md)
-- [listShippingOptionsForCartWorkflow](https://docs.medusajs.com/references/medusa-workflows/listShippingOptionsForCartWorkflow/index.html.md)
-- [refreshCartItemsWorkflow](https://docs.medusajs.com/references/medusa-workflows/refreshCartItemsWorkflow/index.html.md)
-- [listShippingOptionsForCartWithPricingWorkflow](https://docs.medusajs.com/references/medusa-workflows/listShippingOptionsForCartWithPricingWorkflow/index.html.md)
-- [refreshPaymentCollectionForCartWorkflow](https://docs.medusajs.com/references/medusa-workflows/refreshPaymentCollectionForCartWorkflow/index.html.md)
-- [refreshCartShippingMethodsWorkflow](https://docs.medusajs.com/references/medusa-workflows/refreshCartShippingMethodsWorkflow/index.html.md)
-- [transferCartCustomerWorkflow](https://docs.medusajs.com/references/medusa-workflows/transferCartCustomerWorkflow/index.html.md)
-- [updateCartPromotionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateCartPromotionsWorkflow/index.html.md)
-- [updateCartWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateCartWorkflow/index.html.md)
-- [updateLineItemInCartWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateLineItemInCartWorkflow/index.html.md)
-- [validateExistingPaymentCollectionStep](https://docs.medusajs.com/references/medusa-workflows/validateExistingPaymentCollectionStep/index.html.md)
-- [updateTaxLinesWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateTaxLinesWorkflow/index.html.md)
- [createApiKeysWorkflow](https://docs.medusajs.com/references/medusa-workflows/createApiKeysWorkflow/index.html.md)
-- [deleteApiKeysWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteApiKeysWorkflow/index.html.md)
- [revokeApiKeysWorkflow](https://docs.medusajs.com/references/medusa-workflows/revokeApiKeysWorkflow/index.html.md)
+- [deleteApiKeysWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteApiKeysWorkflow/index.html.md)
- [updateApiKeysWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateApiKeysWorkflow/index.html.md)
- [linkSalesChannelsToApiKeyWorkflow](https://docs.medusajs.com/references/medusa-workflows/linkSalesChannelsToApiKeyWorkflow/index.html.md)
-- [createDefaultsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createDefaultsWorkflow/index.html.md)
-- [addDraftOrderPromotionWorkflow](https://docs.medusajs.com/references/medusa-workflows/addDraftOrderPromotionWorkflow/index.html.md)
-- [addDraftOrderShippingMethodsWorkflow](https://docs.medusajs.com/references/medusa-workflows/addDraftOrderShippingMethodsWorkflow/index.html.md)
-- [cancelDraftOrderEditWorkflow](https://docs.medusajs.com/references/medusa-workflows/cancelDraftOrderEditWorkflow/index.html.md)
-- [beginDraftOrderEditWorkflow](https://docs.medusajs.com/references/medusa-workflows/beginDraftOrderEditWorkflow/index.html.md)
-- [confirmDraftOrderEditWorkflow](https://docs.medusajs.com/references/medusa-workflows/confirmDraftOrderEditWorkflow/index.html.md)
-- [convertDraftOrderStep](https://docs.medusajs.com/references/medusa-workflows/convertDraftOrderStep/index.html.md)
-- [convertDraftOrderWorkflow](https://docs.medusajs.com/references/medusa-workflows/convertDraftOrderWorkflow/index.html.md)
-- [addDraftOrderItemsWorkflow](https://docs.medusajs.com/references/medusa-workflows/addDraftOrderItemsWorkflow/index.html.md)
-- [removeDraftOrderActionShippingMethodWorkflow](https://docs.medusajs.com/references/medusa-workflows/removeDraftOrderActionShippingMethodWorkflow/index.html.md)
-- [removeDraftOrderShippingMethodWorkflow](https://docs.medusajs.com/references/medusa-workflows/removeDraftOrderShippingMethodWorkflow/index.html.md)
-- [removeDraftOrderPromotionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/removeDraftOrderPromotionsWorkflow/index.html.md)
-- [requestDraftOrderEditWorkflow](https://docs.medusajs.com/references/medusa-workflows/requestDraftOrderEditWorkflow/index.html.md)
-- [updateDraftOrderActionShippingMethodWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateDraftOrderActionShippingMethodWorkflow/index.html.md)
-- [updateDraftOrderItemWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateDraftOrderItemWorkflow/index.html.md)
-- [updateDraftOrderShippingMethodWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateDraftOrderShippingMethodWorkflow/index.html.md)
-- [updateDraftOrderActionItemWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateDraftOrderActionItemWorkflow/index.html.md)
-- [updateDraftOrderStep](https://docs.medusajs.com/references/medusa-workflows/updateDraftOrderStep/index.html.md)
-- [removeDraftOrderActionItemWorkflow](https://docs.medusajs.com/references/medusa-workflows/removeDraftOrderActionItemWorkflow/index.html.md)
-- [updateDraftOrderWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateDraftOrderWorkflow/index.html.md)
-- [deleteCustomerGroupsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteCustomerGroupsWorkflow/index.html.md)
-- [createCustomerGroupsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createCustomerGroupsWorkflow/index.html.md)
-- [linkCustomerGroupsToCustomerWorkflow](https://docs.medusajs.com/references/medusa-workflows/linkCustomerGroupsToCustomerWorkflow/index.html.md)
-- [linkCustomersToCustomerGroupWorkflow](https://docs.medusajs.com/references/medusa-workflows/linkCustomersToCustomerGroupWorkflow/index.html.md)
-- [deleteFilesWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteFilesWorkflow/index.html.md)
-- [updateCustomerGroupsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateCustomerGroupsWorkflow/index.html.md)
-- [uploadFilesWorkflow](https://docs.medusajs.com/references/medusa-workflows/uploadFilesWorkflow/index.html.md)
- [createCustomerAccountWorkflow](https://docs.medusajs.com/references/medusa-workflows/createCustomerAccountWorkflow/index.html.md)
- [createCustomerAddressesWorkflow](https://docs.medusajs.com/references/medusa-workflows/createCustomerAddressesWorkflow/index.html.md)
-- [deleteCustomerAddressesWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteCustomerAddressesWorkflow/index.html.md)
- [createCustomersWorkflow](https://docs.medusajs.com/references/medusa-workflows/createCustomersWorkflow/index.html.md)
-- [removeCustomerAccountWorkflow](https://docs.medusajs.com/references/medusa-workflows/removeCustomerAccountWorkflow/index.html.md)
-- [updateCustomerAddressesWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateCustomerAddressesWorkflow/index.html.md)
+- [deleteCustomerAddressesWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteCustomerAddressesWorkflow/index.html.md)
- [deleteCustomersWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteCustomersWorkflow/index.html.md)
+- [updateCustomerAddressesWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateCustomerAddressesWorkflow/index.html.md)
+- [removeCustomerAccountWorkflow](https://docs.medusajs.com/references/medusa-workflows/removeCustomerAccountWorkflow/index.html.md)
- [updateCustomersWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateCustomersWorkflow/index.html.md)
-- [batchShippingOptionRulesWorkflow](https://docs.medusajs.com/references/medusa-workflows/batchShippingOptionRulesWorkflow/index.html.md)
+- [createCustomerGroupsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createCustomerGroupsWorkflow/index.html.md)
+- [deleteCustomerGroupsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteCustomerGroupsWorkflow/index.html.md)
+- [linkCustomersToCustomerGroupWorkflow](https://docs.medusajs.com/references/medusa-workflows/linkCustomersToCustomerGroupWorkflow/index.html.md)
+- [updateCustomerGroupsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateCustomerGroupsWorkflow/index.html.md)
+- [linkCustomerGroupsToCustomerWorkflow](https://docs.medusajs.com/references/medusa-workflows/linkCustomerGroupsToCustomerWorkflow/index.html.md)
+- [createDefaultsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createDefaultsWorkflow/index.html.md)
+- [addDraftOrderPromotionWorkflow](https://docs.medusajs.com/references/medusa-workflows/addDraftOrderPromotionWorkflow/index.html.md)
+- [beginDraftOrderEditWorkflow](https://docs.medusajs.com/references/medusa-workflows/beginDraftOrderEditWorkflow/index.html.md)
+- [addDraftOrderShippingMethodsWorkflow](https://docs.medusajs.com/references/medusa-workflows/addDraftOrderShippingMethodsWorkflow/index.html.md)
+- [cancelDraftOrderEditWorkflow](https://docs.medusajs.com/references/medusa-workflows/cancelDraftOrderEditWorkflow/index.html.md)
+- [confirmDraftOrderEditWorkflow](https://docs.medusajs.com/references/medusa-workflows/confirmDraftOrderEditWorkflow/index.html.md)
+- [addDraftOrderItemsWorkflow](https://docs.medusajs.com/references/medusa-workflows/addDraftOrderItemsWorkflow/index.html.md)
+- [convertDraftOrderStep](https://docs.medusajs.com/references/medusa-workflows/convertDraftOrderStep/index.html.md)
+- [convertDraftOrderWorkflow](https://docs.medusajs.com/references/medusa-workflows/convertDraftOrderWorkflow/index.html.md)
+- [removeDraftOrderActionItemWorkflow](https://docs.medusajs.com/references/medusa-workflows/removeDraftOrderActionItemWorkflow/index.html.md)
+- [removeDraftOrderShippingMethodWorkflow](https://docs.medusajs.com/references/medusa-workflows/removeDraftOrderShippingMethodWorkflow/index.html.md)
+- [removeDraftOrderActionShippingMethodWorkflow](https://docs.medusajs.com/references/medusa-workflows/removeDraftOrderActionShippingMethodWorkflow/index.html.md)
+- [requestDraftOrderEditWorkflow](https://docs.medusajs.com/references/medusa-workflows/requestDraftOrderEditWorkflow/index.html.md)
+- [updateDraftOrderActionShippingMethodWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateDraftOrderActionShippingMethodWorkflow/index.html.md)
+- [updateDraftOrderActionItemWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateDraftOrderActionItemWorkflow/index.html.md)
+- [updateDraftOrderShippingMethodWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateDraftOrderShippingMethodWorkflow/index.html.md)
+- [updateDraftOrderStep](https://docs.medusajs.com/references/medusa-workflows/updateDraftOrderStep/index.html.md)
+- [updateDraftOrderItemWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateDraftOrderItemWorkflow/index.html.md)
+- [removeDraftOrderPromotionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/removeDraftOrderPromotionsWorkflow/index.html.md)
+- [updateDraftOrderWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateDraftOrderWorkflow/index.html.md)
+- [batchLinksWorkflow](https://docs.medusajs.com/references/medusa-workflows/batchLinksWorkflow/index.html.md)
+- [updateLinksWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateLinksWorkflow/index.html.md)
+- [createLinksWorkflow](https://docs.medusajs.com/references/medusa-workflows/createLinksWorkflow/index.html.md)
+- [dismissLinksWorkflow](https://docs.medusajs.com/references/medusa-workflows/dismissLinksWorkflow/index.html.md)
+- [addShippingMethodToCartWorkflow](https://docs.medusajs.com/references/medusa-workflows/addShippingMethodToCartWorkflow/index.html.md)
+- [addToCartWorkflow](https://docs.medusajs.com/references/medusa-workflows/addToCartWorkflow/index.html.md)
+- [completeCartWorkflow](https://docs.medusajs.com/references/medusa-workflows/completeCartWorkflow/index.html.md)
+- [createCartCreditLinesWorkflow](https://docs.medusajs.com/references/medusa-workflows/createCartCreditLinesWorkflow/index.html.md)
+- [createCartWorkflow](https://docs.medusajs.com/references/medusa-workflows/createCartWorkflow/index.html.md)
+- [createPaymentCollectionForCartWorkflow](https://docs.medusajs.com/references/medusa-workflows/createPaymentCollectionForCartWorkflow/index.html.md)
+- [deleteCartCreditLinesWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteCartCreditLinesWorkflow/index.html.md)
+- [listShippingOptionsForCartWithPricingWorkflow](https://docs.medusajs.com/references/medusa-workflows/listShippingOptionsForCartWithPricingWorkflow/index.html.md)
+- [confirmVariantInventoryWorkflow](https://docs.medusajs.com/references/medusa-workflows/confirmVariantInventoryWorkflow/index.html.md)
+- [listShippingOptionsForCartWorkflow](https://docs.medusajs.com/references/medusa-workflows/listShippingOptionsForCartWorkflow/index.html.md)
+- [refreshCartShippingMethodsWorkflow](https://docs.medusajs.com/references/medusa-workflows/refreshCartShippingMethodsWorkflow/index.html.md)
+- [refreshCartItemsWorkflow](https://docs.medusajs.com/references/medusa-workflows/refreshCartItemsWorkflow/index.html.md)
+- [refreshPaymentCollectionForCartWorkflow](https://docs.medusajs.com/references/medusa-workflows/refreshPaymentCollectionForCartWorkflow/index.html.md)
+- [updateCartPromotionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateCartPromotionsWorkflow/index.html.md)
+- [updateCartWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateCartWorkflow/index.html.md)
+- [transferCartCustomerWorkflow](https://docs.medusajs.com/references/medusa-workflows/transferCartCustomerWorkflow/index.html.md)
+- [validateExistingPaymentCollectionStep](https://docs.medusajs.com/references/medusa-workflows/validateExistingPaymentCollectionStep/index.html.md)
+- [updateTaxLinesWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateTaxLinesWorkflow/index.html.md)
+- [updateLineItemInCartWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateLineItemInCartWorkflow/index.html.md)
+- [uploadFilesWorkflow](https://docs.medusajs.com/references/medusa-workflows/uploadFilesWorkflow/index.html.md)
+- [deleteFilesWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteFilesWorkflow/index.html.md)
- [cancelFulfillmentWorkflow](https://docs.medusajs.com/references/medusa-workflows/cancelFulfillmentWorkflow/index.html.md)
+- [batchShippingOptionRulesWorkflow](https://docs.medusajs.com/references/medusa-workflows/batchShippingOptionRulesWorkflow/index.html.md)
- [calculateShippingOptionsPricesWorkflow](https://docs.medusajs.com/references/medusa-workflows/calculateShippingOptionsPricesWorkflow/index.html.md)
-- [createServiceZonesWorkflow](https://docs.medusajs.com/references/medusa-workflows/createServiceZonesWorkflow/index.html.md)
-- [createReturnFulfillmentWorkflow](https://docs.medusajs.com/references/medusa-workflows/createReturnFulfillmentWorkflow/index.html.md)
- [createFulfillmentWorkflow](https://docs.medusajs.com/references/medusa-workflows/createFulfillmentWorkflow/index.html.md)
-- [createShippingOptionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createShippingOptionsWorkflow/index.html.md)
- [createShipmentWorkflow](https://docs.medusajs.com/references/medusa-workflows/createShipmentWorkflow/index.html.md)
-- [deleteServiceZonesWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteServiceZonesWorkflow/index.html.md)
+- [createReturnFulfillmentWorkflow](https://docs.medusajs.com/references/medusa-workflows/createReturnFulfillmentWorkflow/index.html.md)
+- [createServiceZonesWorkflow](https://docs.medusajs.com/references/medusa-workflows/createServiceZonesWorkflow/index.html.md)
+- [createShippingOptionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createShippingOptionsWorkflow/index.html.md)
- [createShippingProfilesWorkflow](https://docs.medusajs.com/references/medusa-workflows/createShippingProfilesWorkflow/index.html.md)
-- [markFulfillmentAsDeliveredWorkflow](https://docs.medusajs.com/references/medusa-workflows/markFulfillmentAsDeliveredWorkflow/index.html.md)
-- [deleteShippingOptionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteShippingOptionsWorkflow/index.html.md)
+- [deleteServiceZonesWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteServiceZonesWorkflow/index.html.md)
- [deleteFulfillmentSetsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteFulfillmentSetsWorkflow/index.html.md)
-- [updateServiceZonesWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateServiceZonesWorkflow/index.html.md)
-- [validateFulfillmentDeliverabilityStep](https://docs.medusajs.com/references/medusa-workflows/validateFulfillmentDeliverabilityStep/index.html.md)
+- [deleteShippingOptionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteShippingOptionsWorkflow/index.html.md)
- [updateFulfillmentWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateFulfillmentWorkflow/index.html.md)
+- [markFulfillmentAsDeliveredWorkflow](https://docs.medusajs.com/references/medusa-workflows/markFulfillmentAsDeliveredWorkflow/index.html.md)
- [updateShippingOptionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateShippingOptionsWorkflow/index.html.md)
+- [validateFulfillmentDeliverabilityStep](https://docs.medusajs.com/references/medusa-workflows/validateFulfillmentDeliverabilityStep/index.html.md)
+- [updateServiceZonesWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateServiceZonesWorkflow/index.html.md)
- [updateShippingProfilesWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateShippingProfilesWorkflow/index.html.md)
-- [acceptInviteWorkflow](https://docs.medusajs.com/references/medusa-workflows/acceptInviteWorkflow/index.html.md)
-- [createInvitesWorkflow](https://docs.medusajs.com/references/medusa-workflows/createInvitesWorkflow/index.html.md)
-- [refreshInviteTokensWorkflow](https://docs.medusajs.com/references/medusa-workflows/refreshInviteTokensWorkflow/index.html.md)
-- [deleteInvitesWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteInvitesWorkflow/index.html.md)
-- [batchInventoryItemLevelsWorkflow](https://docs.medusajs.com/references/medusa-workflows/batchInventoryItemLevelsWorkflow/index.html.md)
- [bulkCreateDeleteLevelsWorkflow](https://docs.medusajs.com/references/medusa-workflows/bulkCreateDeleteLevelsWorkflow/index.html.md)
+- [batchInventoryItemLevelsWorkflow](https://docs.medusajs.com/references/medusa-workflows/batchInventoryItemLevelsWorkflow/index.html.md)
- [createInventoryItemsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createInventoryItemsWorkflow/index.html.md)
- [createInventoryLevelsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createInventoryLevelsWorkflow/index.html.md)
- [deleteInventoryItemWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteInventoryItemWorkflow/index.html.md)
@@ -30516,530 +30664,534 @@ Each variant in the retrieved products has a `calculated_price` object. Learn mo
- [updateInventoryItemsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateInventoryItemsWorkflow/index.html.md)
- [updateInventoryLevelsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateInventoryLevelsWorkflow/index.html.md)
- [validateInventoryLevelsDelete](https://docs.medusajs.com/references/medusa-workflows/validateInventoryLevelsDelete/index.html.md)
+- [deleteInvitesWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteInvitesWorkflow/index.html.md)
+- [createInvitesWorkflow](https://docs.medusajs.com/references/medusa-workflows/createInvitesWorkflow/index.html.md)
+- [acceptInviteWorkflow](https://docs.medusajs.com/references/medusa-workflows/acceptInviteWorkflow/index.html.md)
+- [refreshInviteTokensWorkflow](https://docs.medusajs.com/references/medusa-workflows/refreshInviteTokensWorkflow/index.html.md)
- [deleteLineItemsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteLineItemsWorkflow/index.html.md)
-- [processPaymentWorkflow](https://docs.medusajs.com/references/medusa-workflows/processPaymentWorkflow/index.html.md)
- [capturePaymentWorkflow](https://docs.medusajs.com/references/medusa-workflows/capturePaymentWorkflow/index.html.md)
-- [refundPaymentsWorkflow](https://docs.medusajs.com/references/medusa-workflows/refundPaymentsWorkflow/index.html.md)
- [refundPaymentWorkflow](https://docs.medusajs.com/references/medusa-workflows/refundPaymentWorkflow/index.html.md)
-- [validateRefundStep](https://docs.medusajs.com/references/medusa-workflows/validateRefundStep/index.html.md)
+- [refundPaymentsWorkflow](https://docs.medusajs.com/references/medusa-workflows/refundPaymentsWorkflow/index.html.md)
+- [processPaymentWorkflow](https://docs.medusajs.com/references/medusa-workflows/processPaymentWorkflow/index.html.md)
- [validatePaymentsRefundStep](https://docs.medusajs.com/references/medusa-workflows/validatePaymentsRefundStep/index.html.md)
+- [validateRefundStep](https://docs.medusajs.com/references/medusa-workflows/validateRefundStep/index.html.md)
+- [createPriceListPricesWorkflow](https://docs.medusajs.com/references/medusa-workflows/createPriceListPricesWorkflow/index.html.md)
+- [batchPriceListPricesWorkflow](https://docs.medusajs.com/references/medusa-workflows/batchPriceListPricesWorkflow/index.html.md)
+- [createPriceListsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createPriceListsWorkflow/index.html.md)
+- [deletePriceListsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deletePriceListsWorkflow/index.html.md)
+- [updatePriceListsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updatePriceListsWorkflow/index.html.md)
+- [updatePriceListPricesWorkflow](https://docs.medusajs.com/references/medusa-workflows/updatePriceListPricesWorkflow/index.html.md)
+- [removePriceListPricesWorkflow](https://docs.medusajs.com/references/medusa-workflows/removePriceListPricesWorkflow/index.html.md)
- [createPaymentSessionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createPaymentSessionsWorkflow/index.html.md)
- [createRefundReasonsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createRefundReasonsWorkflow/index.html.md)
- [deleteRefundReasonsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteRefundReasonsWorkflow/index.html.md)
-- [updateRefundReasonsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateRefundReasonsWorkflow/index.html.md)
- [deletePaymentSessionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deletePaymentSessionsWorkflow/index.html.md)
-- [createPriceListPricesWorkflow](https://docs.medusajs.com/references/medusa-workflows/createPriceListPricesWorkflow/index.html.md)
-- [removePriceListPricesWorkflow](https://docs.medusajs.com/references/medusa-workflows/removePriceListPricesWorkflow/index.html.md)
-- [updatePriceListPricesWorkflow](https://docs.medusajs.com/references/medusa-workflows/updatePriceListPricesWorkflow/index.html.md)
-- [deletePriceListsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deletePriceListsWorkflow/index.html.md)
-- [createPriceListsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createPriceListsWorkflow/index.html.md)
-- [updatePriceListsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updatePriceListsWorkflow/index.html.md)
-- [batchPriceListPricesWorkflow](https://docs.medusajs.com/references/medusa-workflows/batchPriceListPricesWorkflow/index.html.md)
-- [createPricePreferencesWorkflow](https://docs.medusajs.com/references/medusa-workflows/createPricePreferencesWorkflow/index.html.md)
-- [deletePricePreferencesWorkflow](https://docs.medusajs.com/references/medusa-workflows/deletePricePreferencesWorkflow/index.html.md)
-- [updatePricePreferencesWorkflow](https://docs.medusajs.com/references/medusa-workflows/updatePricePreferencesWorkflow/index.html.md)
+- [updateRefundReasonsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateRefundReasonsWorkflow/index.html.md)
- [acceptOrderTransferValidationStep](https://docs.medusajs.com/references/medusa-workflows/acceptOrderTransferValidationStep/index.html.md)
-- [acceptOrderTransferWorkflow](https://docs.medusajs.com/references/medusa-workflows/acceptOrderTransferWorkflow/index.html.md)
-- [archiveOrderWorkflow](https://docs.medusajs.com/references/medusa-workflows/archiveOrderWorkflow/index.html.md)
- [addOrderLineItemsWorkflow](https://docs.medusajs.com/references/medusa-workflows/addOrderLineItemsWorkflow/index.html.md)
+- [acceptOrderTransferWorkflow](https://docs.medusajs.com/references/medusa-workflows/acceptOrderTransferWorkflow/index.html.md)
- [beginClaimOrderWorkflow](https://docs.medusajs.com/references/medusa-workflows/beginClaimOrderWorkflow/index.html.md)
-- [beginExchangeOrderWorkflow](https://docs.medusajs.com/references/medusa-workflows/beginExchangeOrderWorkflow/index.html.md)
- [beginClaimOrderValidationStep](https://docs.medusajs.com/references/medusa-workflows/beginClaimOrderValidationStep/index.html.md)
-- [beginOrderExchangeValidationStep](https://docs.medusajs.com/references/medusa-workflows/beginOrderExchangeValidationStep/index.html.md)
+- [archiveOrderWorkflow](https://docs.medusajs.com/references/medusa-workflows/archiveOrderWorkflow/index.html.md)
+- [beginExchangeOrderWorkflow](https://docs.medusajs.com/references/medusa-workflows/beginExchangeOrderWorkflow/index.html.md)
- [beginOrderEditOrderWorkflow](https://docs.medusajs.com/references/medusa-workflows/beginOrderEditOrderWorkflow/index.html.md)
- [beginOrderEditValidationStep](https://docs.medusajs.com/references/medusa-workflows/beginOrderEditValidationStep/index.html.md)
-- [beginReturnOrderValidationStep](https://docs.medusajs.com/references/medusa-workflows/beginReturnOrderValidationStep/index.html.md)
+- [beginOrderExchangeValidationStep](https://docs.medusajs.com/references/medusa-workflows/beginOrderExchangeValidationStep/index.html.md)
- [beginReceiveReturnWorkflow](https://docs.medusajs.com/references/medusa-workflows/beginReceiveReturnWorkflow/index.html.md)
-- [beginReturnOrderWorkflow](https://docs.medusajs.com/references/medusa-workflows/beginReturnOrderWorkflow/index.html.md)
-- [cancelBeginOrderClaimWorkflow](https://docs.medusajs.com/references/medusa-workflows/cancelBeginOrderClaimWorkflow/index.html.md)
-- [cancelBeginOrderClaimValidationStep](https://docs.medusajs.com/references/medusa-workflows/cancelBeginOrderClaimValidationStep/index.html.md)
-- [cancelBeginOrderEditWorkflow](https://docs.medusajs.com/references/medusa-workflows/cancelBeginOrderEditWorkflow/index.html.md)
+- [beginReturnOrderValidationStep](https://docs.medusajs.com/references/medusa-workflows/beginReturnOrderValidationStep/index.html.md)
- [beginReceiveReturnValidationStep](https://docs.medusajs.com/references/medusa-workflows/beginReceiveReturnValidationStep/index.html.md)
+- [beginReturnOrderWorkflow](https://docs.medusajs.com/references/medusa-workflows/beginReturnOrderWorkflow/index.html.md)
+- [cancelBeginOrderClaimValidationStep](https://docs.medusajs.com/references/medusa-workflows/cancelBeginOrderClaimValidationStep/index.html.md)
+- [cancelBeginOrderEditValidationStep](https://docs.medusajs.com/references/medusa-workflows/cancelBeginOrderEditValidationStep/index.html.md)
+- [cancelBeginOrderClaimWorkflow](https://docs.medusajs.com/references/medusa-workflows/cancelBeginOrderClaimWorkflow/index.html.md)
+- [cancelBeginOrderEditWorkflow](https://docs.medusajs.com/references/medusa-workflows/cancelBeginOrderEditWorkflow/index.html.md)
- [cancelBeginOrderExchangeWorkflow](https://docs.medusajs.com/references/medusa-workflows/cancelBeginOrderExchangeWorkflow/index.html.md)
- [cancelClaimValidateOrderStep](https://docs.medusajs.com/references/medusa-workflows/cancelClaimValidateOrderStep/index.html.md)
-- [cancelBeginOrderExchangeValidationStep](https://docs.medusajs.com/references/medusa-workflows/cancelBeginOrderExchangeValidationStep/index.html.md)
- [cancelExchangeValidateOrder](https://docs.medusajs.com/references/medusa-workflows/cancelExchangeValidateOrder/index.html.md)
-- [cancelOrderClaimWorkflow](https://docs.medusajs.com/references/medusa-workflows/cancelOrderClaimWorkflow/index.html.md)
+- [cancelBeginOrderExchangeValidationStep](https://docs.medusajs.com/references/medusa-workflows/cancelBeginOrderExchangeValidationStep/index.html.md)
- [cancelOrderChangeWorkflow](https://docs.medusajs.com/references/medusa-workflows/cancelOrderChangeWorkflow/index.html.md)
- [cancelOrderExchangeWorkflow](https://docs.medusajs.com/references/medusa-workflows/cancelOrderExchangeWorkflow/index.html.md)
+- [cancelOrderClaimWorkflow](https://docs.medusajs.com/references/medusa-workflows/cancelOrderClaimWorkflow/index.html.md)
- [cancelOrderFulfillmentValidateOrder](https://docs.medusajs.com/references/medusa-workflows/cancelOrderFulfillmentValidateOrder/index.html.md)
-- [cancelOrderFulfillmentWorkflow](https://docs.medusajs.com/references/medusa-workflows/cancelOrderFulfillmentWorkflow/index.html.md)
-- [cancelBeginOrderEditValidationStep](https://docs.medusajs.com/references/medusa-workflows/cancelBeginOrderEditValidationStep/index.html.md)
-- [cancelOrderWorkflow](https://docs.medusajs.com/references/medusa-workflows/cancelOrderWorkflow/index.html.md)
-- [cancelReceiveReturnValidationStep](https://docs.medusajs.com/references/medusa-workflows/cancelReceiveReturnValidationStep/index.html.md)
- [cancelOrderTransferRequestWorkflow](https://docs.medusajs.com/references/medusa-workflows/cancelOrderTransferRequestWorkflow/index.html.md)
+- [cancelOrderWorkflow](https://docs.medusajs.com/references/medusa-workflows/cancelOrderWorkflow/index.html.md)
+- [cancelOrderFulfillmentWorkflow](https://docs.medusajs.com/references/medusa-workflows/cancelOrderFulfillmentWorkflow/index.html.md)
+- [cancelReceiveReturnValidationStep](https://docs.medusajs.com/references/medusa-workflows/cancelReceiveReturnValidationStep/index.html.md)
+- [cancelRequestReturnValidationStep](https://docs.medusajs.com/references/medusa-workflows/cancelRequestReturnValidationStep/index.html.md)
- [cancelReturnRequestWorkflow](https://docs.medusajs.com/references/medusa-workflows/cancelReturnRequestWorkflow/index.html.md)
- [cancelReturnReceiveWorkflow](https://docs.medusajs.com/references/medusa-workflows/cancelReturnReceiveWorkflow/index.html.md)
-- [cancelRequestReturnValidationStep](https://docs.medusajs.com/references/medusa-workflows/cancelRequestReturnValidationStep/index.html.md)
-- [cancelTransferOrderRequestValidationStep](https://docs.medusajs.com/references/medusa-workflows/cancelTransferOrderRequestValidationStep/index.html.md)
-- [cancelReturnWorkflow](https://docs.medusajs.com/references/medusa-workflows/cancelReturnWorkflow/index.html.md)
-- [cancelValidateOrder](https://docs.medusajs.com/references/medusa-workflows/cancelValidateOrder/index.html.md)
- [cancelReturnValidateOrder](https://docs.medusajs.com/references/medusa-workflows/cancelReturnValidateOrder/index.html.md)
+- [cancelValidateOrder](https://docs.medusajs.com/references/medusa-workflows/cancelValidateOrder/index.html.md)
+- [cancelReturnWorkflow](https://docs.medusajs.com/references/medusa-workflows/cancelReturnWorkflow/index.html.md)
+- [cancelTransferOrderRequestValidationStep](https://docs.medusajs.com/references/medusa-workflows/cancelTransferOrderRequestValidationStep/index.html.md)
- [completeOrderWorkflow](https://docs.medusajs.com/references/medusa-workflows/completeOrderWorkflow/index.html.md)
-- [confirmClaimRequestValidationStep](https://docs.medusajs.com/references/medusa-workflows/confirmClaimRequestValidationStep/index.html.md)
-- [confirmClaimRequestWorkflow](https://docs.medusajs.com/references/medusa-workflows/confirmClaimRequestWorkflow/index.html.md)
- [confirmExchangeRequestValidationStep](https://docs.medusajs.com/references/medusa-workflows/confirmExchangeRequestValidationStep/index.html.md)
-- [confirmOrderEditRequestValidationStep](https://docs.medusajs.com/references/medusa-workflows/confirmOrderEditRequestValidationStep/index.html.md)
-- [confirmOrderEditRequestWorkflow](https://docs.medusajs.com/references/medusa-workflows/confirmOrderEditRequestWorkflow/index.html.md)
+- [confirmClaimRequestWorkflow](https://docs.medusajs.com/references/medusa-workflows/confirmClaimRequestWorkflow/index.html.md)
+- [confirmClaimRequestValidationStep](https://docs.medusajs.com/references/medusa-workflows/confirmClaimRequestValidationStep/index.html.md)
- [confirmExchangeRequestWorkflow](https://docs.medusajs.com/references/medusa-workflows/confirmExchangeRequestWorkflow/index.html.md)
+- [confirmOrderEditRequestValidationStep](https://docs.medusajs.com/references/medusa-workflows/confirmOrderEditRequestValidationStep/index.html.md)
- [confirmReceiveReturnValidationStep](https://docs.medusajs.com/references/medusa-workflows/confirmReceiveReturnValidationStep/index.html.md)
-- [confirmReturnRequestWorkflow](https://docs.medusajs.com/references/medusa-workflows/confirmReturnRequestWorkflow/index.html.md)
-- [createClaimShippingMethodValidationStep](https://docs.medusajs.com/references/medusa-workflows/createClaimShippingMethodValidationStep/index.html.md)
+- [confirmOrderEditRequestWorkflow](https://docs.medusajs.com/references/medusa-workflows/confirmOrderEditRequestWorkflow/index.html.md)
- [confirmReturnReceiveWorkflow](https://docs.medusajs.com/references/medusa-workflows/confirmReturnReceiveWorkflow/index.html.md)
- [createAndCompleteReturnOrderWorkflow](https://docs.medusajs.com/references/medusa-workflows/createAndCompleteReturnOrderWorkflow/index.html.md)
- [confirmReturnRequestValidationStep](https://docs.medusajs.com/references/medusa-workflows/confirmReturnRequestValidationStep/index.html.md)
-- [createCompleteReturnValidationStep](https://docs.medusajs.com/references/medusa-workflows/createCompleteReturnValidationStep/index.html.md)
+- [createClaimShippingMethodValidationStep](https://docs.medusajs.com/references/medusa-workflows/createClaimShippingMethodValidationStep/index.html.md)
+- [confirmReturnRequestWorkflow](https://docs.medusajs.com/references/medusa-workflows/confirmReturnRequestWorkflow/index.html.md)
- [createClaimShippingMethodWorkflow](https://docs.medusajs.com/references/medusa-workflows/createClaimShippingMethodWorkflow/index.html.md)
+- [createCompleteReturnValidationStep](https://docs.medusajs.com/references/medusa-workflows/createCompleteReturnValidationStep/index.html.md)
- [createExchangeShippingMethodValidationStep](https://docs.medusajs.com/references/medusa-workflows/createExchangeShippingMethodValidationStep/index.html.md)
- [createExchangeShippingMethodWorkflow](https://docs.medusajs.com/references/medusa-workflows/createExchangeShippingMethodWorkflow/index.html.md)
-- [createFulfillmentValidateOrder](https://docs.medusajs.com/references/medusa-workflows/createFulfillmentValidateOrder/index.html.md)
- [createOrUpdateOrderPaymentCollectionWorkflow](https://docs.medusajs.com/references/medusa-workflows/createOrUpdateOrderPaymentCollectionWorkflow/index.html.md)
+- [createFulfillmentValidateOrder](https://docs.medusajs.com/references/medusa-workflows/createFulfillmentValidateOrder/index.html.md)
- [createOrderChangeActionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createOrderChangeActionsWorkflow/index.html.md)
- [createOrderCreditLinesWorkflow](https://docs.medusajs.com/references/medusa-workflows/createOrderCreditLinesWorkflow/index.html.md)
-- [createOrderChangeWorkflow](https://docs.medusajs.com/references/medusa-workflows/createOrderChangeWorkflow/index.html.md)
- [createOrderEditShippingMethodValidationStep](https://docs.medusajs.com/references/medusa-workflows/createOrderEditShippingMethodValidationStep/index.html.md)
+- [createOrderChangeWorkflow](https://docs.medusajs.com/references/medusa-workflows/createOrderChangeWorkflow/index.html.md)
- [createOrderEditShippingMethodWorkflow](https://docs.medusajs.com/references/medusa-workflows/createOrderEditShippingMethodWorkflow/index.html.md)
- [createOrderPaymentCollectionWorkflow](https://docs.medusajs.com/references/medusa-workflows/createOrderPaymentCollectionWorkflow/index.html.md)
-- [createOrderShipmentWorkflow](https://docs.medusajs.com/references/medusa-workflows/createOrderShipmentWorkflow/index.html.md)
- [createOrderFulfillmentWorkflow](https://docs.medusajs.com/references/medusa-workflows/createOrderFulfillmentWorkflow/index.html.md)
-- [createOrdersWorkflow](https://docs.medusajs.com/references/medusa-workflows/createOrdersWorkflow/index.html.md)
-- [createReturnShippingMethodValidationStep](https://docs.medusajs.com/references/medusa-workflows/createReturnShippingMethodValidationStep/index.html.md)
+- [createOrderShipmentWorkflow](https://docs.medusajs.com/references/medusa-workflows/createOrderShipmentWorkflow/index.html.md)
- [createOrderWorkflow](https://docs.medusajs.com/references/medusa-workflows/createOrderWorkflow/index.html.md)
+- [createReturnShippingMethodValidationStep](https://docs.medusajs.com/references/medusa-workflows/createReturnShippingMethodValidationStep/index.html.md)
- [createReturnShippingMethodWorkflow](https://docs.medusajs.com/references/medusa-workflows/createReturnShippingMethodWorkflow/index.html.md)
-- [declineOrderChangeWorkflow](https://docs.medusajs.com/references/medusa-workflows/declineOrderChangeWorkflow/index.html.md)
+- [createOrdersWorkflow](https://docs.medusajs.com/references/medusa-workflows/createOrdersWorkflow/index.html.md)
- [declineTransferOrderRequestValidationStep](https://docs.medusajs.com/references/medusa-workflows/declineTransferOrderRequestValidationStep/index.html.md)
-- [deleteOrderChangeActionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteOrderChangeActionsWorkflow/index.html.md)
+- [declineOrderChangeWorkflow](https://docs.medusajs.com/references/medusa-workflows/declineOrderChangeWorkflow/index.html.md)
- [declineOrderTransferRequestWorkflow](https://docs.medusajs.com/references/medusa-workflows/declineOrderTransferRequestWorkflow/index.html.md)
- [createShipmentValidateOrder](https://docs.medusajs.com/references/medusa-workflows/createShipmentValidateOrder/index.html.md)
+- [deleteOrderChangeActionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteOrderChangeActionsWorkflow/index.html.md)
- [deleteOrderChangeWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteOrderChangeWorkflow/index.html.md)
- [deleteOrderPaymentCollections](https://docs.medusajs.com/references/medusa-workflows/deleteOrderPaymentCollections/index.html.md)
-- [exchangeAddNewItemValidationStep](https://docs.medusajs.com/references/medusa-workflows/exchangeAddNewItemValidationStep/index.html.md)
-- [dismissItemReturnRequestValidationStep](https://docs.medusajs.com/references/medusa-workflows/dismissItemReturnRequestValidationStep/index.html.md)
-- [getOrderDetailWorkflow](https://docs.medusajs.com/references/medusa-workflows/getOrderDetailWorkflow/index.html.md)
-- [exchangeRequestItemReturnValidationStep](https://docs.medusajs.com/references/medusa-workflows/exchangeRequestItemReturnValidationStep/index.html.md)
- [dismissItemReturnRequestWorkflow](https://docs.medusajs.com/references/medusa-workflows/dismissItemReturnRequestWorkflow/index.html.md)
+- [dismissItemReturnRequestValidationStep](https://docs.medusajs.com/references/medusa-workflows/dismissItemReturnRequestValidationStep/index.html.md)
+- [exchangeRequestItemReturnValidationStep](https://docs.medusajs.com/references/medusa-workflows/exchangeRequestItemReturnValidationStep/index.html.md)
+- [exchangeAddNewItemValidationStep](https://docs.medusajs.com/references/medusa-workflows/exchangeAddNewItemValidationStep/index.html.md)
+- [markPaymentCollectionAsPaid](https://docs.medusajs.com/references/medusa-workflows/markPaymentCollectionAsPaid/index.html.md)
+- [markOrderFulfillmentAsDeliveredWorkflow](https://docs.medusajs.com/references/medusa-workflows/markOrderFulfillmentAsDeliveredWorkflow/index.html.md)
+- [getOrderDetailWorkflow](https://docs.medusajs.com/references/medusa-workflows/getOrderDetailWorkflow/index.html.md)
- [getOrdersListWorkflow](https://docs.medusajs.com/references/medusa-workflows/getOrdersListWorkflow/index.html.md)
- [orderClaimAddNewItemValidationStep](https://docs.medusajs.com/references/medusa-workflows/orderClaimAddNewItemValidationStep/index.html.md)
-- [orderClaimAddNewItemWorkflow](https://docs.medusajs.com/references/medusa-workflows/orderClaimAddNewItemWorkflow/index.html.md)
-- [markOrderFulfillmentAsDeliveredWorkflow](https://docs.medusajs.com/references/medusa-workflows/markOrderFulfillmentAsDeliveredWorkflow/index.html.md)
- [orderClaimItemValidationStep](https://docs.medusajs.com/references/medusa-workflows/orderClaimItemValidationStep/index.html.md)
- [orderClaimItemWorkflow](https://docs.medusajs.com/references/medusa-workflows/orderClaimItemWorkflow/index.html.md)
- [orderClaimRequestItemReturnValidationStep](https://docs.medusajs.com/references/medusa-workflows/orderClaimRequestItemReturnValidationStep/index.html.md)
-- [markPaymentCollectionAsPaid](https://docs.medusajs.com/references/medusa-workflows/markPaymentCollectionAsPaid/index.html.md)
-- [orderClaimRequestItemReturnWorkflow](https://docs.medusajs.com/references/medusa-workflows/orderClaimRequestItemReturnWorkflow/index.html.md)
+- [orderClaimAddNewItemWorkflow](https://docs.medusajs.com/references/medusa-workflows/orderClaimAddNewItemWorkflow/index.html.md)
- [orderEditAddNewItemValidationStep](https://docs.medusajs.com/references/medusa-workflows/orderEditAddNewItemValidationStep/index.html.md)
- [orderEditAddNewItemWorkflow](https://docs.medusajs.com/references/medusa-workflows/orderEditAddNewItemWorkflow/index.html.md)
-- [orderEditUpdateItemQuantityWorkflow](https://docs.medusajs.com/references/medusa-workflows/orderEditUpdateItemQuantityWorkflow/index.html.md)
-- [orderExchangeAddNewItemWorkflow](https://docs.medusajs.com/references/medusa-workflows/orderExchangeAddNewItemWorkflow/index.html.md)
-- [orderFulfillmentDeliverablilityValidationStep](https://docs.medusajs.com/references/medusa-workflows/orderFulfillmentDeliverablilityValidationStep/index.html.md)
-- [orderExchangeRequestItemReturnWorkflow](https://docs.medusajs.com/references/medusa-workflows/orderExchangeRequestItemReturnWorkflow/index.html.md)
-- [receiveAndCompleteReturnOrderWorkflow](https://docs.medusajs.com/references/medusa-workflows/receiveAndCompleteReturnOrderWorkflow/index.html.md)
+- [orderClaimRequestItemReturnWorkflow](https://docs.medusajs.com/references/medusa-workflows/orderClaimRequestItemReturnWorkflow/index.html.md)
- [orderEditUpdateItemQuantityValidationStep](https://docs.medusajs.com/references/medusa-workflows/orderEditUpdateItemQuantityValidationStep/index.html.md)
+- [orderExchangeAddNewItemWorkflow](https://docs.medusajs.com/references/medusa-workflows/orderExchangeAddNewItemWorkflow/index.html.md)
+- [orderExchangeRequestItemReturnWorkflow](https://docs.medusajs.com/references/medusa-workflows/orderExchangeRequestItemReturnWorkflow/index.html.md)
+- [orderEditUpdateItemQuantityWorkflow](https://docs.medusajs.com/references/medusa-workflows/orderEditUpdateItemQuantityWorkflow/index.html.md)
+- [orderFulfillmentDeliverablilityValidationStep](https://docs.medusajs.com/references/medusa-workflows/orderFulfillmentDeliverablilityValidationStep/index.html.md)
+- [receiveAndCompleteReturnOrderWorkflow](https://docs.medusajs.com/references/medusa-workflows/receiveAndCompleteReturnOrderWorkflow/index.html.md)
- [receiveItemReturnRequestValidationStep](https://docs.medusajs.com/references/medusa-workflows/receiveItemReturnRequestValidationStep/index.html.md)
-- [receiveItemReturnRequestWorkflow](https://docs.medusajs.com/references/medusa-workflows/receiveItemReturnRequestWorkflow/index.html.md)
- [receiveCompleteReturnValidationStep](https://docs.medusajs.com/references/medusa-workflows/receiveCompleteReturnValidationStep/index.html.md)
- [removeAddItemClaimActionWorkflow](https://docs.medusajs.com/references/medusa-workflows/removeAddItemClaimActionWorkflow/index.html.md)
- [removeClaimAddItemActionValidationStep](https://docs.medusajs.com/references/medusa-workflows/removeClaimAddItemActionValidationStep/index.html.md)
- [removeClaimItemActionValidationStep](https://docs.medusajs.com/references/medusa-workflows/removeClaimItemActionValidationStep/index.html.md)
-- [removeExchangeItemActionValidationStep](https://docs.medusajs.com/references/medusa-workflows/removeExchangeItemActionValidationStep/index.html.md)
+- [receiveItemReturnRequestWorkflow](https://docs.medusajs.com/references/medusa-workflows/receiveItemReturnRequestWorkflow/index.html.md)
- [removeClaimShippingMethodWorkflow](https://docs.medusajs.com/references/medusa-workflows/removeClaimShippingMethodWorkflow/index.html.md)
-- [removeExchangeShippingMethodWorkflow](https://docs.medusajs.com/references/medusa-workflows/removeExchangeShippingMethodWorkflow/index.html.md)
-- [removeExchangeShippingMethodValidationStep](https://docs.medusajs.com/references/medusa-workflows/removeExchangeShippingMethodValidationStep/index.html.md)
-- [removeItemClaimActionWorkflow](https://docs.medusajs.com/references/medusa-workflows/removeItemClaimActionWorkflow/index.html.md)
-- [removeItemExchangeActionWorkflow](https://docs.medusajs.com/references/medusa-workflows/removeItemExchangeActionWorkflow/index.html.md)
- [removeClaimShippingMethodValidationStep](https://docs.medusajs.com/references/medusa-workflows/removeClaimShippingMethodValidationStep/index.html.md)
-- [removeItemReceiveReturnActionWorkflow](https://docs.medusajs.com/references/medusa-workflows/removeItemReceiveReturnActionWorkflow/index.html.md)
+- [removeExchangeItemActionValidationStep](https://docs.medusajs.com/references/medusa-workflows/removeExchangeItemActionValidationStep/index.html.md)
+- [removeExchangeShippingMethodWorkflow](https://docs.medusajs.com/references/medusa-workflows/removeExchangeShippingMethodWorkflow/index.html.md)
+- [removeItemClaimActionWorkflow](https://docs.medusajs.com/references/medusa-workflows/removeItemClaimActionWorkflow/index.html.md)
+- [removeExchangeShippingMethodValidationStep](https://docs.medusajs.com/references/medusa-workflows/removeExchangeShippingMethodValidationStep/index.html.md)
+- [removeItemExchangeActionWorkflow](https://docs.medusajs.com/references/medusa-workflows/removeItemExchangeActionWorkflow/index.html.md)
+- [removeItemOrderEditActionWorkflow](https://docs.medusajs.com/references/medusa-workflows/removeItemOrderEditActionWorkflow/index.html.md)
- [removeItemReceiveReturnActionValidationStep](https://docs.medusajs.com/references/medusa-workflows/removeItemReceiveReturnActionValidationStep/index.html.md)
-- [removeOrderEditItemActionValidationStep](https://docs.medusajs.com/references/medusa-workflows/removeOrderEditItemActionValidationStep/index.html.md)
- [removeItemReturnActionWorkflow](https://docs.medusajs.com/references/medusa-workflows/removeItemReturnActionWorkflow/index.html.md)
- [removeOrderEditShippingMethodValidationStep](https://docs.medusajs.com/references/medusa-workflows/removeOrderEditShippingMethodValidationStep/index.html.md)
-- [removeItemOrderEditActionWorkflow](https://docs.medusajs.com/references/medusa-workflows/removeItemOrderEditActionWorkflow/index.html.md)
-- [removeOrderEditShippingMethodWorkflow](https://docs.medusajs.com/references/medusa-workflows/removeOrderEditShippingMethodWorkflow/index.html.md)
+- [removeItemReceiveReturnActionWorkflow](https://docs.medusajs.com/references/medusa-workflows/removeItemReceiveReturnActionWorkflow/index.html.md)
- [removeReturnItemActionValidationStep](https://docs.medusajs.com/references/medusa-workflows/removeReturnItemActionValidationStep/index.html.md)
-- [removeReturnShippingMethodValidationStep](https://docs.medusajs.com/references/medusa-workflows/removeReturnShippingMethodValidationStep/index.html.md)
-- [requestItemReturnValidationStep](https://docs.medusajs.com/references/medusa-workflows/requestItemReturnValidationStep/index.html.md)
-- [requestOrderEditRequestValidationStep](https://docs.medusajs.com/references/medusa-workflows/requestOrderEditRequestValidationStep/index.html.md)
-- [requestItemReturnWorkflow](https://docs.medusajs.com/references/medusa-workflows/requestItemReturnWorkflow/index.html.md)
+- [removeOrderEditItemActionValidationStep](https://docs.medusajs.com/references/medusa-workflows/removeOrderEditItemActionValidationStep/index.html.md)
+- [removeOrderEditShippingMethodWorkflow](https://docs.medusajs.com/references/medusa-workflows/removeOrderEditShippingMethodWorkflow/index.html.md)
- [removeReturnShippingMethodWorkflow](https://docs.medusajs.com/references/medusa-workflows/removeReturnShippingMethodWorkflow/index.html.md)
-- [requestOrderEditRequestWorkflow](https://docs.medusajs.com/references/medusa-workflows/requestOrderEditRequestWorkflow/index.html.md)
+- [requestItemReturnWorkflow](https://docs.medusajs.com/references/medusa-workflows/requestItemReturnWorkflow/index.html.md)
+- [requestItemReturnValidationStep](https://docs.medusajs.com/references/medusa-workflows/requestItemReturnValidationStep/index.html.md)
+- [removeReturnShippingMethodValidationStep](https://docs.medusajs.com/references/medusa-workflows/removeReturnShippingMethodValidationStep/index.html.md)
- [requestOrderTransferValidationStep](https://docs.medusajs.com/references/medusa-workflows/requestOrderTransferValidationStep/index.html.md)
-- [updateClaimAddItemValidationStep](https://docs.medusajs.com/references/medusa-workflows/updateClaimAddItemValidationStep/index.html.md)
-- [throwUnlessPaymentCollectionNotPaid](https://docs.medusajs.com/references/medusa-workflows/throwUnlessPaymentCollectionNotPaid/index.html.md)
+- [requestOrderEditRequestWorkflow](https://docs.medusajs.com/references/medusa-workflows/requestOrderEditRequestWorkflow/index.html.md)
+- [requestOrderEditRequestValidationStep](https://docs.medusajs.com/references/medusa-workflows/requestOrderEditRequestValidationStep/index.html.md)
+- [requestOrderTransferWorkflow](https://docs.medusajs.com/references/medusa-workflows/requestOrderTransferWorkflow/index.html.md)
- [throwUnlessStatusIsNotPaid](https://docs.medusajs.com/references/medusa-workflows/throwUnlessStatusIsNotPaid/index.html.md)
+- [throwUnlessPaymentCollectionNotPaid](https://docs.medusajs.com/references/medusa-workflows/throwUnlessPaymentCollectionNotPaid/index.html.md)
+- [updateClaimAddItemValidationStep](https://docs.medusajs.com/references/medusa-workflows/updateClaimAddItemValidationStep/index.html.md)
- [updateClaimAddItemWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateClaimAddItemWorkflow/index.html.md)
- [updateClaimItemValidationStep](https://docs.medusajs.com/references/medusa-workflows/updateClaimItemValidationStep/index.html.md)
- [updateClaimShippingMethodValidationStep](https://docs.medusajs.com/references/medusa-workflows/updateClaimShippingMethodValidationStep/index.html.md)
-- [updateClaimShippingMethodWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateClaimShippingMethodWorkflow/index.html.md)
-- [updateExchangeAddItemValidationStep](https://docs.medusajs.com/references/medusa-workflows/updateExchangeAddItemValidationStep/index.html.md)
- [updateClaimItemWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateClaimItemWorkflow/index.html.md)
-- [requestOrderTransferWorkflow](https://docs.medusajs.com/references/medusa-workflows/requestOrderTransferWorkflow/index.html.md)
+- [updateClaimShippingMethodWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateClaimShippingMethodWorkflow/index.html.md)
- [updateExchangeAddItemWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateExchangeAddItemWorkflow/index.html.md)
+- [updateExchangeAddItemValidationStep](https://docs.medusajs.com/references/medusa-workflows/updateExchangeAddItemValidationStep/index.html.md)
- [updateExchangeShippingMethodValidationStep](https://docs.medusajs.com/references/medusa-workflows/updateExchangeShippingMethodValidationStep/index.html.md)
- [updateOrderChangeActionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateOrderChangeActionsWorkflow/index.html.md)
-- [updateOrderChangesWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateOrderChangesWorkflow/index.html.md)
- [updateOrderEditAddItemValidationStep](https://docs.medusajs.com/references/medusa-workflows/updateOrderEditAddItemValidationStep/index.html.md)
-- [updateOrderEditAddItemWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateOrderEditAddItemWorkflow/index.html.md)
+- [updateOrderChangesWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateOrderChangesWorkflow/index.html.md)
- [updateExchangeShippingMethodWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateExchangeShippingMethodWorkflow/index.html.md)
+- [updateOrderEditAddItemWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateOrderEditAddItemWorkflow/index.html.md)
- [updateOrderEditItemQuantityValidationStep](https://docs.medusajs.com/references/medusa-workflows/updateOrderEditItemQuantityValidationStep/index.html.md)
- [updateOrderEditItemQuantityWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateOrderEditItemQuantityWorkflow/index.html.md)
- [updateOrderEditShippingMethodValidationStep](https://docs.medusajs.com/references/medusa-workflows/updateOrderEditShippingMethodValidationStep/index.html.md)
-- [updateOrderEditShippingMethodWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateOrderEditShippingMethodWorkflow/index.html.md)
-- [updateOrderWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateOrderWorkflow/index.html.md)
-- [updateReceiveItemReturnRequestValidationStep](https://docs.medusajs.com/references/medusa-workflows/updateReceiveItemReturnRequestValidationStep/index.html.md)
- [updateOrderTaxLinesWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateOrderTaxLinesWorkflow/index.html.md)
-- [updateRequestItemReturnValidationStep](https://docs.medusajs.com/references/medusa-workflows/updateRequestItemReturnValidationStep/index.html.md)
-- [updateReceiveItemReturnRequestWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateReceiveItemReturnRequestWorkflow/index.html.md)
- [updateOrderValidationStep](https://docs.medusajs.com/references/medusa-workflows/updateOrderValidationStep/index.html.md)
-- [updateReturnShippingMethodValidationStep](https://docs.medusajs.com/references/medusa-workflows/updateReturnShippingMethodValidationStep/index.html.md)
-- [updateReturnShippingMethodWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateReturnShippingMethodWorkflow/index.html.md)
+- [updateOrderWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateOrderWorkflow/index.html.md)
+- [updateOrderEditShippingMethodWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateOrderEditShippingMethodWorkflow/index.html.md)
+- [updateReceiveItemReturnRequestWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateReceiveItemReturnRequestWorkflow/index.html.md)
+- [updateReceiveItemReturnRequestValidationStep](https://docs.medusajs.com/references/medusa-workflows/updateReceiveItemReturnRequestValidationStep/index.html.md)
+- [updateRequestItemReturnValidationStep](https://docs.medusajs.com/references/medusa-workflows/updateRequestItemReturnValidationStep/index.html.md)
- [updateRequestItemReturnWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateRequestItemReturnWorkflow/index.html.md)
-- [updateReturnWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateReturnWorkflow/index.html.md)
-- [validateOrderCreditLinesStep](https://docs.medusajs.com/references/medusa-workflows/validateOrderCreditLinesStep/index.html.md)
+- [updateReturnShippingMethodWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateReturnShippingMethodWorkflow/index.html.md)
+- [updateReturnShippingMethodValidationStep](https://docs.medusajs.com/references/medusa-workflows/updateReturnShippingMethodValidationStep/index.html.md)
- [updateReturnValidationStep](https://docs.medusajs.com/references/medusa-workflows/updateReturnValidationStep/index.html.md)
+- [updateReturnWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateReturnWorkflow/index.html.md)
+- [createPricePreferencesWorkflow](https://docs.medusajs.com/references/medusa-workflows/createPricePreferencesWorkflow/index.html.md)
+- [validateOrderCreditLinesStep](https://docs.medusajs.com/references/medusa-workflows/validateOrderCreditLinesStep/index.html.md)
+- [deletePricePreferencesWorkflow](https://docs.medusajs.com/references/medusa-workflows/deletePricePreferencesWorkflow/index.html.md)
+- [updatePricePreferencesWorkflow](https://docs.medusajs.com/references/medusa-workflows/updatePricePreferencesWorkflow/index.html.md)
+- [batchLinkProductsToCollectionWorkflow](https://docs.medusajs.com/references/medusa-workflows/batchLinkProductsToCollectionWorkflow/index.html.md)
- [batchLinkProductsToCategoryWorkflow](https://docs.medusajs.com/references/medusa-workflows/batchLinkProductsToCategoryWorkflow/index.html.md)
- [batchProductVariantsWorkflow](https://docs.medusajs.com/references/medusa-workflows/batchProductVariantsWorkflow/index.html.md)
- [batchProductsWorkflow](https://docs.medusajs.com/references/medusa-workflows/batchProductsWorkflow/index.html.md)
-- [batchLinkProductsToCollectionWorkflow](https://docs.medusajs.com/references/medusa-workflows/batchLinkProductsToCollectionWorkflow/index.html.md)
-- [createProductOptionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createProductOptionsWorkflow/index.html.md)
- [createCollectionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createCollectionsWorkflow/index.html.md)
+- [createProductOptionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createProductOptionsWorkflow/index.html.md)
- [createProductTypesWorkflow](https://docs.medusajs.com/references/medusa-workflows/createProductTypesWorkflow/index.html.md)
-- [createProductVariantsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createProductVariantsWorkflow/index.html.md)
- [createProductTagsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createProductTagsWorkflow/index.html.md)
-- [deleteCollectionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteCollectionsWorkflow/index.html.md)
+- [createProductVariantsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createProductVariantsWorkflow/index.html.md)
- [deleteProductOptionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteProductOptionsWorkflow/index.html.md)
-- [deleteProductVariantsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteProductVariantsWorkflow/index.html.md)
-- [deleteProductTagsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteProductTagsWorkflow/index.html.md)
- [createProductsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createProductsWorkflow/index.html.md)
+- [deleteCollectionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteCollectionsWorkflow/index.html.md)
+- [deleteProductTagsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteProductTagsWorkflow/index.html.md)
+- [deleteProductVariantsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteProductVariantsWorkflow/index.html.md)
- [deleteProductTypesWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteProductTypesWorkflow/index.html.md)
- [deleteProductsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteProductsWorkflow/index.html.md)
-- [importProductsWorkflow](https://docs.medusajs.com/references/medusa-workflows/importProductsWorkflow/index.html.md)
-- [updateCollectionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateCollectionsWorkflow/index.html.md)
- [exportProductsWorkflow](https://docs.medusajs.com/references/medusa-workflows/exportProductsWorkflow/index.html.md)
+- [importProductsWorkflow](https://docs.medusajs.com/references/medusa-workflows/importProductsWorkflow/index.html.md)
- [updateProductOptionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateProductOptionsWorkflow/index.html.md)
-- [updateProductTagsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateProductTagsWorkflow/index.html.md)
+- [updateCollectionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateCollectionsWorkflow/index.html.md)
- [updateProductTypesWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateProductTypesWorkflow/index.html.md)
-- [upsertVariantPricesWorkflow](https://docs.medusajs.com/references/medusa-workflows/upsertVariantPricesWorkflow/index.html.md)
- [updateProductVariantsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateProductVariantsWorkflow/index.html.md)
+- [updateProductTagsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateProductTagsWorkflow/index.html.md)
- [updateProductsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateProductsWorkflow/index.html.md)
- [validateProductInputStep](https://docs.medusajs.com/references/medusa-workflows/validateProductInputStep/index.html.md)
-- [createProductCategoriesWorkflow](https://docs.medusajs.com/references/medusa-workflows/createProductCategoriesWorkflow/index.html.md)
+- [upsertVariantPricesWorkflow](https://docs.medusajs.com/references/medusa-workflows/upsertVariantPricesWorkflow/index.html.md)
- [deleteProductCategoriesWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteProductCategoriesWorkflow/index.html.md)
- [updateProductCategoriesWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateProductCategoriesWorkflow/index.html.md)
+- [createProductCategoriesWorkflow](https://docs.medusajs.com/references/medusa-workflows/createProductCategoriesWorkflow/index.html.md)
- [addOrRemoveCampaignPromotionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/addOrRemoveCampaignPromotionsWorkflow/index.html.md)
- [batchPromotionRulesWorkflow](https://docs.medusajs.com/references/medusa-workflows/batchPromotionRulesWorkflow/index.html.md)
-- [createPromotionRulesWorkflow](https://docs.medusajs.com/references/medusa-workflows/createPromotionRulesWorkflow/index.html.md)
- [createCampaignsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createCampaignsWorkflow/index.html.md)
+- [createPromotionRulesWorkflow](https://docs.medusajs.com/references/medusa-workflows/createPromotionRulesWorkflow/index.html.md)
+- [deleteCampaignsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteCampaignsWorkflow/index.html.md)
- [createPromotionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createPromotionsWorkflow/index.html.md)
- [deletePromotionRulesWorkflow](https://docs.medusajs.com/references/medusa-workflows/deletePromotionRulesWorkflow/index.html.md)
- [deletePromotionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deletePromotionsWorkflow/index.html.md)
-- [deleteCampaignsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteCampaignsWorkflow/index.html.md)
+- [updatePromotionsValidationStep](https://docs.medusajs.com/references/medusa-workflows/updatePromotionsValidationStep/index.html.md)
+- [updatePromotionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updatePromotionsWorkflow/index.html.md)
- [updateCampaignsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateCampaignsWorkflow/index.html.md)
- [updatePromotionRulesWorkflow](https://docs.medusajs.com/references/medusa-workflows/updatePromotionRulesWorkflow/index.html.md)
- [updatePromotionsStatusWorkflow](https://docs.medusajs.com/references/medusa-workflows/updatePromotionsStatusWorkflow/index.html.md)
-- [updatePromotionsValidationStep](https://docs.medusajs.com/references/medusa-workflows/updatePromotionsValidationStep/index.html.md)
-- [updatePromotionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updatePromotionsWorkflow/index.html.md)
+- [createRegionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createRegionsWorkflow/index.html.md)
+- [updateRegionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateRegionsWorkflow/index.html.md)
+- [deleteRegionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteRegionsWorkflow/index.html.md)
- [createReservationsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createReservationsWorkflow/index.html.md)
- [deleteReservationsByLineItemsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteReservationsByLineItemsWorkflow/index.html.md)
-- [updateReservationsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateReservationsWorkflow/index.html.md)
- [deleteReservationsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteReservationsWorkflow/index.html.md)
-- [createRegionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createRegionsWorkflow/index.html.md)
-- [deleteRegionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteRegionsWorkflow/index.html.md)
-- [updateRegionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateRegionsWorkflow/index.html.md)
-- [deleteShippingProfileWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteShippingProfileWorkflow/index.html.md)
-- [validateStepShippingProfileDelete](https://docs.medusajs.com/references/medusa-workflows/validateStepShippingProfileDelete/index.html.md)
-- [createLocationFulfillmentSetWorkflow](https://docs.medusajs.com/references/medusa-workflows/createLocationFulfillmentSetWorkflow/index.html.md)
-- [deleteStockLocationsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteStockLocationsWorkflow/index.html.md)
-- [linkSalesChannelsToStockLocationWorkflow](https://docs.medusajs.com/references/medusa-workflows/linkSalesChannelsToStockLocationWorkflow/index.html.md)
-- [updateStockLocationsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateStockLocationsWorkflow/index.html.md)
-- [createStockLocationsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createStockLocationsWorkflow/index.html.md)
-- [deleteStoresWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteStoresWorkflow/index.html.md)
-- [updateStoresWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateStoresWorkflow/index.html.md)
-- [createStoresWorkflow](https://docs.medusajs.com/references/medusa-workflows/createStoresWorkflow/index.html.md)
-- [createSalesChannelsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createSalesChannelsWorkflow/index.html.md)
-- [linkProductsToSalesChannelWorkflow](https://docs.medusajs.com/references/medusa-workflows/linkProductsToSalesChannelWorkflow/index.html.md)
-- [updateSalesChannelsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateSalesChannelsWorkflow/index.html.md)
-- [deleteSalesChannelsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteSalesChannelsWorkflow/index.html.md)
+- [updateReservationsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateReservationsWorkflow/index.html.md)
- [createReturnReasonsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createReturnReasonsWorkflow/index.html.md)
- [updateReturnReasonsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateReturnReasonsWorkflow/index.html.md)
- [deleteReturnReasonsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteReturnReasonsWorkflow/index.html.md)
-- [createUsersWorkflow](https://docs.medusajs.com/references/medusa-workflows/createUsersWorkflow/index.html.md)
+- [createSalesChannelsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createSalesChannelsWorkflow/index.html.md)
+- [deleteSalesChannelsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteSalesChannelsWorkflow/index.html.md)
+- [linkProductsToSalesChannelWorkflow](https://docs.medusajs.com/references/medusa-workflows/linkProductsToSalesChannelWorkflow/index.html.md)
+- [updateSalesChannelsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateSalesChannelsWorkflow/index.html.md)
+- [createStoresWorkflow](https://docs.medusajs.com/references/medusa-workflows/createStoresWorkflow/index.html.md)
+- [deleteStoresWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteStoresWorkflow/index.html.md)
+- [updateStoresWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateStoresWorkflow/index.html.md)
+- [deleteShippingProfileWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteShippingProfileWorkflow/index.html.md)
+- [validateStepShippingProfileDelete](https://docs.medusajs.com/references/medusa-workflows/validateStepShippingProfileDelete/index.html.md)
+- [createStockLocationsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createStockLocationsWorkflow/index.html.md)
+- [linkSalesChannelsToStockLocationWorkflow](https://docs.medusajs.com/references/medusa-workflows/linkSalesChannelsToStockLocationWorkflow/index.html.md)
+- [createLocationFulfillmentSetWorkflow](https://docs.medusajs.com/references/medusa-workflows/createLocationFulfillmentSetWorkflow/index.html.md)
+- [deleteStockLocationsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteStockLocationsWorkflow/index.html.md)
+- [updateStockLocationsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateStockLocationsWorkflow/index.html.md)
+- [createTaxRateRulesWorkflow](https://docs.medusajs.com/references/medusa-workflows/createTaxRateRulesWorkflow/index.html.md)
+- [createTaxRatesWorkflow](https://docs.medusajs.com/references/medusa-workflows/createTaxRatesWorkflow/index.html.md)
+- [deleteTaxRateRulesWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteTaxRateRulesWorkflow/index.html.md)
+- [createTaxRegionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createTaxRegionsWorkflow/index.html.md)
+- [deleteTaxRatesWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteTaxRatesWorkflow/index.html.md)
+- [setTaxRateRulesWorkflow](https://docs.medusajs.com/references/medusa-workflows/setTaxRateRulesWorkflow/index.html.md)
+- [maybeListTaxRateRuleIdsStep](https://docs.medusajs.com/references/medusa-workflows/maybeListTaxRateRuleIdsStep/index.html.md)
+- [deleteTaxRegionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteTaxRegionsWorkflow/index.html.md)
+- [updateTaxRatesWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateTaxRatesWorkflow/index.html.md)
+- [updateTaxRegionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateTaxRegionsWorkflow/index.html.md)
- [createUserAccountWorkflow](https://docs.medusajs.com/references/medusa-workflows/createUserAccountWorkflow/index.html.md)
+- [createUsersWorkflow](https://docs.medusajs.com/references/medusa-workflows/createUsersWorkflow/index.html.md)
- [deleteUsersWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteUsersWorkflow/index.html.md)
- [removeUserAccountWorkflow](https://docs.medusajs.com/references/medusa-workflows/removeUserAccountWorkflow/index.html.md)
- [updateUsersWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateUsersWorkflow/index.html.md)
-- [createTaxRatesWorkflow](https://docs.medusajs.com/references/medusa-workflows/createTaxRatesWorkflow/index.html.md)
-- [createTaxRegionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createTaxRegionsWorkflow/index.html.md)
-- [createTaxRateRulesWorkflow](https://docs.medusajs.com/references/medusa-workflows/createTaxRateRulesWorkflow/index.html.md)
-- [deleteTaxRegionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteTaxRegionsWorkflow/index.html.md)
-- [deleteTaxRateRulesWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteTaxRateRulesWorkflow/index.html.md)
-- [maybeListTaxRateRuleIdsStep](https://docs.medusajs.com/references/medusa-workflows/maybeListTaxRateRuleIdsStep/index.html.md)
-- [deleteTaxRatesWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteTaxRatesWorkflow/index.html.md)
-- [updateTaxRatesWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateTaxRatesWorkflow/index.html.md)
-- [updateTaxRegionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateTaxRegionsWorkflow/index.html.md)
-- [setTaxRateRulesWorkflow](https://docs.medusajs.com/references/medusa-workflows/setTaxRateRulesWorkflow/index.html.md)
## Steps
-- [linkSalesChannelsToApiKeyStep](https://docs.medusajs.com/references/medusa-workflows/steps/linkSalesChannelsToApiKeyStep/index.html.md)
-- [revokeApiKeysStep](https://docs.medusajs.com/references/medusa-workflows/steps/revokeApiKeysStep/index.html.md)
-- [updateApiKeysStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateApiKeysStep/index.html.md)
-- [createApiKeysStep](https://docs.medusajs.com/references/medusa-workflows/steps/createApiKeysStep/index.html.md)
-- [validateSalesChannelsExistStep](https://docs.medusajs.com/references/medusa-workflows/steps/validateSalesChannelsExistStep/index.html.md)
-- [deleteApiKeysStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteApiKeysStep/index.html.md)
- [setAuthAppMetadataStep](https://docs.medusajs.com/references/medusa-workflows/steps/setAuthAppMetadataStep/index.html.md)
-- [createRemoteLinkStep](https://docs.medusajs.com/references/medusa-workflows/steps/createRemoteLinkStep/index.html.md)
-- [dismissRemoteLinkStep](https://docs.medusajs.com/references/medusa-workflows/steps/dismissRemoteLinkStep/index.html.md)
-- [emitEventStep](https://docs.medusajs.com/references/medusa-workflows/steps/emitEventStep/index.html.md)
-- [removeRemoteLinkStep](https://docs.medusajs.com/references/medusa-workflows/steps/removeRemoteLinkStep/index.html.md)
-- [updateRemoteLinksStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateRemoteLinksStep/index.html.md)
-- [useQueryGraphStep](https://docs.medusajs.com/references/medusa-workflows/steps/useQueryGraphStep/index.html.md)
-- [validatePresenceOfStep](https://docs.medusajs.com/references/medusa-workflows/steps/validatePresenceOfStep/index.html.md)
-- [useRemoteQueryStep](https://docs.medusajs.com/references/medusa-workflows/steps/useRemoteQueryStep/index.html.md)
-- [confirmInventoryStep](https://docs.medusajs.com/references/medusa-workflows/steps/confirmInventoryStep/index.html.md)
-- [createCartsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createCartsStep/index.html.md)
-- [createLineItemAdjustmentsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createLineItemAdjustmentsStep/index.html.md)
-- [addShippingMethodToCartStep](https://docs.medusajs.com/references/medusa-workflows/steps/addShippingMethodToCartStep/index.html.md)
-- [createPaymentCollectionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createPaymentCollectionsStep/index.html.md)
-- [createShippingMethodAdjustmentsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createShippingMethodAdjustmentsStep/index.html.md)
-- [createLineItemsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createLineItemsStep/index.html.md)
-- [findSalesChannelStep](https://docs.medusajs.com/references/medusa-workflows/steps/findSalesChannelStep/index.html.md)
-- [getActionsToComputeFromPromotionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/getActionsToComputeFromPromotionsStep/index.html.md)
-- [findOrCreateCustomerStep](https://docs.medusajs.com/references/medusa-workflows/steps/findOrCreateCustomerStep/index.html.md)
-- [findOneOrAnyRegionStep](https://docs.medusajs.com/references/medusa-workflows/steps/findOneOrAnyRegionStep/index.html.md)
-- [getLineItemActionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/getLineItemActionsStep/index.html.md)
-- [getPromotionCodesToApply](https://docs.medusajs.com/references/medusa-workflows/steps/getPromotionCodesToApply/index.html.md)
-- [prepareAdjustmentsFromPromotionActionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/prepareAdjustmentsFromPromotionActionsStep/index.html.md)
-- [removeLineItemAdjustmentsStep](https://docs.medusajs.com/references/medusa-workflows/steps/removeLineItemAdjustmentsStep/index.html.md)
-- [removeShippingMethodAdjustmentsStep](https://docs.medusajs.com/references/medusa-workflows/steps/removeShippingMethodAdjustmentsStep/index.html.md)
-- [getVariantsStep](https://docs.medusajs.com/references/medusa-workflows/steps/getVariantsStep/index.html.md)
-- [getVariantPriceSetsStep](https://docs.medusajs.com/references/medusa-workflows/steps/getVariantPriceSetsStep/index.html.md)
-- [removeShippingMethodFromCartStep](https://docs.medusajs.com/references/medusa-workflows/steps/removeShippingMethodFromCartStep/index.html.md)
-- [reserveInventoryStep](https://docs.medusajs.com/references/medusa-workflows/steps/reserveInventoryStep/index.html.md)
-- [setTaxLinesForItemsStep](https://docs.medusajs.com/references/medusa-workflows/steps/setTaxLinesForItemsStep/index.html.md)
-- [updateCartsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateCartsStep/index.html.md)
-- [updateLineItemsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateLineItemsStep/index.html.md)
-- [updateCartPromotionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateCartPromotionsStep/index.html.md)
-- [updateShippingMethodsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateShippingMethodsStep/index.html.md)
-- [validateAndReturnShippingMethodsDataStep](https://docs.medusajs.com/references/medusa-workflows/steps/validateAndReturnShippingMethodsDataStep/index.html.md)
-- [validateCartShippingOptionsPriceStep](https://docs.medusajs.com/references/medusa-workflows/steps/validateCartShippingOptionsPriceStep/index.html.md)
-- [validateCartPaymentsStep](https://docs.medusajs.com/references/medusa-workflows/steps/validateCartPaymentsStep/index.html.md)
-- [validateCartShippingOptionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/validateCartShippingOptionsStep/index.html.md)
-- [validateLineItemPricesStep](https://docs.medusajs.com/references/medusa-workflows/steps/validateLineItemPricesStep/index.html.md)
-- [retrieveCartStep](https://docs.medusajs.com/references/medusa-workflows/steps/retrieveCartStep/index.html.md)
-- [validateCartStep](https://docs.medusajs.com/references/medusa-workflows/steps/validateCartStep/index.html.md)
-- [validateShippingStep](https://docs.medusajs.com/references/medusa-workflows/steps/validateShippingStep/index.html.md)
-- [validateVariantPricesStep](https://docs.medusajs.com/references/medusa-workflows/steps/validateVariantPricesStep/index.html.md)
-- [createCustomersStep](https://docs.medusajs.com/references/medusa-workflows/steps/createCustomersStep/index.html.md)
-- [deleteCustomerAddressesStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteCustomerAddressesStep/index.html.md)
-- [maybeUnsetDefaultBillingAddressesStep](https://docs.medusajs.com/references/medusa-workflows/steps/maybeUnsetDefaultBillingAddressesStep/index.html.md)
+- [linkSalesChannelsToApiKeyStep](https://docs.medusajs.com/references/medusa-workflows/steps/linkSalesChannelsToApiKeyStep/index.html.md)
+- [deleteApiKeysStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteApiKeysStep/index.html.md)
+- [createApiKeysStep](https://docs.medusajs.com/references/medusa-workflows/steps/createApiKeysStep/index.html.md)
+- [revokeApiKeysStep](https://docs.medusajs.com/references/medusa-workflows/steps/revokeApiKeysStep/index.html.md)
+- [validateSalesChannelsExistStep](https://docs.medusajs.com/references/medusa-workflows/steps/validateSalesChannelsExistStep/index.html.md)
+- [updateApiKeysStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateApiKeysStep/index.html.md)
- [createCustomerAddressesStep](https://docs.medusajs.com/references/medusa-workflows/steps/createCustomerAddressesStep/index.html.md)
-- [maybeUnsetDefaultShippingAddressesStep](https://docs.medusajs.com/references/medusa-workflows/steps/maybeUnsetDefaultShippingAddressesStep/index.html.md)
+- [deleteCustomerAddressesStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteCustomerAddressesStep/index.html.md)
- [deleteCustomersStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteCustomersStep/index.html.md)
+- [createCustomersStep](https://docs.medusajs.com/references/medusa-workflows/steps/createCustomersStep/index.html.md)
+- [maybeUnsetDefaultBillingAddressesStep](https://docs.medusajs.com/references/medusa-workflows/steps/maybeUnsetDefaultBillingAddressesStep/index.html.md)
+- [maybeUnsetDefaultShippingAddressesStep](https://docs.medusajs.com/references/medusa-workflows/steps/maybeUnsetDefaultShippingAddressesStep/index.html.md)
- [updateCustomersStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateCustomersStep/index.html.md)
-- [validateCustomerAccountCreation](https://docs.medusajs.com/references/medusa-workflows/steps/validateCustomerAccountCreation/index.html.md)
- [updateCustomerAddressesStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateCustomerAddressesStep/index.html.md)
-- [createCustomerGroupsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createCustomerGroupsStep/index.html.md)
-- [linkCustomerGroupsToCustomerStep](https://docs.medusajs.com/references/medusa-workflows/steps/linkCustomerGroupsToCustomerStep/index.html.md)
-- [deleteCustomerGroupStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteCustomerGroupStep/index.html.md)
-- [updateCustomerGroupsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateCustomerGroupsStep/index.html.md)
-- [linkCustomersToCustomerGroupStep](https://docs.medusajs.com/references/medusa-workflows/steps/linkCustomersToCustomerGroupStep/index.html.md)
+- [validateCustomerAccountCreation](https://docs.medusajs.com/references/medusa-workflows/steps/validateCustomerAccountCreation/index.html.md)
+- [dismissRemoteLinkStep](https://docs.medusajs.com/references/medusa-workflows/steps/dismissRemoteLinkStep/index.html.md)
+- [createRemoteLinkStep](https://docs.medusajs.com/references/medusa-workflows/steps/createRemoteLinkStep/index.html.md)
+- [emitEventStep](https://docs.medusajs.com/references/medusa-workflows/steps/emitEventStep/index.html.md)
+- [updateRemoteLinksStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateRemoteLinksStep/index.html.md)
+- [removeRemoteLinkStep](https://docs.medusajs.com/references/medusa-workflows/steps/removeRemoteLinkStep/index.html.md)
+- [useQueryGraphStep](https://docs.medusajs.com/references/medusa-workflows/steps/useQueryGraphStep/index.html.md)
+- [useRemoteQueryStep](https://docs.medusajs.com/references/medusa-workflows/steps/useRemoteQueryStep/index.html.md)
+- [validatePresenceOfStep](https://docs.medusajs.com/references/medusa-workflows/steps/validatePresenceOfStep/index.html.md)
- [createDefaultStoreStep](https://docs.medusajs.com/references/medusa-workflows/steps/createDefaultStoreStep/index.html.md)
- [validateDraftOrderStep](https://docs.medusajs.com/references/medusa-workflows/steps/validateDraftOrderStep/index.html.md)
-- [deleteFilesStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteFilesStep/index.html.md)
-- [uploadFilesStep](https://docs.medusajs.com/references/medusa-workflows/steps/uploadFilesStep/index.html.md)
- [buildPriceSet](https://docs.medusajs.com/references/medusa-workflows/steps/buildPriceSet/index.html.md)
- [calculateShippingOptionsPricesStep](https://docs.medusajs.com/references/medusa-workflows/steps/calculateShippingOptionsPricesStep/index.html.md)
- [cancelFulfillmentStep](https://docs.medusajs.com/references/medusa-workflows/steps/cancelFulfillmentStep/index.html.md)
-- [createFulfillmentStep](https://docs.medusajs.com/references/medusa-workflows/steps/createFulfillmentStep/index.html.md)
- [createFulfillmentSets](https://docs.medusajs.com/references/medusa-workflows/steps/createFulfillmentSets/index.html.md)
-- [createServiceZonesStep](https://docs.medusajs.com/references/medusa-workflows/steps/createServiceZonesStep/index.html.md)
-- [createShippingOptionsPriceSetsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createShippingOptionsPriceSetsStep/index.html.md)
+- [createFulfillmentStep](https://docs.medusajs.com/references/medusa-workflows/steps/createFulfillmentStep/index.html.md)
- [createReturnFulfillmentStep](https://docs.medusajs.com/references/medusa-workflows/steps/createReturnFulfillmentStep/index.html.md)
+- [createShippingOptionsPriceSetsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createShippingOptionsPriceSetsStep/index.html.md)
+- [createServiceZonesStep](https://docs.medusajs.com/references/medusa-workflows/steps/createServiceZonesStep/index.html.md)
- [createShippingProfilesStep](https://docs.medusajs.com/references/medusa-workflows/steps/createShippingProfilesStep/index.html.md)
-- [createShippingOptionRulesStep](https://docs.medusajs.com/references/medusa-workflows/steps/createShippingOptionRulesStep/index.html.md)
- [deleteFulfillmentSetsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteFulfillmentSetsStep/index.html.md)
-- [deleteShippingOptionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteShippingOptionsStep/index.html.md)
-- [setShippingOptionsPricesStep](https://docs.medusajs.com/references/medusa-workflows/steps/setShippingOptionsPricesStep/index.html.md)
-- [deleteShippingOptionRulesStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteShippingOptionRulesStep/index.html.md)
-- [updateFulfillmentStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateFulfillmentStep/index.html.md)
-- [updateServiceZonesStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateServiceZonesStep/index.html.md)
-- [updateShippingProfilesStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateShippingProfilesStep/index.html.md)
+- [createShippingOptionRulesStep](https://docs.medusajs.com/references/medusa-workflows/steps/createShippingOptionRulesStep/index.html.md)
- [deleteServiceZonesStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteServiceZonesStep/index.html.md)
-- [upsertShippingOptionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/upsertShippingOptionsStep/index.html.md)
-- [validateShipmentStep](https://docs.medusajs.com/references/medusa-workflows/steps/validateShipmentStep/index.html.md)
+- [updateFulfillmentStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateFulfillmentStep/index.html.md)
+- [setShippingOptionsPricesStep](https://docs.medusajs.com/references/medusa-workflows/steps/setShippingOptionsPricesStep/index.html.md)
+- [deleteShippingOptionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteShippingOptionsStep/index.html.md)
+- [deleteShippingOptionRulesStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteShippingOptionRulesStep/index.html.md)
+- [updateServiceZonesStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateServiceZonesStep/index.html.md)
- [updateShippingOptionRulesStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateShippingOptionRulesStep/index.html.md)
+- [upsertShippingOptionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/upsertShippingOptionsStep/index.html.md)
+- [updateShippingProfilesStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateShippingProfilesStep/index.html.md)
- [validateShippingOptionPricesStep](https://docs.medusajs.com/references/medusa-workflows/steps/validateShippingOptionPricesStep/index.html.md)
-- [adjustInventoryLevelsStep](https://docs.medusajs.com/references/medusa-workflows/steps/adjustInventoryLevelsStep/index.html.md)
+- [validateShipmentStep](https://docs.medusajs.com/references/medusa-workflows/steps/validateShipmentStep/index.html.md)
+- [addShippingMethodToCartStep](https://docs.medusajs.com/references/medusa-workflows/steps/addShippingMethodToCartStep/index.html.md)
+- [confirmInventoryStep](https://docs.medusajs.com/references/medusa-workflows/steps/confirmInventoryStep/index.html.md)
+- [createLineItemAdjustmentsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createLineItemAdjustmentsStep/index.html.md)
+- [createCartsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createCartsStep/index.html.md)
+- [createLineItemsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createLineItemsStep/index.html.md)
+- [createPaymentCollectionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createPaymentCollectionsStep/index.html.md)
+- [findOneOrAnyRegionStep](https://docs.medusajs.com/references/medusa-workflows/steps/findOneOrAnyRegionStep/index.html.md)
+- [createShippingMethodAdjustmentsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createShippingMethodAdjustmentsStep/index.html.md)
+- [findOrCreateCustomerStep](https://docs.medusajs.com/references/medusa-workflows/steps/findOrCreateCustomerStep/index.html.md)
+- [findSalesChannelStep](https://docs.medusajs.com/references/medusa-workflows/steps/findSalesChannelStep/index.html.md)
+- [getLineItemActionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/getLineItemActionsStep/index.html.md)
+- [getPromotionCodesToApply](https://docs.medusajs.com/references/medusa-workflows/steps/getPromotionCodesToApply/index.html.md)
+- [getActionsToComputeFromPromotionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/getActionsToComputeFromPromotionsStep/index.html.md)
+- [getVariantPriceSetsStep](https://docs.medusajs.com/references/medusa-workflows/steps/getVariantPriceSetsStep/index.html.md)
+- [prepareAdjustmentsFromPromotionActionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/prepareAdjustmentsFromPromotionActionsStep/index.html.md)
+- [removeLineItemAdjustmentsStep](https://docs.medusajs.com/references/medusa-workflows/steps/removeLineItemAdjustmentsStep/index.html.md)
+- [getVariantsStep](https://docs.medusajs.com/references/medusa-workflows/steps/getVariantsStep/index.html.md)
+- [removeShippingMethodAdjustmentsStep](https://docs.medusajs.com/references/medusa-workflows/steps/removeShippingMethodAdjustmentsStep/index.html.md)
+- [reserveInventoryStep](https://docs.medusajs.com/references/medusa-workflows/steps/reserveInventoryStep/index.html.md)
+- [removeShippingMethodFromCartStep](https://docs.medusajs.com/references/medusa-workflows/steps/removeShippingMethodFromCartStep/index.html.md)
+- [retrieveCartStep](https://docs.medusajs.com/references/medusa-workflows/steps/retrieveCartStep/index.html.md)
+- [setTaxLinesForItemsStep](https://docs.medusajs.com/references/medusa-workflows/steps/setTaxLinesForItemsStep/index.html.md)
+- [updateCartsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateCartsStep/index.html.md)
+- [updateCartPromotionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateCartPromotionsStep/index.html.md)
+- [updateLineItemsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateLineItemsStep/index.html.md)
+- [updateShippingMethodsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateShippingMethodsStep/index.html.md)
+- [validateAndReturnShippingMethodsDataStep](https://docs.medusajs.com/references/medusa-workflows/steps/validateAndReturnShippingMethodsDataStep/index.html.md)
+- [validateCartPaymentsStep](https://docs.medusajs.com/references/medusa-workflows/steps/validateCartPaymentsStep/index.html.md)
+- [validateCartShippingOptionsPriceStep](https://docs.medusajs.com/references/medusa-workflows/steps/validateCartShippingOptionsPriceStep/index.html.md)
+- [validateLineItemPricesStep](https://docs.medusajs.com/references/medusa-workflows/steps/validateLineItemPricesStep/index.html.md)
+- [validateCartShippingOptionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/validateCartShippingOptionsStep/index.html.md)
+- [validateVariantPricesStep](https://docs.medusajs.com/references/medusa-workflows/steps/validateVariantPricesStep/index.html.md)
+- [validateCartStep](https://docs.medusajs.com/references/medusa-workflows/steps/validateCartStep/index.html.md)
+- [validateShippingStep](https://docs.medusajs.com/references/medusa-workflows/steps/validateShippingStep/index.html.md)
+- [createCustomerGroupsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createCustomerGroupsStep/index.html.md)
+- [deleteCustomerGroupStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteCustomerGroupStep/index.html.md)
+- [linkCustomersToCustomerGroupStep](https://docs.medusajs.com/references/medusa-workflows/steps/linkCustomersToCustomerGroupStep/index.html.md)
+- [updateCustomerGroupsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateCustomerGroupsStep/index.html.md)
+- [linkCustomerGroupsToCustomerStep](https://docs.medusajs.com/references/medusa-workflows/steps/linkCustomerGroupsToCustomerStep/index.html.md)
+- [deleteFilesStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteFilesStep/index.html.md)
+- [uploadFilesStep](https://docs.medusajs.com/references/medusa-workflows/steps/uploadFilesStep/index.html.md)
- [attachInventoryItemToVariants](https://docs.medusajs.com/references/medusa-workflows/steps/attachInventoryItemToVariants/index.html.md)
-- [deleteInventoryItemStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteInventoryItemStep/index.html.md)
+- [adjustInventoryLevelsStep](https://docs.medusajs.com/references/medusa-workflows/steps/adjustInventoryLevelsStep/index.html.md)
- [createInventoryItemsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createInventoryItemsStep/index.html.md)
-- [deleteInventoryLevelsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteInventoryLevelsStep/index.html.md)
- [createInventoryLevelsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createInventoryLevelsStep/index.html.md)
+- [deleteInventoryItemStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteInventoryItemStep/index.html.md)
+- [deleteInventoryLevelsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteInventoryLevelsStep/index.html.md)
- [updateInventoryItemsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateInventoryItemsStep/index.html.md)
-- [validateInventoryDeleteStep](https://docs.medusajs.com/references/medusa-workflows/steps/validateInventoryDeleteStep/index.html.md)
- [updateInventoryLevelsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateInventoryLevelsStep/index.html.md)
-- [validateInventoryLocationsStep](https://docs.medusajs.com/references/medusa-workflows/steps/validateInventoryLocationsStep/index.html.md)
+- [validateInventoryDeleteStep](https://docs.medusajs.com/references/medusa-workflows/steps/validateInventoryDeleteStep/index.html.md)
- [validateInventoryItemsForCreate](https://docs.medusajs.com/references/medusa-workflows/steps/validateInventoryItemsForCreate/index.html.md)
-- [deleteInvitesStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteInvitesStep/index.html.md)
+- [validateInventoryLocationsStep](https://docs.medusajs.com/references/medusa-workflows/steps/validateInventoryLocationsStep/index.html.md)
- [createInviteStep](https://docs.medusajs.com/references/medusa-workflows/steps/createInviteStep/index.html.md)
-- [refreshInviteTokensStep](https://docs.medusajs.com/references/medusa-workflows/steps/refreshInviteTokensStep/index.html.md)
+- [deleteInvitesStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteInvitesStep/index.html.md)
- [validateTokenStep](https://docs.medusajs.com/references/medusa-workflows/steps/validateTokenStep/index.html.md)
+- [refreshInviteTokensStep](https://docs.medusajs.com/references/medusa-workflows/steps/refreshInviteTokensStep/index.html.md)
- [deleteLineItemsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteLineItemsStep/index.html.md)
- [listLineItemsStep](https://docs.medusajs.com/references/medusa-workflows/steps/listLineItemsStep/index.html.md)
- [updateLineItemsStepWithSelector](https://docs.medusajs.com/references/medusa-workflows/steps/updateLineItemsStepWithSelector/index.html.md)
+- [sendNotificationsStep](https://docs.medusajs.com/references/medusa-workflows/steps/sendNotificationsStep/index.html.md)
+- [notifyOnFailureStep](https://docs.medusajs.com/references/medusa-workflows/steps/notifyOnFailureStep/index.html.md)
+- [addOrderTransactionStep](https://docs.medusajs.com/references/medusa-workflows/steps/addOrderTransactionStep/index.html.md)
+- [cancelOrderChangeStep](https://docs.medusajs.com/references/medusa-workflows/steps/cancelOrderChangeStep/index.html.md)
+- [archiveOrdersStep](https://docs.medusajs.com/references/medusa-workflows/steps/archiveOrdersStep/index.html.md)
+- [cancelOrderExchangeStep](https://docs.medusajs.com/references/medusa-workflows/steps/cancelOrderExchangeStep/index.html.md)
+- [cancelOrderClaimStep](https://docs.medusajs.com/references/medusa-workflows/steps/cancelOrderClaimStep/index.html.md)
+- [cancelOrderFulfillmentStep](https://docs.medusajs.com/references/medusa-workflows/steps/cancelOrderFulfillmentStep/index.html.md)
+- [cancelOrderReturnStep](https://docs.medusajs.com/references/medusa-workflows/steps/cancelOrderReturnStep/index.html.md)
+- [cancelOrdersStep](https://docs.medusajs.com/references/medusa-workflows/steps/cancelOrdersStep/index.html.md)
+- [completeOrdersStep](https://docs.medusajs.com/references/medusa-workflows/steps/completeOrdersStep/index.html.md)
+- [createOrderClaimItemsFromActionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createOrderClaimItemsFromActionsStep/index.html.md)
+- [createOrderChangeStep](https://docs.medusajs.com/references/medusa-workflows/steps/createOrderChangeStep/index.html.md)
+- [createCompleteReturnStep](https://docs.medusajs.com/references/medusa-workflows/steps/createCompleteReturnStep/index.html.md)
+- [createOrderClaimsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createOrderClaimsStep/index.html.md)
+- [createOrderLineItemsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createOrderLineItemsStep/index.html.md)
+- [createOrderExchangeItemsFromActionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createOrderExchangeItemsFromActionsStep/index.html.md)
+- [createOrderExchangesStep](https://docs.medusajs.com/references/medusa-workflows/steps/createOrderExchangesStep/index.html.md)
+- [createOrdersStep](https://docs.medusajs.com/references/medusa-workflows/steps/createOrdersStep/index.html.md)
+- [declineOrderChangeStep](https://docs.medusajs.com/references/medusa-workflows/steps/declineOrderChangeStep/index.html.md)
+- [deleteClaimsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteClaimsStep/index.html.md)
+- [createReturnsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createReturnsStep/index.html.md)
+- [deleteExchangesStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteExchangesStep/index.html.md)
+- [deleteOrderChangeActionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteOrderChangeActionsStep/index.html.md)
+- [deleteOrderShippingMethods](https://docs.medusajs.com/references/medusa-workflows/steps/deleteOrderShippingMethods/index.html.md)
+- [deleteOrderLineItems](https://docs.medusajs.com/references/medusa-workflows/steps/deleteOrderLineItems/index.html.md)
+- [deleteOrderChangesStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteOrderChangesStep/index.html.md)
+- [previewOrderChangeStep](https://docs.medusajs.com/references/medusa-workflows/steps/previewOrderChangeStep/index.html.md)
+- [registerOrderChangesStep](https://docs.medusajs.com/references/medusa-workflows/steps/registerOrderChangesStep/index.html.md)
+- [registerOrderDeliveryStep](https://docs.medusajs.com/references/medusa-workflows/steps/registerOrderDeliveryStep/index.html.md)
+- [deleteReturnsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteReturnsStep/index.html.md)
+- [registerOrderFulfillmentStep](https://docs.medusajs.com/references/medusa-workflows/steps/registerOrderFulfillmentStep/index.html.md)
+- [registerOrderShipmentStep](https://docs.medusajs.com/references/medusa-workflows/steps/registerOrderShipmentStep/index.html.md)
+- [setOrderTaxLinesForItemsStep](https://docs.medusajs.com/references/medusa-workflows/steps/setOrderTaxLinesForItemsStep/index.html.md)
+- [updateOrderChangeActionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateOrderChangeActionsStep/index.html.md)
+- [updateOrdersStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateOrdersStep/index.html.md)
+- [updateOrderChangesStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateOrderChangesStep/index.html.md)
+- [updateOrderShippingMethodsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateOrderShippingMethodsStep/index.html.md)
+- [updateReturnItemsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateReturnItemsStep/index.html.md)
+- [updateReturnsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateReturnsStep/index.html.md)
- [authorizePaymentSessionStep](https://docs.medusajs.com/references/medusa-workflows/steps/authorizePaymentSessionStep/index.html.md)
- [cancelPaymentStep](https://docs.medusajs.com/references/medusa-workflows/steps/cancelPaymentStep/index.html.md)
- [capturePaymentStep](https://docs.medusajs.com/references/medusa-workflows/steps/capturePaymentStep/index.html.md)
-- [refundPaymentStep](https://docs.medusajs.com/references/medusa-workflows/steps/refundPaymentStep/index.html.md)
-- [notifyOnFailureStep](https://docs.medusajs.com/references/medusa-workflows/steps/notifyOnFailureStep/index.html.md)
-- [sendNotificationsStep](https://docs.medusajs.com/references/medusa-workflows/steps/sendNotificationsStep/index.html.md)
- [refundPaymentsStep](https://docs.medusajs.com/references/medusa-workflows/steps/refundPaymentsStep/index.html.md)
-- [archiveOrdersStep](https://docs.medusajs.com/references/medusa-workflows/steps/archiveOrdersStep/index.html.md)
-- [addOrderTransactionStep](https://docs.medusajs.com/references/medusa-workflows/steps/addOrderTransactionStep/index.html.md)
-- [cancelOrderChangeStep](https://docs.medusajs.com/references/medusa-workflows/steps/cancelOrderChangeStep/index.html.md)
-- [cancelOrderClaimStep](https://docs.medusajs.com/references/medusa-workflows/steps/cancelOrderClaimStep/index.html.md)
-- [cancelOrderExchangeStep](https://docs.medusajs.com/references/medusa-workflows/steps/cancelOrderExchangeStep/index.html.md)
-- [cancelOrdersStep](https://docs.medusajs.com/references/medusa-workflows/steps/cancelOrdersStep/index.html.md)
-- [completeOrdersStep](https://docs.medusajs.com/references/medusa-workflows/steps/completeOrdersStep/index.html.md)
-- [cancelOrderReturnStep](https://docs.medusajs.com/references/medusa-workflows/steps/cancelOrderReturnStep/index.html.md)
-- [createCompleteReturnStep](https://docs.medusajs.com/references/medusa-workflows/steps/createCompleteReturnStep/index.html.md)
-- [createOrderChangeStep](https://docs.medusajs.com/references/medusa-workflows/steps/createOrderChangeStep/index.html.md)
-- [createOrderExchangeItemsFromActionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createOrderExchangeItemsFromActionsStep/index.html.md)
-- [createOrderClaimsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createOrderClaimsStep/index.html.md)
-- [createOrderExchangesStep](https://docs.medusajs.com/references/medusa-workflows/steps/createOrderExchangesStep/index.html.md)
-- [createOrderLineItemsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createOrderLineItemsStep/index.html.md)
-- [cancelOrderFulfillmentStep](https://docs.medusajs.com/references/medusa-workflows/steps/cancelOrderFulfillmentStep/index.html.md)
-- [createOrdersStep](https://docs.medusajs.com/references/medusa-workflows/steps/createOrdersStep/index.html.md)
-- [createReturnsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createReturnsStep/index.html.md)
-- [deleteClaimsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteClaimsStep/index.html.md)
-- [createOrderClaimItemsFromActionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createOrderClaimItemsFromActionsStep/index.html.md)
-- [deleteOrderChangeActionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteOrderChangeActionsStep/index.html.md)
-- [deleteExchangesStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteExchangesStep/index.html.md)
-- [declineOrderChangeStep](https://docs.medusajs.com/references/medusa-workflows/steps/declineOrderChangeStep/index.html.md)
-- [deleteOrderLineItems](https://docs.medusajs.com/references/medusa-workflows/steps/deleteOrderLineItems/index.html.md)
-- [deleteOrderShippingMethods](https://docs.medusajs.com/references/medusa-workflows/steps/deleteOrderShippingMethods/index.html.md)
-- [deleteReturnsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteReturnsStep/index.html.md)
-- [previewOrderChangeStep](https://docs.medusajs.com/references/medusa-workflows/steps/previewOrderChangeStep/index.html.md)
-- [deleteOrderChangesStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteOrderChangesStep/index.html.md)
-- [registerOrderChangesStep](https://docs.medusajs.com/references/medusa-workflows/steps/registerOrderChangesStep/index.html.md)
-- [registerOrderFulfillmentStep](https://docs.medusajs.com/references/medusa-workflows/steps/registerOrderFulfillmentStep/index.html.md)
-- [registerOrderDeliveryStep](https://docs.medusajs.com/references/medusa-workflows/steps/registerOrderDeliveryStep/index.html.md)
-- [updateOrderChangeActionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateOrderChangeActionsStep/index.html.md)
-- [registerOrderShipmentStep](https://docs.medusajs.com/references/medusa-workflows/steps/registerOrderShipmentStep/index.html.md)
-- [setOrderTaxLinesForItemsStep](https://docs.medusajs.com/references/medusa-workflows/steps/setOrderTaxLinesForItemsStep/index.html.md)
-- [updateOrderChangesStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateOrderChangesStep/index.html.md)
-- [updateOrderShippingMethodsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateOrderShippingMethodsStep/index.html.md)
-- [updateOrdersStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateOrdersStep/index.html.md)
-- [updateReturnItemsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateReturnItemsStep/index.html.md)
+- [refundPaymentStep](https://docs.medusajs.com/references/medusa-workflows/steps/refundPaymentStep/index.html.md)
+- [createPriceListPricesStep](https://docs.medusajs.com/references/medusa-workflows/steps/createPriceListPricesStep/index.html.md)
+- [createPriceListsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createPriceListsStep/index.html.md)
+- [deletePriceListsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deletePriceListsStep/index.html.md)
+- [getExistingPriceListsPriceIdsStep](https://docs.medusajs.com/references/medusa-workflows/steps/getExistingPriceListsPriceIdsStep/index.html.md)
+- [removePriceListPricesStep](https://docs.medusajs.com/references/medusa-workflows/steps/removePriceListPricesStep/index.html.md)
+- [validateVariantPriceLinksStep](https://docs.medusajs.com/references/medusa-workflows/steps/validateVariantPriceLinksStep/index.html.md)
+- [validatePriceListsStep](https://docs.medusajs.com/references/medusa-workflows/steps/validatePriceListsStep/index.html.md)
+- [updatePriceListPricesStep](https://docs.medusajs.com/references/medusa-workflows/steps/updatePriceListPricesStep/index.html.md)
+- [updatePriceListsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updatePriceListsStep/index.html.md)
- [createPaymentAccountHolderStep](https://docs.medusajs.com/references/medusa-workflows/steps/createPaymentAccountHolderStep/index.html.md)
- [createPaymentSessionStep](https://docs.medusajs.com/references/medusa-workflows/steps/createPaymentSessionStep/index.html.md)
- [createRefundReasonStep](https://docs.medusajs.com/references/medusa-workflows/steps/createRefundReasonStep/index.html.md)
-- [deleteRefundReasonsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteRefundReasonsStep/index.html.md)
- [deletePaymentSessionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deletePaymentSessionsStep/index.html.md)
+- [deleteRefundReasonsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteRefundReasonsStep/index.html.md)
- [updatePaymentCollectionStep](https://docs.medusajs.com/references/medusa-workflows/steps/updatePaymentCollectionStep/index.html.md)
- [updateRefundReasonsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateRefundReasonsStep/index.html.md)
- [validateDeletedPaymentSessionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/validateDeletedPaymentSessionsStep/index.html.md)
-- [updateReturnsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateReturnsStep/index.html.md)
-- [createPriceListPricesStep](https://docs.medusajs.com/references/medusa-workflows/steps/createPriceListPricesStep/index.html.md)
-- [deletePriceListsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deletePriceListsStep/index.html.md)
-- [getExistingPriceListsPriceIdsStep](https://docs.medusajs.com/references/medusa-workflows/steps/getExistingPriceListsPriceIdsStep/index.html.md)
-- [createPriceListsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createPriceListsStep/index.html.md)
-- [updatePriceListPricesStep](https://docs.medusajs.com/references/medusa-workflows/steps/updatePriceListPricesStep/index.html.md)
-- [updatePriceListsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updatePriceListsStep/index.html.md)
-- [validatePriceListsStep](https://docs.medusajs.com/references/medusa-workflows/steps/validatePriceListsStep/index.html.md)
-- [validateVariantPriceLinksStep](https://docs.medusajs.com/references/medusa-workflows/steps/validateVariantPriceLinksStep/index.html.md)
-- [removePriceListPricesStep](https://docs.medusajs.com/references/medusa-workflows/steps/removePriceListPricesStep/index.html.md)
+- [createProductCategoriesStep](https://docs.medusajs.com/references/medusa-workflows/steps/createProductCategoriesStep/index.html.md)
+- [deleteProductCategoriesStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteProductCategoriesStep/index.html.md)
+- [updateProductCategoriesStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateProductCategoriesStep/index.html.md)
- [batchLinkProductsToCollectionStep](https://docs.medusajs.com/references/medusa-workflows/steps/batchLinkProductsToCollectionStep/index.html.md)
-- [batchLinkProductsToCategoryStep](https://docs.medusajs.com/references/medusa-workflows/steps/batchLinkProductsToCategoryStep/index.html.md)
-- [createProductTagsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createProductTagsStep/index.html.md)
+- [createCollectionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createCollectionsStep/index.html.md)
- [createProductOptionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createProductOptionsStep/index.html.md)
+- [createProductTagsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createProductTagsStep/index.html.md)
- [createProductTypesStep](https://docs.medusajs.com/references/medusa-workflows/steps/createProductTypesStep/index.html.md)
- [createProductVariantsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createProductVariantsStep/index.html.md)
-- [createProductsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createProductsStep/index.html.md)
+- [batchLinkProductsToCategoryStep](https://docs.medusajs.com/references/medusa-workflows/steps/batchLinkProductsToCategoryStep/index.html.md)
- [createVariantPricingLinkStep](https://docs.medusajs.com/references/medusa-workflows/steps/createVariantPricingLinkStep/index.html.md)
+- [createProductsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createProductsStep/index.html.md)
- [deleteCollectionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteCollectionsStep/index.html.md)
- [deleteProductOptionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteProductOptionsStep/index.html.md)
-- [deleteProductTypesStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteProductTypesStep/index.html.md)
- [deleteProductVariantsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteProductVariantsStep/index.html.md)
- [deleteProductTagsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteProductTagsStep/index.html.md)
-- [deleteProductsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteProductsStep/index.html.md)
-- [createCollectionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createCollectionsStep/index.html.md)
- [generateProductCsvStep](https://docs.medusajs.com/references/medusa-workflows/steps/generateProductCsvStep/index.html.md)
+- [deleteProductTypesStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteProductTypesStep/index.html.md)
+- [deleteProductsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteProductsStep/index.html.md)
+- [getVariantAvailabilityStep](https://docs.medusajs.com/references/medusa-workflows/steps/getVariantAvailabilityStep/index.html.md)
- [getAllProductsStep](https://docs.medusajs.com/references/medusa-workflows/steps/getAllProductsStep/index.html.md)
- [getProductsStep](https://docs.medusajs.com/references/medusa-workflows/steps/getProductsStep/index.html.md)
- [groupProductsForBatchStep](https://docs.medusajs.com/references/medusa-workflows/steps/groupProductsForBatchStep/index.html.md)
- [parseProductCsvStep](https://docs.medusajs.com/references/medusa-workflows/steps/parseProductCsvStep/index.html.md)
-- [updateCollectionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateCollectionsStep/index.html.md)
-- [updateProductTagsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateProductTagsStep/index.html.md)
- [updateProductOptionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateProductOptionsStep/index.html.md)
+- [updateProductTagsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateProductTagsStep/index.html.md)
+- [updateCollectionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateCollectionsStep/index.html.md)
- [updateProductTypesStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateProductTypesStep/index.html.md)
- [updateProductVariantsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateProductVariantsStep/index.html.md)
-- [getVariantAvailabilityStep](https://docs.medusajs.com/references/medusa-workflows/steps/getVariantAvailabilityStep/index.html.md)
-- [updateProductsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateProductsStep/index.html.md)
- [waitConfirmationProductImportStep](https://docs.medusajs.com/references/medusa-workflows/steps/waitConfirmationProductImportStep/index.html.md)
-- [createPricePreferencesStep](https://docs.medusajs.com/references/medusa-workflows/steps/createPricePreferencesStep/index.html.md)
-- [createPriceSetsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createPriceSetsStep/index.html.md)
-- [updatePricePreferencesAsArrayStep](https://docs.medusajs.com/references/medusa-workflows/steps/updatePricePreferencesAsArrayStep/index.html.md)
-- [updatePricePreferencesStep](https://docs.medusajs.com/references/medusa-workflows/steps/updatePricePreferencesStep/index.html.md)
-- [deletePricePreferencesStep](https://docs.medusajs.com/references/medusa-workflows/steps/deletePricePreferencesStep/index.html.md)
-- [updatePriceSetsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updatePriceSetsStep/index.html.md)
-- [createProductCategoriesStep](https://docs.medusajs.com/references/medusa-workflows/steps/createProductCategoriesStep/index.html.md)
-- [updateProductCategoriesStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateProductCategoriesStep/index.html.md)
-- [deleteProductCategoriesStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteProductCategoriesStep/index.html.md)
-- [addCampaignPromotionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/addCampaignPromotionsStep/index.html.md)
-- [addRulesToPromotionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/addRulesToPromotionsStep/index.html.md)
-- [createCampaignsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createCampaignsStep/index.html.md)
-- [createPromotionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createPromotionsStep/index.html.md)
-- [deletePromotionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deletePromotionsStep/index.html.md)
-- [removeRulesFromPromotionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/removeRulesFromPromotionsStep/index.html.md)
-- [deleteCampaignsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteCampaignsStep/index.html.md)
-- [updateCampaignsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateCampaignsStep/index.html.md)
-- [updatePromotionRulesStep](https://docs.medusajs.com/references/medusa-workflows/steps/updatePromotionRulesStep/index.html.md)
-- [removeCampaignPromotionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/removeCampaignPromotionsStep/index.html.md)
-- [updatePromotionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updatePromotionsStep/index.html.md)
+- [updateProductsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateProductsStep/index.html.md)
- [createReservationsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createReservationsStep/index.html.md)
- [deleteReservationsByLineItemsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteReservationsByLineItemsStep/index.html.md)
-- [updateReservationsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateReservationsStep/index.html.md)
- [deleteReservationsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteReservationsStep/index.html.md)
+- [updateReservationsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateReservationsStep/index.html.md)
+- [addCampaignPromotionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/addCampaignPromotionsStep/index.html.md)
+- [addRulesToPromotionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/addRulesToPromotionsStep/index.html.md)
+- [createPromotionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createPromotionsStep/index.html.md)
+- [deleteCampaignsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteCampaignsStep/index.html.md)
+- [removeCampaignPromotionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/removeCampaignPromotionsStep/index.html.md)
+- [deletePromotionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deletePromotionsStep/index.html.md)
+- [createCampaignsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createCampaignsStep/index.html.md)
+- [removeRulesFromPromotionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/removeRulesFromPromotionsStep/index.html.md)
+- [updateCampaignsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateCampaignsStep/index.html.md)
+- [updatePromotionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updatePromotionsStep/index.html.md)
+- [updatePromotionRulesStep](https://docs.medusajs.com/references/medusa-workflows/steps/updatePromotionRulesStep/index.html.md)
+- [deleteReturnReasonStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteReturnReasonStep/index.html.md)
+- [updateReturnReasonsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateReturnReasonsStep/index.html.md)
+- [createReturnReasonsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createReturnReasonsStep/index.html.md)
- [createRegionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createRegionsStep/index.html.md)
- [deleteRegionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteRegionsStep/index.html.md)
- [setRegionsPaymentProvidersStep](https://docs.medusajs.com/references/medusa-workflows/steps/setRegionsPaymentProvidersStep/index.html.md)
- [updateRegionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateRegionsStep/index.html.md)
-- [createReturnReasonsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createReturnReasonsStep/index.html.md)
-- [deleteReturnReasonStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteReturnReasonStep/index.html.md)
-- [updateReturnReasonsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateReturnReasonsStep/index.html.md)
- [listShippingOptionsForContextStep](https://docs.medusajs.com/references/medusa-workflows/steps/listShippingOptionsForContextStep/index.html.md)
-- [deleteShippingProfilesStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteShippingProfilesStep/index.html.md)
-- [createStoresStep](https://docs.medusajs.com/references/medusa-workflows/steps/createStoresStep/index.html.md)
-- [deleteStoresStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteStoresStep/index.html.md)
-- [updateStoresStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateStoresStep/index.html.md)
-- [deleteUsersStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteUsersStep/index.html.md)
-- [createUsersStep](https://docs.medusajs.com/references/medusa-workflows/steps/createUsersStep/index.html.md)
-- [updateUsersStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateUsersStep/index.html.md)
-- [createTaxRateRulesStep](https://docs.medusajs.com/references/medusa-workflows/steps/createTaxRateRulesStep/index.html.md)
-- [createTaxRatesStep](https://docs.medusajs.com/references/medusa-workflows/steps/createTaxRatesStep/index.html.md)
-- [deleteTaxRateRulesStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteTaxRateRulesStep/index.html.md)
-- [createTaxRegionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createTaxRegionsStep/index.html.md)
-- [deleteTaxRatesStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteTaxRatesStep/index.html.md)
-- [getItemTaxLinesStep](https://docs.medusajs.com/references/medusa-workflows/steps/getItemTaxLinesStep/index.html.md)
-- [deleteTaxRegionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteTaxRegionsStep/index.html.md)
-- [listTaxRateRuleIdsStep](https://docs.medusajs.com/references/medusa-workflows/steps/listTaxRateRuleIdsStep/index.html.md)
-- [listTaxRateIdsStep](https://docs.medusajs.com/references/medusa-workflows/steps/listTaxRateIdsStep/index.html.md)
-- [updateTaxRegionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateTaxRegionsStep/index.html.md)
-- [updateTaxRatesStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateTaxRatesStep/index.html.md)
- [associateLocationsWithSalesChannelsStep](https://docs.medusajs.com/references/medusa-workflows/steps/associateLocationsWithSalesChannelsStep/index.html.md)
- [associateProductsWithSalesChannelsStep](https://docs.medusajs.com/references/medusa-workflows/steps/associateProductsWithSalesChannelsStep/index.html.md)
-- [createDefaultSalesChannelStep](https://docs.medusajs.com/references/medusa-workflows/steps/createDefaultSalesChannelStep/index.html.md)
- [canDeleteSalesChannelsOrThrowStep](https://docs.medusajs.com/references/medusa-workflows/steps/canDeleteSalesChannelsOrThrowStep/index.html.md)
- [createSalesChannelsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createSalesChannelsStep/index.html.md)
-- [detachLocationsFromSalesChannelsStep](https://docs.medusajs.com/references/medusa-workflows/steps/detachLocationsFromSalesChannelsStep/index.html.md)
+- [createDefaultSalesChannelStep](https://docs.medusajs.com/references/medusa-workflows/steps/createDefaultSalesChannelStep/index.html.md)
- [deleteSalesChannelsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteSalesChannelsStep/index.html.md)
-- [updateSalesChannelsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateSalesChannelsStep/index.html.md)
- [detachProductsFromSalesChannelsStep](https://docs.medusajs.com/references/medusa-workflows/steps/detachProductsFromSalesChannelsStep/index.html.md)
+- [updateSalesChannelsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateSalesChannelsStep/index.html.md)
+- [detachLocationsFromSalesChannelsStep](https://docs.medusajs.com/references/medusa-workflows/steps/detachLocationsFromSalesChannelsStep/index.html.md)
- [createStockLocations](https://docs.medusajs.com/references/medusa-workflows/steps/createStockLocations/index.html.md)
-- [deleteStockLocationsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteStockLocationsStep/index.html.md)
- [updateStockLocationsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateStockLocationsStep/index.html.md)
+- [deleteStockLocationsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteStockLocationsStep/index.html.md)
+- [deleteStoresStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteStoresStep/index.html.md)
+- [createStoresStep](https://docs.medusajs.com/references/medusa-workflows/steps/createStoresStep/index.html.md)
+- [updateStoresStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateStoresStep/index.html.md)
+- [deleteShippingProfilesStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteShippingProfilesStep/index.html.md)
+- [createPricePreferencesStep](https://docs.medusajs.com/references/medusa-workflows/steps/createPricePreferencesStep/index.html.md)
+- [createPriceSetsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createPriceSetsStep/index.html.md)
+- [deletePricePreferencesStep](https://docs.medusajs.com/references/medusa-workflows/steps/deletePricePreferencesStep/index.html.md)
+- [updatePricePreferencesAsArrayStep](https://docs.medusajs.com/references/medusa-workflows/steps/updatePricePreferencesAsArrayStep/index.html.md)
+- [updatePricePreferencesStep](https://docs.medusajs.com/references/medusa-workflows/steps/updatePricePreferencesStep/index.html.md)
+- [updatePriceSetsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updatePriceSetsStep/index.html.md)
+- [createTaxRateRulesStep](https://docs.medusajs.com/references/medusa-workflows/steps/createTaxRateRulesStep/index.html.md)
+- [deleteTaxRateRulesStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteTaxRateRulesStep/index.html.md)
+- [createTaxRegionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createTaxRegionsStep/index.html.md)
+- [createTaxRatesStep](https://docs.medusajs.com/references/medusa-workflows/steps/createTaxRatesStep/index.html.md)
+- [deleteTaxRatesStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteTaxRatesStep/index.html.md)
+- [deleteTaxRegionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteTaxRegionsStep/index.html.md)
+- [listTaxRateIdsStep](https://docs.medusajs.com/references/medusa-workflows/steps/listTaxRateIdsStep/index.html.md)
+- [getItemTaxLinesStep](https://docs.medusajs.com/references/medusa-workflows/steps/getItemTaxLinesStep/index.html.md)
+- [listTaxRateRuleIdsStep](https://docs.medusajs.com/references/medusa-workflows/steps/listTaxRateRuleIdsStep/index.html.md)
+- [updateTaxRatesStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateTaxRatesStep/index.html.md)
+- [updateTaxRegionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateTaxRegionsStep/index.html.md)
+- [createUsersStep](https://docs.medusajs.com/references/medusa-workflows/steps/createUsersStep/index.html.md)
+- [deleteUsersStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteUsersStep/index.html.md)
+- [updateUsersStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateUsersStep/index.html.md)
# Events Reference
@@ -31056,9 +31208,9 @@ This documentation page includes the list of all events emitted by [Medusa's wor
|cart.updated|Emitted when a cart's details are updated.|
|cart.customer\_updated|Emitted when the customer in the cart is updated.|
|cart.region\_updated|Emitted when the cart's region is updated. This
-event is emitted alongside the CartWorkflowEvents.UPDATED event.|
+event is emitted alongside the |
-### `cart.created`
+### cart.created
Emitted when a cart is created.
@@ -31072,11 +31224,13 @@ Emitted when a cart is created.
#### Workflows Emitting this Event
+The following workflows emit this event when they're executed. These workflows are executed by Medusa's API routes. You can also view the events emitted by API routes in the [Store](https://docs.medusajs.com/api/store) and [Admin](https://docs.medusajs.com/api/admin) API references.
+
- [createCartWorkflow](https://docs.medusajs.com/references/medusa-workflows/createCartWorkflow/index.html.md)
***
-### `cart.updated`
+### cart.updated
Emitted when a cart's details are updated.
@@ -31090,6 +31244,8 @@ Emitted when a cart's details are updated.
#### Workflows Emitting this Event
+The following workflows emit this event when they're executed. These workflows are executed by Medusa's API routes. You can also view the events emitted by API routes in the [Store](https://docs.medusajs.com/api/store) and [Admin](https://docs.medusajs.com/api/admin) API references.
+
- [updateLineItemInCartWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateLineItemInCartWorkflow/index.html.md)
- [updateCartWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateCartWorkflow/index.html.md)
- [addToCartWorkflow](https://docs.medusajs.com/references/medusa-workflows/addToCartWorkflow/index.html.md)
@@ -31097,7 +31253,7 @@ Emitted when a cart's details are updated.
***
-### `cart.customer_updated`
+### cart.customer\_updated
Emitted when the customer in the cart is updated.
@@ -31111,14 +31267,16 @@ Emitted when the customer in the cart is updated.
#### Workflows Emitting this Event
+The following workflows emit this event when they're executed. These workflows are executed by Medusa's API routes. You can also view the events emitted by API routes in the [Store](https://docs.medusajs.com/api/store) and [Admin](https://docs.medusajs.com/api/admin) API references.
+
- [updateCartWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateCartWorkflow/index.html.md)
***
-### `cart.region_updated`
+### cart.region\_updated
Emitted when the cart's region is updated. This
-event is emitted alongside the CartWorkflowEvents.UPDATED event.
+event is emitted alongside the `cart.updated` event.
#### Payload
@@ -31130,6 +31288,8 @@ event is emitted alongside the CartWorkflowEvents.UPDATED event.
#### Workflows Emitting this Event
+The following workflows emit this event when they're executed. These workflows are executed by Medusa's API routes. You can also view the events emitted by API routes in the [Store](https://docs.medusajs.com/api/store) and [Admin](https://docs.medusajs.com/api/admin) API references.
+
- [updateCartWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateCartWorkflow/index.html.md)
***
@@ -31144,7 +31304,7 @@ event is emitted alongside the CartWorkflowEvents.UPDATED event.
|customer.updated|Emitted when a customer is updated.|
|customer.deleted|Emitted when a customer is deleted.|
-### `customer.created`
+### customer.created
Emitted when a customer is created.
@@ -31158,12 +31318,14 @@ Emitted when a customer is created.
#### Workflows Emitting this Event
+The following workflows emit this event when they're executed. These workflows are executed by Medusa's API routes. You can also view the events emitted by API routes in the [Store](https://docs.medusajs.com/api/store) and [Admin](https://docs.medusajs.com/api/admin) API references.
+
- [createCustomersWorkflow](https://docs.medusajs.com/references/medusa-workflows/createCustomersWorkflow/index.html.md)
- [createCustomerAccountWorkflow](https://docs.medusajs.com/references/medusa-workflows/createCustomerAccountWorkflow/index.html.md)
***
-### `customer.updated`
+### customer.updated
Emitted when a customer is updated.
@@ -31177,11 +31339,13 @@ Emitted when a customer is updated.
#### Workflows Emitting this Event
+The following workflows emit this event when they're executed. These workflows are executed by Medusa's API routes. You can also view the events emitted by API routes in the [Store](https://docs.medusajs.com/api/store) and [Admin](https://docs.medusajs.com/api/admin) API references.
+
- [updateCustomersWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateCustomersWorkflow/index.html.md)
***
-### `customer.deleted`
+### customer.deleted
Emitted when a customer is deleted.
@@ -31195,6 +31359,8 @@ Emitted when a customer is deleted.
#### Workflows Emitting this Event
+The following workflows emit this event when they're executed. These workflows are executed by Medusa's API routes. You can also view the events emitted by API routes in the [Store](https://docs.medusajs.com/api/store) and [Admin](https://docs.medusajs.com/api/admin) API references.
+
- [deleteCustomersWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteCustomersWorkflow/index.html.md)
- [removeCustomerAccountWorkflow](https://docs.medusajs.com/references/medusa-workflows/removeCustomerAccountWorkflow/index.html.md)
@@ -31222,7 +31388,7 @@ order.|
|order.transfer\_requested|Emitted when an order is requested to be transferred to
another customer.|
-### `order.updated`
+### order.updated
Emitted when the details of an order or draft order is updated. This
doesn't include updates made by an edit.
@@ -31237,12 +31403,14 @@ doesn't include updates made by an edit.
#### Workflows Emitting this Event
+The following workflows emit this event when they're executed. These workflows are executed by Medusa's API routes. You can also view the events emitted by API routes in the [Store](https://docs.medusajs.com/api/store) and [Admin](https://docs.medusajs.com/api/admin) API references.
+
- [updateOrderWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateOrderWorkflow/index.html.md)
- [updateDraftOrderWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateDraftOrderWorkflow/index.html.md)
***
-### `order.placed`
+### order.placed
Emitted when an order is placed, or when a draft order is converted to an
order.
@@ -31257,13 +31425,15 @@ order.
#### Workflows Emitting this Event
-- [completeCartWorkflow](https://docs.medusajs.com/references/medusa-workflows/completeCartWorkflow/index.html.md)
+The following workflows emit this event when they're executed. These workflows are executed by Medusa's API routes. You can also view the events emitted by API routes in the [Store](https://docs.medusajs.com/api/store) and [Admin](https://docs.medusajs.com/api/admin) API references.
+
- [convertDraftOrderWorkflow](https://docs.medusajs.com/references/medusa-workflows/convertDraftOrderWorkflow/index.html.md)
+- [completeCartWorkflow](https://docs.medusajs.com/references/medusa-workflows/completeCartWorkflow/index.html.md)
- [processPaymentWorkflow](https://docs.medusajs.com/references/medusa-workflows/processPaymentWorkflow/index.html.md)
***
-### `order.canceled`
+### order.canceled
Emitted when an order is canceld.
@@ -31277,11 +31447,13 @@ Emitted when an order is canceld.
#### Workflows Emitting this Event
+The following workflows emit this event when they're executed. These workflows are executed by Medusa's API routes. You can also view the events emitted by API routes in the [Store](https://docs.medusajs.com/api/store) and [Admin](https://docs.medusajs.com/api/admin) API references.
+
- [cancelOrderWorkflow](https://docs.medusajs.com/references/medusa-workflows/cancelOrderWorkflow/index.html.md)
***
-### `order.completed`
+### order.completed
Emitted when orders are completed.
@@ -31295,11 +31467,13 @@ Emitted when orders are completed.
#### Workflows Emitting this Event
+The following workflows emit this event when they're executed. These workflows are executed by Medusa's API routes. You can also view the events emitted by API routes in the [Store](https://docs.medusajs.com/api/store) and [Admin](https://docs.medusajs.com/api/admin) API references.
+
- [completeOrderWorkflow](https://docs.medusajs.com/references/medusa-workflows/completeOrderWorkflow/index.html.md)
***
-### `order.archived`
+### order.archived
Emitted when an order is archived.
@@ -31313,11 +31487,13 @@ Emitted when an order is archived.
#### Workflows Emitting this Event
+The following workflows emit this event when they're executed. These workflows are executed by Medusa's API routes. You can also view the events emitted by API routes in the [Store](https://docs.medusajs.com/api/store) and [Admin](https://docs.medusajs.com/api/admin) API references.
+
- [archiveOrderWorkflow](https://docs.medusajs.com/references/medusa-workflows/archiveOrderWorkflow/index.html.md)
***
-### `order.fulfillment_created`
+### order.fulfillment\_created
Emitted when a fulfillment is created for an order.
@@ -31327,17 +31503,19 @@ Emitted when a fulfillment is created for an order.
{
order_id, // The ID of the order
fulfillment_id, // The ID of the fulfillment
- no_notification, // Whether to notify the customer
+ no_notification, // (boolean) Whether to notify the customer
}
```
#### Workflows Emitting this Event
+The following workflows emit this event when they're executed. These workflows are executed by Medusa's API routes. You can also view the events emitted by API routes in the [Store](https://docs.medusajs.com/api/store) and [Admin](https://docs.medusajs.com/api/admin) API references.
+
- [createOrderFulfillmentWorkflow](https://docs.medusajs.com/references/medusa-workflows/createOrderFulfillmentWorkflow/index.html.md)
***
-### `order.fulfillment_canceled`
+### order.fulfillment\_canceled
Emitted when an order's fulfillment is canceled.
@@ -31347,17 +31525,19 @@ Emitted when an order's fulfillment is canceled.
{
order_id, // The ID of the order
fulfillment_id, // The ID of the fulfillment
- no_notification, // Whether to notify the customer
+ no_notification, // (boolean) Whether to notify the customer
}
```
#### Workflows Emitting this Event
+The following workflows emit this event when they're executed. These workflows are executed by Medusa's API routes. You can also view the events emitted by API routes in the [Store](https://docs.medusajs.com/api/store) and [Admin](https://docs.medusajs.com/api/admin) API references.
+
- [cancelOrderFulfillmentWorkflow](https://docs.medusajs.com/references/medusa-workflows/cancelOrderFulfillmentWorkflow/index.html.md)
***
-### `order.return_requested`
+### order.return\_requested
Emitted when a return request is confirmed.
@@ -31372,12 +31552,14 @@ Emitted when a return request is confirmed.
#### Workflows Emitting this Event
+The following workflows emit this event when they're executed. These workflows are executed by Medusa's API routes. You can also view the events emitted by API routes in the [Store](https://docs.medusajs.com/api/store) and [Admin](https://docs.medusajs.com/api/admin) API references.
+
- [createAndCompleteReturnOrderWorkflow](https://docs.medusajs.com/references/medusa-workflows/createAndCompleteReturnOrderWorkflow/index.html.md)
- [confirmReturnRequestWorkflow](https://docs.medusajs.com/references/medusa-workflows/confirmReturnRequestWorkflow/index.html.md)
***
-### `order.return_received`
+### order.return\_received
Emitted when a return is marked as received.
@@ -31392,12 +31574,14 @@ Emitted when a return is marked as received.
#### Workflows Emitting this Event
+The following workflows emit this event when they're executed. These workflows are executed by Medusa's API routes. You can also view the events emitted by API routes in the [Store](https://docs.medusajs.com/api/store) and [Admin](https://docs.medusajs.com/api/admin) API references.
+
- [createAndCompleteReturnOrderWorkflow](https://docs.medusajs.com/references/medusa-workflows/createAndCompleteReturnOrderWorkflow/index.html.md)
- [confirmReturnReceiveWorkflow](https://docs.medusajs.com/references/medusa-workflows/confirmReturnReceiveWorkflow/index.html.md)
***
-### `order.claim_created`
+### order.claim\_created
Emitted when a claim is created for an order.
@@ -31412,11 +31596,13 @@ Emitted when a claim is created for an order.
#### Workflows Emitting this Event
+The following workflows emit this event when they're executed. These workflows are executed by Medusa's API routes. You can also view the events emitted by API routes in the [Store](https://docs.medusajs.com/api/store) and [Admin](https://docs.medusajs.com/api/admin) API references.
+
- [confirmClaimRequestWorkflow](https://docs.medusajs.com/references/medusa-workflows/confirmClaimRequestWorkflow/index.html.md)
***
-### `order.exchange_created`
+### order.exchange\_created
Emitted when an exchange is created for an order.
@@ -31431,11 +31617,13 @@ Emitted when an exchange is created for an order.
#### Workflows Emitting this Event
+The following workflows emit this event when they're executed. These workflows are executed by Medusa's API routes. You can also view the events emitted by API routes in the [Store](https://docs.medusajs.com/api/store) and [Admin](https://docs.medusajs.com/api/admin) API references.
+
- [confirmExchangeRequestWorkflow](https://docs.medusajs.com/references/medusa-workflows/confirmExchangeRequestWorkflow/index.html.md)
***
-### `order.transfer_requested`
+### order.transfer\_requested
Emitted when an order is requested to be transferred to
another customer.
@@ -31451,6 +31639,8 @@ another customer.
#### Workflows Emitting this Event
+The following workflows emit this event when they're executed. These workflows are executed by Medusa's API routes. You can also view the events emitted by API routes in the [Store](https://docs.medusajs.com/api/store) and [Admin](https://docs.medusajs.com/api/admin) API references.
+
- [requestOrderTransferWorkflow](https://docs.medusajs.com/references/medusa-workflows/requestOrderTransferWorkflow/index.html.md)
***
@@ -31465,7 +31655,7 @@ another customer.
|order-edit.confirmed|Emitted when an order edit request is confirmed.|
|order-edit.canceled|Emitted when an order edit request is canceled.|
-### `order-edit.requested`
+### order-edit.requested
Emitted when an order edit is requested.
@@ -31474,17 +31664,19 @@ Emitted when an order edit is requested.
```ts
{
order_id, // The ID of the order
- actions, // The actions to edit the order
+ actions, // (array) The [actions](https://docs.medusajs.com/resources/references/fulfillment/interfaces/fulfillment.OrderChangeActionDTO) to edit the order
}
```
#### Workflows Emitting this Event
+The following workflows emit this event when they're executed. These workflows are executed by Medusa's API routes. You can also view the events emitted by API routes in the [Store](https://docs.medusajs.com/api/store) and [Admin](https://docs.medusajs.com/api/admin) API references.
+
- [requestOrderEditRequestWorkflow](https://docs.medusajs.com/references/medusa-workflows/requestOrderEditRequestWorkflow/index.html.md)
***
-### `order-edit.confirmed`
+### order-edit.confirmed
Emitted when an order edit request is confirmed.
@@ -31493,17 +31685,18 @@ Emitted when an order edit request is confirmed.
```ts
{
order_id, // The ID of the order
- actions, // The actions to edit the order
-}
+ actions, // (array) The [actions](https://docs.medusajs.com/resources/references/fulfillment/interfaces/fulfillment.OrderChangeActionDTO) to edit the order
```
#### Workflows Emitting this Event
+The following workflows emit this event when they're executed. These workflows are executed by Medusa's API routes. You can also view the events emitted by API routes in the [Store](https://docs.medusajs.com/api/store) and [Admin](https://docs.medusajs.com/api/admin) API references.
+
- [confirmOrderEditRequestWorkflow](https://docs.medusajs.com/references/medusa-workflows/confirmOrderEditRequestWorkflow/index.html.md)
***
-### `order-edit.canceled`
+### order-edit.canceled
Emitted when an order edit request is canceled.
@@ -31512,12 +31705,14 @@ Emitted when an order edit request is canceled.
```ts
{
order_id, // The ID of the order
- actions, // The actions to edit the order
+ actions, // (array) The [actions](https://docs.medusajs.com/resources/references/fulfillment/interfaces/fulfillment.OrderChangeActionDTO) to edit the order
}
```
#### Workflows Emitting this Event
+The following workflows emit this event when they're executed. These workflows are executed by Medusa's API routes. You can also view the events emitted by API routes in the [Store](https://docs.medusajs.com/api/store) and [Admin](https://docs.medusajs.com/api/admin) API references.
+
- [cancelBeginOrderEditWorkflow](https://docs.medusajs.com/references/medusa-workflows/cancelBeginOrderEditWorkflow/index.html.md)
***
@@ -31532,7 +31727,7 @@ Emitted when an order edit request is canceled.
|user.updated|Emitted when users are updated.|
|user.deleted|Emitted when users are deleted.|
-### `user.created`
+### user.created
Emitted when users are created.
@@ -31546,13 +31741,15 @@ Emitted when users are created.
#### Workflows Emitting this Event
+The following workflows emit this event when they're executed. These workflows are executed by Medusa's API routes. You can also view the events emitted by API routes in the [Store](https://docs.medusajs.com/api/store) and [Admin](https://docs.medusajs.com/api/admin) API references.
+
- [createUsersWorkflow](https://docs.medusajs.com/references/medusa-workflows/createUsersWorkflow/index.html.md)
- [createUserAccountWorkflow](https://docs.medusajs.com/references/medusa-workflows/createUserAccountWorkflow/index.html.md)
- [acceptInviteWorkflow](https://docs.medusajs.com/references/medusa-workflows/acceptInviteWorkflow/index.html.md)
***
-### `user.updated`
+### user.updated
Emitted when users are updated.
@@ -31566,11 +31763,13 @@ Emitted when users are updated.
#### Workflows Emitting this Event
+The following workflows emit this event when they're executed. These workflows are executed by Medusa's API routes. You can also view the events emitted by API routes in the [Store](https://docs.medusajs.com/api/store) and [Admin](https://docs.medusajs.com/api/admin) API references.
+
- [updateUsersWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateUsersWorkflow/index.html.md)
***
-### `user.deleted`
+### user.deleted
Emitted when users are deleted.
@@ -31584,6 +31783,8 @@ Emitted when users are deleted.
#### Workflows Emitting this Event
+The following workflows emit this event when they're executed. These workflows are executed by Medusa's API routes. You can also view the events emitted by API routes in the [Store](https://docs.medusajs.com/api/store) and [Admin](https://docs.medusajs.com/api/admin) API references.
+
- [deleteUsersWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteUsersWorkflow/index.html.md)
- [removeUserAccountWorkflow](https://docs.medusajs.com/references/medusa-workflows/removeUserAccountWorkflow/index.html.md)
@@ -31603,7 +31804,7 @@ to send an email to the invited users, for example.|
refreshed. You can listen to this event to send an email to the invited users,
for example.|
-### `invite.accepted`
+### invite.accepted
Emitted when an invite is accepted.
@@ -31617,11 +31818,13 @@ Emitted when an invite is accepted.
#### Workflows Emitting this Event
+The following workflows emit this event when they're executed. These workflows are executed by Medusa's API routes. You can also view the events emitted by API routes in the [Store](https://docs.medusajs.com/api/store) and [Admin](https://docs.medusajs.com/api/admin) API references.
+
- [acceptInviteWorkflow](https://docs.medusajs.com/references/medusa-workflows/acceptInviteWorkflow/index.html.md)
***
-### `invite.created`
+### invite.created
Emitted when invites are created. You can listen to this event
to send an email to the invited users, for example.
@@ -31636,11 +31839,13 @@ to send an email to the invited users, for example.
#### Workflows Emitting this Event
+The following workflows emit this event when they're executed. These workflows are executed by Medusa's API routes. You can also view the events emitted by API routes in the [Store](https://docs.medusajs.com/api/store) and [Admin](https://docs.medusajs.com/api/admin) API references.
+
- [createInvitesWorkflow](https://docs.medusajs.com/references/medusa-workflows/createInvitesWorkflow/index.html.md)
***
-### `invite.deleted`
+### invite.deleted
Emitted when invites are deleted.
@@ -31654,11 +31859,13 @@ Emitted when invites are deleted.
#### Workflows Emitting this Event
+The following workflows emit this event when they're executed. These workflows are executed by Medusa's API routes. You can also view the events emitted by API routes in the [Store](https://docs.medusajs.com/api/store) and [Admin](https://docs.medusajs.com/api/admin) API references.
+
- [deleteInvitesWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteInvitesWorkflow/index.html.md)
***
-### `invite.resent`
+### invite.resent
Emitted when invites should be resent because their token was
refreshed. You can listen to this event to send an email to the invited users,
@@ -31674,6 +31881,8 @@ for example.
#### Workflows Emitting this Event
+The following workflows emit this event when they're executed. These workflows are executed by Medusa's API routes. You can also view the events emitted by API routes in the [Store](https://docs.medusajs.com/api/store) and [Admin](https://docs.medusajs.com/api/admin) API references.
+
- [refreshInviteTokensWorkflow](https://docs.medusajs.com/references/medusa-workflows/refreshInviteTokensWorkflow/index.html.md)
***
@@ -31687,7 +31896,7 @@ for example.
|auth.password\_reset|Emitted when a reset password token is generated. You can listen to this event
to send a reset password email to the user or customer, for example.|
-### `auth.password_reset`
+### auth.password\_reset
Emitted when a reset password token is generated. You can listen to this event
to send a reset password email to the user or customer, for example.
@@ -31704,6 +31913,8 @@ to send a reset password email to the user or customer, for example.
#### Workflows Emitting this Event
+The following workflows emit this event when they're executed. These workflows are executed by Medusa's API routes. You can also view the events emitted by API routes in the [Store](https://docs.medusajs.com/api/store) and [Admin](https://docs.medusajs.com/api/admin) API references.
+
- [generateResetPasswordTokenWorkflow](https://docs.medusajs.com/references/medusa-workflows/generateResetPasswordTokenWorkflow/index.html.md)
***
@@ -31718,7 +31929,7 @@ to send a reset password email to the user or customer, for example.
|sales-channel.updated|Emitted when sales channels are updated.|
|sales-channel.deleted|Emitted when sales channels are deleted.|
-### `sales-channel.created`
+### sales-channel.created
Emitted when sales channels are created.
@@ -31732,11 +31943,13 @@ Emitted when sales channels are created.
#### Workflows Emitting this Event
+The following workflows emit this event when they're executed. These workflows are executed by Medusa's API routes. You can also view the events emitted by API routes in the [Store](https://docs.medusajs.com/api/store) and [Admin](https://docs.medusajs.com/api/admin) API references.
+
- [createSalesChannelsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createSalesChannelsWorkflow/index.html.md)
***
-### `sales-channel.updated`
+### sales-channel.updated
Emitted when sales channels are updated.
@@ -31750,11 +31963,13 @@ Emitted when sales channels are updated.
#### Workflows Emitting this Event
+The following workflows emit this event when they're executed. These workflows are executed by Medusa's API routes. You can also view the events emitted by API routes in the [Store](https://docs.medusajs.com/api/store) and [Admin](https://docs.medusajs.com/api/admin) API references.
+
- [updateSalesChannelsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateSalesChannelsWorkflow/index.html.md)
***
-### `sales-channel.deleted`
+### sales-channel.deleted
Emitted when sales channels are deleted.
@@ -31768,6 +31983,8 @@ Emitted when sales channels are deleted.
#### Workflows Emitting this Event
+The following workflows emit this event when they're executed. These workflows are executed by Medusa's API routes. You can also view the events emitted by API routes in the [Store](https://docs.medusajs.com/api/store) and [Admin](https://docs.medusajs.com/api/admin) API references.
+
- [deleteSalesChannelsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteSalesChannelsWorkflow/index.html.md)
***
@@ -31782,7 +31999,7 @@ Emitted when sales channels are deleted.
|product-category.updated|Emitted when product categories are updated.|
|product-category.deleted|Emitted when product categories are deleted.|
-### `product-category.created`
+### product-category.created
Emitted when product categories are created.
@@ -31796,11 +32013,13 @@ Emitted when product categories are created.
#### Workflows Emitting this Event
+The following workflows emit this event when they're executed. These workflows are executed by Medusa's API routes. You can also view the events emitted by API routes in the [Store](https://docs.medusajs.com/api/store) and [Admin](https://docs.medusajs.com/api/admin) API references.
+
- [createProductCategoriesWorkflow](https://docs.medusajs.com/references/medusa-workflows/createProductCategoriesWorkflow/index.html.md)
***
-### `product-category.updated`
+### product-category.updated
Emitted when product categories are updated.
@@ -31814,11 +32033,13 @@ Emitted when product categories are updated.
#### Workflows Emitting this Event
+The following workflows emit this event when they're executed. These workflows are executed by Medusa's API routes. You can also view the events emitted by API routes in the [Store](https://docs.medusajs.com/api/store) and [Admin](https://docs.medusajs.com/api/admin) API references.
+
- [updateProductCategoriesWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateProductCategoriesWorkflow/index.html.md)
***
-### `product-category.deleted`
+### product-category.deleted
Emitted when product categories are deleted.
@@ -31832,6 +32053,8 @@ Emitted when product categories are deleted.
#### Workflows Emitting this Event
+The following workflows emit this event when they're executed. These workflows are executed by Medusa's API routes. You can also view the events emitted by API routes in the [Store](https://docs.medusajs.com/api/store) and [Admin](https://docs.medusajs.com/api/admin) API references.
+
- [deleteProductCategoriesWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteProductCategoriesWorkflow/index.html.md)
***
@@ -31846,7 +32069,7 @@ Emitted when product categories are deleted.
|product-collection.updated|Emitted when product collections are updated.|
|product-collection.deleted|Emitted when product collections are deleted.|
-### `product-collection.created`
+### product-collection.created
Emitted when product collections are created.
@@ -31860,11 +32083,13 @@ Emitted when product collections are created.
#### Workflows Emitting this Event
+The following workflows emit this event when they're executed. These workflows are executed by Medusa's API routes. You can also view the events emitted by API routes in the [Store](https://docs.medusajs.com/api/store) and [Admin](https://docs.medusajs.com/api/admin) API references.
+
- [createCollectionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createCollectionsWorkflow/index.html.md)
***
-### `product-collection.updated`
+### product-collection.updated
Emitted when product collections are updated.
@@ -31878,11 +32103,13 @@ Emitted when product collections are updated.
#### Workflows Emitting this Event
+The following workflows emit this event when they're executed. These workflows are executed by Medusa's API routes. You can also view the events emitted by API routes in the [Store](https://docs.medusajs.com/api/store) and [Admin](https://docs.medusajs.com/api/admin) API references.
+
- [updateCollectionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateCollectionsWorkflow/index.html.md)
***
-### `product-collection.deleted`
+### product-collection.deleted
Emitted when product collections are deleted.
@@ -31896,6 +32123,8 @@ Emitted when product collections are deleted.
#### Workflows Emitting this Event
+The following workflows emit this event when they're executed. These workflows are executed by Medusa's API routes. You can also view the events emitted by API routes in the [Store](https://docs.medusajs.com/api/store) and [Admin](https://docs.medusajs.com/api/admin) API references.
+
- [deleteCollectionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteCollectionsWorkflow/index.html.md)
***
@@ -31910,7 +32139,7 @@ Emitted when product collections are deleted.
|product-variant.created|Emitted when product variants are created.|
|product-variant.deleted|Emitted when product variants are deleted.|
-### `product-variant.updated`
+### product-variant.updated
Emitted when product variants are updated.
@@ -31924,12 +32153,14 @@ Emitted when product variants are updated.
#### Workflows Emitting this Event
+The following workflows emit this event when they're executed. These workflows are executed by Medusa's API routes. You can also view the events emitted by API routes in the [Store](https://docs.medusajs.com/api/store) and [Admin](https://docs.medusajs.com/api/admin) API references.
+
- [updateProductVariantsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateProductVariantsWorkflow/index.html.md)
- [batchProductVariantsWorkflow](https://docs.medusajs.com/references/medusa-workflows/batchProductVariantsWorkflow/index.html.md)
***
-### `product-variant.created`
+### product-variant.created
Emitted when product variants are created.
@@ -31943,6 +32174,8 @@ Emitted when product variants are created.
#### Workflows Emitting this Event
+The following workflows emit this event when they're executed. These workflows are executed by Medusa's API routes. You can also view the events emitted by API routes in the [Store](https://docs.medusajs.com/api/store) and [Admin](https://docs.medusajs.com/api/admin) API references.
+
- [createProductVariantsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createProductVariantsWorkflow/index.html.md)
- [createProductsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createProductsWorkflow/index.html.md)
- [batchProductVariantsWorkflow](https://docs.medusajs.com/references/medusa-workflows/batchProductVariantsWorkflow/index.html.md)
@@ -31951,7 +32184,7 @@ Emitted when product variants are created.
***
-### `product-variant.deleted`
+### product-variant.deleted
Emitted when product variants are deleted.
@@ -31965,6 +32198,8 @@ Emitted when product variants are deleted.
#### Workflows Emitting this Event
+The following workflows emit this event when they're executed. These workflows are executed by Medusa's API routes. You can also view the events emitted by API routes in the [Store](https://docs.medusajs.com/api/store) and [Admin](https://docs.medusajs.com/api/admin) API references.
+
- [deleteProductVariantsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteProductVariantsWorkflow/index.html.md)
- [batchProductVariantsWorkflow](https://docs.medusajs.com/references/medusa-workflows/batchProductVariantsWorkflow/index.html.md)
@@ -31980,7 +32215,7 @@ Emitted when product variants are deleted.
|product.created|Emitted when products are created.|
|product.deleted|Emitted when products are deleted.|
-### `product.updated`
+### product.updated
Emitted when products are updated.
@@ -31994,13 +32229,15 @@ Emitted when products are updated.
#### Workflows Emitting this Event
+The following workflows emit this event when they're executed. These workflows are executed by Medusa's API routes. You can also view the events emitted by API routes in the [Store](https://docs.medusajs.com/api/store) and [Admin](https://docs.medusajs.com/api/admin) API references.
+
- [updateProductsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateProductsWorkflow/index.html.md)
- [batchProductsWorkflow](https://docs.medusajs.com/references/medusa-workflows/batchProductsWorkflow/index.html.md)
- [importProductsWorkflow](https://docs.medusajs.com/references/medusa-workflows/importProductsWorkflow/index.html.md)
***
-### `product.created`
+### product.created
Emitted when products are created.
@@ -32014,13 +32251,15 @@ Emitted when products are created.
#### Workflows Emitting this Event
+The following workflows emit this event when they're executed. These workflows are executed by Medusa's API routes. You can also view the events emitted by API routes in the [Store](https://docs.medusajs.com/api/store) and [Admin](https://docs.medusajs.com/api/admin) API references.
+
- [createProductsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createProductsWorkflow/index.html.md)
- [batchProductsWorkflow](https://docs.medusajs.com/references/medusa-workflows/batchProductsWorkflow/index.html.md)
- [importProductsWorkflow](https://docs.medusajs.com/references/medusa-workflows/importProductsWorkflow/index.html.md)
***
-### `product.deleted`
+### product.deleted
Emitted when products are deleted.
@@ -32034,6 +32273,8 @@ Emitted when products are deleted.
#### Workflows Emitting this Event
+The following workflows emit this event when they're executed. These workflows are executed by Medusa's API routes. You can also view the events emitted by API routes in the [Store](https://docs.medusajs.com/api/store) and [Admin](https://docs.medusajs.com/api/admin) API references.
+
- [deleteProductsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteProductsWorkflow/index.html.md)
- [batchProductsWorkflow](https://docs.medusajs.com/references/medusa-workflows/batchProductsWorkflow/index.html.md)
- [importProductsWorkflow](https://docs.medusajs.com/references/medusa-workflows/importProductsWorkflow/index.html.md)
@@ -32050,7 +32291,7 @@ Emitted when products are deleted.
|product-type.created|Emitted when product types are created.|
|product-type.deleted|Emitted when product types are deleted.|
-### `product-type.updated`
+### product-type.updated
Emitted when product types are updated.
@@ -32064,11 +32305,13 @@ Emitted when product types are updated.
#### Workflows Emitting this Event
+The following workflows emit this event when they're executed. These workflows are executed by Medusa's API routes. You can also view the events emitted by API routes in the [Store](https://docs.medusajs.com/api/store) and [Admin](https://docs.medusajs.com/api/admin) API references.
+
- [updateProductTypesWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateProductTypesWorkflow/index.html.md)
***
-### `product-type.created`
+### product-type.created
Emitted when product types are created.
@@ -32082,11 +32325,13 @@ Emitted when product types are created.
#### Workflows Emitting this Event
+The following workflows emit this event when they're executed. These workflows are executed by Medusa's API routes. You can also view the events emitted by API routes in the [Store](https://docs.medusajs.com/api/store) and [Admin](https://docs.medusajs.com/api/admin) API references.
+
- [createProductTypesWorkflow](https://docs.medusajs.com/references/medusa-workflows/createProductTypesWorkflow/index.html.md)
***
-### `product-type.deleted`
+### product-type.deleted
Emitted when product types are deleted.
@@ -32100,6 +32345,8 @@ Emitted when product types are deleted.
#### Workflows Emitting this Event
+The following workflows emit this event when they're executed. These workflows are executed by Medusa's API routes. You can also view the events emitted by API routes in the [Store](https://docs.medusajs.com/api/store) and [Admin](https://docs.medusajs.com/api/admin) API references.
+
- [deleteProductTypesWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteProductTypesWorkflow/index.html.md)
***
@@ -32114,7 +32361,7 @@ Emitted when product types are deleted.
|product-tag.created|Emitted when product tags are created.|
|product-tag.deleted|Emitted when product tags are deleted.|
-### `product-tag.updated`
+### product-tag.updated
Emitted when product tags are updated.
@@ -32128,11 +32375,13 @@ Emitted when product tags are updated.
#### Workflows Emitting this Event
+The following workflows emit this event when they're executed. These workflows are executed by Medusa's API routes. You can also view the events emitted by API routes in the [Store](https://docs.medusajs.com/api/store) and [Admin](https://docs.medusajs.com/api/admin) API references.
+
- [updateProductTagsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateProductTagsWorkflow/index.html.md)
***
-### `product-tag.created`
+### product-tag.created
Emitted when product tags are created.
@@ -32146,11 +32395,13 @@ Emitted when product tags are created.
#### Workflows Emitting this Event
+The following workflows emit this event when they're executed. These workflows are executed by Medusa's API routes. You can also view the events emitted by API routes in the [Store](https://docs.medusajs.com/api/store) and [Admin](https://docs.medusajs.com/api/admin) API references.
+
- [createProductTagsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createProductTagsWorkflow/index.html.md)
***
-### `product-tag.deleted`
+### product-tag.deleted
Emitted when product tags are deleted.
@@ -32164,6 +32415,8 @@ Emitted when product tags are deleted.
#### Workflows Emitting this Event
+The following workflows emit this event when they're executed. These workflows are executed by Medusa's API routes. You can also view the events emitted by API routes in the [Store](https://docs.medusajs.com/api/store) and [Admin](https://docs.medusajs.com/api/admin) API references.
+
- [deleteProductTagsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteProductTagsWorkflow/index.html.md)
***
@@ -32178,7 +32431,7 @@ Emitted when product tags are deleted.
|product-option.created|Emitted when product options are created.|
|product-option.deleted|Emitted when product options are deleted.|
-### `product-option.updated`
+### product-option.updated
Emitted when product options are updated.
@@ -32192,11 +32445,13 @@ Emitted when product options are updated.
#### Workflows Emitting this Event
+The following workflows emit this event when they're executed. These workflows are executed by Medusa's API routes. You can also view the events emitted by API routes in the [Store](https://docs.medusajs.com/api/store) and [Admin](https://docs.medusajs.com/api/admin) API references.
+
- [updateProductOptionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateProductOptionsWorkflow/index.html.md)
***
-### `product-option.created`
+### product-option.created
Emitted when product options are created.
@@ -32210,11 +32465,13 @@ Emitted when product options are created.
#### Workflows Emitting this Event
+The following workflows emit this event when they're executed. These workflows are executed by Medusa's API routes. You can also view the events emitted by API routes in the [Store](https://docs.medusajs.com/api/store) and [Admin](https://docs.medusajs.com/api/admin) API references.
+
- [createProductOptionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createProductOptionsWorkflow/index.html.md)
***
-### `product-option.deleted`
+### product-option.deleted
Emitted when product options are deleted.
@@ -32228,6 +32485,8 @@ Emitted when product options are deleted.
#### Workflows Emitting this Event
+The following workflows emit this event when they're executed. These workflows are executed by Medusa's API routes. You can also view the events emitted by API routes in the [Store](https://docs.medusajs.com/api/store) and [Admin](https://docs.medusajs.com/api/admin) API references.
+
- [deleteProductOptionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteProductOptionsWorkflow/index.html.md)
***
@@ -32242,7 +32501,7 @@ Emitted when product options are deleted.
|region.created|Emitted when regions are created.|
|region.deleted|Emitted when regions are deleted.|
-### `region.updated`
+### region.updated
Emitted when regions are updated.
@@ -32256,11 +32515,13 @@ Emitted when regions are updated.
#### Workflows Emitting this Event
+The following workflows emit this event when they're executed. These workflows are executed by Medusa's API routes. You can also view the events emitted by API routes in the [Store](https://docs.medusajs.com/api/store) and [Admin](https://docs.medusajs.com/api/admin) API references.
+
- [updateRegionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateRegionsWorkflow/index.html.md)
***
-### `region.created`
+### region.created
Emitted when regions are created.
@@ -32274,11 +32535,13 @@ Emitted when regions are created.
#### Workflows Emitting this Event
+The following workflows emit this event when they're executed. These workflows are executed by Medusa's API routes. You can also view the events emitted by API routes in the [Store](https://docs.medusajs.com/api/store) and [Admin](https://docs.medusajs.com/api/admin) API references.
+
- [createRegionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createRegionsWorkflow/index.html.md)
***
-### `region.deleted`
+### region.deleted
Emitted when regions are deleted.
@@ -32292,6 +32555,8 @@ Emitted when regions are deleted.
#### Workflows Emitting this Event
+The following workflows emit this event when they're executed. These workflows are executed by Medusa's API routes. You can also view the events emitted by API routes in the [Store](https://docs.medusajs.com/api/store) and [Admin](https://docs.medusajs.com/api/admin) API references.
+
- [deleteRegionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteRegionsWorkflow/index.html.md)
***
@@ -32305,7 +32570,7 @@ Emitted when regions are deleted.
|shipment.created|Emitted when a shipment is created for an order.|
|delivery.created|Emitted when a fulfillment is marked as delivered.|
-### `shipment.created`
+### shipment.created
Emitted when a shipment is created for an order.
@@ -32314,17 +32579,19 @@ Emitted when a shipment is created for an order.
```ts
{
id, // the ID of the shipment
- no_notification, // whether to notify the customer
+ no_notification, // (boolean) whether to notify the customer
}
```
#### Workflows Emitting this Event
+The following workflows emit this event when they're executed. These workflows are executed by Medusa's API routes. You can also view the events emitted by API routes in the [Store](https://docs.medusajs.com/api/store) and [Admin](https://docs.medusajs.com/api/admin) API references.
+
- [createOrderShipmentWorkflow](https://docs.medusajs.com/references/medusa-workflows/createOrderShipmentWorkflow/index.html.md)
***
-### `delivery.created`
+### delivery.created
Emitted when a fulfillment is marked as delivered.
@@ -32338,6 +32605,8 @@ Emitted when a fulfillment is marked as delivered.
#### Workflows Emitting this Event
+The following workflows emit this event when they're executed. These workflows are executed by Medusa's API routes. You can also view the events emitted by API routes in the [Store](https://docs.medusajs.com/api/store) and [Admin](https://docs.medusajs.com/api/admin) API references.
+
- [markOrderFulfillmentAsDeliveredWorkflow](https://docs.medusajs.com/references/medusa-workflows/markOrderFulfillmentAsDeliveredWorkflow/index.html.md)
@@ -32484,6 +32753,68 @@ npx medusa db:sync-links
|\`--execute-all\`|Skip prompts when syncing links and execute all (including unsafe) actions.|No|Prompts are shown for unsafe actions, by default.|
+# build Command - Medusa CLI Reference
+
+Create a standalone build of the Medusa application.
+
+This creates a build that:
+
+- Doesn't rely on the source TypeScript files.
+- Can be copied to a production server reliably.
+
+The build is outputted to a new `.medusa/server` directory.
+
+```bash
+npx medusa build
+```
+
+Refer to [this section](#run-built-medusa-application) for next steps.
+
+## Options
+
+|Option|Description|
+|---|---|---|
+|\`--admin-only\`|Whether to only build the admin to host it separately. If this option is not passed, the admin is built to the |
+
+***
+
+## Run Built Medusa Application
+
+After running the `build` command, use the following step to run the built Medusa application:
+
+- Change to the `.medusa/server` directory and install the dependencies:
+
+```bash npm2yarn
+cd .medusa/server && npm install
+```
+
+- When running the application locally, make sure to copy the `.env` file from the root project's directory. In production, use system environment variables instead.
+
+```bash npm2yarn
+cp .env .medusa/server/.env.production
+```
+
+- In the system environment variables, set `NODE_ENV` to `production`:
+
+```bash
+NODE_ENV=production
+```
+
+- Use the `start` command to run the application:
+
+```bash npm2yarn
+cd .medusa/server && npm run start
+```
+
+***
+
+## Build Medusa Admin
+
+By default, the Medusa Admin is built to the `.medusa/server/public/admin` directory.
+
+If you want a separate build to host the admin standalone, such as on Vercel, pass the `--admin-only` option as explained in the [Options](#options) section. This outputs the admin to the `.medusa/admin` directory instead.
+
+
# exec Command - Medusa CLI Reference
Run a custom CLI script. Learn more about it in [this guide](https://docs.medusajs.com/docs/learn/fundamentals/custom-cli-scripts/index.html.md).
@@ -32500,51 +32831,6 @@ npx medusa exec [file] [args...]
|\`args\`|A list of arguments to pass to the function. These arguments are passed in the |No|
-# develop Command - Medusa CLI Reference
-
-Start Medusa application in development. This command watches files for any changes, then rebuilds the files and restarts the Medusa application.
-
-```bash
-npx medusa develop
-```
-
-## Options
-
-|Option|Description|Default|
-|---|---|---|---|---|
-|\`-H \\`|Set host of the Medusa server.|\`localhost\`|
-|\`-p \\`|Set port of the Medusa server.|\`9000\`|
-
-
-# new Command - Medusa CLI Reference
-
-Create a new Medusa application. Unlike the `create-medusa-app` CLI tool, this command provides more flexibility for experienced Medusa developers in creating and configuring their project.
-
-```bash
-medusa new [ []]
-```
-
-## Arguments
-
-|Argument|Description|Required|Default|
-|---|---|---|---|---|---|---|
-|\`dir\_name\`|The name of the directory to create the Medusa application in.|Yes|-|
-|\`starter\_url\`|The URL of the starter repository to create the project from.|No|\`https://github.com/medusajs/medusa-starter-default\`|
-
-## Options
-
-|Option|Description|
-|---|---|---|
-|\`-y\`|Skip all prompts, such as databaes prompts. A database might not be created if default PostgreSQL credentials don't work.|
-|\`--skip-db\`|Skip database creation.|
-|\`--skip-env\`|Skip populating |
-|\`--db-user \\`|The database user to use for database setup.|
-|\`--db-database \\`|The name of the database used for database setup.|
-|\`--db-pass \\`|The database password to use for database setup.|
-|\`--db-port \\`|The database port to use for database setup.|
-|\`--db-host \\`|The database host to use for database setup.|
-
-
# plugin Commands - Medusa CLI Reference
Commands starting with `plugin:` perform actions related to [plugin](https://docs.medusajs.com/docs/learn/fundamentals/plugins/index.html.md) development.
@@ -32606,66 +32892,49 @@ npx medusa plugin:build
```
-# build Command - Medusa CLI Reference
+# new Command - Medusa CLI Reference
-Create a standalone build of the Medusa application.
-
-This creates a build that:
-
-- Doesn't rely on the source TypeScript files.
-- Can be copied to a production server reliably.
-
-The build is outputted to a new `.medusa/server` directory.
+Create a new Medusa application. Unlike the `create-medusa-app` CLI tool, this command provides more flexibility for experienced Medusa developers in creating and configuring their project.
```bash
-npx medusa build
+medusa new [ []]
```
-Refer to [this section](#run-built-medusa-application) for next steps.
+## Arguments
+
+|Argument|Description|Required|Default|
+|---|---|---|---|---|---|---|
+|\`dir\_name\`|The name of the directory to create the Medusa application in.|Yes|-|
+|\`starter\_url\`|The URL of the starter repository to create the project from.|No|\`https://github.com/medusajs/medusa-starter-default\`|
## Options
|Option|Description|
|---|---|---|
-|\`--admin-only\`|Whether to only build the admin to host it separately. If this option is not passed, the admin is built to the |
+|\`-y\`|Skip all prompts, such as databaes prompts. A database might not be created if default PostgreSQL credentials don't work.|
+|\`--skip-db\`|Skip database creation.|
+|\`--skip-env\`|Skip populating |
+|\`--db-user \\`|The database user to use for database setup.|
+|\`--db-database \\`|The name of the database used for database setup.|
+|\`--db-pass \\`|The database password to use for database setup.|
+|\`--db-port \\`|The database port to use for database setup.|
+|\`--db-host \\`|The database host to use for database setup.|
-***
-## Run Built Medusa Application
+# develop Command - Medusa CLI Reference
-After running the `build` command, use the following step to run the built Medusa application:
-
-- Change to the `.medusa/server` directory and install the dependencies:
-
-```bash npm2yarn
-cd .medusa/server && npm install
-```
-
-- When running the application locally, make sure to copy the `.env` file from the root project's directory. In production, use system environment variables instead.
-
-```bash npm2yarn
-cp .env .medusa/server/.env.production
-```
-
-- In the system environment variables, set `NODE_ENV` to `production`:
+Start Medusa application in development. This command watches files for any changes, then rebuilds the files and restarts the Medusa application.
```bash
-NODE_ENV=production
+npx medusa develop
```
-- Use the `start` command to run the application:
+## Options
-```bash npm2yarn
-cd .medusa/server && npm run start
-```
-
-***
-
-## Build Medusa Admin
-
-By default, the Medusa Admin is built to the `.medusa/server/public/admin` directory.
-
-If you want a separate build to host the admin standalone, such as on Vercel, pass the `--admin-only` option as explained in the [Options](#options) section. This outputs the admin to the `.medusa/admin` directory instead.
+|Option|Description|Default|
+|---|---|---|---|---|
+|\`-H \\`|Set host of the Medusa server.|\`localhost\`|
+|\`-p \\`|Set port of the Medusa server.|\`9000\`|
# telemetry Command - Medusa CLI Reference
@@ -32684,23 +32953,6 @@ npx medusa telemetry
|\`--disable\`|Disable telemetry.|
-# start Command - Medusa CLI Reference
-
-Start the Medusa application in production.
-
-```bash
-npx medusa start
-```
-
-## Options
-
-|Option|Description|Default|
-|---|---|---|---|---|
-|\`-H \\`|Set host of the Medusa server.|\`localhost\`|
-|\`-p \\`|Set port of the Medusa server.|\`9000\`|
-|\`--cluster \\`|Start Medusa's Node.js server in |Cluster mode is disabled by default. If the option is passed but no number is passed, Medusa will try to consume all available CPU cores.|
-
-
# user Command - Medusa CLI Reference
Create a new admin user.
@@ -32720,6 +32972,23 @@ npx medusa user --email [--password ]
If ran successfully, you'll receive the invite token in the output.|No|\`false\`|
+# start Command - Medusa CLI Reference
+
+Start the Medusa application in production.
+
+```bash
+npx medusa start
+```
+
+## Options
+
+|Option|Description|Default|
+|---|---|---|---|---|
+|\`-H \\`|Set host of the Medusa server.|\`localhost\`|
+|\`-p \\`|Set port of the Medusa server.|\`9000\`|
+|\`--cluster \\`|Start Medusa's Node.js server in |Cluster mode is disabled by default. If the option is passed but no number is passed, Medusa will try to consume all available CPU cores.|
+
+
# Medusa CLI Reference
The Medusa CLI tool provides commands that facilitate your development.
@@ -32743,6 +33012,22 @@ npx medusa --help
***
+# exec Command - Medusa CLI Reference
+
+Run a custom CLI script. Learn more about it in [this guide](https://docs.medusajs.com/docs/learn/fundamentals/custom-cli-scripts/index.html.md).
+
+```bash
+npx medusa exec [file] [args...]
+```
+
+## Arguments
+
+|Argument|Description|Required|
+|---|---|---|---|---|
+|\`file\`|The path to the TypeScript or JavaScript file holding the function to execute.|Yes|
+|\`args\`|A list of arguments to pass to the function. These arguments are passed in the |No|
+
+
# build Command - Medusa CLI Reference
Create a standalone build of the Medusa application.
@@ -32805,22 +33090,6 @@ By default, the Medusa Admin is built to the `.medusa/server/public/admin` direc
If you want a separate build to host the admin standalone, such as on Vercel, pass the `--admin-only` option as explained in the [Options](#options) section. This outputs the admin to the `.medusa/admin` directory instead.
-# develop Command - Medusa CLI Reference
-
-Start Medusa application in development. This command watches files for any changes, then rebuilds the files and restarts the Medusa application.
-
-```bash
-npx medusa develop
-```
-
-## Options
-
-|Option|Description|Default|
-|---|---|---|---|---|
-|\`-H \\`|Set host of the Medusa server.|\`localhost\`|
-|\`-p \\`|Set port of the Medusa server.|\`9000\`|
-
-
# db Commands - Medusa CLI Reference
Commands starting with `db:` perform actions on the database.
@@ -32941,6 +33210,22 @@ npx medusa db:sync-links
|\`--execute-all\`|Skip prompts when syncing links and execute all (including unsafe) actions.|No|Prompts are shown for unsafe actions, by default.|
+# develop Command - Medusa CLI Reference
+
+Start Medusa application in development. This command watches files for any changes, then rebuilds the files and restarts the Medusa application.
+
+```bash
+npx medusa develop
+```
+
+## Options
+
+|Option|Description|Default|
+|---|---|---|---|---|
+|\`-H \\`|Set host of the Medusa server.|\`localhost\`|
+|\`-p \\`|Set port of the Medusa server.|\`9000\`|
+
+
# new Command - Medusa CLI Reference
Create a new Medusa application. Unlike the `create-medusa-app` CLI tool, this command provides more flexibility for experienced Medusa developers in creating and configuring their project.
@@ -33031,39 +33316,6 @@ npx medusa plugin:build
```
-# start Command - Medusa CLI Reference
-
-Start the Medusa application in production.
-
-```bash
-npx medusa start
-```
-
-## Options
-
-|Option|Description|Default|
-|---|---|---|---|---|
-|\`-H \\`|Set host of the Medusa server.|\`localhost\`|
-|\`-p \\`|Set port of the Medusa server.|\`9000\`|
-|\`--cluster \\`|Start Medusa's Node.js server in |Cluster mode is disabled by default. If the option is passed but no number is passed, Medusa will try to consume all available CPU cores.|
-
-
-# exec Command - Medusa CLI Reference
-
-Run a custom CLI script. Learn more about it in [this guide](https://docs.medusajs.com/docs/learn/fundamentals/custom-cli-scripts/index.html.md).
-
-```bash
-npx medusa exec [file] [args...]
-```
-
-## Arguments
-
-|Argument|Description|Required|
-|---|---|---|---|---|
-|\`file\`|The path to the TypeScript or JavaScript file holding the function to execute.|Yes|
-|\`args\`|A list of arguments to pass to the function. These arguments are passed in the |No|
-
-
# user Command - Medusa CLI Reference
Create a new admin user.
@@ -33083,6 +33335,23 @@ npx medusa user --email [--password ]
If ran successfully, you'll receive the invite token in the output.|No|\`false\`|
+# start Command - Medusa CLI Reference
+
+Start the Medusa application in production.
+
+```bash
+npx medusa start
+```
+
+## Options
+
+|Option|Description|Default|
+|---|---|---|---|---|
+|\`-H \\`|Set host of the Medusa server.|\`localhost\`|
+|\`-p \\`|Set port of the Medusa server.|\`9000\`|
+|\`--cluster \\`|Start Medusa's Node.js server in |Cluster mode is disabled by default. If the option is passed but no number is passed, Medusa will try to consume all available CPU cores.|
+
+
# telemetry Command - Medusa CLI Reference
Enable or disable the collection of anonymous data usage. If no option is provided, the command enables the collection of anonymous data usage.
@@ -42238,6 +42507,1876 @@ For a quick access to code snippets of the different concepts you learned about,
Deployment guides are a collection of guides that help you deploy your Medusa server and admin to different platforms. Learn more in the [Deployment Overview](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/deployment/index.html.md) documentation.
+# Implement Product Reviews in Medusa
+
+In this tutorial, you'll learn how to implement product reviews in Medusa.
+
+When you install a Medusa application, you get a fully-fledged commerce platform with a Framework for customization. The Medusa application's commerce features are built around [Commerce Modules](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/index.html.md) which are available out-of-the-box. The features include product-management features.
+
+Medusa doesn't provide product reviews out-of-the-box, but the Medusa Framework facilitates implementing customizations like product reviews. In this tutorial, you'll learn how to customize the Medusa server, Admin dashboard, and Next.js Starter Storefront to implement product reviews.
+
+You can follow this guide whether you're new to Medusa or an advanced Medusa developer.
+
+## Summary
+
+By following this tutorial, you'll learn how to:
+
+- Install and set up Medusa.
+- Define product reviews models and implement their management features in the Medusa server.
+- Customize the Medusa Admin to allow merchants to view and manage product reviews.
+- Customize the Next.js storefront to display product reviews and allow customers to submit reviews.
+
+
+
+- [Product Reviews Repository](https://github.com/medusajs/examples/tree/main/product-reviews): Find the full code for this guide in this repository.
+- [OpenApi Specs for Postman](https://res.cloudinary.com/dza7lstvk/raw/upload/v1741941475/OpenApi/product-reviews_jh8ohj.yaml): Import this OpenApi Specs file into tools like Postman.
+
+***
+
+## Step 1: Install a Medusa Application
+
+### Prerequisites
+
+- [Node.js v20+](https://nodejs.org/en/download)
+- [Git CLI tool](https://git-scm.com/downloads)
+- [PostgreSQL](https://www.postgresql.org/download/)
+
+Start by installing the Medusa application on your machine with the following command:
+
+```bash
+npx create-medusa-app@latest
+```
+
+You'll first be asked for the project's name. Then, when asked whether you want to install the [Next.js starter storefront](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/nextjs-starter/index.html.md), choose Yes.
+
+Afterwards, the installation process will start, which will install the Medusa application in a directory with your project's name, and the Next.js Starter Storefront in a separate directory with the `{project-name}-storefront` name.
+
+The Medusa application is composed of a headless Node.js server and an admin dashboard. The storefront is installed or custom-built separately and connects to the Medusa application through its REST endpoints, called [API routes](https://docs.medusajs.com/docs/learn/fundamentals/api-routes/index.html.md). Learn more in [Medusa's Architecture documentation](https://docs.medusajs.com/docs/learn/introduction/architecture/index.html.md).
+
+Once the installation finishes successfully, the Medusa Admin dashboard will open with a form to create a new user. Enter the user's credentials and submit the form. Afterwards, you can log in with the new user and explore the dashboard.
+
+Check out the [troubleshooting guides](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/troubleshooting/create-medusa-app-errors/index.html.md) for help.
+
+***
+
+## Step 2: Add Product Review Module
+
+In Medusa, you can build custom features in a [module](https://docs.medusajs.com/docs/learn/fundamentals/modules/index.html.md). A module is a reusable package with functionalities related to a single feature or domain. Medusa integrates the module into your application without implications or side effects on your setup.
+
+In the module, you define the data models necessary for a feature and the logic to manage these data models. Later, you can build commerce flows around your module.
+
+In this step, you'll build a Product Review Module that defines the necessary data models to store and manage product reviews.
+
+Refer to the [Modules documentation](https://docs.medusajs.com/docs/learn/fundamentals/modules/index.html.md) to learn more.
+
+### Create Module Directory
+
+A module is created under the `src/modules` directory of your Medusa application. So, create the directory `src/modules/product-review`.
+
+### Create Data Models
+
+A data model represents a table in the database. You create data models using Medusa's Data Model Language (DML). It simplifies defining a table's columns, relations, and indexes with straightforward methods and configurations.
+
+Refer to the [Data Models documentation](https://docs.medusajs.com/docs/learn/fundamentals/modules#1-create-data-model/index.html.md) to learn more.
+
+For the Product Review Module, you need to define a `Review` data model that represents a product review. So, create the file `src/modules/product-review/models/review.ts` with the following content:
+
+```ts title="src/modules/product-review/models/review.ts"
+import { model } from "@medusajs/framework/utils"
+
+const Review = model.define("review", {
+ id: model.id().primaryKey(),
+ title: model.text().nullable(),
+ content: model.text(),
+ rating: model.float(),
+ first_name: model.text(),
+ last_name: model.text(),
+ status: model.enum(["pending", "approved", "rejected"]).default("pending"),
+ product_id: model.text().index("IDX_REVIEW_PRODUCT_ID"),
+ customer_id: model.text().nullable(),
+})
+.checks([
+ {
+ name: "rating_range",
+ expression: (columns) => `${columns.rating} >= 1 AND ${columns.rating} <= 5`,
+ },
+])
+
+export default Review
+```
+
+You define the `Review` data model using the `model.define` method of the DML. It accepts the data model's table name as a first parameter, and the model's schema object as a second parameter.
+
+The `Review` data model has the following properties:
+
+- `id`: A unique ID for the review.
+- `title`: The review's title.
+- `content`: The review's content.
+- `rating`: The review's rating. You also add a [check constraint](https://docs.medusajs.com/docs/learn/fundamentals/data-models/check-constraints/index.html.md) to ensure the rating is between 1 and 5.
+- `first_name`: The first name of the reviewer.
+- `last_name`: The last name of the reviewer.
+- `status`: The review's status, which can be `pending`, `approved`, or `rejected`.
+- `product_id`: The ID of the product the review is for.
+- `customer_id`: The ID of the customer who submitted the review.
+
+Learn more about defining data model properties in the [Property Types documentation](https://docs.medusajs.com/docs/learn/fundamentals/data-models/properties/index.html.md).
+
+### Create Module's Service
+
+You now have the necessary data model in the Review Module, but you'll need to manage its records. You do this by creating a service in the module.
+
+A service is a TypeScript or JavaScript class that the module exports. In the service's methods, you can connect to the database, allowing you to manage your data models, or connect to a third-party service, which is useful if you're integrating with external services.
+
+Refer to the [Module Service documentation](https://docs.medusajs.com/docs/learn/fundamentals/modules#2-create-service/index.html.md) to learn more.
+
+To create the Review Module's service, create the file `src/modules/product-review/service.ts` with the following content:
+
+```ts title="src/modules/product-review/service.ts"
+import { MedusaService } from "@medusajs/framework/utils"
+import Review from "./models/review"
+
+class ProductReviewModuleService extends MedusaService({
+ Review,
+}) {
+}
+
+export default ProductReviewModuleService
+```
+
+The `ProductReviewModuleService` extends `MedusaService` from the Modules SDK which generates a class with data-management methods for your module's data models. This saves you time on implementing Create, Read, Update, and Delete (CRUD) methods.
+
+So, the `ProductReviewModuleService` class now has methods like `createReviews` and `retrieveReview`.
+
+Find all methods generated by the `MedusaService` in [the Service Factory reference](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/service-factory-reference/index.html.md).
+
+You'll use this service later when you implement custom flows for product reviews.
+
+### Export Module Definition
+
+The final piece to a module is its definition, which you export in an `index.ts` file at its root directory. This definition tells Medusa the name of the module and its service.
+
+So, create the file `src/modules/product-review/index.ts` with the following content:
+
+```ts title="src/modules/product-review/index.ts"
+import { Module } from "@medusajs/framework/utils"
+import ProductReviewModuleService from "./service"
+
+export const PRODUCT_REVIEW_MODULE = "productReview"
+
+export default Module(PRODUCT_REVIEW_MODULE, {
+ service: ProductReviewModuleService,
+})
+```
+
+You use the `Module` function from the Modules SDK to create the module's definition. It accepts two parameters:
+
+1. The module's name, which is `productReview`.
+2. An object with a required property `service` indicating the module's service.
+
+You also export the module's name as `PRODUCT_REVIEW_MODULE` so you can reference it later.
+
+### Add Module to Medusa's Configurations
+
+Once you finish building the module, add it to Medusa's configurations to start using it.
+
+In `medusa-config.ts`, add a `modules` property and pass an array with your custom module:
+
+```ts title="medusa-config.ts"
+module.exports = defineConfig({
+ // ...
+ modules: [
+ {
+ resolve: "./src/modules/product-review",
+ },
+ ],
+})
+```
+
+Each object in the `modules` array has a `resolve` property, whose value is either a path to the module's directory, or an `npm` package’s name.
+
+### Generate Migrations
+
+Since data models represent tables in the database, you define how they're created in the database with migrations. A migration is a TypeScript or JavaScript file that defines database changes made by a module.
+
+Refer to the [Migrations documentation](https://docs.medusajs.com/docs/learn/fundamentals/modules#5-generate-migrations/index.html.md) to learn more.
+
+Medusa's CLI tool can generate the migrations for you. To generate a migration for the Review Module, run the following command in your Medusa application's directory:
+
+```bash
+npx medusa db:generate productReview
+```
+
+The `db:generate` command of the Medusa CLI accepts the name of the module to generate the migration for. You'll now have a `migrations` directory under `src/modules/product-review` that holds the generated migration.
+
+Then, to reflect these migrations on the database, run the following command:
+
+```bash
+npx medusa db:migrate
+```
+
+The table for the `Review` data model is now created in the database.
+
+***
+
+## Step 3: Define Review \<> Product Link
+
+When you defined the `Review` data model, you added properties that store the ID of records managed by other modules. For example, the `product_id` property stores the ID of the product this review is for, but products are managed by the [Product Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/product/index.html.md).
+
+Medusa integrates modules into your application without implications or side effects by isolating modules from one another. This means you can't directly create relationships between data models in your module and data models in other modules.
+
+Instead, Medusa provides the mechanism to define links between data models, and retrieve and manage linked records while maintaining module isolation. Links are useful to define associations between data models in different modules, or extend a model in another module to associate custom properties with it.
+
+Refer to the [Module Isolation documentation](https://docs.medusajs.com/docs/learn/fundamentals/modules/isolation/index.html.md) to learn more.
+
+In this step, you'll define a link between the Product Review Module's `Review` data model, and the Product Module's `Product` data model. You'll then use this link to retrieve the product associated with a review.
+
+You can also define a link between the `Review` data model and the `Customer` data model to retrieve the customer who submitted the review in a similar manner.
+
+You can define links between data models in a TypeScript or JavaScript file under the `src/links` directory. So, create the file `src/links/review-product.ts` with the following content:
+
+```ts title="src/links/review-product.ts"
+import { defineLink } from "@medusajs/framework/utils"
+import ProductReviewModule from "../modules/product-review"
+import ProductModule from "@medusajs/medusa/product"
+
+export default defineLink(
+ {
+ linkable: ProductReviewModule.linkable.review,
+ field: "product_id",
+ isList: false,
+ },
+ ProductModule.linkable.product,
+ {
+ readOnly: true,
+ }
+)
+```
+
+You define a link using the `defineLink` function from the Modules SDK. It accepts three parameters:
+
+1. An object indicating the first data model part of the link. A module has a special `linkable` property that contains link configurations for its data models. So, you can pass the link configurations for the `Review` data model from the Product Review module, specifying that its `product_id` property holds the ID of the linked record. You also specify `isList` as `false` since a review can only have one product.
+2. An object indicating the second data model part of the link. You pass the linkable configurations of the Product Module's `Product` data model.
+3. An optional object with additional configurations for the link. By default, Medusa creates a table in the database to represent the link you define. However, when you only want to retrieve the linked records without managing and storing the links, you can set the `readOnly` option to `true`.
+
+You can now retrieve the product of a review, as you'll see in later steps.
+
+***
+
+## Step 4: Create Review Workflow
+
+You're now ready to start implementing product-review features. The first one you'll implement is the ability for customers to create a product review.
+
+To build custom commerce features in Medusa, you create a [workflow](https://docs.medusajs.com/docs/learn/fundamentals/workflows/index.html.md). A workflow is a series of queries and actions, called steps, that complete a task. You construct a workflow like you construct a function, but it's a special function that allows you to track its executions' progress, define roll-back logic, and configure other advanced features. Then, you execute the workflow from other customizations, such as in an endpoint.
+
+So, in this section, you'll learn how to create a workflow that creates a review. Later, you'll execute this workflow in an API route.
+
+Learn more about workflows in the [Workflows documentation](https://docs.medusajs.com/docs/learn/fundamentals/workflows/index.html.md).
+
+The workflow will have the following steps:
+
+- [useQueryGraphStep](https://docs.medusajs.com/references/helper-steps/useQueryGraphStep/index.html.md): Retrieve the product to confirm it exists.
+- [createReviewStep](#createReviewStep): Create the review.
+
+The `useQueryGraphStep` step is provided by Medusa in its `@medusajs/medusa/core-flows` package. So, you only need to implement the `createReviewStep` step.
+
+### createReviewStep
+
+In the second step of the workflow, you create the review. To create a step, create the file `src/workflows/steps/create-review.ts` with the following content:
+
+```ts title="src/workflows/steps/create-review.ts" highlights={createReviewHighlights}
+import {
+ createStep,
+ StepResponse,
+} from "@medusajs/framework/workflows-sdk"
+import { PRODUCT_REVIEW_MODULE } from "../../modules/product-review"
+import ProductReviewModuleService from "../../modules/product-review/service"
+
+export type CreateReviewStepInput = {
+ title?: string
+ content: string
+ rating: number
+ product_id: string
+ customer_id?: string
+ first_name: string
+ last_name: string
+ status?: "pending" | "approved" | "rejected"
+}
+
+export const createReviewStep = createStep(
+ "create-review",
+ async (input: CreateReviewStepInput, { container }) => {
+ const reviewModuleService: ProductReviewModuleService = container.resolve(
+ PRODUCT_REVIEW_MODULE
+ )
+
+ const review = await reviewModuleService.createReviews(input)
+
+ return new StepResponse(review, review.id)
+ },
+ async (reviewId, { container }) => {
+ if (!reviewId) {
+ return
+ }
+
+ const reviewModuleService: ProductReviewModuleService = container.resolve(
+ PRODUCT_REVIEW_MODULE
+ )
+
+ await reviewModuleService.deleteReviews(reviewId)
+ }
+)
+```
+
+You create a step with `createStep` from the Workflows SDK. It accepts two parameters:
+
+1. The step's unique name, which is `create-review`.
+2. An async function that receives two parameters:
+ - The step's input, which is in this case an object with the review's properties.
+ - An object that has properties including the [Medusa container](https://docs.medusajs.com/docs/learn/fundamentals/medusa-container/index.html.md), which is a registry of Framework and commerce tools that you can access in the step.
+
+In the step function, you resolve the Review Module's service from the Medusa container using its `resolve` method, passing it the module's name as a parameter.
+
+Then, you create the review using the `createReviews` method. As you remember, the Review Module's service extends the `MedusaService` which generates data-management methods for you.
+
+A step function must return a `StepResponse` instance. The `StepResponse` constructor accepts two parameters:
+
+1. The step's output, which is the review created.
+2. Data to pass to the step's compensation function.
+
+#### Compensation Function
+
+The compensation function undoes the actions performed in a step. Then, if an error occurs during the workflow's execution, the compensation functions of executed steps are called to roll back the changes. This mechanism ensures data consistency in your application, especially as you integrate external systems.
+
+The compensation function accepts two parameters:
+
+1. The data passed from the step in the second parameter of `StepResponse`, which in this case is the ID of the created review.
+2. An object that has properties including the [Medusa container](https://docs.medusajs.com/docs/learn/fundamentals/medusa-container/index.html.md).
+
+In the compensation function, you resolve the Review Module's service from the Medusa container and call the `deleteReviews` method to delete the review created in the step.
+
+### Add createReviewWorkflow
+
+You can now create the workflow using the step provided by Medusa and your custom step.
+
+To create the workflow, create the file `src/workflows/create-review.ts` with the following content:
+
+```ts title="src/workflows/create-review.ts"
+import {
+ createWorkflow,
+ WorkflowResponse,
+} from "@medusajs/framework/workflows-sdk"
+import { createReviewStep } from "./steps/create-review"
+import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
+
+type CreateReviewInput = {
+ title?: string
+ content: string
+ rating: number
+ product_id: string
+ customer_id?: string
+ first_name: string
+ last_name: string
+ status?: "pending" | "approved" | "rejected"
+}
+
+export const createReviewWorkflow = createWorkflow(
+ "create-review",
+ (input: CreateReviewInput) => {
+ // Check product exists
+ // @ts-ignore
+ useQueryGraphStep({
+ entity: "product",
+ fields: ["id"],
+ filters: {
+ id: input.product_id,
+ },
+ options: {
+ throwIfKeyNotFound: true,
+ },
+ })
+
+ // Create the review
+ const review = createReviewStep(input)
+
+ // @ts-ignore
+ return new WorkflowResponse({
+ review,
+ })
+ }
+)
+```
+
+You create a workflow using `createWorkflow` from the Workflows SDK. It accepts the workflow's unique name as a first parameter.
+
+It accepts as a second parameter a constructor function, which is the workflow's implementation. The function can accept input, which in this case is an object of the review's details.
+
+In the workflow's constructor function, you:
+
+- use `useQueryGraphStep` to retrieve the product. By setting the `options.throwIfKeyNotFound` to `true`, the step throws an error if the product doesn't exist.
+- Call the `createReviewStep` step to create the review.
+
+`useQueryGraphStep` uses [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), which allows you to retrieve data across modules. For example, in the above snippet you're retrieving the cart's promotions, which are managed in the [Promotion Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/promotion/index.html.md), by passing `promotions.code` to the `fields` array.
+
+A workflow must return an instance of `WorkflowResponse`. The `WorkflowResponse` constructor accepts the workflow's output as a parameter, which is an object holding the created review in this case.
+
+In the next step, you'll learn how to execute this workflow in an API route.
+
+***
+
+## Step 5: Create Review API Route
+
+Now that you have the logic to create a product review, you need to expose it so that frontend clients, such as a storefront, can use it. You do this by creating an [API route](https://docs.medusajs.com/docs/learn/fundamentals/api-routes/index.html.md).
+
+An API Route is an endpoint that exposes commerce features to external applications and clients, such as storefronts. You'll create an API route at the path `/store/reviews` that executes the workflow from the previous step.
+
+Learn more about API routes in [this documentation](https://docs.medusajs.com/docs/learn/fundamentals/api-routes/index.html.md).
+
+### Implement API Route
+
+An API route is created in a `route.ts` file under a sub-directory of the `src/api` directory. The path of the API route is the file's path relative to `src/api`.
+
+So, to create an API route at the path `/store/reviews`, create the file `src/api/store/reviews/route.ts` with the following content:
+
+```ts title="src/api/store/reviews/route.ts" highlights={PostStoreReviewHighlights}
+import type {
+ AuthenticatedMedusaRequest,
+ MedusaResponse,
+} from "@medusajs/framework/http"
+import { createReviewWorkflow } from "../../../workflows/create-review"
+
+import { z } from "zod"
+
+export const PostStoreReviewSchema = z.object({
+ title: z.string().optional(),
+ content: z.string(),
+ rating: z.preprocess(
+ (val) => {
+ if (val && typeof val === "string") {
+ return parseInt(val)
+ }
+ return val
+ },
+ z.number().min(1).max(5)
+ ),
+ product_id: z.string(),
+ first_name: z.string(),
+ last_name: z.string(),
+})
+
+type PostStoreReviewReq = z.infer
+
+export const POST = async (
+ req: AuthenticatedMedusaRequest,
+ res: MedusaResponse
+) => {
+ const input = req.validatedBody
+
+ const { result } = await createReviewWorkflow(req.scope)
+ .run({
+ input: {
+ ...input,
+ customer_id: req.auth_context?.actor_id,
+ },
+ })
+
+ res.json(result)
+}
+```
+
+You first define a [Zod](https://zod.dev/) schema for the request body of the API route. You'll later use this schema to enforce validation on the API route.
+
+Then, since you export a `POST` function, you're exposing a `POST` API route at the path `/store/reviews`. The route handler function accepts two parameters:
+
+1. A request object with details and context on the request, such as body parameters or authenticated customer details.
+2. A response object to manipulate and send the response.
+
+`AuthenticatedMedusaRequest` accepts the request body's type as a type argument.
+
+In the route handler, you execute the `createReviewWorkflow` workflow by invoking it, passing it the Medusa container (which is stored in the `scope` property of a request object). Then, you call its `run` method, passing to the workflow the request body as input.
+
+### Apply Validation and Authentication Middlewares
+
+Now that you have the API route, you need to enforce validation of the request body, and require authentication to access the route. You can do this with a middleware. A middleware is a function executed when a request is sent to an API Route. It's executed before the route handler.
+
+Learn more about middleware in the [Middlewares documentation](https://docs.medusajs.com/docs/learn/fundamentals/api-routes/middlewares/index.html.md).
+
+Middlewares are created in the `src/api/middlewares.ts` file. So create the file `src/api/middlewares.ts` with the following content:
+
+```ts title="src/api/middlewares.ts"
+import {
+ defineMiddlewares,
+ authenticate,
+ validateAndTransformBody,
+} from "@medusajs/framework/http"
+import { PostStoreReviewSchema } from "./store/reviews/route"
+
+
+export default defineMiddlewares({
+ routes: [
+ {
+ method: ["POST"],
+ matcher: "/store/reviews",
+ middlewares: [
+ authenticate("customer", ["session", "bearer"]),
+ validateAndTransformBody(PostStoreReviewSchema),
+ ],
+ },
+ ],
+})
+```
+
+To export the middlewares, you use the `defineMiddlewares` function. It accepts an object having a `routes` property, whose value is an array of middleware route objects. Each middleware route object has the following properties:
+
+- `method`: The HTTP methods the middleware applies to, which is in this case `POST`.
+- `matcher`: The path of the route the middleware applies to.
+- `middlewares`: An array of middleware functions to apply to the route. In this case, you apply two middlewares:
+ - `authenticate`: ensures the request is authenticated as a customer with a session or bearer token.
+ - `validateAndTransformBody`: validates that the request body parameters match the Zod schema passed as a parameter.
+
+The create product review route is now ready for use.
+
+### Test the API Route
+
+To test out the API route, start the Medusa application:
+
+```bash npm2yarn
+npm run dev
+```
+
+Then, open the Medusa Admin dashboard at `http://localhost:9000/app` and login using the credentials you set up earlier.
+
+#### Retrieve Publishable API Key
+
+All requests sent to routes starting with `/store` must have a publishable API key in their header. This ensures that the request is scoped to a specific sales channel of your storefront.
+
+To learn more about publishable API keys, refer to the [Publishable API Key documentation](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/sales-channel/publishable-api-keys/index.html.md).
+
+To retrieve the publishable API key from the Medusa Admin, refer to [this user guide](https://docs.medusajs.com/user-guide/settings/developer/publishable-api-keys/index.html.md).
+
+#### Retrieve Customer Authentication Token
+
+As mentioned before, the API route you added requires the customer to be authenticated. So, you'll first create a customer, then retrieve their authentication token to use in the request.
+
+Before creating the customer, retrieve a registration token using the [Retrieve Registration JWT Token API route](https://docs.medusajs.com/api/store#auth_postactor_typeauth_provider_register):
+
+```bash
+curl -X POST 'http://localhost:9000/auth/customer/emailpass/register' \
+-H 'Content-Type: application/json' \
+--data-raw '{
+ "email": "customer@gmail.com",
+ "password": "supersecret"
+}'
+```
+
+Make sure to replace the email and password with the credentials you want.
+
+Then, register the customer using the [Create Customer API route](https://docs.medusajs.com/api/store#customers_postcustomers):
+
+```bash
+curl -X POST 'http://localhost:9000/store/customers' \
+-H 'Authorization: Bearer {token}' \
+-H 'Content-Type: application/json' \
+-H 'x-publishable-api-key: {your_publishable_api_key}' \
+--data-raw '{
+ "email": "customer@gmail.com"
+}'
+```
+
+Make sure to replace:
+
+- `{token}` with the registration token you received from the previous request.
+- `{your_publishable_api_key}` with the publishable API key you retrieved from the Medusa Admin.
+
+Also, if you changed the email in the first request, make sure to change it here as well.
+
+The customer is now registered. Lastly, you need to retrieve its authenticated token by sending a request to the [Authenticate Customer API route](https://docs.medusajs.com/api/store#auth_postactor_typeauth_provider):
+
+```bash
+curl -X POST 'http://localhost:9000/auth/customer/emailpass' \
+-H 'Content-Type: application/json' \
+--data-raw '{
+ "email": "customer@gmail.com",
+ "password": "supersecret"
+}'
+```
+
+Copy the returned token to use it in the next requests.
+
+#### Retrieve Product ID
+
+Before creating a review, you need the ID of a product. You can either copy one from the Medusa Admin, or send the following request:
+
+```bash
+curl 'http://localhost:9000/store/products' \
+-H 'x-publishable-api-key: {your_publishable_api_key}'
+```
+
+Make sure to replace `{your_publishable_api_key}` with the publishable API key you retrieved from the Medusa Admin.
+
+#### Create a Review
+
+You can now create a review for the product you chose. To do that, send the following request:
+
+```bash
+curl --location 'http://localhost:9000/store/reviews' \
+--header 'x-publishable-api-key: {your_publishable_api_key}' \
+--header 'Content-Type: application/json' \
+-H 'Authorization: Bearer {token}' \
+--data '{
+ "product_id": "{product_id}",
+ "title": "Really good",
+ "content": "The material is nice",
+ "rating": 5,
+ "first_name": "John",
+ "last_name": "Smith"
+}'
+```
+
+Make sure to replace:
+
+- `{your_publishable_api_key}` with the publishable API key you retrieved from the Medusa Admin.
+- `{token}` with the authentication token you retrieved from the previous request.
+- `{product_id}` with the ID of the product you chose.
+
+If the request is successful, you'll receive a response with the created review. Notice that the review is in the `pending` status. In the upcoming steps, you'll allow admin users to approve or reject reviews.
+
+***
+
+## Step 6: List Reviews Admin API Route
+
+In this step, you'll create an API route that lists the reviews of a product. You'll use this route in the Medusa Admin customizations to allow admin users to view and manage product reviews.
+
+### Create API Route
+
+To create the API route that retrieves a paginated list of reviews, create the file `src/api/admin/reviews/route.ts` with the following content:
+
+```ts title="src/api/admin/reviews/route.ts" highlights={GetAdminReviewsHighlights}
+import {
+ MedusaRequest,
+ MedusaResponse,
+} from "@medusajs/framework/http"
+import { createFindParams } from "@medusajs/medusa/api/utils/validators"
+
+export const GetAdminReviewsSchema = createFindParams()
+
+export const GET = async (
+ req: MedusaRequest,
+ res: MedusaResponse
+) => {
+ const query = req.scope.resolve("query")
+
+ const {
+ data: reviews,
+ metadata: { count, take, skip } = {
+ count: 0,
+ take: 20,
+ skip: 0,
+ },
+ } = await query.graph({
+ entity: "review",
+ ...req.queryConfig,
+ })
+
+ res.json({
+ reviews,
+ count,
+ limit: take,
+ offset: skip,
+ })
+}
+```
+
+You first define a `GetAdminReviewsSchema` schema that will allow clients to pass the following query parameters:
+
+- `limit`: The number of reviews to retrieve.
+- `offset`: The number of items to skip before retrieving the reviews.
+- `order`: The fields to sort the reviews by in ascending or descending order.
+
+Then, you export a `GET` function, which exposes a `GET` API Route at the path `/admin/reviews`. In the route handler you resolve [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md) from the Medusa container, which allows you to retrieve data across modules.
+
+Next, you retrieve all reviews using Query. Notice that you pass in `query.graph` the `req.queryConfig` object. This object holds the fields to retrieve and the pagination configurations.
+
+Finally, you return the reviews with pagination fields.
+
+### Apply Query Configurations Middleware
+
+After adding the API route, you need to add a middleware that validates the query parameters passed to the request, and sets the default Query configurations.
+
+Routes starting with `/admin` are protected by default. So, you don't need to add the `authenticate` middleware to enforce authentication.
+
+In `src/api/middlewares.ts`, add a new middleware:
+
+```ts title="src/api/middlewares.ts"
+// other imports...
+import {
+ validateAndTransformQuery,
+} from "@medusajs/framework/http"
+import { GetAdminReviewsSchema } from "./admin/reviews/route"
+
+export default defineMiddlewares({
+ routes: [
+ {
+ matcher: "/admin/reviews",
+ method: ["GET"],
+ middlewares: [
+ validateAndTransformQuery(GetAdminReviewsSchema, {
+ isList: true,
+ defaults: [
+ "id",
+ "title",
+ "content",
+ "rating",
+ "product_id",
+ "customer_id",
+ "status",
+ "created_at",
+ "updated_at",
+ "product.*",
+ ],
+ }),
+ ],
+ },
+ ],
+})
+```
+
+You use the `validateAndTransformQuery` middleware to enforce validation on the query parameters passed to the request. The middleware accepts two parameters:
+
+- The Zod schema to validate the query parameters, which is the `GetAdminReviewsSchema` schema you defined earlier.
+- The Query configurations, which is an object with the following properties:
+ - `isList`: A boolean that indicates whether the query is a list query.
+ - `defaults`: An array of fields to retrieve by default.
+
+You'll test the API route as you customize the Medusa Admin in the next step.
+
+You pass `product.*` in the fields to retrieve, allowing you to retrieve the product associated with each review. This is possible because you defined a link between the `Review` data model and the `Product` data model in a previous step.
+
+***
+
+## Step 7: Add Reviews UI Route
+
+Now that you have an API route that retrieves reviews, you'll customize the Medusa Admin to add a new "Reviews" page by creating a [UI Route](https://docs.medusajs.com/docs/learn/fundamentals/admin/ui-routes/index.html.md).
+
+A UI route is a React component that specifies the content to be shown in a new page in the Medusa Admin dashboard. You'll create a UI route to display the list of reviews in the Medusa Admin.
+
+Learn more about UI routes in the [UI Routes documentation](https://docs.medusajs.com/docs/learn/fundamentals/admin/ui-routes/index.html.md).
+
+### Configure JS SDK
+
+Medusa provides a [JS SDK](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/js-sdk/index.html.md) that you can use to send requests to the Medusa server from any client application, including your Medusa Admin customizations.
+
+The JS SDK is installed by default in your Medusa application. To configure it, create the file `src/admin/lib/sdk.ts` with the following content:
+
+```ts title="src/admin/lib/sdk.ts"
+import Medusa from "@medusajs/js-sdk"
+
+export const sdk = new Medusa({
+ baseUrl: "http://localhost:9000",
+ debug: process.env.NODE_ENV === "development",
+ auth: {
+ type: "session",
+ },
+})
+```
+
+You create an instance of the JS SDK using the `Medusa` class from the JS SDK. You pass it an object having the following properties:
+
+- `baseUrl`: The base URL of the Medusa server.
+- `debug`: A boolean indicating whether to log debug information into the console.
+- `auth`: An object specifying the authentication type. When using the JS SDK for admin customizations, you use the `session` authentication type.
+
+### Create UI Route
+
+You'll now create the UI Route that lists the reviews. To do this, create the file `src/admin/routes/reviews/page.tsx` with the following content:
+
+```tsx title="src/admin/routes/reviews/page.tsx" highlights={listUIRoutesHighlight1} collapsibleLines="1-18" expandButtonLabel="Show Imports"
+import { defineRouteConfig } from "@medusajs/admin-sdk"
+import { ChatBubbleLeftRight } from "@medusajs/icons"
+import {
+ createDataTableColumnHelper,
+ Container,
+ DataTable,
+ useDataTable,
+ Heading,
+ StatusBadge,
+ Toaster,
+ DataTablePaginationState,
+} from "@medusajs/ui"
+import { useQuery } from "@tanstack/react-query"
+import { useMemo, useState } from "react"
+import { sdk } from "../../lib/sdk"
+import { HttpTypes } from "@medusajs/framework/types"
+import { Link } from "react-router-dom"
+
+type Review = {
+ id: string
+ title?: string
+ content: string
+ rating: number
+ product_id: string
+ customer_id?: string
+ status: "pending" | "approved" | "rejected"
+ created_at: Date
+ updated_at: Date
+ product?: HttpTypes.AdminProduct
+ customer?: HttpTypes.AdminCustomer
+}
+
+
+const columnHelper = createDataTableColumnHelper()
+
+const columns = [
+ columnHelper.accessor("id", {
+ header: "ID",
+ }),
+ columnHelper.accessor("title", {
+ header: "Title",
+ }),
+ columnHelper.accessor("rating", {
+ header: "Rating",
+ }),
+ columnHelper.accessor("content", {
+ header: "Content",
+ }),
+ columnHelper.accessor("status", {
+ header: "Status",
+ cell: ({ row }) => {
+ const color = row.original.status === "approved" ?
+ "green" : row.original.status === "rejected"
+ ? "red" : "grey"
+ return (
+
+ {row.original.status.charAt(0).toUpperCase() + row.original.status.slice(1)}
+
+ )
+ },
+ }),
+ columnHelper.accessor("product", {
+ header: "Product",
+ cell: ({ row }) => {
+ return (
+
+ {row.original.product?.title}
+
+ )
+ },
+ }),
+]
+
+// TODO add component
+```
+
+Before defining the component, you define a `Review` type, then define the columns of the table you'll show on the page.
+
+To display the table, you'll use the [DataTable](https://docs.medusajs.com/ui/components/data-table/index.html.md) component from Medusa UI. To define the columns of the table, you use the `createDataTableColumnHelper` function from Medusa UI, which returns a `columnHelper` object. You then use the `columnHelper` object to define the table's columns.
+
+Next, you'll add the component that renders the content of the page. Replace the `TODO` with the following:
+
+```tsx title="src/admin/routes/reviews/page.tsx" highlights={reviewsPageHighlights}
+const limit = 15
+
+const ReviewsPage = () => {
+ const [pagination, setPagination] = useState({
+ pageSize: limit,
+ pageIndex: 0,
+ })
+
+ const offset = useMemo(() => {
+ return pagination.pageIndex * limit
+ }, [pagination])
+
+ const { data, isLoading, refetch } = useQuery<{
+ reviews: Review[]
+ count: number
+ limit: number
+ offset: number
+ }>({
+ queryKey: ["reviews", offset, limit],
+ queryFn: () => sdk.client.fetch("/admin/reviews", {
+ query: {
+ offset: pagination.pageIndex * pagination.pageSize,
+ limit: pagination.pageSize,
+ order: "-created_at",
+ },
+ }),
+ })
+
+ const table = useDataTable({
+ columns,
+ data: data?.reviews || [],
+ rowCount: data?.count || 0,
+ isLoading,
+ pagination: {
+ state: pagination,
+ onPaginationChange: setPagination,
+ },
+ getRowId: (row) => row.id,
+ })
+
+ return (
+
+
+
+
+ Reviews
+
+
+
+
+
+
+
+ )
+}
+
+export const config = defineRouteConfig({
+ label: "Reviews",
+ icon: ChatBubbleLeftRight,
+})
+
+export default ReviewsPage
+```
+
+You create a `ReviewPage` component, which holds the UI route's content. In the component, you:
+
+- Define state variables to configure pagination.
+- Use the `useQuery` hook from `@tanstack/react-query` to fetch the reviews from the API route. In the query function, you use the JS SDK to send a request to the `/admin/reviews` API route. The JS SDK has a `client.fetch` method that has a similar signature to JavaScript's [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API). You can use it to send requests to custom routes.
+- Use the `useDataTable` hook from Medusa UI to create a DataTable instance. You pass the columns, data, and pagination configurations to the hook.
+- Render the DataTable component, passing the DataTable instance to the `instance` prop. You also render the DataTable's toolbar, table, and pagination components.
+
+The file also exports a configuration object created with `defineRouteConfig`. You export this object to tell Medusa that you want to add the new route to the Medusa Admin's sidebar. You specify the sidebar's item and title.
+
+### Test the UI Route
+
+To test out the UI route, start the Medusa application:
+
+```bash npm2yarn
+npm run dev
+```
+
+Then, open the Medusa Admin dashboard at `http://localhost:9000/app` and login using the credentials you set up earlier.
+
+You'll find a new sidebar item `Review`. Click on it to view the list of reviews. In the upcoming steps, you'll add functionality to approve or reject reviews.
+
+
+
+***
+
+## Step 8: Change Review Status API Route
+
+Next, you want to allow the admin user to approve or reject reviews. To do this, you'll create a workflow that updates a review's status, then use it in an API route that exposes the functionality.
+
+### Update Review Step
+
+The workflow to update a review's status will have on step that updates the review. To create the step, create the file `src/workflows/steps/update-review.ts` with the following content:
+
+```ts title="src/workflows/steps/update-review.ts" highlights={updateReviewStepHighlights}
+import {
+ createStep,
+ StepResponse,
+} from "@medusajs/framework/workflows-sdk"
+import { PRODUCT_REVIEW_MODULE } from "../../modules/product-review"
+import ProductReviewModuleService from "../../modules/product-review/service"
+
+export type UpdateReviewsStepInput = {
+ id: string
+ status: "pending" | "approved" | "rejected"
+}[]
+
+export const updateReviewsStep = createStep(
+ "update-review-step",
+ async (input: UpdateReviewsStepInput, { container }) => {
+ const reviewModuleService: ProductReviewModuleService = container.resolve(
+ PRODUCT_REVIEW_MODULE
+ )
+
+ // Get original review before update
+ const originalReviews = await reviewModuleService.listReviews({
+ id: input.map((review) => review.id),
+ })
+
+ const reviews = await reviewModuleService.updateReviews(input)
+
+ return new StepResponse(reviews, originalReviews)
+ },
+ async (originalData, { container }) => {
+ if (!originalData) {
+ return
+ }
+
+ const reviewModuleService: ProductReviewModuleService = container.resolve(
+ PRODUCT_REVIEW_MODULE
+ )
+
+ // Restore original review status
+ await reviewModuleService.updateReviews(originalData)
+ }
+)
+```
+
+This step receives an array of objects, each with the ID of the review to update and its new status.
+
+In the step function, you first retrieve the original reviews before the update. Then, you update the reviews using the `updateReviews` method of the Review Module's service.
+
+After that, you return the updated reviews, and you pass the original reviews to the compensation function.
+
+In the compensation function, you restore the original reviews' status if an error occurs.
+
+### Update Review Workflow
+
+You can now create the workflow that uses the above step to update the review. To create the workflow, create the file `src/workflows/update-review.ts` with the following content:
+
+```ts title="src/workflows/update-review.ts"
+import {
+ createWorkflow,
+ WorkflowResponse,
+} from "@medusajs/framework/workflows-sdk"
+import { updateReviewsStep } from "./steps/update-review"
+
+export type UpdateReviewInput = {
+ id: string
+ status: "pending" | "approved" | "rejected"
+}[]
+
+export const updateReviewWorkflow = createWorkflow(
+ "update-review",
+ (input: UpdateReviewInput) => {
+ const reviews = updateReviewsStep(input)
+
+ return new WorkflowResponse({
+ reviews,
+ })
+ }
+)
+```
+
+The workflow receives an array of objects, each with the ID of the review to update and its new status. It uses the `updateReviewsStep` to update the reviews, then returns the updated reviews.
+
+### Create API Route
+
+Next, you'll create the API route that exposes the workflow's functionality. Create the file `src/api/admin/reviews/status/route.ts` with the following content:
+
+```ts title="src/api/admin/reviews/status/route.ts" highlights={PostAdminUpdateReviewsStatusHighlights}
+import type {
+ MedusaRequest,
+ MedusaResponse,
+} from "@medusajs/framework/http"
+import { updateReviewWorkflow } from "../../../../workflows/update-review"
+import { z } from "zod"
+
+export const PostAdminUpdateReviewsStatusSchema = z.object({
+ ids: z.array(z.string()),
+ status: z.enum(["pending", "approved", "rejected"]),
+})
+
+export async function POST(
+ req: MedusaRequest>,
+ res: MedusaResponse
+) {
+ const { ids, status } = req.validatedBody
+
+ const { result } = await updateReviewWorkflow(req.scope).run({
+ input: ids.map((id) => ({
+ id,
+ status,
+ })),
+ })
+
+ res.json(result)
+}
+```
+
+You first define a Zod schema for the request body of the API route. You'll later use this schema to enforce validation on the API route. The request body must include the following parameters:
+
+- `ids`: An array of review IDs to update.
+- `status`: The new status to set for the reviews.
+
+Then, since you export a `POST` function, you're exposing a `POST` API route at the path `/admin/reviews/status`. In the route handler you execute the `updateReviewWorkflow` workflow, passing it the data from the request body.
+
+Finally, you return the updated reviews.
+
+### Apply Validation Middlewares
+
+The last step is to add the validation middleware that enforces validation the body parameters of requests sent to the API route.
+
+In `src/api/middlewares.ts`, add a new middleware:
+
+```ts title="src/api/middlewares.ts"
+// other imports...
+import { PostAdminUpdateReviewsStatusSchema } from "./admin/reviews/status/route"
+
+export default defineMiddlewares({
+ routes: [
+ // ...
+ {
+ matcher: "/admin/reviews/status",
+ method: ["POST"],
+ middlewares: [
+ validateAndTransformBody(PostAdminUpdateReviewsStatusSchema),
+ ],
+ },
+ ],
+})
+```
+
+You use the `validateAndTransformBody` middleware to enforce validation on an incoming request's body parameters. You pass the Zod schema you defined in the API route's file to the middleware.
+
+In the next step, you'll customize the UI route you added earlier to allow the admin user to approve or reject reviews.
+
+***
+
+## Step 9: Approve and Reject Reviews in UI Route
+
+You'll now customize the UI route you added earlier to allow the admin user to approve or reject reviews. You'll add a checkbox column to the table that allows the admin user to select multiple reviews, then choose to approve or reject them.
+
+The `DataTable` component from Medusa UI supports a command bar that is triggered by a select (or checkbox) column in the table.
+
+Start by adding the necessary imports at the top of `src/admin/routes/reviews/page.tsx`:
+
+```tsx title="src/admin/routes/reviews/page.tsx"
+import {
+ createDataTableCommandHelper,
+ DataTableRowSelectionState,
+} from "@medusajs/ui"
+```
+
+Then, in the `columns` array, add a new select column as the first item in the array:
+
+```tsx title="src/admin/routes/reviews/page.tsx"
+const columns = [
+ columnHelper.select(),
+ // ...
+]
+```
+
+The select column adds a checkbox to each row in the table, allowing the admin user to select multiple reviews.
+
+Next, you need to add the commands that allow the admin user to approve or reject the selected reviews. So, add the following after the `columns` array:
+
+```tsx title="src/admin/routes/reviews/page.tsx" highlights={commandHelperHighlights}
+const commandHelper = createDataTableCommandHelper()
+
+const useCommands = (refetch: () => void) => {
+ return [
+ commandHelper.command({
+ label: "Approve",
+ shortcut: "A",
+ action: async (selection) => {
+ const reviewsToApproveIds = Object.keys(selection)
+
+ sdk.client.fetch("/admin/reviews/status", {
+ method: "POST",
+ body: {
+ ids: reviewsToApproveIds,
+ status: "approved",
+ },
+ }).then(() => {
+ toast.success("Reviews approved")
+ refetch()
+ }).catch(() => {
+ toast.error("Failed to approve reviews")
+ })
+ },
+ }),
+ commandHelper.command({
+ label: "Reject",
+ shortcut: "R",
+ action: async (selection) => {
+ const reviewsToRejectIds = Object.keys(selection)
+
+ sdk.client.fetch("/admin/reviews/status", {
+ method: "POST",
+ body: {
+ ids: reviewsToRejectIds,
+ status: "rejected",
+ },
+ }).then(() => {
+ toast.success("Reviews rejected")
+ refetch()
+ }).catch(() => {
+ toast.error("Failed to reject reviews")
+ })
+ },
+ }),
+ ]
+}
+```
+
+You first initialize the command helper using the `createDataTableCommandHelper` function from Medusa UI. Then, you create a custom hook `useCommands` that returns an array of commands created with the command helper.
+
+You add `Approve` and `Reject` commands, and both of them send a request to the `/admin/reviews/status` API route to update the reviews' status, but each with a different status in the request body.
+
+Next, add the following state variable in the `ReviewsPage` component:
+
+```tsx title="src/admin/routes/reviews/page.tsx"
+const [rowSelection, setRowSelection] = useState({})
+```
+
+This state variable will hold the selected reviews in the table.
+
+Then, call the `useCommands` hook and pass new properties to the `useDataTable` hook:
+
+```tsx title="src/admin/routes/reviews/page.tsx"
+const commands = useCommands(refetch)
+
+const table = useDataTable({
+ // ...
+ commands,
+ rowSelection: {
+ state: rowSelection,
+ onRowSelectionChange: setRowSelection,
+ },
+})
+```
+
+You call the `useCommands` hook and pass it the `refetch` function (returned by `useQuery`). The `refetch` function allows you to refetch the reviews after approving or rejecting them to ensure their status in the table is updated.
+
+Then, you pass the commands and row selection configurations (from the state variables you added) to the `useDataTable` hook.
+
+Finally, in the `return` statement, add the command bar after the pagination component:
+
+```tsx title="src/admin/routes/reviews/page.tsx"
+ `${count} selected`} />
+```
+
+This command bar will show the actions to perform on the selected reviews.
+
+### Test the UI Route
+
+To test out the UI route, start the Medusa application:
+
+```bash npm2yarn
+npm run dev
+```
+
+Then, open the Medusa Admin dashboard and go to the Reviews page. You'll see a new column with checkboxes that allow you to select multiple reviews.
+
+If you try selecting multiple reviews, you'll see a command bar at the bottom center of the page that allows you to approve or reject the selected reviews.
+
+If you choose to approve or reject the reviews, the status of the selected reviews will change, and the table will update to reflect the new status.
+
+
+
+***
+
+## Step 10: List Reviews Store API Route
+
+In the upcoming steps, you'll start customizing the storefront to show the reviews of a product and allow logged-in customers to add reviews.
+
+Before doing that, you need to add an API route that retrieves the list of approved reviews. You'll later show these in the storefront.
+
+### Add Average Rating Method in Service
+
+On the product's page, you want to display the average rating of a product. To do this, you'll add a method that retrieves the average rating of a product's reviews in the Review Module's service.
+
+In `src/modules/product-review/service.ts`, add the following methods to the `ProductReviewModuleService` class:
+
+```ts title="src/modules/product-review/service.ts"
+import { InjectManager, MedusaService, MedusaContext } from "@medusajs/framework/utils"
+import Review from "./models/review"
+import { Context } from "@medusajs/framework/types"
+import { EntityManager } from "@mikro-orm/knex"
+
+class ProductReviewModuleService extends MedusaService({
+ Review,
+}) {
+ @InjectManager()
+ async getAverageRating(
+ productId: string,
+ @MedusaContext() sharedContext?: Context
+ ): Promise {
+ const result = await sharedContext?.manager?.execute(
+ `SELECT AVG(rating) as average
+ FROM review
+ WHERE product_id = '${productId}' AND status = 'approved'`
+ )
+
+ return parseFloat(parseFloat(result?.[0]?.average ?? 0).toFixed(2))
+ }
+}
+
+export default ProductReviewModuleService
+```
+
+To run queries on the database in a service's method, you need to:
+
+- Add the `InjectManager` decorator to the method.
+- Pass as the last parameter a context parameter that has the `MedusaContext` decorator.
+
+By doing the above, Medusa injects the method with a context parameter that has a `manger` property whose value is a [forked entity manager](https://mikro-orm.io/docs/identity-map#forking-entity-manager).
+
+Then, you run a raw SQL query to calculate the average rating of the reviews for a product with the given ID. You also filter the reviews by the status `approved`.
+
+You'll use this method next in the API route.
+
+### Create API Route
+
+To create the API route that lists the reviews of a product with average rating, create the file `src/api/store/products/[id]/reviews/route.ts` with the following content:
+
+```ts title="src/api/store/products/[id]/reviews/route.ts" highlights={GetStoreReviewsHighlights} collapsibleLines="1-9" expandButtonLabel="Show Imports"
+import {
+ MedusaRequest,
+ MedusaResponse,
+} from "@medusajs/framework/http"
+import { ContainerRegistrationKeys } from "@medusajs/framework/utils"
+import { PRODUCT_REVIEW_MODULE } from "../../../../../modules/product-review"
+import ProductReviewModuleService from "../../../../../modules/product-review/service"
+import { createFindParams } from "@medusajs/medusa/api/utils/validators"
+
+export const GetStoreReviewsSchema = createFindParams()
+
+export const GET = async (
+ req: MedusaRequest,
+ res: MedusaResponse
+) => {
+ const { id } = req.params
+
+ const query = req.scope.resolve(ContainerRegistrationKeys.QUERY)
+ const reviewModuleService: ProductReviewModuleService = req.scope.resolve(PRODUCT_REVIEW_MODULE)
+
+ // Get reviews for product
+ const { data: reviews, metadata: {
+ count,
+ take,
+ skip,
+ } = { count: 0, take: 10, skip: 0 } } = await query.graph({
+ entity: "review",
+ filters: {
+ product_id: id,
+ // @ts-ignore
+ status: "approved",
+ },
+ ...req.queryConfig,
+ })
+
+ res.json({
+ reviews,
+ count,
+ limit: take,
+ offset: skip,
+ average_rating: await reviewModuleService.getAverageRating(id),
+ })
+}
+```
+
+You first define a `GetStoreReviewsSchema` schema that will allow clients to pass the following query parameters:
+
+- `limit`: The number of reviews to retrieve.
+- `offset`: The number of items to skip before retrieving the reviews.
+- `order`: The fields to sort the reviews by in ascending or descending order.
+
+Then, you export a `GET` function, and that exposes a `GET` API Route at the path `/store/products/[id]/reviews`. In the route handler you resolve [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md) from the Medusa container, which allows you to retrieve data across modules.
+
+Next, you retrieve the approved reviews of a product using Query. Notice that you pass in `query.graph` the `req.queryConfig` object. This object holds the fields to retrieve and the pagination configurations. You'll configure this object in a bit.
+
+Finally, you return the reviews with pagination fields and the average rating of the product.
+
+### Apply Query Configurations Middleware
+
+The last step is to add a middleware that validates the query parameters passed to the request, and sets the default Query configuations.
+
+In `src/api/middlewares.ts`, add a new middleware:
+
+```ts title="src/api/middlewares.ts"
+// other imports
+import {
+ validateAndTransformQuery,
+} from "@medusajs/framework/http"
+import { GetStoreReviewsSchema } from "./store/products/[id]/reviews/route"
+
+export default defineMiddlewares({
+ routes: [
+ // ...
+ {
+ matcher: "/store/products/:id/reviews",
+ methods: ["GET"],
+ middlewares: [
+ validateAndTransformQuery(GetStoreReviewsSchema, {
+ isList: true,
+ defaults: [
+ "id",
+ "rating",
+ "title",
+ "first_name",
+ "last_name",
+ "content",
+ "created_at",
+ ],
+ }),
+ ],
+ },
+ ],
+})
+```
+
+You apply the `validateAndTransformQuery` middleware to the `GET` API route at the path `/store/products/:id/reviews`. Similar to before, you pass to the middleware:
+
+- The validation schema of the request's query parameters, which is the `GetStoreReviewsSchema` you created earlier.
+- An object of Query configurations. It has the following properties:
+ - `isList`: A boolean indicating whether the route returns a list of items. This enables the pagination configurations.
+ - `defaults`: An array of fields to retrieve by default.
+
+By adding this middleware, you allow clients to pass pagination query parameters to the API route, and set default fields to retrieve.
+
+You'll use this API route next as you customize the Next.js Starter Storefront.
+
+***
+
+## Step 11: Customize Next.js Starter Storefront
+
+In this step, you'll customize the Next.js Starter Storefront to:
+
+- Display a product's review and average rating on its page.
+- Allow authenticated customers to submit a review for a product.
+
+### Add Product Review Types
+
+Before implementing the customizations, you'll add a type definition for the product review which you'll re-use in the storefront.
+
+In `src/types/global.ts`, add the following types:
+
+```ts title="src/types/global.ts" badgeLabel="Storefront" badgeColor="blue"
+export type StoreProductReview = {
+ id: string
+ title: string
+ rating: number
+ content: string
+ first_name: string
+ last_name: string
+}
+```
+
+You define the type of a product review object and the properties it has.
+
+### Add Functions to Fetch and Submit Reviews
+
+Next, you'll add two functions that fetch and submit reviews using the API routes you created earlier. To send requests to the API routes, you can use Medusa's [JS SDK](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/js-sdk/index.html.md).
+
+In `src/lib/data/products.ts`, add the following functions:
+
+```ts title="src/lib/data/products.ts" badgeLabel="Storefront" badgeColor="blue"
+import { StoreProductReview } from "../../types/global"
+
+// ...
+
+export const getProductReviews = async ({
+ productId,
+ limit = 10,
+ offset = 0,
+}: {
+ productId: string
+ limit?: number
+ offset?: number
+}) => {
+ const headers = {
+ ...(await getAuthHeaders()),
+ }
+
+ const next = {
+ ...(await getCacheOptions(`product-reviews-${productId}`)),
+ }
+
+ return sdk.client.fetch<{
+ reviews: StoreProductReview[]
+ average_rating: number
+ limit: number
+ offset: number
+ count: number
+ }>(`/store/products/${productId}/reviews`, {
+ headers,
+ query: {
+ limit,
+ offset,
+ order: "-created_at",
+ },
+ next,
+ cache: "force-cache",
+ })
+}
+
+export const addProductReview = async (input: {
+ title?: string
+ content: string
+ first_name: string
+ last_name: string
+ rating: number,
+ product_id: string
+}) => {
+ const headers = {
+ ...(await getAuthHeaders()),
+ }
+
+ return sdk.client.fetch(`/store/reviews`, {
+ method: "POST",
+ headers,
+ body: input,
+ next: {
+ ...(await getCacheOptions(`product-reviews-${input.product_id}`)),
+ },
+ cache: "no-store",
+ })
+}
+```
+
+You define two functions:
+
+- `getProductReviews`: Fetches the reviews of a product with the given ID. It accepts an object with the product ID, and optional limit and offset parameters, allowing you to paginate the reviews.
+- `addProductReview`: Submits a review for a product. It accepts an object with the review's details.
+
+To send requests to your custom API routes, you use the JS SDK's `client.fetch` method.
+
+### Add Product Review Form
+
+You'll now create a component that shows the product review form for authenticated customers. Afterwards, you'll display this component on the product's page.
+
+To create the form component, create the file `src/modules/products/components/product-reviews/form.tsx` with the following content:
+
+```tsx title="src/modules/products/components/product-reviews/form.tsx" badgeLabel="Storefront" badgeColor="blue"
+"use client"
+
+import { useState } from "react"
+
+import { useEffect } from "react"
+import { retrieveCustomer } from "../../../../lib/data/customer"
+import { HttpTypes } from "@medusajs/types"
+import { Button, Input, Label, Textarea, toast, Toaster } from "@medusajs/ui"
+import { Star, StarSolid } from "@medusajs/icons"
+import { addProductReview } from "../../../../lib/data/products"
+
+type ProductReviewsFormProps = {
+ productId: string
+}
+
+export default function ProductReviewsForm({ productId }: ProductReviewsFormProps) {
+ const [customer, setCustomer] = useState(null)
+ const [isLoading, setIsLoading] = useState(false)
+ const [showForm, setShowForm] = useState(false)
+ const [title, setTitle] = useState("")
+ const [content, setContent] = useState("")
+ const [rating, setRating] = useState(0)
+
+ useEffect(() => {
+ if (customer) {
+ return
+ }
+
+ retrieveCustomer().then(setCustomer)
+ }, [])
+
+ if (!customer) {
+ return <>
+ }
+
+ const handleSubmit = async (e: React.FormEvent) => {
+ if (!content || !rating) {
+ toast.error("Error", {
+ description: "Please fill in required fields.",
+ })
+ return
+ }
+
+ e.preventDefault()
+ setIsLoading(true)
+ addProductReview({
+ title,
+ content,
+ rating,
+ first_name: customer.first_name || "",
+ last_name: customer.last_name || "",
+ product_id: productId,
+ }).then(() => {
+ setShowForm(false)
+ setTitle("")
+ setContent("")
+ setRating(0)
+ toast.success("Success", {
+ description: "Your review has been submitted and is awaiting approval.",
+ })
+ }).catch(() => {
+ toast.error("Error", {
+ description: "An error occurred while submitting your review. Please try again later.",
+ })
+ }).finally(() => {
+ setIsLoading(false)
+ })
+ }
+
+ // TODO render form
+}
+```
+
+You create a `ProductReviewsForm` component that accepts the product's ID as a prop. In the component, you:
+
+- Fetch the authenticated customer's details. If the customer is not authenticated, you return an empty fragment.
+- Implement a `handleSubmit` function that submits the review when the form is submitted.
+
+Next, you'll add a return statement that shows the form when the customer is authenticated. Replace the `TODO` with the following:
+
+```tsx title="src/modules/products/components/product-reviews/form.tsx" badgeLabel="Storefront" badgeColor="blue"
+return (
+