From 97daa5a41c5b8065de9ebb88c5ed69a77c1190ed Mon Sep 17 00:00:00 2001
From: Shahed Nasser <shahednasser@gmail.com>
Date: Thu, 24 Apr 2025 15:44:35 +0300
Subject: [PATCH] docs: clarify ISO format for province codes (#12282)

* docs: clarify ISO format for province codes

* regenerate
---
 www/apps/book/public/llms-full.txt            | 29204 ++++++++--------
 .../fulfillment/concepts/page.mdx             |     6 +
 .../fulfillment/shipping-option/page.mdx      |     6 +
 .../products/price/page.mdx                   |     2 +-
 www/apps/resources/generated/edit-dates.mjs   |     6 +-
 .../app/settings/tax-regions/page.mdx         |     2 +-
 .../get_admin_customers_[id]_addresses.ts     |    14 +-
 .../operations/admin/get_admin_tax-regions.ts |    14 +-
 .../post_admin_customers_[id]_addresses.ts    |     8 +-
 ...n_customers_[id]_addresses_[address_id].ts |     6 +-
 .../admin/post_admin_draft-orders.ts          |    12 +-
 ...min_fulfillment-sets_[id]_service-zones.ts |    18 +-
 ...lment-sets_[id]_service-zones_[zone_id].ts |    18 +-
 .../admin/post_admin_fulfillments.ts          |     2 +-
 .../admin/post_admin_tax-regions.ts           |     4 +-
 .../operations/store/get_store_products.ts    |     8 +-
 .../store/get_store_products_[id].ts          |     8 +-
 .../post_store_customers_me_addresses.ts      |     8 +-
 ...ore_customers_me_addresses_[address_id].ts |     6 +-
 .../schemas/AdminCreateFulfillment.ts         |     6 +-
 .../schemas/AdminCreateTaxRegion.ts           |     6 +-
 .../schemas/AdminCustomerAddress.ts           |     6 +-
 .../schemas/AdminFulfillmentAddress.ts        |     6 +-
 .../oas-output/schemas/AdminGeoZone.ts        |     6 +-
 .../oas-output/schemas/AdminOrderAddress.ts   |     6 +-
 .../schemas/AdminStockLocationAddress.ts      |     6 +-
 .../oas-output/schemas/AdminTaxRegion.ts      |     6 +-
 .../schemas/AdminUpdateDraftOrder.ts          |    12 +-
 .../oas-output/schemas/AdminUpdateOrder.ts    |    12 +-
 .../schemas/AdminUpdateStockLocation.ts       |     6 +-
 .../schemas/AdminUpdateTaxRegion.ts           |     6 +-
 .../AdminUpsertStockLocationAddress.ts        |     6 +-
 .../oas-output/schemas/BaseOrderAddress.ts    |     6 +-
 .../oas-output/schemas/CreateAddress.ts       |     6 +-
 .../oas-output/schemas/OrderAddress.ts        |     6 +-
 .../oas-output/schemas/StoreCartAddress.ts    |     6 +-
 .../schemas/StoreCustomerAddress.ts           |     6 +-
 .../oas-output/schemas/StoreOrderAddress.ts   |     6 +-
 .../oas-output/schemas/UpdateAddress.ts       |     6 +-
 39 files changed, 14830 insertions(+), 14654 deletions(-)

diff --git a/www/apps/book/public/llms-full.txt b/www/apps/book/public/llms-full.txt
index dca8e229c2..b5892a245f 100644
--- a/www/apps/book/public/llms-full.txt
+++ b/www/apps/book/public/llms-full.txt
@@ -1361,50 +1361,6 @@ 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": "npm run resolve:aliases && medusa build"
-  }
-}
-```
-
-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.
@@ -1713,6 +1669,50 @@ Replace the email `admin-medusa@test.com` and password `supersecret` with the cr
 You can use these credentials to log into the Medusa Admin dashboard.
 
 
+# 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": "npm run resolve:aliases && medusa build"
+  }
+}
+```
+
+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"
+```
+
+
 # Admin Development
 
 In this chapter, you'll learn about th Medusa Admin dashboard and the possible ways to customize it.
@@ -1888,6 +1888,187 @@ npx medusa exec ./src/scripts/my-script.ts arg1 arg2
 ```
 
 
+# Events and Subscribers
+
+In this chapter, you’ll learn about Medusa's event system, and how to handle events with subscribers.
+
+## Handle Core Commerce Flows with Events
+
+When building commerce digital applications, you'll often need to perform an action after a commerce operation is performed. For example, sending an order confirmation email when the customer places an order, or syncing data that's updated in Medusa to a third-party system.
+
+Medusa emits events when core commerce features are performed, and you can listen to and handle these events in asynchronous functions. You can think of Medusa's events like you'd think about webhooks in other commerce platforms, but instead of having to setup separate applications to handle webhooks, your efforts only go into writing the logic right in your Medusa codebase.
+
+You listen to an event in a subscriber, which is an asynchronous function that's executed when its associated event is emitted.
+
+![A diagram showcasing an example of how an event is emitted when an order is placed.](https://res.cloudinary.com/dza7lstvk/image/upload/v1732277948/Medusa%20Book/order-placed-event-example_e4e4kw.jpg)
+
+Subscribers are useful to perform actions that aren't integral to the original flow. For example, you can handle the `order.placed` event in a subscriber that sends a confirmation email to the customer. The subscriber has no impact on the original order-placement flow, as it's executed outside of it.
+
+If the action you're performing is integral to the main flow of the core commerce feature, use [workflow hooks](https://docs.medusajs.com/learn/fundamentals/workflows/workflow-hooks/index.html.md) instead.
+
+### List of Emitted Events
+
+Find a list of all emitted events in [this reference](https://docs.medusajs.com/resources/events-reference/index.html.md).
+
+***
+
+## How to Create a Subscriber?
+
+You create a subscriber in a TypeScript or JavaScript file under the `src/subscribers` directory. The file exports the function to execute and the subscriber's configuration that indicate what event(s) it listens to.
+
+For example, create the file `src/subscribers/order-placed.ts` with the following content:
+
+![Example of subscriber file in the application's directory structure](https://res.cloudinary.com/dza7lstvk/image/upload/v1732866244/Medusa%20Book/subscriber-dir-overview_pusyeu.jpg)
+
+```ts title="src/subscribers/product-created.ts"
+import { SubscriberArgs, type SubscriberConfig } from "@medusajs/framework"
+import { sendOrderConfirmationWorkflow } from "../workflows/send-order-confirmation"
+
+export default async function orderPlacedHandler({
+  event: { data },
+  container,
+}: SubscriberArgs<{ id: string }>) {
+  const logger = container.resolve("logger")
+
+  logger.info("Sending confirmation email...")
+
+  await sendOrderConfirmationWorkflow(container)
+    .run({
+      input: {
+        id: data.id,
+      },
+    })
+}
+
+export const config: SubscriberConfig = {
+  event: `order.placed`,
+}
+```
+
+This subscriber file exports:
+
+- An asynchronous subscriber function that's executed whenever the associated event, which is `order.placed` is triggered.
+- A configuration object with an `event` property whose value is the event the subscriber is listening to. You can also pass an array of event names to listen to multiple events in the same subscriber.
+
+The subscriber function receives an object as a parameter that has the following properties:
+
+- `event`: An object with the event's details. The `data` property contains the data payload of the event emitted, which is the order's ID in this case.
+- `container`: The [Medusa container](https://docs.medusajs.com/learn/fundamentals/medusa-container/index.html.md) that you can use to resolve registered resources.
+
+In the subscriber function, you use the container to resolve the Logger utility and log a message in the console. Also, assuming you have a [workflow](https://docs.medusajs.com/learn/fundamentals/workflows/index.html.md) that sends an order confirmation email, you execute it in the subscriber.
+
+***
+
+## Test the Subscriber
+
+To test the subscriber, start the Medusa application:
+
+```bash npm2yarn
+npm run dev
+```
+
+Then, try placing an order either using Medusa's API routes or the [Next.js Storefront](https://docs.medusajs.com/resources/nextjs-starter/index.html.md). You'll see the following message in the terminal:
+
+```bash
+info:    Processing order.placed which has 1 subscribers
+Sending confirmation email...
+```
+
+The first message indicates that the `order.placed` event was emitted, and the second one is the message logged from the subscriber.
+
+***
+
+## Event Module
+
+The subscription and emitting of events is handled by an Event Module, an Infrastructure Module that implements the pub/sub functionalities of Medusa's event system.
+
+Medusa provides two Event Modules out of the box:
+
+- [Local Event Module](https://docs.medusajs.com/resources/infrastructure-modules/event/local/index.html.md), used by default. It's useful for development, as you don't need additional setup to use it.
+- [Redis Event Module](https://docs.medusajs.com/resources/infrastructure-modules/event/redis/index.html.md), which is useful in production. It uses [Redis](https://redis.io/) to implement Medusa's pub/sub events system.
+
+Medusa's [architecture](https://docs.medusajs.com/learn/introduction/architecture/index.html.md) also allows you to build a custom Event Module that uses a different service or logic to implement the pub/sub system. Learn how to build an Event Module in [this guide](https://docs.medusajs.com/resources/infrastructure-modules/event/create/index.html.md).
+
+
+# Environment Variables
+
+In this chapter, you'll learn how environment variables are loaded in Medusa.
+
+## System Environment Variables
+
+The Medusa application loads and uses system environment variables.
+
+For example, if you set the `PORT` environment variable to `8000`, the Medusa application runs on that port instead of `9000`.
+
+In production, you should always use system environment variables that you set through your hosting provider.
+
+***
+
+## Environment Variables in .env Files
+
+During development, it's easier to set environment variables in a `.env` file in your repository.
+
+Based on your `NODE_ENV` system environment variable, Medusa will try to load environment variables from the following `.env` files:
+
+As of [Medusa v2.5.0](https://github.com/medusajs/medusa/releases/tag/v2.5.0), `NODE_ENV` defaults to `production` when using `medusa start`. Otherwise, it defaults to `development`.
+
+|\`.env\`|
+|---|---|
+|\`NODE\_ENV\`|\`.env\`|
+|\`NODE\_ENV\`|\`.env.production\`|
+|\`NODE\_ENV\`|\`.env.staging\`|
+|\`NODE\_ENV\`|\`.env.test\`|
+
+### Set Environment in `loadEnv`
+
+In the `medusa-config.ts` file of your Medusa application, you'll find a `loadEnv` function used that accepts `process.env.NODE_ENV` as a first parameter.
+
+This function is responsible for loading the correct `.env` file based on the value of `process.env.NODE_ENV`.
+
+To ensure that the correct `.env` file is loaded as shown in the table above, only specify `development`, `production`, `staging` or `test` as the value of `process.env.NODE_ENV` or as the parameter of `loadEnv`.
+
+***
+
+## Environment Variables for Admin Customizations
+
+Since the Medusa Admin is built on top of [Vite](https://vite.dev/), you prefix the environment variables you want to use in a widget or UI route with `VITE_`. Then, you can access or use them with the `import.meta.env` object.
+
+Learn more in [this documentation](https://docs.medusajs.com/learn/fundamentals/admin/environment-variables/index.html.md).
+
+***
+
+## Predefined Medusa Environment Variables
+
+The Medusa application uses the following predefined environment variables that you can set:
+
+You should opt for setting configurations in `medusa-config.ts` where possible. For a full list of Medusa configurations, refer to the [Medusa Configurations chapter](https://docs.medusajs.com/learn/configurations/medusa-config/index.html.md).
+
+|Environment Variable|Description|Default|
+|---|---|---|---|---|
+|
+|
+|
+|
+||The URL to connect to the PostgreSQL database. Only used if ||
+||URLs of storefronts that can access the Medusa backend's Store APIs. Only used if ||
+||URLs of admin dashboards that can access the Medusa backend's Admin APIs. Only used if ||
+||URLs of clients that can access the Medusa backend's authentication routes. Only used if ||
+||A random string used to create authentication tokens in the http layer. Only used if ||
+||A random string used to create cookie tokens in the http layer. Only used if ||
+||The URL to the Medusa backend. Only used if ||
+|
+|
+|
+|
+|
+|
+|
+|
+||The allowed levels to log. Learn more in ||
+||The file to save logs in. By default, logs aren't saved in any file. Learn more in ||
+||Whether to disable analytics data collection. Learn more in ||
+
+
 # Data Models
 
 In this chapter, you'll learn what a data model is and how to create a data model.
@@ -1992,187 +2173,6 @@ 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.
 
 
-# Environment Variables
-
-In this chapter, you'll learn how environment variables are loaded in Medusa.
-
-## System Environment Variables
-
-The Medusa application loads and uses system environment variables.
-
-For example, if you set the `PORT` environment variable to `8000`, the Medusa application runs on that port instead of `9000`.
-
-In production, you should always use system environment variables that you set through your hosting provider.
-
-***
-
-## Environment Variables in .env Files
-
-During development, it's easier to set environment variables in a `.env` file in your repository.
-
-Based on your `NODE_ENV` system environment variable, Medusa will try to load environment variables from the following `.env` files:
-
-As of [Medusa v2.5.0](https://github.com/medusajs/medusa/releases/tag/v2.5.0), `NODE_ENV` defaults to `production` when using `medusa start`. Otherwise, it defaults to `development`.
-
-|\`.env\`|
-|---|---|
-|\`NODE\_ENV\`|\`.env\`|
-|\`NODE\_ENV\`|\`.env.production\`|
-|\`NODE\_ENV\`|\`.env.staging\`|
-|\`NODE\_ENV\`|\`.env.test\`|
-
-### Set Environment in `loadEnv`
-
-In the `medusa-config.ts` file of your Medusa application, you'll find a `loadEnv` function used that accepts `process.env.NODE_ENV` as a first parameter.
-
-This function is responsible for loading the correct `.env` file based on the value of `process.env.NODE_ENV`.
-
-To ensure that the correct `.env` file is loaded as shown in the table above, only specify `development`, `production`, `staging` or `test` as the value of `process.env.NODE_ENV` or as the parameter of `loadEnv`.
-
-***
-
-## Environment Variables for Admin Customizations
-
-Since the Medusa Admin is built on top of [Vite](https://vite.dev/), you prefix the environment variables you want to use in a widget or UI route with `VITE_`. Then, you can access or use them with the `import.meta.env` object.
-
-Learn more in [this documentation](https://docs.medusajs.com/learn/fundamentals/admin/environment-variables/index.html.md).
-
-***
-
-## Predefined Medusa Environment Variables
-
-The Medusa application uses the following predefined environment variables that you can set:
-
-You should opt for setting configurations in `medusa-config.ts` where possible. For a full list of Medusa configurations, refer to the [Medusa Configurations chapter](https://docs.medusajs.com/learn/configurations/medusa-config/index.html.md).
-
-|Environment Variable|Description|Default|
-|---|---|---|---|---|
-|
-|
-|
-|
-||The URL to connect to the PostgreSQL database. Only used if ||
-||URLs of storefronts that can access the Medusa backend's Store APIs. Only used if ||
-||URLs of admin dashboards that can access the Medusa backend's Admin APIs. Only used if ||
-||URLs of clients that can access the Medusa backend's authentication routes. Only used if ||
-||A random string used to create authentication tokens in the http layer. Only used if ||
-||A random string used to create cookie tokens in the http layer. Only used if ||
-||The URL to the Medusa backend. Only used if ||
-|
-|
-|
-|
-|
-|
-|
-|
-||The allowed levels to log. Learn more in ||
-||The file to save logs in. By default, logs aren't saved in any file. Learn more in ||
-||Whether to disable analytics data collection. Learn more in ||
-
-
-# Events and Subscribers
-
-In this chapter, you’ll learn about Medusa's event system, and how to handle events with subscribers.
-
-## Handle Core Commerce Flows with Events
-
-When building commerce digital applications, you'll often need to perform an action after a commerce operation is performed. For example, sending an order confirmation email when the customer places an order, or syncing data that's updated in Medusa to a third-party system.
-
-Medusa emits events when core commerce features are performed, and you can listen to and handle these events in asynchronous functions. You can think of Medusa's events like you'd think about webhooks in other commerce platforms, but instead of having to setup separate applications to handle webhooks, your efforts only go into writing the logic right in your Medusa codebase.
-
-You listen to an event in a subscriber, which is an asynchronous function that's executed when its associated event is emitted.
-
-![A diagram showcasing an example of how an event is emitted when an order is placed.](https://res.cloudinary.com/dza7lstvk/image/upload/v1732277948/Medusa%20Book/order-placed-event-example_e4e4kw.jpg)
-
-Subscribers are useful to perform actions that aren't integral to the original flow. For example, you can handle the `order.placed` event in a subscriber that sends a confirmation email to the customer. The subscriber has no impact on the original order-placement flow, as it's executed outside of it.
-
-If the action you're performing is integral to the main flow of the core commerce feature, use [workflow hooks](https://docs.medusajs.com/learn/fundamentals/workflows/workflow-hooks/index.html.md) instead.
-
-### List of Emitted Events
-
-Find a list of all emitted events in [this reference](https://docs.medusajs.com/resources/events-reference/index.html.md).
-
-***
-
-## How to Create a Subscriber?
-
-You create a subscriber in a TypeScript or JavaScript file under the `src/subscribers` directory. The file exports the function to execute and the subscriber's configuration that indicate what event(s) it listens to.
-
-For example, create the file `src/subscribers/order-placed.ts` with the following content:
-
-![Example of subscriber file in the application's directory structure](https://res.cloudinary.com/dza7lstvk/image/upload/v1732866244/Medusa%20Book/subscriber-dir-overview_pusyeu.jpg)
-
-```ts title="src/subscribers/product-created.ts"
-import { SubscriberArgs, type SubscriberConfig } from "@medusajs/framework"
-import { sendOrderConfirmationWorkflow } from "../workflows/send-order-confirmation"
-
-export default async function orderPlacedHandler({
-  event: { data },
-  container,
-}: SubscriberArgs<{ id: string }>) {
-  const logger = container.resolve("logger")
-
-  logger.info("Sending confirmation email...")
-
-  await sendOrderConfirmationWorkflow(container)
-    .run({
-      input: {
-        id: data.id,
-      },
-    })
-}
-
-export const config: SubscriberConfig = {
-  event: `order.placed`,
-}
-```
-
-This subscriber file exports:
-
-- An asynchronous subscriber function that's executed whenever the associated event, which is `order.placed` is triggered.
-- A configuration object with an `event` property whose value is the event the subscriber is listening to. You can also pass an array of event names to listen to multiple events in the same subscriber.
-
-The subscriber function receives an object as a parameter that has the following properties:
-
-- `event`: An object with the event's details. The `data` property contains the data payload of the event emitted, which is the order's ID in this case.
-- `container`: The [Medusa container](https://docs.medusajs.com/learn/fundamentals/medusa-container/index.html.md) that you can use to resolve registered resources.
-
-In the subscriber function, you use the container to resolve the Logger utility and log a message in the console. Also, assuming you have a [workflow](https://docs.medusajs.com/learn/fundamentals/workflows/index.html.md) that sends an order confirmation email, you execute it in the subscriber.
-
-***
-
-## Test the Subscriber
-
-To test the subscriber, start the Medusa application:
-
-```bash npm2yarn
-npm run dev
-```
-
-Then, try placing an order either using Medusa's API routes or the [Next.js Storefront](https://docs.medusajs.com/resources/nextjs-starter/index.html.md). You'll see the following message in the terminal:
-
-```bash
-info:    Processing order.placed which has 1 subscribers
-Sending confirmation email...
-```
-
-The first message indicates that the `order.placed` event was emitted, and the second one is the message logged from the subscriber.
-
-***
-
-## Event Module
-
-The subscription and emitting of events is handled by an Event Module, an Infrastructure Module that implements the pub/sub functionalities of Medusa's event system.
-
-Medusa provides two Event Modules out of the box:
-
-- [Local Event Module](https://docs.medusajs.com/resources/infrastructure-modules/event/local/index.html.md), used by default. It's useful for development, as you don't need additional setup to use it.
-- [Redis Event Module](https://docs.medusajs.com/resources/infrastructure-modules/event/redis/index.html.md), which is useful in production. It uses [Redis](https://redis.io/) to implement Medusa's pub/sub events system.
-
-Medusa's [architecture](https://docs.medusajs.com/learn/introduction/architecture/index.html.md) also allows you to build a custom Event Module that uses a different service or logic to implement the pub/sub system. Learn how to build an Event Module in [this guide](https://docs.medusajs.com/resources/infrastructure-modules/event/create/index.html.md).
-
-
 # Framework Overview
 
 In this chapter, you'll learn about the Medusa Framework and how it facilitates building customizations in your Medusa application.
@@ -3308,100 +3308,6 @@ npx medusa db:migrate
 ```
 
 
-# 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:
-
-![Example of scheduled job file in the application's directory structure](https://res.cloudinary.com/dza7lstvk/image/upload/v1732866423/Medusa%20Book/scheduled-job-dir-overview_ediqgm.jpg)
-
-```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.
-
-
 # Plugins
 
 In this chapter, you'll learn what a plugin is in Medusa.
@@ -3740,6 +3646,100 @@ 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.
 
 
+# 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:
+
+![Example of scheduled job file in the application's directory structure](https://res.cloudinary.com/dza7lstvk/image/upload/v1732866423/Medusa%20Book/scheduled-job-dir-overview_ediqgm.jpg)
+
+```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.
+
+
 # Logging
 
 In this chapter, you’ll learn how to use Medusa’s logging utility.
@@ -4447,28 +4447,6 @@ Medusa provides the tooling to create a plugin package, test it in a local Medus
 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.
-
-
 # Medusa's Architecture
 
 In this chapter, you'll learn about the architectural layers in Medusa.
@@ -4542,6 +4520,28 @@ The following diagram illustrates Medusa's architecture including all its layers
 ![Full diagram illustrating Medusa's architecture combining all the different layers.](https://res.cloudinary.com/dza7lstvk/image/upload/v1727174897/Medusa%20Book/architectural-diagram-full.jpg)
 
 
+# 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.
+
+
 # Worker Mode of Medusa Instance
 
 In this chapter, you'll learn about the different modes of running a Medusa instance and how to configure the mode.
@@ -4801,51 +4801,6 @@ When you build the Medusa application, including the Medusa Admin, with the `bui
 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 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",
-})
-```
-
-
 # Admin Routing Customizations
 
 The Medusa Admin dashboard uses [React Router](https://reactrouter.com) under the hood to manage routing. So, you can have more flexibility in routing-related customizations using some of React Router's utilities, hooks, and components.
@@ -4999,255 +4954,50 @@ 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.
 
 
-# Admin Development Tips
+# Admin Development Constraints
 
-In this chapter, you'll find some tips for your admin development.
+This chapter lists some constraints of admin widgets and UI routes.
 
-## Send Requests to API Routes
+## Arrow Functions
 
-To send a request to an API route in the Medusa Application, use Medusa's [JS SDK](https://docs.medusajs.com/resources/js-sdk/index.html.md) with [Tanstack Query](https://tanstack.com/query/latest). Both of these tools are installed in your project by default.
+Widget and UI route components must be created as arrow functions.
 
-Do not install Tanstack Query as that will cause unexpected errors in your development. If you prefer installing it for better auto-completion in your code editor, make sure to install `v5.64.2` as a development dependency.
-
-First, create the file `src/admin/lib/config.ts` to setup the SDK for use in your customizations:
-
-```ts
-import Medusa from "@medusajs/js-sdk"
-
-export const sdk = new Medusa({
-  baseUrl: import.meta.env.VITE_BACKEND_URL || "/",
-  debug: import.meta.env.DEV,
-  auth: {
-    type: "session",
-  },
-})
-```
-
-Notice that you use `import.meta.env` to access environment variables in your customizations, as explained in [this chapter](https://docs.medusajs.com/learn/fundamentals/admin/environment-variables/index.html.md).
-
-Learn more about the JS SDK's configurations [this documentation](https://docs.medusajs.com/resources/js-sdk#js-sdk-configurations/index.html.md).
-
-Then, use the configured SDK with the `useQuery` Tanstack Query hook to send `GET` requests, and `useMutation` hook to send `POST` or `DELETE` requests.
-
-For example:
-
-### Query
-
-```tsx title="src/admin/widgets/product-widget.ts" highlights={queryHighlights}
-import { defineWidgetConfig } from "@medusajs/admin-sdk"
-import { Button, Container } from "@medusajs/ui"
-import { useQuery } from "@tanstack/react-query"
-import { sdk } from "../lib/config"
-import { DetailWidgetProps, HttpTypes } from "@medusajs/framework/types"
+```ts highlights={arrowHighlights}
+// Don't
+function ProductWidget() {
+  // ...
+}
 
+// Do
 const ProductWidget = () => {
-  const { data, isLoading } = useQuery({
-    queryFn: () => sdk.admin.product.list(),
-    queryKey: ["products"],
-  })
-  
-  return (
-    <Container className="divide-y p-0">
-      {isLoading && <span>Loading...</span>}
-      {data?.products && (
-        <ul>
-          {data.products.map((product) => (
-            <li key={product.id}>{product.title}</li>
-          ))}
-        </ul>
-      )}
-    </Container>
-  )
+  // ...
 }
-
-export const config = defineWidgetConfig({
-  zone: "product.list.before",
-})
-
-export default ProductWidget
 ```
 
-### Mutation
+***
 
-```tsx title="src/admin/widgets/product-widget.ts" highlights={mutationHighlights}
-import { defineWidgetConfig } from "@medusajs/admin-sdk"
-import { Button, Container } from "@medusajs/ui"
-import { useMutation } from "@tanstack/react-query"
-import { sdk } from "../lib/config"
-import { DetailWidgetProps, HttpTypes } from "@medusajs/framework/types"
+## Widget Zone
 
-const ProductWidget = ({ 
-  data: productData,
-}: DetailWidgetProps<HttpTypes.AdminProduct>) => {
-  const { mutateAsync } = useMutation({
-    mutationFn: (payload: HttpTypes.AdminUpdateProduct) => 
-      sdk.admin.product.update(productData.id, payload),
-    onSuccess: () => alert("updated product"),
-  })
+A widget zone's value must be wrapped in double or single quotes. It can't be a template literal or a variable.
 
-  const handleUpdate = () => {
-    mutateAsync({
-      title: "New Product Title",
-    })
-  }
-  
-  return (
-    <Container className="divide-y p-0">
-      <Button onClick={handleUpdate}>Update Title</Button>
-    </Container>
-  )
-}
+```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
 ```
 
-You can also send requests to custom routes as explained in the [JS SDK reference](https://docs.medusajs.com/resources/js-sdk/index.html.md).
-
-### Use Route Loaders for Initial Data
-
-You may need to retrieve data before your component is rendered, or you may need to pass some initial data to your component to be used while data is being fetched. In those cases, you can use a [route loader](https://docs.medusajs.com/learn/fundamentals/admin/routing/index.html.md).
-
-***
-
-## Global Variables in Admin Customizations
-
-In your admin customizations, you can use the following global variables:
-
-- `__BASE__`: The base path of the Medusa Admin, as set in the [admin.path](https://docs.medusajs.com/learn/configurations/medusa-config#path/index.html.md) configuration in `medusa-config.ts`.
-- `__BACKEND_URL__`: The URL to the Medusa backend, as set in the [admin.backendUrl](https://docs.medusajs.com/learn/configurations/medusa-config#backendurl/index.html.md) configuration in `medusa-config.ts`.
-- `__STOREFRONT_URL__`: The URL to the storefront, as set in the [admin.storefrontUrl](https://docs.medusajs.com/learn/configurations/medusa-config#storefrontUrl/index.html.md) configuration in `medusa-config.ts`.
-
-***
-
-## Admin Translations
-
-The Medusa Admin dashboard can be displayed in languages other than English, which is the default. Other languages are added through community contributions.
-
-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).
-
-
-# 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:
-
-![Example of widget file in the application's directory structure](https://res.cloudinary.com/dza7lstvk/image/upload/v1732867137/Medusa%20Book/widget-dir-overview_dqsbct.jpg)
-
-```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 (
-    <Container className="divide-y p-0">
-      <div className="flex items-center justify-between px-6 py-4">
-        <Heading level="h2">Product Widget</Heading>
-      </div>
-    </Container>
-  )
-}
-
-// 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<AdminProduct>) => {
-  return (
-    <Container className="divide-y p-0">
-      <div className="flex items-center justify-between px-6 py-4">
-        <Heading level="h2">
-          Product Widget {data.title}
-        </Heading>
-      </div>
-    </Container>
-  )
-}
-
-// 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
 
@@ -5485,6 +5235,137 @@ 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).
 
 
+# Admin Development Tips
+
+In this chapter, you'll find some tips for your admin development.
+
+## Send Requests to API Routes
+
+To send a request to an API route in the Medusa Application, use Medusa's [JS SDK](https://docs.medusajs.com/resources/js-sdk/index.html.md) with [Tanstack Query](https://tanstack.com/query/latest). Both of these tools are installed in your project by default.
+
+Do not install Tanstack Query as that will cause unexpected errors in your development. If you prefer installing it for better auto-completion in your code editor, make sure to install `v5.64.2` as a development dependency.
+
+First, create the file `src/admin/lib/config.ts` to setup the SDK for use in your customizations:
+
+```ts
+import Medusa from "@medusajs/js-sdk"
+
+export const sdk = new Medusa({
+  baseUrl: import.meta.env.VITE_BACKEND_URL || "/",
+  debug: import.meta.env.DEV,
+  auth: {
+    type: "session",
+  },
+})
+```
+
+Notice that you use `import.meta.env` to access environment variables in your customizations, as explained in [this chapter](https://docs.medusajs.com/learn/fundamentals/admin/environment-variables/index.html.md).
+
+Learn more about the JS SDK's configurations [this documentation](https://docs.medusajs.com/resources/js-sdk#js-sdk-configurations/index.html.md).
+
+Then, use the configured SDK with the `useQuery` Tanstack Query hook to send `GET` requests, and `useMutation` hook to send `POST` or `DELETE` requests.
+
+For example:
+
+### Query
+
+```tsx title="src/admin/widgets/product-widget.ts" highlights={queryHighlights}
+import { defineWidgetConfig } from "@medusajs/admin-sdk"
+import { Button, Container } from "@medusajs/ui"
+import { useQuery } from "@tanstack/react-query"
+import { sdk } from "../lib/config"
+import { DetailWidgetProps, HttpTypes } from "@medusajs/framework/types"
+
+const ProductWidget = () => {
+  const { data, isLoading } = useQuery({
+    queryFn: () => sdk.admin.product.list(),
+    queryKey: ["products"],
+  })
+  
+  return (
+    <Container className="divide-y p-0">
+      {isLoading && <span>Loading...</span>}
+      {data?.products && (
+        <ul>
+          {data.products.map((product) => (
+            <li key={product.id}>{product.title}</li>
+          ))}
+        </ul>
+      )}
+    </Container>
+  )
+}
+
+export const config = defineWidgetConfig({
+  zone: "product.list.before",
+})
+
+export default ProductWidget
+```
+
+### Mutation
+
+```tsx title="src/admin/widgets/product-widget.ts" highlights={mutationHighlights}
+import { defineWidgetConfig } from "@medusajs/admin-sdk"
+import { Button, Container } from "@medusajs/ui"
+import { useMutation } from "@tanstack/react-query"
+import { sdk } from "../lib/config"
+import { DetailWidgetProps, HttpTypes } from "@medusajs/framework/types"
+
+const ProductWidget = ({ 
+  data: productData,
+}: DetailWidgetProps<HttpTypes.AdminProduct>) => {
+  const { mutateAsync } = useMutation({
+    mutationFn: (payload: HttpTypes.AdminUpdateProduct) => 
+      sdk.admin.product.update(productData.id, payload),
+    onSuccess: () => alert("updated product"),
+  })
+
+  const handleUpdate = () => {
+    mutateAsync({
+      title: "New Product Title",
+    })
+  }
+  
+  return (
+    <Container className="divide-y p-0">
+      <Button onClick={handleUpdate}>Update Title</Button>
+    </Container>
+  )
+}
+
+export const config = defineWidgetConfig({
+  zone: "product.details.before",
+})
+
+export default ProductWidget
+```
+
+You can also send requests to custom routes as explained in the [JS SDK reference](https://docs.medusajs.com/resources/js-sdk/index.html.md).
+
+### Use Route Loaders for Initial Data
+
+You may need to retrieve data before your component is rendered, or you may need to pass some initial data to your component to be used while data is being fetched. In those cases, you can use a [route loader](https://docs.medusajs.com/learn/fundamentals/admin/routing/index.html.md).
+
+***
+
+## Global Variables in Admin Customizations
+
+In your admin customizations, you can use the following global variables:
+
+- `__BASE__`: The base path of the Medusa Admin, as set in the [admin.path](https://docs.medusajs.com/learn/configurations/medusa-config#path/index.html.md) configuration in `medusa-config.ts`.
+- `__BACKEND_URL__`: The URL to the Medusa backend, as set in the [admin.backendUrl](https://docs.medusajs.com/learn/configurations/medusa-config#backendurl/index.html.md) configuration in `medusa-config.ts`.
+- `__STOREFRONT_URL__`: The URL to the storefront, as set in the [admin.storefrontUrl](https://docs.medusajs.com/learn/configurations/medusa-config#storefrontUrl/index.html.md) configuration in `medusa-config.ts`.
+
+***
+
+## Admin Translations
+
+The Medusa Admin dashboard can be displayed in languages other than English, which is the default. Other languages are added through community contributions.
+
+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).
+
+
 # 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.
@@ -5684,6 +5565,232 @@ createProductsWorkflow.hooks.productsCreated(
 This updates the products to their original state before adding the brand to their `metadata` property.
 
 
+# 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:
+
+![Example of widget file in the application's directory structure](https://res.cloudinary.com/dza7lstvk/image/upload/v1732867137/Medusa%20Book/widget-dir-overview_dqsbct.jpg)
+
+```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 (
+    <Container className="divide-y p-0">
+      <div className="flex items-center justify-between px-6 py-4">
+        <Heading level="h2">Product Widget</Heading>
+      </div>
+    </Container>
+  )
+}
+
+// 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<AdminProduct>) => {
+  return (
+    <Container className="divide-y p-0">
+      <div className="flex items-center justify-between px-6 py-4">
+        <Heading level="h2">
+          Product Widget {data.title}
+        </Heading>
+      </div>
+    </Container>
+  )
+}
+
+// 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.
+
+
+# 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.
+
+
 # Handling CORS in API Routes
 
 In this chapter, you’ll learn about the CORS middleware and how to configure it for custom API routes.
@@ -5796,156 +5903,6 @@ export default defineMiddlewares({
 This retrieves the configurations exported from `medusa-config.ts` and applies the `storeCors` to routes starting with `/custom`.
 
 
-# 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.
@@ -6294,6 +6251,49 @@ A middleware can not override an existing middleware. Instead, middlewares are a
 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.
 
 
+# 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`.
+
+
 # API Route Parameters
 
 In this chapter, you’ll learn about path, query, and request body parameters.
@@ -6914,88 +6914,6 @@ This API route opens a stream by setting the `Content-Type` in the header to `te
 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.
@@ -7245,6 +7163,88 @@ For example, if you omit the `a` parameter, you'll receive a `400` response code
 To see different examples and learn more about creating a validation schema, refer to [Zod's documentation](https://zod.dev).
 
 
+# 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.
+
+
 # Seed Data with Custom CLI Script
 
 In this chapter, you'll learn how to seed data using a custom CLI script.
@@ -7433,6 +7433,219 @@ 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.
 
 
+# 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!/events-reference) 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.
+
+## Event Types
+
+In your customization, you can emit an event, then listen to it in a subscriber and perform an asynchronus action, such as send a notification or data to a third-party system.
+
+There are two types of events in Medusa:
+
+1. Workflow event: an event that's emitted in a workflow after a commerce feature is performed. For example, Medusa emits the `order.placed` event after a cart is completed.
+2. Service event: an event that's emitted to track, trace, or debug processes under the hood. For example, you can emit an event with an audit trail.
+
+### Which Event Type to Use?
+
+**Workflow events** are the most common event type in development, as most custom features and customizations are built around workflows.
+
+Some examples of workflow events:
+
+1. When a user creates a blog post and you're emitting an event to send a newsletter email.
+2. When you finish syncing products to a third-party system and you want to notify the admin user of new products added.
+3. When a customer purchases a digital product and you want to generate and send it to them.
+
+You should only go for a **service event** if you're emitting an event for processes under the hood that don't directly affect front-facing features.
+
+Some examples of service events:
+
+1. When you're tracing data manipulation and changes, and you want to track every time some custom data is changed.
+2. When you're syncing data with a search engine.
+
+***
+
+## Emit Event in a Workflow
+
+To emit a workflow event, use the `emitEventStep` helper step provided in the `@medusajs/medusa/core-flows` package.
+
+For example:
+
+```ts highlights={highlights}
+import { 
+  createWorkflow,
+} from "@medusajs/framework/workflows-sdk"
+import {
+  emitEventStep,
+} from "@medusajs/medusa/core-flows"
+
+const helloWorldWorkflow = createWorkflow(
+  "hello-world",
+  () => {
+    // ...
+
+    emitEventStep({
+      eventName: "custom.created",
+      data: {
+        id: "123",
+        // other data payload
+      },
+    })
+  }
+)
+```
+
+The `emitEventStep` accepts an object having the following properties:
+
+- `eventName`: The event's name.
+- `data`: The data payload as an object. You can pass any properties in the object, and subscribers listening to the event will receive this data in the event's payload.
+
+In this example, you emit the event `custom.created` and pass in the data payload an ID property.
+
+### Test it Out
+
+If you execute the workflow, the event is emitted and you can see it in your application's logs.
+
+Any subscribers listening to the event are executed.
+
+***
+
+## Emit Event in a Service
+
+To emit a service event:
+
+1. Resolve `event_bus` from the module's container in your service's constructor:
+
+### Extending Service Factory
+
+```ts title="src/modules/blog/service.ts" highlights={["9"]}
+import { IEventBusService } from "@medusajs/framework/types"
+import { MedusaService } from "@medusajs/framework/utils"
+
+class BlogModuleService extends MedusaService({
+  Post,
+}){
+  protected eventBusService_: AbstractEventBusModuleService
+
+  constructor({ event_bus }) {
+    super(...arguments)
+    this.eventBusService_ = event_bus
+  }
+}
+```
+
+### Without Service Factory
+
+```ts title="src/modules/blog/service.ts" highlights={["6"]}
+import { IEventBusService } from "@medusajs/framework/types"
+
+class BlogModuleService {
+  protected eventBusService_: AbstractEventBusModuleService
+
+  constructor({ event_bus }) {
+    this.eventBusService_ = event_bus
+  }
+}
+```
+
+2. Use the event bus service's `emit` method in the service's methods to emit an event:
+
+```ts title="src/modules/blog/service.ts" highlights={serviceHighlights}
+class BlogModuleService {
+  // ...
+  performAction() {
+    // TODO perform action
+
+    this.eventBusService_.emit({
+      name: "custom.event",
+      data: {
+        id: "123",
+        // other data payload
+      },
+    })
+  }
+}
+```
+
+The method accepts an object having the following properties:
+
+- `name`: The event's name.
+- `data`: The data payload as an object. You can pass any properties in the object, and subscribers listening to the event will receive this data in the event's payload.
+
+3. By default, the Event Module's service isn't injected into your module's container. To add it to the container, pass it in the module's registration object in `medusa-config.ts` in the `dependencies` property:
+
+```ts title="medusa-config.ts" highlights={depsHighlight}
+import { Modules } from "@medusajs/framework/utils"
+
+module.exports = defineConfig({
+  // ...
+  modules: [
+    {
+      resolve: "./src/modules/blog",
+      dependencies: [
+        Modules.EVENT_BUS,
+      ],
+    },
+  ],
+})
+```
+
+The `dependencies` property accepts an array of module registration keys. The specified modules' main services are injected into the module's container.
+
+That's how you can resolve it in your module's main service's constructor.
+
+### Test it Out
+
+If you execute the `performAction` method of your service, the event is emitted and you can see it in your application's logs.
+
+Any subscribers listening to the event are also executed.
+
+
 # Add Data Model Check Constraints
 
 In this chapter, you'll learn how to add check constraints to your data model.
@@ -7505,6 +7718,46 @@ 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.
 
 
+# Infer Type of Data Model
+
+In this chapter, you'll learn how to infer the type of a data model.
+
+## How to Infer Type of Data Model?
+
+Consider you have a `Post` data model. You can't reference this data model in a type, such as a workflow input or service method output types, since it's a variable.
+
+Instead, Medusa provides `InferTypeOf` that transforms your data model to a type.
+
+For example:
+
+```ts
+import { InferTypeOf } from "@medusajs/framework/types"
+import { Post } from "../modules/blog/models/post" // relative path to the model
+
+export type Post = InferTypeOf<typeof Post>
+```
+
+`InferTypeOf` accepts as a type argument the type of the data model.
+
+Since the `Post` data model is a variable, use the `typeof` operator to pass the data model as a type argument to `InferTypeOf`.
+
+You can now use the `Post` type to reference a data model in other types, such as in workflow inputs or service method outputs:
+
+```ts title="Example Service"
+// other imports...
+import { InferTypeOf } from "@medusajs/framework/types"
+import { Post } from "../models/post"
+
+type Post = InferTypeOf<typeof Post>
+
+class BlogModuleService extends MedusaService({ Post }) {
+  async doSomething(): Promise<Post> {
+    // ...
+  }
+}
+```
+
+
 # Data Model Database Index
 
 In this chapter, you’ll learn how to define a database index on a data model.
@@ -7617,264 +7870,6 @@ export default MyCustom
 This creates a unique composite index on the `name` and `age` properties.
 
 
-# Infer Type of Data Model
-
-In this chapter, you'll learn how to infer the type of a data model.
-
-## How to Infer Type of Data Model?
-
-Consider you have a `Post` data model. You can't reference this data model in a type, such as a workflow input or service method output types, since it's a variable.
-
-Instead, Medusa provides `InferTypeOf` that transforms your data model to a type.
-
-For example:
-
-```ts
-import { InferTypeOf } from "@medusajs/framework/types"
-import { Post } from "../modules/blog/models/post" // relative path to the model
-
-export type Post = InferTypeOf<typeof Post>
-```
-
-`InferTypeOf` accepts as a type argument the type of the data model.
-
-Since the `Post` data model is a variable, use the `typeof` operator to pass the data model as a type argument to `InferTypeOf`.
-
-You can now use the `Post` type to reference a data model in other types, such as in workflow inputs or service method outputs:
-
-```ts title="Example Service"
-// other imports...
-import { InferTypeOf } from "@medusajs/framework/types"
-import { Post } from "../models/post"
-
-type Post = InferTypeOf<typeof Post>
-
-class BlogModuleService extends MedusaService({ Post }) {
-  async doSomething(): Promise<Post> {
-    // ...
-  }
-}
-```
-
-
-# Manage Relationships
-
-In this chapter, you'll learn how to manage relationships between data models when creating, updating, or retrieving records using the module's main service.
-
-## Manage One-to-One Relationship
-
-### BelongsTo Side of One-to-One
-
-When you create a record of a data model that belongs to another through a one-to-one relation, pass the ID of the other data model's record in the `{relation}_id` property, where `{relation}` is the name of the relation property.
-
-For example, assuming you have the [User and Email data models from the previous chapter](https://docs.medusajs.com/learn/fundamentals/data-models/relationships#one-to-one-relationship/index.html.md), set an email's user ID as follows:
-
-```ts highlights={belongsHighlights}
-// when creating an email
-const email = await helloModuleService.createEmails({
-  // other properties...
-  user_id: "123",
-})
-
-// when updating an email
-const email = await helloModuleService.updateEmails({
-  id: "321",
-  // other properties...
-  user_id: "123",
-})
-```
-
-In the example above, you pass the `user_id` property when creating or updating an email to specify the user it belongs to.
-
-### HasOne Side
-
-When you create a record of a data model that has one of another, pass the ID of the other data model's record in the relation property.
-
-For example, assuming you have the [User and Email data models from the previous chapter](https://docs.medusajs.com/learn/fundamentals/data-models/relationships#one-to-one-relationship/index.html.md), set a user's email ID as follows:
-
-```ts highlights={hasOneHighlights}
-// when creating a user
-const user = await helloModuleService.createUsers({
-  // other properties...
-  email: "123",
-})
-
-// when updating a user
-const user = await helloModuleService.updateUsers({
-  id: "321",
-  // other properties...
-  email: "123",
-})
-```
-
-In the example above, you pass the `email` property when creating or updating a user to specify the email it has.
-
-***
-
-## Manage One-to-Many Relationship
-
-In a one-to-many relationship, you can only manage the associations from the `belongsTo` side.
-
-When you create a record of the data model on the `belongsTo` side, pass the ID of the other data model's record in the `{relation}_id` property, where `{relation}` is the name of the relation property.
-
-For example, assuming you have the [Product and Store data models from the previous chapter](https://docs.medusajs.com/learn/fundamentals/data-models/relationships#one-to-many-relationship/index.html.md), set a product's store ID as follows:
-
-```ts highlights={manyBelongsHighlights}
-// when creating a product
-const product = await helloModuleService.createProducts({
-  // other properties...
-  store_id: "123",
-})
-
-// when updating a product
-const product = await helloModuleService.updateProducts({
-  id: "321",
-  // other properties...
-  store_id: "123",
-})
-```
-
-In the example above, you pass the `store_id` property when creating or updating a product to specify the store it belongs to.
-
-***
-
-## Manage Many-to-Many Relationship
-
-If your many-to-many relation is represented with a [pivotEntity](https://docs.medusajs.com/learn/fundamentals/data-models/relationships#many-to-many-with-custom-columns/index.html.md), refer to [this section](#manage-many-to-many-relationship-with-pivotentity) instead.
-
-### Create Associations
-
-When you create a record of a data model that has a many-to-many relationship to another data model, pass an array of IDs of the other data model's records in the relation property.
-
-For example, assuming you have the [Order and Product data models from the previous chapter](https://docs.medusajs.com/learn/fundamentals/data-models/relationships#many-to-many-relationship/index.html.md), set the association between products and orders as follows:
-
-```ts highlights={manyHighlights}
-// when creating a product
-const product = await helloModuleService.createProducts({
-  // other properties...
-  orders: ["123", "321"],
-})
-
-// when creating an order
-const order = await helloModuleService.createOrders({
-  id: "321",
-  // other properties...
-  products: ["123", "321"],
-})
-```
-
-In the example above, you pass the `orders` property when you create a product, and you pass the `products` property when you create an order.
-
-### Update Associations
-
-When you use the `update` methods generated by the service factory, you also pass an array of IDs as the relation property's value to add new associated records.
-
-However, this removes any existing associations to records whose IDs aren't included in the array.
-
-For example, assuming you have the [Order and Product data models from the previous chapter](https://docs.medusajs.com/learn/fundamentals/data-models/relationships#many-to-many-relationship/index.html.md), you update the product's related orders as so:
-
-```ts
-const product = await helloModuleService.updateProducts({
-  id: "123",
-  // other properties...
-  orders: ["321"],
-})
-```
-
-If the product was associated with an order, and you don't include that order's ID in the `orders` array, the association between the product and order is removed.
-
-So, to add a new association without removing existing ones, retrieve the product first to pass its associated orders when updating the product:
-
-```ts highlights={updateAssociationHighlights}
-const product = await helloModuleService.retrieveProduct(
-  "123",
-  {
-    relations: ["orders"],
-  }
-)
-
-const updatedProduct = await helloModuleService.updateProducts({
-  id: product.id,
-  // other properties...
-  orders: [
-    ...product.orders.map((order) => order.id),
-    "321",
-  ],
-})
-```
-
-This keeps existing associations between the product and orders, and adds a new one.
-
-***
-
-## Manage Many-to-Many Relationship with pivotEntity
-
-If your many-to-many relation is represented without a [pivotEntity](https://docs.medusajs.com/learn/fundamentals/data-models/relationships#many-to-many-with-custom-columns/index.html.md), refer to [this section](#manage-many-to-many-relationship) instead.
-
-If you have a many-to-many relation with a `pivotEntity` specified, make sure to pass the data model representing the pivot table to [MedusaService](https://docs.medusajs.com/learn/fundamentals/modules/service-factory/index.html.md) that your module's service extends.
-
-For example, assuming you have the [Order, Product, and OrderProduct models from the previous chapter](https://docs.medusajs.com/learn/fundamentals/data-models/relationships#many-to-many-with-custom-columns/index.html.md), add `OrderProduct` to `MedusaService`'s object parameter:
-
-```ts highlights={["4"]}
-class BlogModuleService extends MedusaService({
-  Order,
-  Product,
-  OrderProduct,
-}) {}
-```
-
-This will generate Create, Read, Update and Delete (CRUD) methods for the `OrderProduct` data model, which you can use to create relations between orders and products and manage the extra columns in the pivot table.
-
-For example:
-
-```ts
-// create order-product association
-const orderProduct = await blogModuleService.createOrderProducts({
-  order_id: "123",
-  product_id: "123",
-  metadata: {
-    test: true,
-  },
-})
-
-// update order-product association
-const orderProduct = await blogModuleService.updateOrderProducts({
-  id: "123",
-  metadata: {
-    test: false,
-  },
-})
-
-// delete order-product association
-await blogModuleService.deleteOrderProducts("123")
-```
-
-Since the `OrderProduct` data model belongs to the `Order` and `Product` data models, you can set its order and product as explained in the [one-to-many relationship section](#manage-one-to-many-relationship) using `order_id` and `product_id`.
-
-Refer to the [service factory reference](https://docs.medusajs.com/resources/service-factory-reference/index.html.md) for a full list of generated methods and their usages.
-
-***
-
-## Retrieve Records of Relation
-
-The `list`, `listAndCount`, and `retrieve` methods of a module's main service accept as a second parameter an object of options.
-
-To retrieve the records associated with a data model's records through a relationship, pass in the second parameter object a `relations` property whose value is an array of relationship names.
-
-For example, assuming you have the [Order and Product data models from the previous chapter](https://docs.medusajs.com/learn/fundamentals/data-models/relationships#many-to-many-relationship/index.html.md), you retrieve a product's orders as follows:
-
-```ts highlights={retrieveHighlights}
-const product = await blogModuleService.retrieveProducts(
-  "123",
-  {
-    relations: ["orders"],
-  }
-)
-```
-
-In the example above, the retrieved product has an `orders` property, whose value is an array of orders associated with the product.
-
-
 # Data Model Properties
 
 In this chapter, you'll learn about the different property types you can use in a data model and how to configure a data model's properties.
@@ -8227,6 +8222,322 @@ const posts = await blogModuleService.listPosts({
 This retrieves records that include `New Products` in their `title` property.
 
 
+# Manage Relationships
+
+In this chapter, you'll learn how to manage relationships between data models when creating, updating, or retrieving records using the module's main service.
+
+## Manage One-to-One Relationship
+
+### BelongsTo Side of One-to-One
+
+When you create a record of a data model that belongs to another through a one-to-one relation, pass the ID of the other data model's record in the `{relation}_id` property, where `{relation}` is the name of the relation property.
+
+For example, assuming you have the [User and Email data models from the previous chapter](https://docs.medusajs.com/learn/fundamentals/data-models/relationships#one-to-one-relationship/index.html.md), set an email's user ID as follows:
+
+```ts highlights={belongsHighlights}
+// when creating an email
+const email = await helloModuleService.createEmails({
+  // other properties...
+  user_id: "123",
+})
+
+// when updating an email
+const email = await helloModuleService.updateEmails({
+  id: "321",
+  // other properties...
+  user_id: "123",
+})
+```
+
+In the example above, you pass the `user_id` property when creating or updating an email to specify the user it belongs to.
+
+### HasOne Side
+
+When you create a record of a data model that has one of another, pass the ID of the other data model's record in the relation property.
+
+For example, assuming you have the [User and Email data models from the previous chapter](https://docs.medusajs.com/learn/fundamentals/data-models/relationships#one-to-one-relationship/index.html.md), set a user's email ID as follows:
+
+```ts highlights={hasOneHighlights}
+// when creating a user
+const user = await helloModuleService.createUsers({
+  // other properties...
+  email: "123",
+})
+
+// when updating a user
+const user = await helloModuleService.updateUsers({
+  id: "321",
+  // other properties...
+  email: "123",
+})
+```
+
+In the example above, you pass the `email` property when creating or updating a user to specify the email it has.
+
+***
+
+## Manage One-to-Many Relationship
+
+In a one-to-many relationship, you can only manage the associations from the `belongsTo` side.
+
+When you create a record of the data model on the `belongsTo` side, pass the ID of the other data model's record in the `{relation}_id` property, where `{relation}` is the name of the relation property.
+
+For example, assuming you have the [Product and Store data models from the previous chapter](https://docs.medusajs.com/learn/fundamentals/data-models/relationships#one-to-many-relationship/index.html.md), set a product's store ID as follows:
+
+```ts highlights={manyBelongsHighlights}
+// when creating a product
+const product = await helloModuleService.createProducts({
+  // other properties...
+  store_id: "123",
+})
+
+// when updating a product
+const product = await helloModuleService.updateProducts({
+  id: "321",
+  // other properties...
+  store_id: "123",
+})
+```
+
+In the example above, you pass the `store_id` property when creating or updating a product to specify the store it belongs to.
+
+***
+
+## Manage Many-to-Many Relationship
+
+If your many-to-many relation is represented with a [pivotEntity](https://docs.medusajs.com/learn/fundamentals/data-models/relationships#many-to-many-with-custom-columns/index.html.md), refer to [this section](#manage-many-to-many-relationship-with-pivotentity) instead.
+
+### Create Associations
+
+When you create a record of a data model that has a many-to-many relationship to another data model, pass an array of IDs of the other data model's records in the relation property.
+
+For example, assuming you have the [Order and Product data models from the previous chapter](https://docs.medusajs.com/learn/fundamentals/data-models/relationships#many-to-many-relationship/index.html.md), set the association between products and orders as follows:
+
+```ts highlights={manyHighlights}
+// when creating a product
+const product = await helloModuleService.createProducts({
+  // other properties...
+  orders: ["123", "321"],
+})
+
+// when creating an order
+const order = await helloModuleService.createOrders({
+  id: "321",
+  // other properties...
+  products: ["123", "321"],
+})
+```
+
+In the example above, you pass the `orders` property when you create a product, and you pass the `products` property when you create an order.
+
+### Update Associations
+
+When you use the `update` methods generated by the service factory, you also pass an array of IDs as the relation property's value to add new associated records.
+
+However, this removes any existing associations to records whose IDs aren't included in the array.
+
+For example, assuming you have the [Order and Product data models from the previous chapter](https://docs.medusajs.com/learn/fundamentals/data-models/relationships#many-to-many-relationship/index.html.md), you update the product's related orders as so:
+
+```ts
+const product = await helloModuleService.updateProducts({
+  id: "123",
+  // other properties...
+  orders: ["321"],
+})
+```
+
+If the product was associated with an order, and you don't include that order's ID in the `orders` array, the association between the product and order is removed.
+
+So, to add a new association without removing existing ones, retrieve the product first to pass its associated orders when updating the product:
+
+```ts highlights={updateAssociationHighlights}
+const product = await helloModuleService.retrieveProduct(
+  "123",
+  {
+    relations: ["orders"],
+  }
+)
+
+const updatedProduct = await helloModuleService.updateProducts({
+  id: product.id,
+  // other properties...
+  orders: [
+    ...product.orders.map((order) => order.id),
+    "321",
+  ],
+})
+```
+
+This keeps existing associations between the product and orders, and adds a new one.
+
+***
+
+## Manage Many-to-Many Relationship with pivotEntity
+
+If your many-to-many relation is represented without a [pivotEntity](https://docs.medusajs.com/learn/fundamentals/data-models/relationships#many-to-many-with-custom-columns/index.html.md), refer to [this section](#manage-many-to-many-relationship) instead.
+
+If you have a many-to-many relation with a `pivotEntity` specified, make sure to pass the data model representing the pivot table to [MedusaService](https://docs.medusajs.com/learn/fundamentals/modules/service-factory/index.html.md) that your module's service extends.
+
+For example, assuming you have the [Order, Product, and OrderProduct models from the previous chapter](https://docs.medusajs.com/learn/fundamentals/data-models/relationships#many-to-many-with-custom-columns/index.html.md), add `OrderProduct` to `MedusaService`'s object parameter:
+
+```ts highlights={["4"]}
+class BlogModuleService extends MedusaService({
+  Order,
+  Product,
+  OrderProduct,
+}) {}
+```
+
+This will generate Create, Read, Update and Delete (CRUD) methods for the `OrderProduct` data model, which you can use to create relations between orders and products and manage the extra columns in the pivot table.
+
+For example:
+
+```ts
+// create order-product association
+const orderProduct = await blogModuleService.createOrderProducts({
+  order_id: "123",
+  product_id: "123",
+  metadata: {
+    test: true,
+  },
+})
+
+// update order-product association
+const orderProduct = await blogModuleService.updateOrderProducts({
+  id: "123",
+  metadata: {
+    test: false,
+  },
+})
+
+// delete order-product association
+await blogModuleService.deleteOrderProducts("123")
+```
+
+Since the `OrderProduct` data model belongs to the `Order` and `Product` data models, you can set its order and product as explained in the [one-to-many relationship section](#manage-one-to-many-relationship) using `order_id` and `product_id`.
+
+Refer to the [service factory reference](https://docs.medusajs.com/resources/service-factory-reference/index.html.md) for a full list of generated methods and their usages.
+
+***
+
+## Retrieve Records of Relation
+
+The `list`, `listAndCount`, and `retrieve` methods of a module's main service accept as a second parameter an object of options.
+
+To retrieve the records associated with a data model's records through a relationship, pass in the second parameter object a `relations` property whose value is an array of relationship names.
+
+For example, assuming you have the [Order and Product data models from the previous chapter](https://docs.medusajs.com/learn/fundamentals/data-models/relationships#many-to-many-relationship/index.html.md), you retrieve a product's orders as follows:
+
+```ts highlights={retrieveHighlights}
+const product = await blogModuleService.retrieveProducts(
+  "123",
+  {
+    relations: ["orders"],
+  }
+)
+```
+
+In the example above, the retrieved product has an `orders` property, whose value is an array of orders associated with the product.
+
+
+# Migrations
+
+In this chapter, you'll learn what a migration is and how to generate a migration or write it manually.
+
+## What is a Migration?
+
+A migration is a TypeScript or JavaScript file that defines database changes made by a module. Migrations are useful when you re-use a module or you're working in a team, so that when one member of a team makes a database change, everyone else can reflect it on their side by running the migrations.
+
+The migration's file has a class with two methods:
+
+- The `up` method reflects changes on the database.
+- The `down` method reverts the changes made in the `up` method.
+
+***
+
+## Generate Migration
+
+Instead of you writing the migration manually, the Medusa CLI tool provides a [db:generate](https://docs.medusajs.com/resources/medusa-cli/commands/db#dbgenerate/index.html.md) command to generate a migration for a modules' data models.
+
+For example, assuming you have a `blog` Module, you can generate a migration for it by running the following command:
+
+```bash
+npx medusa db:generate blog
+```
+
+This generates a migration file under the `migrations` directory of the Blog Module. You can then run it to reflect the changes in the database as mentioned in [this section](#run-the-migration).
+
+***
+
+## Write a Migration Manually
+
+You can also write migrations manually. To do that, create a file in the `migrations` directory of the module and in it, a class that has an `up` and `down` method. The class's name should be of the format `Migration{YEAR}{MONTH}{DAY}{HOUR}{MINUTE}.ts` to ensure migrations are ran in the correct order.
+
+For example:
+
+```ts title="src/modules/blog/migrations/Migration202507021059.ts"
+import { Migration } from "@mikro-orm/migrations"
+
+export class Migration202507021059 extends Migration {
+
+  async up(): Promise<void> {
+    this.addSql("create table if not exists \"author\" (\"id\" text not null, \"name\" text not null, \"created_at\" timestamptz not null default now(), \"updated_at\" timestamptz not null default now(), \"deleted_at\" timestamptz null, constraint \"author_pkey\" primary key (\"id\"));")
+  }
+
+  async down(): Promise<void> {
+    this.addSql("drop table if exists \"author\" cascade;")
+  }
+
+}
+```
+
+The migration class in the file extends the `Migration` class imported from `@mikro-orm/migrations`. In the `up` and `down` method of the migration class, you use the `addSql` method provided by MikroORM's `Migration` class to run PostgreSQL syntax.
+
+In the example above, the `up` method creates the table `author`, and the `down` method drops the table if the migration is reverted.
+
+Refer to [MikroORM's documentation](https://mikro-orm.io/docs/migrations#migration-class) for more details on writing migrations.
+
+***
+
+## Run the Migration
+
+To run your migration, run the following command:
+
+This command also syncs module links. If you don't want that, use the `--skip-links` option.
+
+```bash
+npx medusa db:migrate
+```
+
+This reflects the changes in the database as implemented in the migration's `up` method.
+
+***
+
+## Rollback the Migration
+
+To rollback or revert the last migration you ran for a module, run the following command:
+
+```bash
+npx medusa db:rollback blog
+```
+
+This rolls back the last ran migration on the Blog Module.
+
+### Caution: Rollback Migration before Deleting
+
+If you need to delete a migration file, make sure to rollback the migration first. Otherwise, you might encounter issues when generating and running new migrations.
+
+For example, if you delete the migration of the Blog Module, then try to create a new one, Medusa will create a brand new migration that re-creates the tables or indices. If those are still in the database, you might encounter errors.
+
+So, always rollback the migration before deleting it.
+
+***
+
+## More Database Commands
+
+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).
+
+
 # Data Model Relationships
 
 In this chapter, you’ll learn how to define relationships between data models in your module.
@@ -8522,316 +8833,66 @@ 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.
 
 
-# Event Data Payload
+# Module Link Direction
 
-In this chapter, you'll learn how subscribers receive an event's data payload.
+In this chapter, you'll learn about the difference in module link directions, and which to use based on your use case.
 
-## Access Event's Data Payload
+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.
 
-When events are emitted, they’re emitted with a data payload.
+## Link Direction
 
-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.
+The module link's direction depends on the order you pass the data model configuration parameters to `defineLink`.
 
-For example:
+For example, the following defines a link from the Blog Module's `post` data model to the Product Module's `product` data model:
 
-```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!/events-reference) for a full list of events emitted by Medusa and their data payloads. */}
-
-
-# Migrations
-
-In this chapter, you'll learn what a migration is and how to generate a migration or write it manually.
-
-## What is a Migration?
-
-A migration is a TypeScript or JavaScript file that defines database changes made by a module. Migrations are useful when you re-use a module or you're working in a team, so that when one member of a team makes a database change, everyone else can reflect it on their side by running the migrations.
-
-The migration's file has a class with two methods:
-
-- The `up` method reflects changes on the database.
-- The `down` method reverts the changes made in the `up` method.
-
-***
-
-## Generate Migration
-
-Instead of you writing the migration manually, the Medusa CLI tool provides a [db:generate](https://docs.medusajs.com/resources/medusa-cli/commands/db#dbgenerate/index.html.md) command to generate a migration for a modules' data models.
-
-For example, assuming you have a `blog` Module, you can generate a migration for it by running the following command:
-
-```bash
-npx medusa db:generate blog
-```
-
-This generates a migration file under the `migrations` directory of the Blog Module. You can then run it to reflect the changes in the database as mentioned in [this section](#run-the-migration).
-
-***
-
-## Write a Migration Manually
-
-You can also write migrations manually. To do that, create a file in the `migrations` directory of the module and in it, a class that has an `up` and `down` method. The class's name should be of the format `Migration{YEAR}{MONTH}{DAY}{HOUR}{MINUTE}.ts` to ensure migrations are ran in the correct order.
-
-For example:
-
-```ts title="src/modules/blog/migrations/Migration202507021059.ts"
-import { Migration } from "@mikro-orm/migrations"
-
-export class Migration202507021059 extends Migration {
-
-  async up(): Promise<void> {
-    this.addSql("create table if not exists \"author\" (\"id\" text not null, \"name\" text not null, \"created_at\" timestamptz not null default now(), \"updated_at\" timestamptz not null default now(), \"deleted_at\" timestamptz null, constraint \"author_pkey\" primary key (\"id\"));")
-  }
-
-  async down(): Promise<void> {
-    this.addSql("drop table if exists \"author\" cascade;")
-  }
-
-}
-```
-
-The migration class in the file extends the `Migration` class imported from `@mikro-orm/migrations`. In the `up` and `down` method of the migration class, you use the `addSql` method provided by MikroORM's `Migration` class to run PostgreSQL syntax.
-
-In the example above, the `up` method creates the table `author`, and the `down` method drops the table if the migration is reverted.
-
-Refer to [MikroORM's documentation](https://mikro-orm.io/docs/migrations#migration-class) for more details on writing migrations.
-
-***
-
-## Run the Migration
-
-To run your migration, run the following command:
-
-This command also syncs module links. If you don't want that, use the `--skip-links` option.
-
-```bash
-npx medusa db:migrate
-```
-
-This reflects the changes in the database as implemented in the migration's `up` method.
-
-***
-
-## Rollback the Migration
-
-To rollback or revert the last migration you ran for a module, run the following command:
-
-```bash
-npx medusa db:rollback blog
-```
-
-This rolls back the last ran migration on the Blog Module.
-
-### Caution: Rollback Migration before Deleting
-
-If you need to delete a migration file, make sure to rollback the migration first. Otherwise, you might encounter issues when generating and running new migrations.
-
-For example, if you delete the migration of the Blog Module, then try to create a new one, Medusa will create a brand new migration that re-creates the tables or indices. If those are still in the database, you might encounter errors.
-
-So, always rollback the migration before deleting it.
-
-***
-
-## More Database Commands
-
-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).
-
-
-# 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.
-
-## Event Types
-
-In your customization, you can emit an event, then listen to it in a subscriber and perform an asynchronus action, such as send a notification or data to a third-party system.
-
-There are two types of events in Medusa:
-
-1. Workflow event: an event that's emitted in a workflow after a commerce feature is performed. For example, Medusa emits the `order.placed` event after a cart is completed.
-2. Service event: an event that's emitted to track, trace, or debug processes under the hood. For example, you can emit an event with an audit trail.
-
-### Which Event Type to Use?
-
-**Workflow events** are the most common event type in development, as most custom features and customizations are built around workflows.
-
-Some examples of workflow events:
-
-1. When a user creates a blog post and you're emitting an event to send a newsletter email.
-2. When you finish syncing products to a third-party system and you want to notify the admin user of new products added.
-3. When a customer purchases a digital product and you want to generate and send it to them.
-
-You should only go for a **service event** if you're emitting an event for processes under the hood that don't directly affect front-facing features.
-
-Some examples of service events:
-
-1. When you're tracing data manipulation and changes, and you want to track every time some custom data is changed.
-2. When you're syncing data with a search engine.
-
-***
-
-## Emit Event in a Workflow
-
-To emit a workflow event, use the `emitEventStep` helper step provided in the `@medusajs/medusa/core-flows` package.
-
-For example:
-
-```ts highlights={highlights}
-import { 
-  createWorkflow,
-} from "@medusajs/framework/workflows-sdk"
-import {
-  emitEventStep,
-} from "@medusajs/medusa/core-flows"
-
-const helloWorldWorkflow = createWorkflow(
-  "hello-world",
-  () => {
-    // ...
-
-    emitEventStep({
-      eventName: "custom.created",
-      data: {
-        id: "123",
-        // other data payload
-      },
-    })
-  }
+```ts
+export default defineLink(
+  BlogModule.linkable.post,
+  ProductModule.linkable.product
 )
 ```
 
-The `emitEventStep` accepts an object having the following properties:
+Whereas the following defines a link from the Product Module's `product` data model to the Blog Module's `post` data model:
 
-- `eventName`: The event's name.
-- `data`: The data payload as an object. You can pass any properties in the object, and subscribers listening to the event will receive this data in the event's payload.
+```ts
+export default defineLink(
+  ProductModule.linkable.product,
+  BlogModule.linkable.post
+)
+```
 
-In this example, you emit the event `custom.created` and pass in the data payload an ID property.
-
-### Test it Out
-
-If you execute the workflow, the event is emitted and you can see it in your application's logs.
-
-Any subscribers listening to the event are executed.
+The above links are two different links that serve different purposes.
 
 ***
 
-## Emit Event in a Service
+## Which Link Direction to Use?
 
-To emit a service event:
+### Extend Data Models
 
-1. Resolve `event_bus` from the module's container in your service's constructor:
+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.
 
-### Extending Service Factory
+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 title="src/modules/blog/service.ts" highlights={["9"]}
-import { IEventBusService } from "@medusajs/framework/types"
-import { MedusaService } from "@medusajs/framework/utils"
-
-class BlogModuleService extends MedusaService({
-  Post,
-}){
-  protected eventBusService_: AbstractEventBusModuleService
-
-  constructor({ event_bus }) {
-    super(...arguments)
-    this.eventBusService_ = event_bus
-  }
-}
+```ts
+export default defineLink(
+  ProductModule.linkable.product,
+  BlogModule.linkable.subtitle
+)
 ```
 
-### Without Service Factory
+### Associate Data Models
 
-```ts title="src/modules/blog/service.ts" highlights={["6"]}
-import { IEventBusService } from "@medusajs/framework/types"
+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.
 
-class BlogModuleService {
-  protected eventBusService_: AbstractEventBusModuleService
+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`:
 
-  constructor({ event_bus }) {
-    this.eventBusService_ = event_bus
-  }
-}
+```ts
+export default defineLink(
+  BlogModule.linkable.post,
+  ProductModule.linkable.product
+)
 ```
 
-2. Use the event bus service's `emit` method in the service's methods to emit an event:
-
-```ts title="src/modules/blog/service.ts" highlights={serviceHighlights}
-class BlogModuleService {
-  // ...
-  performAction() {
-    // TODO perform action
-
-    this.eventBusService_.emit({
-      name: "custom.event",
-      data: {
-        id: "123",
-        // other data payload
-      },
-    })
-  }
-}
-```
-
-The method accepts an object having the following properties:
-
-- `name`: The event's name.
-- `data`: The data payload as an object. You can pass any properties in the object, and subscribers listening to the event will receive this data in the event's payload.
-
-3. By default, the Event Module's service isn't injected into your module's container. To add it to the container, pass it in the module's registration object in `medusa-config.ts` in the `dependencies` property:
-
-```ts title="medusa-config.ts" highlights={depsHighlight}
-import { Modules } from "@medusajs/framework/utils"
-
-module.exports = defineConfig({
-  // ...
-  modules: [
-    {
-      resolve: "./src/modules/blog",
-      dependencies: [
-        Modules.EVENT_BUS,
-      ],
-    },
-  ],
-})
-```
-
-The `dependencies` property accepts an array of module registration keys. The specified modules' main services are injected into the module's container.
-
-That's how you can resolve it in your module's main service's constructor.
-
-### Test it Out
-
-If you execute the `performAction` method of your service, the event is emitted and you can see it in your application's logs.
-
-Any subscribers listening to the event are also executed.
-
 
 # Add Columns to a Link Table
 
@@ -8991,1033 +9052,6 @@ await link.create({
 ```
 
 
-# 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
-)
-```
-
-
-# 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<void> {
-  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",
-  },
-})
-```
-
-
-# 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<any> | 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<any> | 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<any> | 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).
-
-
-# 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.
-
-
-# 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.
-
-![Diagram illustrating the read-only module link from cart to customer](https://res.cloudinary.com/dza7lstvk/image/upload/v1742212508/Medusa%20Book/cart-customer_w6vk59.jpg)
-
-***
-
-## 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<any> | 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).
-
-
 # Query
 
 In this chapter, you’ll learn about Query and how to use it to fetch data from modules.
@@ -10574,6 +9608,986 @@ Try passing one of the Query configuration parameters, like `fields` or `limit`,
 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.
 
 
+# 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<void> {
+  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",
+  },
+})
+```
+
+
+# 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<any> | 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<any> | 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<any> | 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.
+
+![Diagram illustrating the read-only module link from cart to customer](https://res.cloudinary.com/dza7lstvk/image/upload/v1742212508/Medusa%20Book/cart-customer_w6vk59.jpg)
+
+***
+
+## 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<any> | 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
+
+In this chapter, you'll learn about Medusa's Commerce Modules.
+
+## What is a Commerce Module?
+
+Commerce Modules are built-in [modules](https://docs.medusajs.com/learn/fundamentals/modules/index.html.md) of Medusa that provide core commerce logic specific to domains like Products, Orders, Customers, Fulfillment, and much more.
+
+Medusa's Commerce Modules are used to form Medusa's default [workflows](https://docs.medusajs.com/resources/medusa-workflows-reference/index.html.md) and [APIs](https://docs.medusajs.com/api/store). For example, when you call the add to cart endpoint. the add to cart workflow runs which uses the Product Module to check if the product exists, the Inventory Module to ensure the product is available in the inventory, and the Cart Module to finally add the product to the cart.
+
+You'll find the details and steps of the add-to-cart workflow in [this workflow reference](https://docs.medusajs.com/resources/references/medusa-workflows/addToCartWorkflow/index.html.md)
+
+The core commerce logic contained in Commerce Modules is also available directly when you are building customizations. This granular access to commerce functionality is unique and expands what's possible to build with Medusa drastically.
+
+### List of Medusa's Commerce Modules
+
+Refer to [this reference](https://docs.medusajs.com/resources/commerce-modules/index.html.md) for a full list of Commerce Modules in Medusa.
+
+***
+
+## Use Commerce Modules in Custom Flows
+
+Similar to your [custom modules](https://docs.medusajs.com/learn/fundamentals/modules/index.html.md), the Medusa application registers a Commerce Module's service in the [container](https://docs.medusajs.com/learn/fundamentals/medusa-container/index.html.md). So, you can resolve it in your custom flows. This is useful as you build unique requirements extending core commerce features.
+
+For example, consider you have a [workflow](https://docs.medusajs.com/learn/fundamentals/workflows/index.html.md) (a special function that performs a task in a series of steps with rollback mechanism) that needs a step to retrieve the total number of products. You can create a step in the workflow that resolves the Product Module's service from the container to use its methods:
+
+```ts highlights={highlights}
+import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk"
+
+export const countProductsStep = createStep(
+  "count-products",
+  async ({ }, { container }) => {
+    const productModuleService = container.resolve("product")
+
+    const [,count] = await productModuleService.listAndCountProducts()
+
+    return new StepResponse(count)
+  }
+)
+```
+
+Your workflow can use services of both custom and Commerce Modules, supporting you in building custom flows without having to re-build core commerce features.
+
+
 # Create a Plugin
 
 In this chapter, you'll learn how to create a Medusa plugin and publish it.
@@ -11008,116 +11022,6 @@ npm publish
 This will publish an updated version of your plugin under a new version.
 
 
-# Module Container
-
-In this chapter, you'll learn about the module's container and how to resolve resources in that container.
-
-Since modules are isolated, each module has a local container only used by the resources of that module.
-
-So, resources in the module, such as services or loaders, can only resolve other resources registered in the module's container.
-
-### List of Registered Resources
-
-Find a list of resources or dependencies registered in a module's container in [the Container Resources reference](https://docs.medusajs.com/resources/medusa-container-resources/index.html.md).
-
-***
-
-## Resolve Resources
-
-### Services
-
-A service's constructor accepts as a first parameter an object used to resolve resources registered in the module's container.
-
-For example:
-
-```ts highlights={[["4"], ["10"]]}
-import { Logger } from "@medusajs/framework/types"
-
-type InjectedDependencies = {
-  logger: Logger
-}
-
-export default class BlogModuleService {
-  protected logger_: Logger
-
-  constructor({ logger }: InjectedDependencies) {
-    this.logger_ = logger
-
-    this.logger_.info("[BlogModuleService]: Hello World!")
-  }
-
-  // ...
-}
-```
-
-### Loader
-
-A loader function accepts as a parameter an object having the property `container`. Its value is the module's container used to resolve resources.
-
-For example:
-
-```ts highlights={[["9"]]}
-import {
-  LoaderOptions,
-} from "@medusajs/framework/types"
-import { 
-  ContainerRegistrationKeys,
-} from "@medusajs/framework/utils"
-
-export default async function helloWorldLoader({
-  container,
-}: LoaderOptions) {
-  const logger = container.resolve(ContainerRegistrationKeys.LOGGER)
-
-  logger.info("[helloWorldLoader]: Hello, World!")
-}
-```
-
-
-# Commerce Modules
-
-In this chapter, you'll learn about Medusa's Commerce Modules.
-
-## What is a Commerce Module?
-
-Commerce Modules are built-in [modules](https://docs.medusajs.com/learn/fundamentals/modules/index.html.md) of Medusa that provide core commerce logic specific to domains like Products, Orders, Customers, Fulfillment, and much more.
-
-Medusa's Commerce Modules are used to form Medusa's default [workflows](https://docs.medusajs.com/resources/medusa-workflows-reference/index.html.md) and [APIs](https://docs.medusajs.com/api/store). For example, when you call the add to cart endpoint. the add to cart workflow runs which uses the Product Module to check if the product exists, the Inventory Module to ensure the product is available in the inventory, and the Cart Module to finally add the product to the cart.
-
-You'll find the details and steps of the add-to-cart workflow in [this workflow reference](https://docs.medusajs.com/resources/references/medusa-workflows/addToCartWorkflow/index.html.md)
-
-The core commerce logic contained in Commerce Modules is also available directly when you are building customizations. This granular access to commerce functionality is unique and expands what's possible to build with Medusa drastically.
-
-### List of Medusa's Commerce Modules
-
-Refer to [this reference](https://docs.medusajs.com/resources/commerce-modules/index.html.md) for a full list of Commerce Modules in Medusa.
-
-***
-
-## Use Commerce Modules in Custom Flows
-
-Similar to your [custom modules](https://docs.medusajs.com/learn/fundamentals/modules/index.html.md), the Medusa application registers a Commerce Module's service in the [container](https://docs.medusajs.com/learn/fundamentals/medusa-container/index.html.md). So, you can resolve it in your custom flows. This is useful as you build unique requirements extending core commerce features.
-
-For example, consider you have a [workflow](https://docs.medusajs.com/learn/fundamentals/workflows/index.html.md) (a special function that performs a task in a series of steps with rollback mechanism) that needs a step to retrieve the total number of products. You can create a step in the workflow that resolves the Product Module's service from the container to use its methods:
-
-```ts highlights={highlights}
-import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk"
-
-export const countProductsStep = createStep(
-  "count-products",
-  async ({ }, { container }) => {
-    const productModuleService = container.resolve("product")
-
-    const [,count] = await productModuleService.listAndCountProducts()
-
-    return new StepResponse(count)
-  }
-)
-```
-
-Your workflow can use services of both custom and Commerce Modules, supporting you in building custom flows without having to re-build core commerce features.
-
-
 # Perform Database Operations in a Service
 
 In this chapter, you'll learn how to perform database operations in a module's service.
@@ -11725,36 +11629,70 @@ class BlogModuleService {
 ```
 
 
-# Infrastructure Modules
+# Module Container
 
-In this chapter, you’ll learn about Infrastructure Modules.
+In this chapter, you'll learn about the module's container and how to resolve resources in that container.
 
-## What is an Infrastructure Module?
+Since modules are isolated, each module has a local container only used by the resources of that module.
 
-An Infrastructure Module implements features and mechanisms related to the Medusa application’s architecture and infrastructure.
+So, resources in the module, such as services or loaders, can only resolve other resources registered in the module's container.
 
-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.
+### List of Registered Resources
+
+Find a list of resources or dependencies registered in a module's container in [the Container Resources reference](https://docs.medusajs.com/resources/medusa-container-resources/index.html.md).
 
 ***
 
-## Infrastructure Module Types
+## Resolve Resources
 
-There are different Infrastructure Module types including:
+### Services
 
-![Diagram illustrating how the modules connect to third-party services](https://res.cloudinary.com/dza7lstvk/image/upload/v1727095814/Medusa%20Book/infrastructure-modules_bj9bb9.jpg)
+A service's constructor accepts as a first parameter an object used to resolve resources registered in the module's container.
 
-- 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.
+For example:
 
-***
+```ts highlights={[["4"], ["10"]]}
+import { Logger } from "@medusajs/framework/types"
 
-## Infrastructure Modules List
+type InjectedDependencies = {
+  logger: Logger
+}
 
-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.
+export default class BlogModuleService {
+  protected logger_: Logger
+
+  constructor({ logger }: InjectedDependencies) {
+    this.logger_ = logger
+
+    this.logger_.info("[BlogModuleService]: Hello World!")
+  }
+
+  // ...
+}
+```
+
+### Loader
+
+A loader function accepts as a parameter an object having the property `container`. Its value is the module's container used to resolve resources.
+
+For example:
+
+```ts highlights={[["9"]]}
+import {
+  LoaderOptions,
+} from "@medusajs/framework/types"
+import { 
+  ContainerRegistrationKeys,
+} from "@medusajs/framework/utils"
+
+export default async function helloWorldLoader({
+  container,
+}: LoaderOptions) {
+  const logger = container.resolve(ContainerRegistrationKeys.LOGGER)
+
+  logger.info("[helloWorldLoader]: Hello, World!")
+}
+```
 
 
 # Module Isolation
@@ -11858,6 +11796,65 @@ export const syncBrandsWorkflow = createWorkflow(
 You can then use this workflow in an API route, scheduled job, or other resources that use this functionality.
 
 
+# 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:
+
+![Diagram illustrating how the modules connect to third-party services](https://res.cloudinary.com/dza7lstvk/image/upload/v1727095814/Medusa%20Book/infrastructure-modules_bj9bb9.jpg)
+
+- 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.
+
+
+# Modules Directory Structure
+
+In this document, you'll learn about the expected files and directories in your module.
+
+![Module Directory Structure Example](https://res.cloudinary.com/dza7lstvk/image/upload/v1714379976/Medusa%20Book/modules-dir-overview_nqq7ne.jpg)
+
+## 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.
+
+
 # Loaders
 
 In this chapter, you’ll learn about loaders and how to use them.
@@ -12239,198 +12236,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 Options
-
-In this chapter, you’ll learn about passing options to your module from the Medusa application’s configurations and using them in the module’s resources.
-
-## What are Module Options?
-
-A module can receive options to customize or configure its functionality. For example, if you’re creating a module that integrates a third-party service, you’ll want to receive the integration credentials in the options rather than adding them directly in your code.
-
-***
-
-## How to Pass Options to a Module?
-
-To pass options to a module, add an `options` property to the module’s configuration in `medusa-config.ts`.
-
-For example:
-
-```ts title="medusa-config.ts"
-module.exports = defineConfig({
-  // ...
-  modules: [
-    {
-      resolve: "./src/modules/blog",
-      options: {
-        capitalize: true,
-      },
-    },
-  ],
-})
-```
-
-The `options` property’s value is an object. You can pass any properties you want.
-
-### Pass Options to a Module in a Plugin
-
-If your module is part of a plugin, you can pass options to the module in the plugin’s configuration.
-
-For example:
-
-```ts title="medusa-config.ts"
-import { defineConfig } from "@medusajs/framework/utils"
-module.exports = defineConfig({
-  plugins: [
-    {
-      resolve: "@myorg/plugin-name",
-      options: {
-        capitalize: true,
-      },
-    },
-  ],
-})
-```
-
-The `options` property in the plugin configuration is passed to all modules in a plugin.
-
-***
-
-## Access Module Options in Main Service
-
-The module’s main service receives the module options as a second parameter.
-
-For example:
-
-```ts title="src/modules/blog/service.ts" highlights={[["12"], ["14", "options?: ModuleOptions"], ["17"], ["18"], ["19"]]}
-import { MedusaService } from "@medusajs/framework/utils"
-import Post from "./models/post"
-
-// recommended to define type in another file
-type ModuleOptions = {
-  capitalize?: boolean
-}
-
-export default class BlogModuleService extends MedusaService({
-  Post,
-}){
-  protected options_: ModuleOptions
-
-  constructor({}, options?: ModuleOptions) {
-    super(...arguments)
-
-    this.options_ = options || {
-      capitalize: false,
-    }
-  }
-
-  // ...
-}
-```
-
-***
-
-## Access Module Options in Loader
-
-The object that a module’s loaders receive as a parameter has an `options` property holding the module's options.
-
-For example:
-
-```ts title="src/modules/blog/loaders/hello-world.ts" highlights={[["11"], ["12", "ModuleOptions", "The type of expected module options."], ["16"]]}
-import {
-  LoaderOptions,
-} from "@medusajs/framework/types"
-
-// recommended to define type in another file
-type ModuleOptions = {
-  capitalize?: boolean
-}
-
-export default async function helloWorldLoader({
-  options,
-}: LoaderOptions<ModuleOptions>) {
-  
-  console.log(
-    "[BLOG MODULE] Just started the Medusa application!",
-    options
-  )
-}
-```
-
-***
-
-## Validate Module Options
-
-If you expect a certain option and want to throw an error if it's not provided or isn't valid, it's recommended to perform the validation in a loader. The module's service is only instantiated when it's used, whereas the loader runs the when the Medusa application starts.
-
-So, by performing the validation in the loader, you ensure you can throw an error at an early point, rather than when the module is used.
-
-For example, to validate that the Hello Module received an `apiKey` option, create the loader `src/modules/loaders/validate.ts`:
-
-```ts title="src/modules/blog/loaders/validate.ts" 
-import { LoaderOptions } from "@medusajs/framework/types"
-import { MedusaError } from "@medusajs/framework/utils"
-
-// recommended to define type in another file
-type ModuleOptions = {
-  apiKey?: string
-}
-
-export default async function validationLoader({
-  options,
-}: LoaderOptions<ModuleOptions>) {
-  if (!options.apiKey) {
-    throw new MedusaError(
-      MedusaError.Types.INVALID_DATA,
-      "Hello Module requires an apiKey option."
-    )
-  }
-}
-```
-
-Then, export the loader in the module's definition file, as explained in [this chapter](https://docs.medusajs.com/learn/fundamentals/modules/loaders/index.html.md):
-
-```ts title="src/modules/blog/index.ts"
-// other imports...
-import validationLoader from "./loaders/validate"
-
-export const BLOG_MODULE = "blog"
-
-export default Module(BLOG_MODULE, {
-  // ...
-  loaders: [validationLoader],
-})
-```
-
-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.
-
-
-# Modules Directory Structure
-
-In this document, you'll learn about the expected files and directories in your module.
-
-![Module Directory Structure Example](https://res.cloudinary.com/dza7lstvk/image/upload/v1714379976/Medusa%20Book/modules-dir-overview_nqq7ne.jpg)
-
-## 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.
-
-
 # Service Factory
 
 In this chapter, you’ll learn about what the service factory is and how to use it.
@@ -12606,6 +12411,171 @@ export default BlogModuleService
 ```
 
 
+# Module Options
+
+In this chapter, you’ll learn about passing options to your module from the Medusa application’s configurations and using them in the module’s resources.
+
+## What are Module Options?
+
+A module can receive options to customize or configure its functionality. For example, if you’re creating a module that integrates a third-party service, you’ll want to receive the integration credentials in the options rather than adding them directly in your code.
+
+***
+
+## How to Pass Options to a Module?
+
+To pass options to a module, add an `options` property to the module’s configuration in `medusa-config.ts`.
+
+For example:
+
+```ts title="medusa-config.ts"
+module.exports = defineConfig({
+  // ...
+  modules: [
+    {
+      resolve: "./src/modules/blog",
+      options: {
+        capitalize: true,
+      },
+    },
+  ],
+})
+```
+
+The `options` property’s value is an object. You can pass any properties you want.
+
+### Pass Options to a Module in a Plugin
+
+If your module is part of a plugin, you can pass options to the module in the plugin’s configuration.
+
+For example:
+
+```ts title="medusa-config.ts"
+import { defineConfig } from "@medusajs/framework/utils"
+module.exports = defineConfig({
+  plugins: [
+    {
+      resolve: "@myorg/plugin-name",
+      options: {
+        capitalize: true,
+      },
+    },
+  ],
+})
+```
+
+The `options` property in the plugin configuration is passed to all modules in a plugin.
+
+***
+
+## Access Module Options in Main Service
+
+The module’s main service receives the module options as a second parameter.
+
+For example:
+
+```ts title="src/modules/blog/service.ts" highlights={[["12"], ["14", "options?: ModuleOptions"], ["17"], ["18"], ["19"]]}
+import { MedusaService } from "@medusajs/framework/utils"
+import Post from "./models/post"
+
+// recommended to define type in another file
+type ModuleOptions = {
+  capitalize?: boolean
+}
+
+export default class BlogModuleService extends MedusaService({
+  Post,
+}){
+  protected options_: ModuleOptions
+
+  constructor({}, options?: ModuleOptions) {
+    super(...arguments)
+
+    this.options_ = options || {
+      capitalize: false,
+    }
+  }
+
+  // ...
+}
+```
+
+***
+
+## Access Module Options in Loader
+
+The object that a module’s loaders receive as a parameter has an `options` property holding the module's options.
+
+For example:
+
+```ts title="src/modules/blog/loaders/hello-world.ts" highlights={[["11"], ["12", "ModuleOptions", "The type of expected module options."], ["16"]]}
+import {
+  LoaderOptions,
+} from "@medusajs/framework/types"
+
+// recommended to define type in another file
+type ModuleOptions = {
+  capitalize?: boolean
+}
+
+export default async function helloWorldLoader({
+  options,
+}: LoaderOptions<ModuleOptions>) {
+  
+  console.log(
+    "[BLOG MODULE] Just started the Medusa application!",
+    options
+  )
+}
+```
+
+***
+
+## Validate Module Options
+
+If you expect a certain option and want to throw an error if it's not provided or isn't valid, it's recommended to perform the validation in a loader. The module's service is only instantiated when it's used, whereas the loader runs the when the Medusa application starts.
+
+So, by performing the validation in the loader, you ensure you can throw an error at an early point, rather than when the module is used.
+
+For example, to validate that the Hello Module received an `apiKey` option, create the loader `src/modules/loaders/validate.ts`:
+
+```ts title="src/modules/blog/loaders/validate.ts" 
+import { LoaderOptions } from "@medusajs/framework/types"
+import { MedusaError } from "@medusajs/framework/utils"
+
+// recommended to define type in another file
+type ModuleOptions = {
+  apiKey?: string
+}
+
+export default async function validationLoader({
+  options,
+}: LoaderOptions<ModuleOptions>) {
+  if (!options.apiKey) {
+    throw new MedusaError(
+      MedusaError.Types.INVALID_DATA,
+      "Hello Module requires an apiKey option."
+    )
+  }
+}
+```
+
+Then, export the loader in the module's definition file, as explained in [this chapter](https://docs.medusajs.com/learn/fundamentals/modules/loaders/index.html.md):
+
+```ts title="src/modules/blog/index.ts"
+// other imports...
+import validationLoader from "./loaders/validate"
+
+export const BLOG_MODULE = "blog"
+
+export default Module(BLOG_MODULE, {
+  // ...
+  loaders: [validationLoader],
+})
+```
+
+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.
+
+
 # Service Constraints
 
 This chapter lists constraints to keep in mind when creating a service.
@@ -12644,6 +12614,36 @@ export default BlogModuleService
 ```
 
 
+# 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.
+
+
 # Access Workflow Errors
 
 In this chapter, you’ll learn how to access errors that occur during a workflow’s execution.
@@ -12758,6 +12758,165 @@ The hook is available on the workflow's `hooks` property using its name `product
 You invoke the hook, passing a step function (the hook handler) as a parameter.
 
 
+# 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`.
+
+
 # Compensation Function
 
 In this chapter, you'll learn what a compensation function is and how to add it to a step.
@@ -13012,295 +13171,6 @@ The `StepResponse.permanentFailure` fails the step and its workflow, triggering
 So, if an error occurs during the loop, the compensation function will still receive the `prevData` variable to undo the changes made before the step failed.
 
 
-# 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.
-
-## Execute in a Workflow
-
-To execute a workflow in another, use the `runAsStep` method that every workflow has.
-
-For example:
-
-```ts highlights={workflowsHighlights} collapsibleLines="1-7" expandMoreButton="Show Imports"
-import {
-  createWorkflow,
-} from "@medusajs/framework/workflows-sdk"
-import { 
-  createProductsWorkflow,
-} from "@medusajs/medusa/core-flows"
-
-const workflow = createWorkflow(
-  "hello-world",
-  async (input) => {
-    const products = createProductsWorkflow.runAsStep({
-      input: {
-        products: [
-          // ...
-        ],
-      },
-    })
-
-    // ...
-  }
-)
-```
-
-Instead of invoking the workflow and passing it the container, you use its `runAsStep` method and pass it an object as a parameter.
-
-The object has an `input` property to pass input to the workflow.
-
-***
-
-## Preparing Input Data
-
-If you need to perform some data manipulation to prepare the other workflow's input data, use `transform` from the Workflows SDK.
-
-Learn about transform in [this chapter](https://docs.medusajs.com/learn/fundamentals/workflows/variable-manipulation/index.html.md).
-
-For example:
-
-```ts highlights={transformHighlights} collapsibleLines="1-12"
-import {
-  createWorkflow,
-  transform,
-} from "@medusajs/framework/workflows-sdk"
-import { 
-  createProductsWorkflow,
-} from "@medusajs/medusa/core-flows"
-
-type WorkflowInput = {
-  title: string
-}
-
-const workflow = createWorkflow(
-  "hello-product",
-  async (input: WorkflowInput) => {
-    const createProductsData = transform({
-      input,
-    }, (data) => [
-      {
-        title: `Hello ${data.input.title}`,
-      },
-    ])
-
-    const products = createProductsWorkflow.runAsStep({
-      input: {
-        products: createProductsData,
-      },
-    })
-
-    // ...
-  }
-)
-```
-
-In this example, you use the `transform` function to prepend `Hello` to the title of the product. Then, you pass the result as an input to the `createProductsWorkflow`.
-
-***
-
-## Run Workflow Conditionally
-
-To run a workflow in another based on a condition, use when-then from the Workflows SDK.
-
-Learn about when-then in [this chapter](https://docs.medusajs.com/learn/fundamentals/workflows/conditions/index.html.md).
-
-For example:
-
-```ts highlights={whenHighlights} collapsibleLines="1-16"
-import {
-  createWorkflow,
-  when,
-} from "@medusajs/framework/workflows-sdk"
-import { 
-  createProductsWorkflow,
-} from "@medusajs/medusa/core-flows"
-import { 
-  CreateProductWorkflowInputDTO,
-} from "@medusajs/framework/types"
-
-type WorkflowInput = {
-  product?: CreateProductWorkflowInputDTO
-  should_create?: boolean
-}
-
-const workflow = createWorkflow(
-  "hello-product",
-  async (input: WorkflowInput) => {
-    const product = when(input, ({ should_create }) => should_create)
-      .then(() => {
-        return createProductsWorkflow.runAsStep({
-          input: {
-            products: [input.product],
-          },
-        })
-      })
-  }
-)
-```
-
-In this example, you use when-then to run the `createProductsWorkflow` only if `should_create` (passed in the `input`) is enabled.
-
-
 # Workflow Constraints
 
 This chapter lists constraints of defining a workflow or its steps.
@@ -13649,6 +13519,136 @@ const step1 = createStep(
 ```
 
 
+# Execute Another Workflow
+
+In this chapter, you'll learn how to execute a workflow in another.
+
+## Execute in a Workflow
+
+To execute a workflow in another, use the `runAsStep` method that every workflow has.
+
+For example:
+
+```ts highlights={workflowsHighlights} collapsibleLines="1-7" expandMoreButton="Show Imports"
+import {
+  createWorkflow,
+} from "@medusajs/framework/workflows-sdk"
+import { 
+  createProductsWorkflow,
+} from "@medusajs/medusa/core-flows"
+
+const workflow = createWorkflow(
+  "hello-world",
+  async (input) => {
+    const products = createProductsWorkflow.runAsStep({
+      input: {
+        products: [
+          // ...
+        ],
+      },
+    })
+
+    // ...
+  }
+)
+```
+
+Instead of invoking the workflow and passing it the container, you use its `runAsStep` method and pass it an object as a parameter.
+
+The object has an `input` property to pass input to the workflow.
+
+***
+
+## Preparing Input Data
+
+If you need to perform some data manipulation to prepare the other workflow's input data, use `transform` from the Workflows SDK.
+
+Learn about transform in [this chapter](https://docs.medusajs.com/learn/fundamentals/workflows/variable-manipulation/index.html.md).
+
+For example:
+
+```ts highlights={transformHighlights} collapsibleLines="1-12"
+import {
+  createWorkflow,
+  transform,
+} from "@medusajs/framework/workflows-sdk"
+import { 
+  createProductsWorkflow,
+} from "@medusajs/medusa/core-flows"
+
+type WorkflowInput = {
+  title: string
+}
+
+const workflow = createWorkflow(
+  "hello-product",
+  async (input: WorkflowInput) => {
+    const createProductsData = transform({
+      input,
+    }, (data) => [
+      {
+        title: `Hello ${data.input.title}`,
+      },
+    ])
+
+    const products = createProductsWorkflow.runAsStep({
+      input: {
+        products: createProductsData,
+      },
+    })
+
+    // ...
+  }
+)
+```
+
+In this example, you use the `transform` function to prepend `Hello` to the title of the product. Then, you pass the result as an input to the `createProductsWorkflow`.
+
+***
+
+## Run Workflow Conditionally
+
+To run a workflow in another based on a condition, use when-then from the Workflows SDK.
+
+Learn about when-then in [this chapter](https://docs.medusajs.com/learn/fundamentals/workflows/conditions/index.html.md).
+
+For example:
+
+```ts highlights={whenHighlights} collapsibleLines="1-16"
+import {
+  createWorkflow,
+  when,
+} from "@medusajs/framework/workflows-sdk"
+import { 
+  createProductsWorkflow,
+} from "@medusajs/medusa/core-flows"
+import { 
+  CreateProductWorkflowInputDTO,
+} from "@medusajs/framework/types"
+
+type WorkflowInput = {
+  product?: CreateProductWorkflowInputDTO
+  should_create?: boolean
+}
+
+const workflow = createWorkflow(
+  "hello-product",
+  async (input: WorkflowInput) => {
+    const product = when(input, ({ should_create }) => should_create)
+      .then(() => {
+        return createProductsWorkflow.runAsStep({
+          input: {
+            products: [input.product],
+          },
+        })
+      })
+  }
+)
+```
+
+In this example, you use when-then to run the `createProductsWorkflow` only if `should_create` (passed in the `input`) is enabled.
+
+
 # Multiple Step Usage in Workflow
 
 In this chapter, you'll learn how to use a step multiple times in a workflow.
@@ -13723,6 +13723,59 @@ The `config` method accepts an object with a `name` property. Its value is a new
 The first `useQueryGraphStep` usage has the ID `use-query-graph`, and the second `useQueryGraphStep` usage has the ID `fetch-customers`.
 
 
+# Run Workflow Steps in Parallel
+
+In this chapter, you’ll learn how to run workflow steps in parallel.
+
+## parallelize Utility Function
+
+If your workflow has steps that don’t rely on one another’s results, run them in parallel using `parallelize` from the Workflows SDK.
+
+The workflow waits until all steps passed to the `parallelize` function finish executing before continuing to the next step.
+
+For example:
+
+```ts highlights={highlights} collapsibleLines="1-12" expandButtonLabel="Show Imports"
+import {
+  createWorkflow,
+  WorkflowResponse,
+  parallelize,
+} from "@medusajs/framework/workflows-sdk"
+import {
+  createProductStep,
+  getProductStep,
+  createPricesStep,
+  attachProductToSalesChannelStep,
+} from "./steps"
+
+interface WorkflowInput {
+  title: string
+}
+
+const myWorkflow = createWorkflow(
+  "my-workflow", 
+  (input: WorkflowInput) => {
+   const product = createProductStep(input)
+
+   const [prices, productSalesChannel] = parallelize(
+     createPricesStep(product),
+     attachProductToSalesChannelStep(product)
+   )
+
+   const refetchedProduct = getProductStep(product.id)
+
+   return new WorkflowResponse(refetchedProduct)
+ }
+)
+```
+
+The `parallelize` function accepts the steps to run in parallel as a parameter.
+
+It returns an array of the steps' results in the same order they're passed to the `parallelize` function.
+
+So, `prices` is the result of `createPricesStep`, and `productSalesChannel` is the result of `attachProductToSalesChannelStep`.
+
+
 # Long-Running Workflows
 
 In this chapter, you’ll learn what a long-running workflow is and how to configure it.
@@ -14018,129 +14071,6 @@ To find a full example of a long-running workflow, refer to the [restaurant-deli
 In the recipe, you use a long-running workflow that moves an order from placed to completed. The workflow waits for the restaurant to accept the order, the driver to pick up the order, and other external actions.
 
 
-# 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).
-
-
 # Store Workflow Executions
 
 In this chapter, you'll learn how to store workflow executions in the database and access them later.
@@ -14491,57 +14421,213 @@ const myWorkflow = createWorkflow(
 ```
 
 
-# Run Workflow Steps in Parallel
+# Retry Failed Steps
 
-In this chapter, you’ll learn how to run workflow steps in parallel.
+In this chapter, you’ll learn how to configure steps to allow retrial on failure.
 
-## parallelize Utility Function
+## What is a Step Retrial?
 
-If your workflow has steps that don’t rely on one another’s results, run them in parallel using `parallelize` from the Workflows SDK.
+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.
 
-The workflow waits until all steps passed to the `parallelize` function finish executing before continuing to the next step.
+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 highlights={highlights} collapsibleLines="1-12" expandButtonLabel="Show Imports"
-import {
+```ts title="src/workflows/hello-world.ts" highlights={[["10"]]} collapsibleLines="1-6" expandButtonLabel="Show Imports"
+import { 
+  createStep, 
   createWorkflow,
   WorkflowResponse,
-  parallelize,
 } from "@medusajs/framework/workflows-sdk"
-import {
-  createProductStep,
-  getProductStep,
-  createPricesStep,
-  attachProductToSalesChannelStep,
-} from "./steps"
 
-interface WorkflowInput {
-  title: string
-}
+const step1 = createStep(
+  {
+    name: "step-1",
+    maxRetries: 2,
+  },
+  async () => {
+    console.log("Executing step 1")
+
+    throw new Error("Oops! Something happened.")
+  }
+)
 
 const myWorkflow = createWorkflow(
-  "my-workflow", 
-  (input: WorkflowInput) => {
-   const product = createProductStep(input)
+  "hello-world", 
+  function () {
+  const str1 = step1()
 
-   const [prices, productSalesChannel] = parallelize(
-     createPricesStep(product),
-     attachProductToSalesChannelStep(product)
-   )
+  return new WorkflowResponse({
+    message: str1,
+  })
+})
 
-   const refetchedProduct = getProductStep(product.id)
+export default myWorkflow
+```
 
-   return new WorkflowResponse(refetchedProduct)
- }
+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 () => {
+    // ...
+  }
 )
 ```
 
-The `parallelize` function accepts the steps to run in parallel as a parameter.
+In this example, if the step fails, it will be retried after two seconds.
 
-It returns an array of the steps' results in the same order they're passed to the `parallelize` function.
+### Maximum Retry Interval
 
-So, `prices` is the result of `createPricesStep`, and `productSalesChannel` is the result of `attachProductToSalesChannelStep`.
+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).
+
+
+# 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/access-workflow-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/access-workflow-errors/index.html.md). The error’s name is `TransactionStepTimeoutError`.
 
 
 # Workflow Hooks
@@ -14668,209 +14754,294 @@ export async function POST(req: MedusaRequest, res: MedusaResponse) {
 Your hook handler then receives that passed data in the `additional_data` object.
 
 
-# Workflow Timeout
+# Write Integration Tests
 
-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/access-workflow-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/access-workflow-errors/index.html.md). The error’s name is `TransactionStepTimeoutError`.
-
-
-# Write Tests for Modules
-
-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 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)
 
-## moduleIntegrationTestRunner Utility
+## medusaIntegrationTestRunner Utility
 
-`moduleIntegrationTestRunner` creates integration tests for a module. The integration tests run on a test Medusa application with only the specified module enabled.
+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, assuming you have a `blog` module, create a test file at `src/modules/blog/__tests__/service.spec.ts`:
+For example:
 
-```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"
+```ts title="integration-tests/http/test.spec.ts" highlights={highlights}
+import { medusaIntegrationTestRunner } from "@medusajs/test-utils"
 
-moduleIntegrationTestRunner<BlogModuleService>({
-  moduleName: BLOG_MODULE,
-  moduleModels: [Post],
-  resolve: "./src/modules/blog",
-  testSuite: ({ service }) => {
-    // TODO write tests
+medusaIntegrationTestRunner({
+  testSuite: ({ api, getContainer }) => {
+    // TODO write tests...
   },
 })
 
 jest.setTimeout(60 * 1000)
 ```
 
-The `moduleIntegrationTestRunner` function accepts as a parameter an object with the following properties:
+The `medusaIntegrationTestRunner` function accepts an object as a parameter. The object has a required property `testSuite`.
 
-- `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.
+`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:
 
-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.
+- `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
 
-## 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.
-
-For example:
-
-```ts
-import { moduleIntegrationTestRunner } from "@medusajs/test-utils"
-import BlogModuleService from "../service"
-
-moduleIntegrationTestRunner<BlogModuleService>({
-  moduleOptions: {
-    apiKey: "123",
-  },
-  // ...
-})
-```
-
-***
-
-## Write Tests for Modules without Data Models
-
-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<BlogModuleService>({
-  moduleModels: [DummyModel],
-  // ...
-})
+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)
 ```
 
 ***
 
-### Other Options and Inputs
+### Run Tests
 
-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.
+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 `moduleIntegrationTestRunner` function creates a database with a random name before running the tests. Then, it drops that database after all the tests end.
+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/moduleIntegrationTestRunner/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).
+
+***
+
+## Example Integration Tests
+
+The next chapters provide examples of writing integration tests for API routes and workflows.
+
+
+# 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:
+
+![Directory structure of the Medusa application after adding the route](https://res.cloudinary.com/dza7lstvk/image/upload/v1732869882/Medusa%20Book/brand-route-dir-overview-2_hjqlnf.jpg)
+
+```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<PostAdminCreateBrandType>,
+  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:
+
+![Directory structure of Medusa application after adding validators file](https://res.cloudinary.com/dza7lstvk/image/upload/v1732869806/Medusa%20Book/brand-route-dir-overview-1_yfyjss.jpg)
+
+```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<typeof PostAdminCreateBrand>
+
+// ...
+```
+
+***
+
+## 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:
+
+![Directory structure of the Medusa application after adding the middleware](https://res.cloudinary.com/dza7lstvk/image/upload/v1732869977/Medusa%20Book/brand-route-dir-overview-3_kcx511.jpg)
+
+```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
@@ -15245,6 +15416,125 @@ 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.
 
 
+# Write Tests for Modules
+
+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
+
+- [Testing Tools Setup](https://docs.medusajs.com/learn/debugging-and-testing/testing-tools/index.html.md)
+
+## 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<BlogModuleService>({
+  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.
+
+For example:
+
+```ts
+import { moduleIntegrationTestRunner } from "@medusajs/test-utils"
+import BlogModuleService from "../service"
+
+moduleIntegrationTestRunner<BlogModuleService>({
+  moduleOptions: {
+    apiKey: "123",
+  },
+  // ...
+})
+```
+
+***
+
+## Write Tests for Modules without Data Models
+
+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<BlogModuleService>({
+  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).
+
+
 # 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.
@@ -15399,86 +15689,142 @@ 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.
 
 
-# Write Integration Tests
+# Guide: Create Brand Workflow
 
-In this chapter, you'll learn about `medusaIntegrationTestRunner` from Medusa's Testing Framework and how to use it to write integration tests.
+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
 
-- [Testing Tools Setup](https://docs.medusajs.com/learn/debugging-and-testing/testing-tools/index.html.md)
+- [Brand Module](https://docs.medusajs.com/learn/customization/custom-features/module/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.
+## 1. Create createBrandStep
 
-For example:
+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
 
-```ts title="integration-tests/http/test.spec.ts" highlights={highlights}
-import { medusaIntegrationTestRunner } from "@medusajs/test-utils"
+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:
 
-medusaIntegrationTestRunner({
-  testSuite: ({ api, getContainer }) => {
-    // TODO write tests...
-  },
-})
+![Directory structure in the Medusa project after adding the file for createBrandStep](https://res.cloudinary.com/dza7lstvk/image/upload/v1732869184/Medusa%20Book/brand-workflow-dir-overview-1_fjvf5j.jpg)
 
-jest.setTimeout(60 * 1000)
+```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)
+  }
+)
 ```
 
-The `medusaIntegrationTestRunner` function accepts an object as a parameter. The object has a required property `testSuite`.
+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.
 
-`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:
+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.
 
-- `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 [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.
 
-The tests in the `testSuite` function are written using [Jest](https://jestjs.io/).
+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.
 
-### Jest Timeout
+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).
 
-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:
+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.
 
-```ts title="integration-tests/http/test.spec.ts"
-// in your test's file
-jest.setTimeout(60 * 1000)
+### 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.
+
 ***
 
-### Run Tests
+## 2. Create createBrandWorkflow
 
-Run the following command to run your tests:
+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.
 
-```bash npm2yarn
-npm run test:integration
+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)
+  }
+)
 ```
 
-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).
+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 runs your Medusa application and runs the tests available under the `src/integrations/http` directory.
+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.
 
 ***
 
-## Other Options and Inputs
+## Next Steps: Expose Create Brand API Route
 
-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.
+You now have a `createBrandWorkflow` that you can execute to create a brand.
 
-***
-
-## 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.
+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: Implement Brand Module
@@ -15637,661 +15983,6 @@ The Brand Module now creates a `brand` table in the database and provides a clas
 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:
-
-![Directory structure of the Medusa application after adding the route](https://res.cloudinary.com/dza7lstvk/image/upload/v1732869882/Medusa%20Book/brand-route-dir-overview-2_hjqlnf.jpg)
-
-```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<PostAdminCreateBrandType>,
-  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:
-
-![Directory structure of Medusa application after adding validators file](https://res.cloudinary.com/dza7lstvk/image/upload/v1732869806/Medusa%20Book/brand-route-dir-overview-1_yfyjss.jpg)
-
-```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<typeof PostAdminCreateBrand>
-
-// ...
-```
-
-***
-
-## 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:
-
-![Directory structure of the Medusa application after adding the middleware](https://res.cloudinary.com/dza7lstvk/image/upload/v1732869977/Medusa%20Book/brand-route-dir-overview-3_kcx511.jpg)
-
-```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: 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:
-
-![Directory structure in the Medusa project after adding the file for createBrandStep](https://res.cloudinary.com/dza7lstvk/image/upload/v1732869184/Medusa%20Book/brand-workflow-dir-overview-1_fjvf5j.jpg)
-
-```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: Schedule Syncing Brands from Third-Party
-
-In the previous chapters, you've [integrated a third-party CMS](https://docs.medusajs.com/learn/customization/integrate-systems/service/index.html.md) and implemented the logic to [sync created brands](https://docs.medusajs.com/learn/customization/integrate-systems/handle-event/index.html.md) from Medusa to the CMS.
-
-However, when you integrate a third-party system, you want the data to be in sync between the Medusa application and the system. One way to do so is by automatically syncing the data once a day.
-
-You can create an action to be automatically executed at a specified interval using scheduled jobs. A scheduled job is an asynchronous function with a specified schedule of when the Medusa application should run it. Scheduled jobs are useful to automate repeated tasks.
-
-Learn more about scheduled jobs in [this chapter](https://docs.medusajs.com/learn/fundamentals/scheduled-jobs/index.html.md).
-
-In this chapter, you'll create a scheduled job that triggers syncing the brands from the third-party CMS to Medusa once a day. You'll implement the syncing logic in a workflow, and execute that workflow in the scheduled job.
-
-### Prerequisites
-
-- [CMS Module](https://docs.medusajs.com/learn/customization/integrate-systems/service/index.html.md)
-
-***
-
-## 1. Implement Syncing Workflow
-
-You'll start by implementing the syncing logic in a workflow, then execute the workflow later in the scheduled job.
-
-Workflows have a built-in durable execution engine that helps you complete tasks spanning multiple systems. Also, their rollback mechanism ensures that data is consistent across systems even when errors occur during execution.
-
-Learn more about workflows in [this chapter](https://docs.medusajs.com/learn/fundamentals/workflows/index.html.md).
-
-This workflow will have three steps:
-
-1. `retrieveBrandsFromCmsStep` to retrieve the brands from the CMS.
-2. `createBrandsStep` to create the brands retrieved in the first step that don't exist in Medusa.
-3. `updateBrandsStep` to update the brands retrieved in the first step that exist in Medusa.
-
-### retrieveBrandsFromCmsStep
-
-To create the step that retrieves the brands from the third-party CMS, create the file `src/workflows/sync-brands-from-cms.ts` with the following content:
-
-![Directory structure of the Medusa application after creating the file.](https://res.cloudinary.com/dza7lstvk/image/upload/v1733494196/Medusa%20Book/cms-dir-overview-6_z1omsi.jpg)
-
-```ts title="src/workflows/sync-brands-from-cms.ts" collapsibleLines="1-7" expandButtonLabel="Show Imports"
-import {
-  createStep,
-  StepResponse,
-} from "@medusajs/framework/workflows-sdk"
-import CmsModuleService from "../modules/cms/service"
-import { CMS_MODULE } from "../modules/cms"
-
-const retrieveBrandsFromCmsStep = createStep(
-  "retrieve-brands-from-cms",
-  async (_, { container }) => {
-    const cmsModuleService: CmsModuleService = container.resolve(
-      CMS_MODULE
-    )
-
-    const brands = await cmsModuleService.retrieveBrands()
-
-    return new StepResponse(brands)
-  }
-)
-```
-
-You create a `retrieveBrandsFromCmsStep` that resolves the CMS Module's service and uses its `retrieveBrands` method to retrieve the brands in the CMS. You return those brands in the step's response.
-
-### createBrandsStep
-
-The brands retrieved in the first step may have brands that don't exist in Medusa. So, you'll create a step that creates those brands. Add the step to the same `src/workflows/sync-brands-from-cms.ts` file:
-
-```ts title="src/workflows/sync-brands-from-cms.ts" highlights={createBrandsHighlights} collapsibleLines="1-8" expandButtonLabel="Show Imports"
-// other imports...
-import BrandModuleService from "../modules/brand/service"
-import { BRAND_MODULE } from "../modules/brand"
-
-// ...
-
-type CreateBrand = {
-  name: string
-}
-
-type CreateBrandsInput = {
-  brands: CreateBrand[]
-}
-
-export const createBrandsStep = createStep(
-  "create-brands-step",
-  async (input: CreateBrandsInput, { container }) => {
-    const brandModuleService: BrandModuleService = container.resolve(
-      BRAND_MODULE
-    )
-
-    const brands = await brandModuleService.createBrands(input.brands)
-
-    return new StepResponse(brands, brands)
-  },
-  async (brands, { container }) => {
-    if (!brands) {
-      return
-    }
-
-    const brandModuleService: BrandModuleService = container.resolve(
-      BRAND_MODULE
-    )
-
-    await brandModuleService.deleteBrands(brands.map((brand) => brand.id))
-  }
-)
-```
-
-The `createBrandsStep` accepts the brands to create as an input. It resolves the [Brand Module](https://docs.medusajs.com/learn/customization/custom-features/module/index.html.md)'s service and uses the generated `createBrands` method to create the brands.
-
-The step passes the created brands to the compensation function, which deletes those brands if an error occurs during the workflow's execution.
-
-Learn more about compensation functions in [this chapter](https://docs.medusajs.com/learn/fundamentals/workflows/compensation-function/index.html.md).
-
-### Update Brands Step
-
-The brands retrieved in the first step may also have brands that exist in Medusa. So, you'll create a step that updates their details to match that of the CMS. Add the step to the same `src/workflows/sync-brands-from-cms.ts` file:
-
-```ts title="src/workflows/sync-brands-from-cms.ts" highlights={updateBrandsHighlights}
-// ...
-
-type UpdateBrand = {
-  id: string
-  name: string
-}
-
-type UpdateBrandsInput = {
-  brands: UpdateBrand[]
-}
-
-export const updateBrandsStep = createStep(
-  "update-brands-step",
-  async ({ brands }: UpdateBrandsInput, { container }) => {
-    const brandModuleService: BrandModuleService = container.resolve(
-      BRAND_MODULE
-    )
-
-    const prevUpdatedBrands = await brandModuleService.listBrands({
-      id: brands.map((brand) => brand.id),
-    })
-
-    const updatedBrands = await brandModuleService.updateBrands(brands)
-
-    return new StepResponse(updatedBrands, prevUpdatedBrands)
-  },
-  async (prevUpdatedBrands, { container }) => {
-    if (!prevUpdatedBrands) {
-      return
-    }
-
-    const brandModuleService: BrandModuleService = container.resolve(
-      BRAND_MODULE
-    )
-
-    await brandModuleService.updateBrands(prevUpdatedBrands)
-  }
-)
-```
-
-The `updateBrandsStep` receives the brands to update in Medusa. In the step, you retrieve the brand's details in Medusa before the update to pass them to the compensation function. You then update the brands using the Brand Module's `updateBrands` generated method.
-
-In the compensation function, which receives the brand's old data, you revert the update using the same `updateBrands` method.
-
-### Create Workflow
-
-Finally, you'll create the workflow that uses the above steps to sync the brands from the CMS to Medusa. Add to the same `src/workflows/sync-brands-from-cms.ts` file the following:
-
-```ts title="src/workflows/sync-brands-from-cms.ts"
-// other imports...
-import {
-  // ...
-  createWorkflow,
-  transform,
-  WorkflowResponse,
-} from "@medusajs/framework/workflows-sdk"
-
-// ...
-
-export const syncBrandsFromCmsWorkflow = createWorkflow(
-  "sync-brands-from-system",
-  () => {
-    const brands = retrieveBrandsFromCmsStep()
-
-    // TODO create and update brands
-  }
-)
-```
-
-In the workflow, you only use the `retrieveBrandsFromCmsStep` for now, which retrieves the brands from the third-party CMS.
-
-Next, you need to identify which brands must be created or updated. Since workflows are constructed internally and are only evaluated during execution, you can't access values to perform data manipulation directly. Instead, use [transform](https://docs.medusajs.com/learn/fundamentals/workflows/variable-manipulation/index.html.md) from the Workflows SDK that gives you access to the real-time values of the data, allowing you to create new variables using those values.
-
-Learn more about data manipulation using `transform` in [this chapter](https://docs.medusajs.com/learn/fundamentals/workflows/variable-manipulation/index.html.md).
-
-So, replace the `TODO` with the following:
-
-```ts title="src/workflows/sync-brands-from-cms.ts"
-const { toCreate, toUpdate } = transform(
-  {
-    brands,
-  },
-  (data) => {
-    const toCreate: CreateBrand[] = []
-    const toUpdate: UpdateBrand[] = []
-
-    data.brands.forEach((brand) => {
-      if (brand.external_id) {
-        toUpdate.push({
-          id: brand.external_id as string,
-          name: brand.name as string,
-        })
-      } else {
-        toCreate.push({
-          name: brand.name as string,
-        })
-      }
-    })
-
-    return { toCreate, toUpdate }
-  }
-)
-
-// TODO create and update the brands
-```
-
-`transform` accepts two parameters:
-
-1. The data to be passed to the function in the second parameter.
-2. A function to execute only when the workflow is executed. Its return value can be consumed by the rest of the workflow.
-
-In `transform`'s function, you loop over the brands array to check which should be created or updated. This logic assumes that a brand in the CMS has an `external_id` property whose value is the brand's ID in Medusa.
-
-You now have the list of brands to create and update. So, replace the new `TODO` with the following:
-
-```ts title="src/workflows/sync-brands-from-cms.ts"
-const created = createBrandsStep({ brands: toCreate })
-const updated = updateBrandsStep({ brands: toUpdate })
-
-return new WorkflowResponse({
-  created,
-  updated,
-})
-```
-
-You first run the `createBrandsStep` to create the brands that don't exist in Medusa, then the `updateBrandsStep` to update the brands that exist in Medusa. You pass the arrays returned by `transform` as the inputs for the steps.
-
-Finally, you return an object of the created and updated brands. You'll execute this workflow in the scheduled job next.
-
-***
-
-## 2. Schedule Syncing Task
-
-You now have the workflow to sync the brands from the CMS to Medusa. Next, you'll create a scheduled job that runs this workflow once a day to ensure the data between Medusa and the CMS are always in sync.
-
-A scheduled job is created in a TypeScript or JavaScript file under the `src/jobs` directory. So, create the file `src/jobs/sync-brands-from-cms.ts` with the following content:
-
-![Directory structure of the Medusa application after adding the scheduled job](https://res.cloudinary.com/dza7lstvk/image/upload/v1733494592/Medusa%20Book/cms-dir-overview-7_dkjb9s.jpg)
-
-```ts title="src/jobs/sync-brands-from-cms.ts"
-import { MedusaContainer } from "@medusajs/framework/types"
-import { syncBrandsFromCmsWorkflow } from "../workflows/sync-brands-from-cms"
-
-export default async function (container: MedusaContainer) {
-  const logger = container.resolve("logger")
-
-  const { result } = await syncBrandsFromCmsWorkflow(container).run()
-
-  logger.info(
-    `Synced brands from third-party system: ${
-      result.created.length
-    } brands created and ${result.updated.length} brands updated.`)
-}
-
-export const config = {
-  name: "sync-brands-from-system",
-  schedule: "0 0 * * *", // change to * * * * * for debugging
-}
-```
-
-A scheduled job file must export:
-
-- An asynchronous function that will be executed at the specified schedule. This function must be the file's default export.
-- An object of scheduled jobs configuration. It has two properties:
-  - `name`: A unique name for the scheduled job.
-  - `schedule`: A string that holds a [cron expression](https://crontab.guru/) indicating the schedule to run the job.
-
-The scheduled job function accepts as a parameter the [Medusa container](https://docs.medusajs.com/learn/fundamentals/medusa-container/index.html.md) used to resolve Framework and commerce tools. You then execute the `syncBrandsFromCmsWorkflow` and use its result to log how many brands were created or updated.
-
-Based on the cron expression specified in `config.schedule`, Medusa will run the scheduled job every day at midnight. You can also change it to `* * * * *` to run it every minute for easier debugging.
-
-***
-
-## Test it Out
-
-To test out the scheduled job, start the Medusa application:
-
-```bash npm2yarn
-npm run dev
-```
-
-If you set the schedule to `* * * * *` for debugging, the scheduled job will run in a minute. You'll see in the logs how many brands were created or updated.
-
-***
-
-## Summary
-
-By following the previous chapters, you utilized the Medusa Framework and orchestration tools to perform and automate tasks that span across systems.
-
-With Medusa, you can integrate any service from your commerce ecosystem with ease. You don't have to set up separate applications to manage your different customizations, or worry about data inconsistency across systems. Your efforts only go into implementing the business logic that ties your systems together.
-
-
 # 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.
@@ -16723,6 +16414,385 @@ 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.
 
 
+# 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:
+
+![The directory structure of the Medusa application after adding the link.](https://res.cloudinary.com/dza7lstvk/image/upload/v1733329897/Medusa%20Book/brands-link-dir-overview_t1rhlp.jpg)
+
+```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: Schedule Syncing Brands from Third-Party
+
+In the previous chapters, you've [integrated a third-party CMS](https://docs.medusajs.com/learn/customization/integrate-systems/service/index.html.md) and implemented the logic to [sync created brands](https://docs.medusajs.com/learn/customization/integrate-systems/handle-event/index.html.md) from Medusa to the CMS.
+
+However, when you integrate a third-party system, you want the data to be in sync between the Medusa application and the system. One way to do so is by automatically syncing the data once a day.
+
+You can create an action to be automatically executed at a specified interval using scheduled jobs. A scheduled job is an asynchronous function with a specified schedule of when the Medusa application should run it. Scheduled jobs are useful to automate repeated tasks.
+
+Learn more about scheduled jobs in [this chapter](https://docs.medusajs.com/learn/fundamentals/scheduled-jobs/index.html.md).
+
+In this chapter, you'll create a scheduled job that triggers syncing the brands from the third-party CMS to Medusa once a day. You'll implement the syncing logic in a workflow, and execute that workflow in the scheduled job.
+
+### Prerequisites
+
+- [CMS Module](https://docs.medusajs.com/learn/customization/integrate-systems/service/index.html.md)
+
+***
+
+## 1. Implement Syncing Workflow
+
+You'll start by implementing the syncing logic in a workflow, then execute the workflow later in the scheduled job.
+
+Workflows have a built-in durable execution engine that helps you complete tasks spanning multiple systems. Also, their rollback mechanism ensures that data is consistent across systems even when errors occur during execution.
+
+Learn more about workflows in [this chapter](https://docs.medusajs.com/learn/fundamentals/workflows/index.html.md).
+
+This workflow will have three steps:
+
+1. `retrieveBrandsFromCmsStep` to retrieve the brands from the CMS.
+2. `createBrandsStep` to create the brands retrieved in the first step that don't exist in Medusa.
+3. `updateBrandsStep` to update the brands retrieved in the first step that exist in Medusa.
+
+### retrieveBrandsFromCmsStep
+
+To create the step that retrieves the brands from the third-party CMS, create the file `src/workflows/sync-brands-from-cms.ts` with the following content:
+
+![Directory structure of the Medusa application after creating the file.](https://res.cloudinary.com/dza7lstvk/image/upload/v1733494196/Medusa%20Book/cms-dir-overview-6_z1omsi.jpg)
+
+```ts title="src/workflows/sync-brands-from-cms.ts" collapsibleLines="1-7" expandButtonLabel="Show Imports"
+import {
+  createStep,
+  StepResponse,
+} from "@medusajs/framework/workflows-sdk"
+import CmsModuleService from "../modules/cms/service"
+import { CMS_MODULE } from "../modules/cms"
+
+const retrieveBrandsFromCmsStep = createStep(
+  "retrieve-brands-from-cms",
+  async (_, { container }) => {
+    const cmsModuleService: CmsModuleService = container.resolve(
+      CMS_MODULE
+    )
+
+    const brands = await cmsModuleService.retrieveBrands()
+
+    return new StepResponse(brands)
+  }
+)
+```
+
+You create a `retrieveBrandsFromCmsStep` that resolves the CMS Module's service and uses its `retrieveBrands` method to retrieve the brands in the CMS. You return those brands in the step's response.
+
+### createBrandsStep
+
+The brands retrieved in the first step may have brands that don't exist in Medusa. So, you'll create a step that creates those brands. Add the step to the same `src/workflows/sync-brands-from-cms.ts` file:
+
+```ts title="src/workflows/sync-brands-from-cms.ts" highlights={createBrandsHighlights} collapsibleLines="1-8" expandButtonLabel="Show Imports"
+// other imports...
+import BrandModuleService from "../modules/brand/service"
+import { BRAND_MODULE } from "../modules/brand"
+
+// ...
+
+type CreateBrand = {
+  name: string
+}
+
+type CreateBrandsInput = {
+  brands: CreateBrand[]
+}
+
+export const createBrandsStep = createStep(
+  "create-brands-step",
+  async (input: CreateBrandsInput, { container }) => {
+    const brandModuleService: BrandModuleService = container.resolve(
+      BRAND_MODULE
+    )
+
+    const brands = await brandModuleService.createBrands(input.brands)
+
+    return new StepResponse(brands, brands)
+  },
+  async (brands, { container }) => {
+    if (!brands) {
+      return
+    }
+
+    const brandModuleService: BrandModuleService = container.resolve(
+      BRAND_MODULE
+    )
+
+    await brandModuleService.deleteBrands(brands.map((brand) => brand.id))
+  }
+)
+```
+
+The `createBrandsStep` accepts the brands to create as an input. It resolves the [Brand Module](https://docs.medusajs.com/learn/customization/custom-features/module/index.html.md)'s service and uses the generated `createBrands` method to create the brands.
+
+The step passes the created brands to the compensation function, which deletes those brands if an error occurs during the workflow's execution.
+
+Learn more about compensation functions in [this chapter](https://docs.medusajs.com/learn/fundamentals/workflows/compensation-function/index.html.md).
+
+### Update Brands Step
+
+The brands retrieved in the first step may also have brands that exist in Medusa. So, you'll create a step that updates their details to match that of the CMS. Add the step to the same `src/workflows/sync-brands-from-cms.ts` file:
+
+```ts title="src/workflows/sync-brands-from-cms.ts" highlights={updateBrandsHighlights}
+// ...
+
+type UpdateBrand = {
+  id: string
+  name: string
+}
+
+type UpdateBrandsInput = {
+  brands: UpdateBrand[]
+}
+
+export const updateBrandsStep = createStep(
+  "update-brands-step",
+  async ({ brands }: UpdateBrandsInput, { container }) => {
+    const brandModuleService: BrandModuleService = container.resolve(
+      BRAND_MODULE
+    )
+
+    const prevUpdatedBrands = await brandModuleService.listBrands({
+      id: brands.map((brand) => brand.id),
+    })
+
+    const updatedBrands = await brandModuleService.updateBrands(brands)
+
+    return new StepResponse(updatedBrands, prevUpdatedBrands)
+  },
+  async (prevUpdatedBrands, { container }) => {
+    if (!prevUpdatedBrands) {
+      return
+    }
+
+    const brandModuleService: BrandModuleService = container.resolve(
+      BRAND_MODULE
+    )
+
+    await brandModuleService.updateBrands(prevUpdatedBrands)
+  }
+)
+```
+
+The `updateBrandsStep` receives the brands to update in Medusa. In the step, you retrieve the brand's details in Medusa before the update to pass them to the compensation function. You then update the brands using the Brand Module's `updateBrands` generated method.
+
+In the compensation function, which receives the brand's old data, you revert the update using the same `updateBrands` method.
+
+### Create Workflow
+
+Finally, you'll create the workflow that uses the above steps to sync the brands from the CMS to Medusa. Add to the same `src/workflows/sync-brands-from-cms.ts` file the following:
+
+```ts title="src/workflows/sync-brands-from-cms.ts"
+// other imports...
+import {
+  // ...
+  createWorkflow,
+  transform,
+  WorkflowResponse,
+} from "@medusajs/framework/workflows-sdk"
+
+// ...
+
+export const syncBrandsFromCmsWorkflow = createWorkflow(
+  "sync-brands-from-system",
+  () => {
+    const brands = retrieveBrandsFromCmsStep()
+
+    // TODO create and update brands
+  }
+)
+```
+
+In the workflow, you only use the `retrieveBrandsFromCmsStep` for now, which retrieves the brands from the third-party CMS.
+
+Next, you need to identify which brands must be created or updated. Since workflows are constructed internally and are only evaluated during execution, you can't access values to perform data manipulation directly. Instead, use [transform](https://docs.medusajs.com/learn/fundamentals/workflows/variable-manipulation/index.html.md) from the Workflows SDK that gives you access to the real-time values of the data, allowing you to create new variables using those values.
+
+Learn more about data manipulation using `transform` in [this chapter](https://docs.medusajs.com/learn/fundamentals/workflows/variable-manipulation/index.html.md).
+
+So, replace the `TODO` with the following:
+
+```ts title="src/workflows/sync-brands-from-cms.ts"
+const { toCreate, toUpdate } = transform(
+  {
+    brands,
+  },
+  (data) => {
+    const toCreate: CreateBrand[] = []
+    const toUpdate: UpdateBrand[] = []
+
+    data.brands.forEach((brand) => {
+      if (brand.external_id) {
+        toUpdate.push({
+          id: brand.external_id as string,
+          name: brand.name as string,
+        })
+      } else {
+        toCreate.push({
+          name: brand.name as string,
+        })
+      }
+    })
+
+    return { toCreate, toUpdate }
+  }
+)
+
+// TODO create and update the brands
+```
+
+`transform` accepts two parameters:
+
+1. The data to be passed to the function in the second parameter.
+2. A function to execute only when the workflow is executed. Its return value can be consumed by the rest of the workflow.
+
+In `transform`'s function, you loop over the brands array to check which should be created or updated. This logic assumes that a brand in the CMS has an `external_id` property whose value is the brand's ID in Medusa.
+
+You now have the list of brands to create and update. So, replace the new `TODO` with the following:
+
+```ts title="src/workflows/sync-brands-from-cms.ts"
+const created = createBrandsStep({ brands: toCreate })
+const updated = updateBrandsStep({ brands: toUpdate })
+
+return new WorkflowResponse({
+  created,
+  updated,
+})
+```
+
+You first run the `createBrandsStep` to create the brands that don't exist in Medusa, then the `updateBrandsStep` to update the brands that exist in Medusa. You pass the arrays returned by `transform` as the inputs for the steps.
+
+Finally, you return an object of the created and updated brands. You'll execute this workflow in the scheduled job next.
+
+***
+
+## 2. Schedule Syncing Task
+
+You now have the workflow to sync the brands from the CMS to Medusa. Next, you'll create a scheduled job that runs this workflow once a day to ensure the data between Medusa and the CMS are always in sync.
+
+A scheduled job is created in a TypeScript or JavaScript file under the `src/jobs` directory. So, create the file `src/jobs/sync-brands-from-cms.ts` with the following content:
+
+![Directory structure of the Medusa application after adding the scheduled job](https://res.cloudinary.com/dza7lstvk/image/upload/v1733494592/Medusa%20Book/cms-dir-overview-7_dkjb9s.jpg)
+
+```ts title="src/jobs/sync-brands-from-cms.ts"
+import { MedusaContainer } from "@medusajs/framework/types"
+import { syncBrandsFromCmsWorkflow } from "../workflows/sync-brands-from-cms"
+
+export default async function (container: MedusaContainer) {
+  const logger = container.resolve("logger")
+
+  const { result } = await syncBrandsFromCmsWorkflow(container).run()
+
+  logger.info(
+    `Synced brands from third-party system: ${
+      result.created.length
+    } brands created and ${result.updated.length} brands updated.`)
+}
+
+export const config = {
+  name: "sync-brands-from-system",
+  schedule: "0 0 * * *", // change to * * * * * for debugging
+}
+```
+
+A scheduled job file must export:
+
+- An asynchronous function that will be executed at the specified schedule. This function must be the file's default export.
+- An object of scheduled jobs configuration. It has two properties:
+  - `name`: A unique name for the scheduled job.
+  - `schedule`: A string that holds a [cron expression](https://crontab.guru/) indicating the schedule to run the job.
+
+The scheduled job function accepts as a parameter the [Medusa container](https://docs.medusajs.com/learn/fundamentals/medusa-container/index.html.md) used to resolve Framework and commerce tools. You then execute the `syncBrandsFromCmsWorkflow` and use its result to log how many brands were created or updated.
+
+Based on the cron expression specified in `config.schedule`, Medusa will run the scheduled job every day at midnight. You can also change it to `* * * * *` to run it every minute for easier debugging.
+
+***
+
+## Test it Out
+
+To test out the scheduled job, start the Medusa application:
+
+```bash npm2yarn
+npm run dev
+```
+
+If you set the schedule to `* * * * *` for debugging, the scheduled job will run in a minute. You'll see in the logs how many brands were created or updated.
+
+***
+
+## Summary
+
+By following the previous chapters, you utilized the Medusa Framework and orchestration tools to perform and automate tasks that span across systems.
+
+With Medusa, you can integrate any service from your commerce ecosystem with ease. You don't have to set up separate applications to manage your different customizations, or worry about data inconsistency across systems. Your efforts only go into implementing the business logic that ties your systems together.
+
+
 # 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.
@@ -17083,76 +17153,6 @@ Clients, such as the Medusa Admin dashboard, can now use brand-related features,
 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: 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:
-
-![The directory structure of the Medusa application after adding the link.](https://res.cloudinary.com/dza7lstvk/image/upload/v1733329897/Medusa%20Book/brands-link-dir-overview_t1rhlp.jpg)
-
-```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.
-
-
 # Translate Medusa Admin
 
 The Medusa Admin supports multiple languages, with the default being English. In this documentation, you'll learn how to contribute to the community by translating the Medusa Admin to a language you're fluent in.
@@ -17511,76 +17511,6 @@ console.log("This block can't use semi colons")
 ~~~ */}
 
 
-# Example: Integration Tests for a Module
-
-In this chapter, find an example of writing an integration test for a module using [moduleIntegrationTestRunner](https://docs.medusajs.com/learn/debugging-and-testing/testing-tools/modules-tests/index.html.md) from Medusa's Testing Framework.
-
-### Prerequisites
-
-- [Testing Tools Setup](https://docs.medusajs.com/learn/debugging-and-testing/testing-tools/index.html.md)
-
-## Write Integration Test for Module
-
-Consider a `blog` module with a `BlogModuleService` that has a `getMessage` method:
-
-```ts title="src/modules/blog/service.ts"
-import { MedusaService } from "@medusajs/framework/utils"
-import MyCustom from "./models/my-custom"
-
-class BlogModuleService extends MedusaService({
-  MyCustom,
-}){
-  getMessage(): string {
-    return "Hello, World!"
-  }
-}
-
-export default BlogModuleService
-```
-
-To create an integration test for the method, create the file `src/modules/blog/__tests__/service.spec.ts` with the following content:
-
-```ts title="src/modules/blog/__tests__/service.spec.ts"
-import { moduleIntegrationTestRunner } from "@medusajs/test-utils"
-import { BLOG_MODULE } from ".."
-import BlogModuleService from "../service"
-import MyCustom from "../models/my-custom"
-
-moduleIntegrationTestRunner<BlogModuleService>({
-  moduleName: BLOG_MODULE,
-  moduleModels: [MyCustom],
-  resolve: "./src/modules/blog",
-  testSuite: ({ service }) => {
-    describe("BlogModuleService", () => {
-      it("says hello world", () => {
-        const message = service.getMessage()
-
-        expect(message).toEqual("Hello, World!")
-      })
-    })
-  },
-})
-
-jest.setTimeout(60 * 1000)
-```
-
-You use the `moduleIntegrationTestRunner` function to add tests for the `blog` module. You have one test that passes if the `getMessage` method returns the `"Hello, World!"` string.
-
-***
-
-## Run Test
-
-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.
-
-
 # Example: Write Integration Tests for API Routes
 
 In this chapter, you'll learn how to write integration tests for API routes using [medusaIntegrationTestRunner](https://docs.medusajs.com/learn/debugging-and-testing/testing-tools/integration-tests/index.html.md) from Medusa's Testing Framework.
@@ -18281,6 +18211,76 @@ The `errors` property contains an array of errors thrown during the execution of
 If you threw a `MedusaError`, then you can check the error message in `errors[0].error.message`.
 
 
+# Example: Integration Tests for a Module
+
+In this chapter, find an example of writing an integration test for a module using [moduleIntegrationTestRunner](https://docs.medusajs.com/learn/debugging-and-testing/testing-tools/modules-tests/index.html.md) from Medusa's Testing Framework.
+
+### Prerequisites
+
+- [Testing Tools Setup](https://docs.medusajs.com/learn/debugging-and-testing/testing-tools/index.html.md)
+
+## Write Integration Test for Module
+
+Consider a `blog` module with a `BlogModuleService` that has a `getMessage` method:
+
+```ts title="src/modules/blog/service.ts"
+import { MedusaService } from "@medusajs/framework/utils"
+import MyCustom from "./models/my-custom"
+
+class BlogModuleService extends MedusaService({
+  MyCustom,
+}){
+  getMessage(): string {
+    return "Hello, World!"
+  }
+}
+
+export default BlogModuleService
+```
+
+To create an integration test for the method, create the file `src/modules/blog/__tests__/service.spec.ts` with the following content:
+
+```ts title="src/modules/blog/__tests__/service.spec.ts"
+import { moduleIntegrationTestRunner } from "@medusajs/test-utils"
+import { BLOG_MODULE } from ".."
+import BlogModuleService from "../service"
+import MyCustom from "../models/my-custom"
+
+moduleIntegrationTestRunner<BlogModuleService>({
+  moduleName: BLOG_MODULE,
+  moduleModels: [MyCustom],
+  resolve: "./src/modules/blog",
+  testSuite: ({ service }) => {
+    describe("BlogModuleService", () => {
+      it("says hello world", () => {
+        const message = service.getMessage()
+
+        expect(message).toEqual("Hello, World!")
+      })
+    })
+  },
+})
+
+jest.setTimeout(60 * 1000)
+```
+
+You use the `moduleIntegrationTestRunner` function to add tests for the `blog` module. You have one test that passes if the `getMessage` method returns the `"Hello, World!"` string.
+
+***
+
+## Run Test
+
+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.
+
+
 # Commerce Modules
 
 In this section of the documentation, you'll find guides and references related to Medusa's Commerce Modules.
@@ -18461,6 +18461,136 @@ Learn more about workflows in [this documentation](https://docs.medusajs.com/doc
 ***
 
 
+# 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.
+
+***
+
+
 # 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.
@@ -18900,24 +19030,27 @@ Learn more about workflows in [this documentation](https://docs.medusajs.com/doc
 ***
 
 
-# Auth Module
+# Inventory 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.
+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.
 
-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.
+Refer to the [Medusa Admin User Guide](https://docs.medusajs.com/user-guide/inventory/index.html.md) to learn how to manage inventory and related features using the dashboard.
+
+Medusa has inventory related features available out-of-the-box through the Inventory 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 Inventory 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
+## Inventory 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.
+- [Inventory Items Management](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/inventory/concepts/index.html.md): Store and manage inventory of any stock-kept item, such as product variants.
+- [Inventory Across Locations](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/inventory/concepts#inventorylevel/index.html.md): Manage inventory levels across different locations, such as warehouses.
+- [Reservation Management](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/inventory/concepts#reservationitem/index.html.md): Reserve quantities of inventory items at specific locations for orders or other purposes.
+- [Check Inventory Availability](https://docs.medusajs.com/references/inventory-next/confirmInventory/index.html.md): Check whether an inventory item has the necessary quantity for purchase.
+- [Inventory Kits](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.
 
 ***
 
-## How to Use the Auth Module
+## How to Use the Inventory 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.
 
@@ -18925,67 +19058,45 @@ You can build custom workflows and steps. You can also re-use Medusa's workflows
 
 For example:
 
-```ts title="src/workflows/authenticate-user.ts" highlights={highlights}
+```ts title="src/workflows/create-inventory-item.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"
+import { Modules } from "@medusajs/framework/utils"
 
-type Input = {
-  req: MedusaRequest
-}
+const createInventoryItemStep = createStep(
+  "create-inventory-item",
+  async ({}, { container }) => {
+    const inventoryModuleService = container.resolve(Modules.INVENTORY)
 
-const authenticateUserStep = createStep(
-  "authenticate-user",
-  async ({ req }: Input, { container }) => {
-    const authModuleService = container.resolve(Modules.AUTH)
+    const inventoryItem = await inventoryModuleService.createInventoryItems({
+      sku: "SHIRT",
+      title: "Green Medusa Shirt",
+      requires_shipping: true,
+    })
 
-    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)
+    return new StepResponse({ inventoryItem }, inventoryItem.id)
   },
-  async (authIdentityId, { container }) => {
-    if (!authIdentityId) {
+  async (inventoryItemId, { container }) => {
+    if (!inventoryItemId) {
       return
     }
-    
-    const authModuleService = container.resolve(Modules.AUTH)
+    const inventoryModuleService = container.resolve(Modules.INVENTORY)
 
-    await authModuleService.deleteAuthIdentities([authIdentityId])
+    await inventoryModuleService.deleteInventoryItems([inventoryItemId])
   }
 )
 
-export const authenticateUserWorkflow = createWorkflow(
-  "authenticate-user",
-  (input: Input) => {
-    const { authIdentity } = authenticateUserStep(input)
+export const createInventoryItemWorkflow = createWorkflow(
+  "create-inventory-item-workflow",
+  () => {
+    const { inventoryItem } = createInventoryItemStep()
 
     return new WorkflowResponse({
-      authIdentity,
+      inventoryItem,
     })
   }
 )
@@ -18993,42 +19104,75 @@ export const authenticateUserWorkflow = createWorkflow(
 
 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"
+### 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 { authenticateUserWorkflow } from "../../workflows/authenticate-user"
+import { createInventoryItemWorkflow } from "../../workflows/create-inventory-item"
 
 export async function GET(
   req: MedusaRequest,
   res: MedusaResponse
 ) {
-  const { result } = await authenticateUserWorkflow(req.scope)
-    .run({
-      req,
-    })
+  const { result } = await createInventoryItemWorkflow(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 { createInventoryItemWorkflow } from "../workflows/create-inventory-item"
+
+export default async function handleUserCreated({
+  event: { data },
+  container,
+}: SubscriberArgs<{ id: string }>) {
+  const { result } = await createInventoryItemWorkflow(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 { createInventoryItemWorkflow } from "../workflows/create-inventory-item"
+
+export default async function myCustomJob(
+  container: MedusaContainer
+) {
+  const { result } = await createInventoryItemWorkflow(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 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.
-
-***
-
 
 # Fulfillment Module
 
@@ -19196,150 +19340,6 @@ The Fulfillment Module accepts options for further configurations. Refer to [thi
 ***
 
 
-# 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.
-
-Refer to the [Medusa Admin User Guide](https://docs.medusajs.com/user-guide/inventory/index.html.md) to learn how to manage inventory and related features using the dashboard.
-
-Medusa has inventory related features available out-of-the-box through the Inventory 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 Inventory Module.
-
-Learn more about why modules are isolated in [this documentation](https://docs.medusajs.com/docs/learn/fundamentals/modules/isolation/index.html.md).
-
-## Inventory Features
-
-- [Inventory Items Management](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/inventory/concepts/index.html.md): Store and manage inventory of any stock-kept item, such as product variants.
-- [Inventory Across Locations](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/inventory/concepts#inventorylevel/index.html.md): Manage inventory levels across different locations, such as warehouses.
-- [Reservation Management](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/inventory/concepts#reservationitem/index.html.md): Reserve quantities of inventory items at specific locations for orders or other purposes.
-- [Check Inventory Availability](https://docs.medusajs.com/references/inventory-next/confirmInventory/index.html.md): Check whether an inventory item has the necessary quantity for purchase.
-- [Inventory Kits](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.
-
-***
-
-## How to Use the Inventory 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-inventory-item.ts" highlights={highlights}
-import { 
-  createWorkflow, 
-  WorkflowResponse,
-  createStep,
-  StepResponse,
-} from "@medusajs/framework/workflows-sdk"
-import { Modules } from "@medusajs/framework/utils"
-
-const createInventoryItemStep = createStep(
-  "create-inventory-item",
-  async ({}, { container }) => {
-    const inventoryModuleService = container.resolve(Modules.INVENTORY)
-
-    const inventoryItem = await inventoryModuleService.createInventoryItems({
-      sku: "SHIRT",
-      title: "Green Medusa Shirt",
-      requires_shipping: true,
-    })
-
-    return new StepResponse({ inventoryItem }, inventoryItem.id)
-  },
-  async (inventoryItemId, { container }) => {
-    if (!inventoryItemId) {
-      return
-    }
-    const inventoryModuleService = container.resolve(Modules.INVENTORY)
-
-    await inventoryModuleService.deleteInventoryItems([inventoryItemId])
-  }
-)
-
-export const createInventoryItemWorkflow = createWorkflow(
-  "create-inventory-item-workflow",
-  () => {
-    const { inventoryItem } = createInventoryItemStep()
-
-    return new WorkflowResponse({
-      inventoryItem,
-    })
-  }
-)
-```
-
-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 { createInventoryItemWorkflow } from "../../workflows/create-inventory-item"
-
-export async function GET(
-  req: MedusaRequest,
-  res: MedusaResponse
-) {
-  const { result } = await createInventoryItemWorkflow(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 { createInventoryItemWorkflow } from "../workflows/create-inventory-item"
-
-export default async function handleUserCreated({
-  event: { data },
-  container,
-}: SubscriberArgs<{ id: string }>) {
-  const { result } = await createInventoryItemWorkflow(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 { createInventoryItemWorkflow } from "../workflows/create-inventory-item"
-
-export default async function myCustomJob(
-  container: MedusaContainer
-) {
-  const { result } = await createInventoryItemWorkflow(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.
@@ -19805,303 +19805,6 @@ Medusa provides the following payment providers out-of-the-box. You can use them
 ***
 
 
-# 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.
-
-Refer to the [Medusa Admin User Guide](https://docs.medusajs.com/user-guide/settings/regions/index.html.md) to learn how to manage regions using the dashboard.
-
-Medusa has region related features available out-of-the-box through the Region 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 Region Module.
-
-Learn more about why modules are isolated in [this documentation](https://docs.medusajs.com/docs/learn/fundamentals/modules/isolation/index.html.md).
-
-***
-
-## Region Features
-
-- [Region Management](https://docs.medusajs.com/references/region/models/Region/index.html.md): Manage regions in your store. You can create regions with different currencies and settings.
-- [Multi-Currency Support](https://docs.medusajs.com/references/region/models/Region/index.html.md): Each region has a currency. You can support multiple currencies in your store by creating multiple regions.
-- [Different Settings Per Region](https://docs.medusajs.com/references/region/models/Region/index.html.md): Each region has its own settings, such as what countries belong to a region or its tax settings.
-
-***
-
-## How to Use Region 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-region.ts" highlights={highlights}
-import { 
-  createWorkflow, 
-  WorkflowResponse,
-  createStep,
-  StepResponse,
-} from "@medusajs/framework/workflows-sdk"
-import { Modules } from "@medusajs/framework/utils"
-
-const createRegionStep = createStep(
-  "create-region",
-  async ({}, { container }) => {
-    const regionModuleService = container.resolve(Modules.REGION)
-
-    const region = await regionModuleService.createRegions({
-      name: "Europe",
-      currency_code: "eur",
-    })
-
-    return new StepResponse({ region }, region.id)
-  },
-  async (regionId, { container }) => {
-    if (!regionId) {
-      return
-    }
-    const regionModuleService = container.resolve(Modules.REGION)
-
-    await regionModuleService.deleteRegions([regionId])
-  }
-)
-
-export const createRegionWorkflow = createWorkflow(
-  "create-region",
-  () => {
-    const { region } = createRegionStep()
-
-    return new WorkflowResponse({
-      region,
-    })
-  }
-)
-```
-
-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 { createRegionWorkflow } from "../../workflows/create-region"
-
-export async function GET(
-  req: MedusaRequest,
-  res: MedusaResponse
-) {
-  const { result } = await createRegionWorkflow(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 { createRegionWorkflow } from "../workflows/create-region"
-
-export default async function handleUserCreated({
-  event: { data },
-  container,
-}: SubscriberArgs<{ id: string }>) {
-  const { result } = await createRegionWorkflow(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 { createRegionWorkflow } from "../workflows/create-region"
-
-export default async function myCustomJob(
-  container: MedusaContainer
-) {
-  const { result } = await createRegionWorkflow(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.
-
-***
-
-## 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.
@@ -20410,6 +20113,303 @@ Learn more about workflows in [this documentation](https://docs.medusajs.com/doc
 ***
 
 
+# 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.
+
+***
+
+## 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).
+
+***
+
+
+# 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.
+
+Refer to the [Medusa Admin User Guide](https://docs.medusajs.com/user-guide/settings/regions/index.html.md) to learn how to manage regions using the dashboard.
+
+Medusa has region related features available out-of-the-box through the Region 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 Region Module.
+
+Learn more about why modules are isolated in [this documentation](https://docs.medusajs.com/docs/learn/fundamentals/modules/isolation/index.html.md).
+
+***
+
+## Region Features
+
+- [Region Management](https://docs.medusajs.com/references/region/models/Region/index.html.md): Manage regions in your store. You can create regions with different currencies and settings.
+- [Multi-Currency Support](https://docs.medusajs.com/references/region/models/Region/index.html.md): Each region has a currency. You can support multiple currencies in your store by creating multiple regions.
+- [Different Settings Per Region](https://docs.medusajs.com/references/region/models/Region/index.html.md): Each region has its own settings, such as what countries belong to a region or its tax settings.
+
+***
+
+## How to Use Region 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-region.ts" highlights={highlights}
+import { 
+  createWorkflow, 
+  WorkflowResponse,
+  createStep,
+  StepResponse,
+} from "@medusajs/framework/workflows-sdk"
+import { Modules } from "@medusajs/framework/utils"
+
+const createRegionStep = createStep(
+  "create-region",
+  async ({}, { container }) => {
+    const regionModuleService = container.resolve(Modules.REGION)
+
+    const region = await regionModuleService.createRegions({
+      name: "Europe",
+      currency_code: "eur",
+    })
+
+    return new StepResponse({ region }, region.id)
+  },
+  async (regionId, { container }) => {
+    if (!regionId) {
+      return
+    }
+    const regionModuleService = container.resolve(Modules.REGION)
+
+    await regionModuleService.deleteRegions([regionId])
+  }
+)
+
+export const createRegionWorkflow = createWorkflow(
+  "create-region",
+  () => {
+    const { region } = createRegionStep()
+
+    return new WorkflowResponse({
+      region,
+    })
+  }
+)
+```
+
+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 { createRegionWorkflow } from "../../workflows/create-region"
+
+export async function GET(
+  req: MedusaRequest,
+  res: MedusaResponse
+) {
+  const { result } = await createRegionWorkflow(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 { createRegionWorkflow } from "../workflows/create-region"
+
+export default async function handleUserCreated({
+  event: { data },
+  container,
+}: SubscriberArgs<{ id: string }>) {
+  const { result } = await createRegionWorkflow(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 { createRegionWorkflow } from "../workflows/create-region"
+
+export default async function myCustomJob(
+  container: MedusaContainer
+) {
+  const { result } = await createRegionWorkflow(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).
+
+***
+
+
 # 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.
@@ -20979,57 +20979,6 @@ The User Module accepts options for further configurations. Refer to [this docum
 ***
 
 
-# API Key Concepts
-
-In this document, you’ll learn about the different types of API keys, their expiration and verification.
-
-## API Key Types
-
-There are two types of API keys:
-
-- `publishable`: A public key used in client applications, such as a storefront.
-- `secret`: A secret key used for authentication and verification purposes, such as an admin user’s authentication token or a password reset token.
-
-The API key’s type is stored in the `type` property of the [ApiKey data model](https://docs.medusajs.com/references/api-key/models/ApiKey/index.html.md).
-
-***
-
-## API Key Expiration
-
-An API key expires when it’s revoked using the [revoke method of the module’s main service](https://docs.medusajs.com/references/api-key/revoke/index.html.md).
-
-The associated token is no longer usable or verifiable.
-
-***
-
-## Token Verification
-
-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.
@@ -21128,6 +21077,1293 @@ createRemoteLinkStep({
 ```
 
 
+# API Key Concepts
+
+In this document, you’ll learn about the different types of API keys, their expiration and verification.
+
+## API Key Types
+
+There are two types of API keys:
+
+- `publishable`: A public key used in client applications, such as a storefront.
+- `secret`: A secret key used for authentication and verification purposes, such as an admin user’s authentication token or a password reset token.
+
+The API key’s type is stored in the `type` property of the [ApiKey data model](https://docs.medusajs.com/references/api-key/models/ApiKey/index.html.md).
+
+***
+
+## API Key Expiration
+
+An API key expires when it’s revoked using the [revoke method of the module’s main service](https://docs.medusajs.com/references/api-key/revoke/index.html.md).
+
+The associated token is no longer usable or verifiable.
+
+***
+
+## Token Verification
+
+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.
+
+
+# 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`.
+
+![Diagram showcasing the basic authentication flow](https://res.cloudinary.com/dza7lstvk/image/upload/v1711373749/Medusa%20Resources/basic-auth_lgpqsj.jpg)
+
+### 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.
+
+![Diagram showcasing the first part of the third-party authentication flow](https://res.cloudinary.com/dza7lstvk/image/upload/v1711374847/Medusa%20Resources/third-party-auth-1_enyedy.jpg)
+
+### 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.
+
+![Diagram showcasing the second part of the third-party authentication flow](https://res.cloudinary.com/dza7lstvk/image/upload/v1711375123/Medusa%20Resources/third-party-auth-2_kmjxju.jpg)
+
+***
+
+## 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:
+
+![Diagram showcasing the basic authentication flow between the frontend and the Medusa application](https://res.cloudinary.com/dza7lstvk/image/upload/v1725539370/Medusa%20Resources/basic-auth-routes_pgpjch.jpg)
+
+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:
+
+![Diagram showcasing the authentication flow between the frontend, Medusa application, and third-party service](https://res.cloudinary.com/dza7lstvk/image/upload/v1725528159/Medusa%20Resources/Third_Party_Auth_tvf4ng.jpg)
+
+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<CreateManagerWorkflowInput, "manager">, 
+  { 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<RequestBody>, 
+  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<void> {
+  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<DeleteManagerWorkflow>
+  ): WorkflowResponse<string> => {
+    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.
+
+
+# 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)
+
+
+# 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).
+
+
+# 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 Customer Module and Other Modules
 
 This document showcases the module links defined between the Customer Module and other Commerce Modules.
@@ -21838,81 +23074,6 @@ const { data: carts } = useQueryGraphStep({
 ```
 
 
-# Tax Lines in Cart Module
-
-In this document, you’ll learn about tax lines in a cart and how to retrieve tax lines with the Tax Module.
-
-## What are Tax Lines?
-
-A tax line indicates the tax rate of a line item or a shipping method. The [LineItemTaxLine data model](https://docs.medusajs.com/references/cart/models/LineItemTaxLine/index.html.md) represents a line item’s tax line, and the [ShippingMethodTaxLine data model](https://docs.medusajs.com/references/cart/models/ShippingMethodTaxLine/index.html.md) represents a shipping method’s tax line.
-
-![A diagram showcasing the relation between other data models and the tax line models](https://res.cloudinary.com/dza7lstvk/image/upload/v1711534431/Medusa%20Resources/cart-tax-lines_oheaq6.jpg)
-
-***
-
-## Tax Inclusivity
-
-By default, the tax amount is calculated by taking the tax rate from the line item or shipping method’s amount, and then adding them to the item/method’s subtotal.
-
-However, line items and shipping methods have an `is_tax_inclusive` property that, when enabled, indicates that the item or method’s price already includes taxes.
-
-So, instead of calculating the tax rate and adding it to the item/method’s subtotal, it’s calculated as part of the subtotal.
-
-The following diagram is a simplified showcase of how a subtotal is calculated from the taxes perspective.
-
-![A diagram showing an example of calculating the subtotal of a line item using its taxes](https://res.cloudinary.com/dza7lstvk/image/upload/v1711535295/Medusa%20Resources/cart-tax-inclusive_shpr3t.jpg)
-
-For example, if a line item's amount is `5000`, the tax rate is `10`, and tax inclusivity is enabled, the tax amount is 10% of `5000`, which is `500`, making the unit price of the line item `4500`.
-
-***
-
-## Retrieve Tax Lines
-
-When using the Cart and Tax modules together, you can use the `getTaxLines` method of the Tax Module’s main service. It retrieves the tax lines for a cart’s line items and shipping methods.
-
-```ts
-// retrieve the cart
-const cart = await cartModuleService.retrieveCart("cart_123", {
-  relations: [
-    "items.tax_lines",
-    "shipping_methods.tax_lines",
-    "shipping_address",
-  ],
-})
-
-// retrieve the tax lines
-const taxLines = await taxModuleService.getTaxLines(
-  [
-    ...(cart.items as TaxableItemDTO[]),
-    ...(cart.shipping_methods as TaxableShippingDTO[]),
-  ],
-  {
-    address: {
-      ...cart.shipping_address,
-      country_code:
-        cart.shipping_address.country_code || "us",
-    },
-  }
-)
-```
-
-Then, use the returned tax lines to set the line items and shipping methods’ tax lines:
-
-```ts
-// set line item tax lines
-await cartModuleService.setLineItemTaxLines(
-  cart.id,
-  taxLines.filter((line) => "line_item_id" in line)
-)
-
-// set shipping method tax lines
-await cartModuleService.setLineItemTaxLines(
-  cart.id,
-  taxLines.filter((line) => "shipping_line_id" in line)
-)
-```
-
-
 # Promotions Adjustments in Carts
 
 In this document, you’ll learn how a promotion is applied to a cart’s line items and shipping methods using adjustment lines.
@@ -22031,1838 +23192,80 @@ await cartModuleService.setShippingMethodAdjustments(
 ```
 
 
-# Authentication Flows with the Auth Main Service
+# Tax Lines in Cart Module
 
-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 about tax lines in a cart and how to retrieve tax lines with the Tax Module.
 
-## Authentication Methods
+## What are Tax Lines?
 
-### Register
+A tax line indicates the tax rate of a line item or a shipping method. The [LineItemTaxLine data model](https://docs.medusajs.com/references/cart/models/LineItemTaxLine/index.html.md) represents a line item’s tax line, and the [ShippingMethodTaxLine data model](https://docs.medusajs.com/references/cart/models/ShippingMethodTaxLine/index.html.md) represents a shipping method’s tax line.
 
-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.
+![A diagram showcasing the relation between other data models and the tax line models](https://res.cloudinary.com/dza7lstvk/image/upload/v1711534431/Medusa%20Resources/cart-tax-lines_oheaq6.jpg)
 
-For example:
+***
+
+## Tax Inclusivity
+
+By default, the tax amount is calculated by taking the tax rate from the line item or shipping method’s amount, and then adding them to the item/method’s subtotal.
+
+However, line items and shipping methods have an `is_tax_inclusive` property that, when enabled, indicates that the item or method’s price already includes taxes.
+
+So, instead of calculating the tax rate and adding it to the item/method’s subtotal, it’s calculated as part of the subtotal.
+
+The following diagram is a simplified showcase of how a subtotal is calculated from the taxes perspective.
+
+![A diagram showing an example of calculating the subtotal of a line item using its taxes](https://res.cloudinary.com/dza7lstvk/image/upload/v1711535295/Medusa%20Resources/cart-tax-inclusive_shpr3t.jpg)
+
+For example, if a line item's amount is `5000`, the tax rate is `10`, and tax inclusivity is enabled, the tax amount is 10% of `5000`, which is `500`, making the unit price of the line item `4500`.
+
+***
+
+## Retrieve Tax Lines
+
+When using the Cart and Tax modules together, you can use the `getTaxLines` method of the Tax Module’s main service. It retrieves the tax lines for a cart’s line items and shipping methods.
 
 ```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`.
-
-![Diagram showcasing the basic authentication flow](https://res.cloudinary.com/dza7lstvk/image/upload/v1711373749/Medusa%20Resources/basic-auth_lgpqsj.jpg)
-
-### 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.
-
-![Diagram showcasing the first part of the third-party authentication flow](https://res.cloudinary.com/dza7lstvk/image/upload/v1711374847/Medusa%20Resources/third-party-auth-1_enyedy.jpg)
-
-### 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.
-
-![Diagram showcasing the second part of the third-party authentication flow](https://res.cloudinary.com/dza7lstvk/image/upload/v1711375123/Medusa%20Resources/third-party-auth-2_kmjxju.jpg)
-
-***
-
-## 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.
-
-
-# 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:
-
-![Diagram showcasing the basic authentication flow between the frontend and the Medusa application](https://res.cloudinary.com/dza7lstvk/image/upload/v1725539370/Medusa%20Resources/basic-auth-routes_pgpjch.jpg)
-
-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:
-
-![Diagram showcasing the authentication flow between the frontend, Medusa application, and third-party service](https://res.cloudinary.com/dza7lstvk/image/upload/v1725528159/Medusa%20Resources/Third_Party_Auth_tvf4ng.jpg)
-
-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"
-}
-```
-
-
-# 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"]),
-      ],
-    },
+// retrieve the cart
+const cart = await cartModuleService.retrieveCart("cart_123", {
+  relations: [
+    "items.tax_lines",
+    "shipping_methods.tax_lines",
+    "shipping_address",
   ],
 })
-```
 
-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 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<CreateManagerWorkflowInput, "manager">, 
-  { 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<RequestBody>, 
-  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<void> {
-  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<DeleteManagerWorkflow>
-  ): WorkflowResponse<string> => {
-    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.
-
-
-# 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)
-
-
-# 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).
-
-
-# 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(
+// retrieve the tax lines
+const taxLines = await taxModuleService.getTaxLines(
   [
-    {
-      name: "Shipping",
-      type: "shipping",
+    ...(cart.items as TaxableItemDTO[]),
+    ...(cart.shipping_methods as TaxableShippingDTO[]),
+  ],
+  {
+    address: {
+      ...cart.shipping_address,
+      country_code:
+        cart.shipping_address.country_code || "us",
     },
-    {
-      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 diagram showcasing the relation between fulfillment sets, service zones, and geo zones](https://res.cloudinary.com/dza7lstvk/image/upload/v1712329770/Medusa%20Resources/service-zone_awmvfs.jpg)
-
-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.
-
-***
-
-## 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.
-
-
-# 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.
-
-![A diagram showcasing the relation between a fulfillment, fulfillment provider, and shipping option](https://res.cloudinary.com/dza7lstvk/image/upload/v1712331947/Medusa%20Resources/fulfillment-shipping-option_jk9ndp.jpg)
-
-***
-
-## 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.
-
-![A diagram showcasing the relation between fulfillment and fulfillment items.](https://res.cloudinary.com/dza7lstvk/image/upload/v1712332114/Medusa%20Resources/fulfillment-item_etzxb0.jpg)
-
-***
-
-## 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.
-
-
-# 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|
-|---|---|---|---|
-| in ||Stored - one-to-many||
-| in ||Stored - one-to-many||
-| in ||Stored - many-to-one||
-| in ||Stored - many-to-one||
-| in ||Stored - one-to-many||
-| in ||Stored - one-to-many||
-
-***
-
-## 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 diagram showcasing an example of how data models from the Fulfillment and Order modules are linked](https://res.cloudinary.com/dza7lstvk/image/upload/v1716549903/Medusa%20Resources/order-fulfillment_h0vlps.jpg)
-
-A fulfillment is also created for a return's items. So, Medusa defines a link between the `Fulfillment` and `Return` data models.
-
-![A diagram showcasing an example of how data models from the Fulfillment and Order modules are linked](https://res.cloudinary.com/dza7lstvk/image/upload/v1728399052/Medusa%20Resources/Social_Media_Graphics_2024_Order_Return_vetimk.jpg)
-
-### 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
+Then, use the returned tax lines to set the line items and shipping methods’ tax lines:
 
 ```ts
-const { data: fulfillments } = await query.graph({
-  entity: "fulfillment",
-  fields: [
-    "order.*",
-  ],
-})
+// set line item tax lines
+await cartModuleService.setLineItemTaxLines(
+  cart.id,
+  taxLines.filter((line) => "line_item_id" in line)
+)
 
-// fulfillments.order
+// set shipping method tax lines
+await cartModuleService.setLineItemTaxLines(
+  cart.id,
+  taxLines.filter((line) => "shipping_line_id" in line)
+)
 ```
 
-### 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.
-
-![A diagram showcasing an example of how data models from the Pricing and Fulfillment modules are linked](https://res.cloudinary.com/dza7lstvk/image/upload/v1716561747/Medusa%20Resources/pricing-fulfillment_spywwa.jpg)
-
-### 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.
-
-![A diagram showcasing an example of how data models from the Fulfillment and Stock Location modules are linked](https://res.cloudinary.com/dza7lstvk/image/upload/v1712567101/Medusa%20Resources/fulfillment-stock-location_nlkf7e.jpg)
-
-Medusa also defines a link between the `FulfillmentProvider` and `StockLocation` data models to indicate the providers that can be used in a location.
-
-![A diagram showcasing an example of how data models from the Fulfillment and Stock Location modules are linked](https://res.cloudinary.com/dza7lstvk/image/upload/v1728399492/Medusa%20Resources/fulfillment-provider-stock-location_b0mulo.jpg)
-
-### 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.
-
-![A diagram showcasing the relation between shipping options and service zones.](https://res.cloudinary.com/dza7lstvk/image/upload/v1712330831/Medusa%20Resources/shipping-option-service-zone_pobh6k.jpg)
-
-Service zones can be more restrictive, such as restricting to certain cities or province codes.
-
-![A diagram showcasing the relation between shipping options, service zones, and geo zones](https://res.cloudinary.com/dza7lstvk/image/upload/v1712331186/Medusa%20Resources/shipping-option-service-zone-city_m5sxod.jpg)
-
-***
-
-## 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 diagram showcasing the relation between shipping option and shipping option rules.](https://res.cloudinary.com/dza7lstvk/image/upload/v1712331340/Medusa%20Resources/shipping-option-rule_oosopf.jpg)
-
-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.
-
-![A diagram showcasing how a shipping option can have multiple rules.](https://res.cloudinary.com/dza7lstvk/image/upload/v1712331462/Medusa%20Resources/shipping-option-rule-2_ylaqdb.jpg)
-
-***
-
-## 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
 
@@ -24497,53 +23900,605 @@ const { data: inventoryLevels } = useQueryGraphStep({
 ```
 
 
-# Order Concepts
+# Fulfillment Module Provider
 
-In this document, you’ll learn about orders and related concepts
+In this document, you’ll learn what a fulfillment module provider is.
 
-## Order Items
+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.
 
-The items purchased in the order are represented by the [OrderItem data model](https://docs.medusajs.com/references/order/models/OrderItem/index.html.md). An order can have multiple items.
+## What’s a Fulfillment Module Provider?
 
-![A diagram showcasing the relation between an order and its items.](https://res.cloudinary.com/dza7lstvk/image/upload/v1712304722/Medusa%20Resources/order-order-items_uvckxd.jpg)
+A fulfillment module provider handles fulfilling items, typically using a third-party integration.
 
-### Item’s Product Details
-
-The details of the purchased products are represented by the [LineItem data model](https://docs.medusajs.com/references/order/models/OrderLineItem/index.html.md). Not only does a line item hold the details of the product, but also details related to its price, adjustments due to promotions, and taxes.
+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).
 
 ***
 
-## Order’s Shipping Method
+## Configure Fulfillment Providers
 
-An order has one or more shipping methods used to handle item shipment.
+The Fulfillment Module accepts a `providers` option that allows you to register providers in your application.
 
-Each shipping method is represented by the [OrderShippingMethod data model](https://docs.medusajs.com/references/order/models/OrderShippingMethod/index.html.md) that holds its details. The shipping method is linked to the order through the [OrderShipping data model](https://docs.medusajs.com/references/order/models/OrderShipping/index.html.md).
-
-![A diagram showcasing the relation between an order and its items.](https://res.cloudinary.com/dza7lstvk/image/upload/v1719570409/Medusa%20Resources/order-shipping-method_tkggvd.jpg)
-
-### data Property
-
-When fulfilling the order, you can use a third-party fulfillment provider that requires additional custom data to be passed along from the order creation process.
-
-The `OrderShippingMethod` data model has a `data` property. It’s an object used to store custom data relevant later for fulfillment.
-
-The Medusa application passes the `data` property to the Fulfillment Module when fulfilling items.
+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).
 
 ***
 
-## Order Totals
+## How to Create a Fulfillment Provider?
 
-The order’s total amounts (including tax total, total after an item is returned, etc…) are represented by the [OrderSummary data model](https://docs.medusajs.com/references/order/models/OrderSummary/index.html.md).
+Refer to [this guide](https://docs.medusajs.com/references/fulfillment/provider/index.html.md) to learn how to create a fulfillment module provider.
+
+
+# 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",
+    },
+  ]
+)
+```
 
 ***
 
-## Order Payments
+## Service Zone
 
-Payments made on an order, whether they’re capture or refund payments, are recorded as transactions represented by the [OrderTransaction data model](https://docs.medusajs.com/references/order/models/OrderTransaction/index.html.md).
+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.
 
-An order can have multiple transactions. The sum of these transactions must be equal to the order summary’s total. Otherwise, there’s an outstanding amount.
+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.
 
-Learn more about transactions in [this guide](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/order/transactions/index.html.md).
+![A diagram showcasing the relation between fulfillment sets, service zones, and geo zones](https://res.cloudinary.com/dza7lstvk/image/upload/v1712329770/Medusa%20Resources/service-zone_awmvfs.jpg)
+
+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.
+
+
+# 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.
+
+![A diagram showcasing the relation between a fulfillment, fulfillment provider, and shipping option](https://res.cloudinary.com/dza7lstvk/image/upload/v1712331947/Medusa%20Resources/fulfillment-shipping-option_jk9ndp.jpg)
+
+***
+
+## 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.
+
+![A diagram showcasing the relation between fulfillment and fulfillment items.](https://res.cloudinary.com/dza7lstvk/image/upload/v1712332114/Medusa%20Resources/fulfillment-item_etzxb0.jpg)
+
+***
+
+## 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.
+
+
+# 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|
+|---|---|---|---|
+| in ||Stored - one-to-many||
+| in ||Stored - one-to-many||
+| in ||Stored - many-to-one||
+| in ||Stored - many-to-one||
+| in ||Stored - one-to-many||
+| in ||Stored - one-to-many||
+
+***
+
+## 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 diagram showcasing an example of how data models from the Fulfillment and Order modules are linked](https://res.cloudinary.com/dza7lstvk/image/upload/v1716549903/Medusa%20Resources/order-fulfillment_h0vlps.jpg)
+
+A fulfillment is also created for a return's items. So, Medusa defines a link between the `Fulfillment` and `Return` data models.
+
+![A diagram showcasing an example of how data models from the Fulfillment and Order modules are linked](https://res.cloudinary.com/dza7lstvk/image/upload/v1728399052/Medusa%20Resources/Social_Media_Graphics_2024_Order_Return_vetimk.jpg)
+
+### 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.
+
+![A diagram showcasing an example of how data models from the Pricing and Fulfillment modules are linked](https://res.cloudinary.com/dza7lstvk/image/upload/v1716561747/Medusa%20Resources/pricing-fulfillment_spywwa.jpg)
+
+### 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.
+
+![A diagram showcasing an example of how data models from the Fulfillment and Stock Location modules are linked](https://res.cloudinary.com/dza7lstvk/image/upload/v1712567101/Medusa%20Resources/fulfillment-stock-location_nlkf7e.jpg)
+
+Medusa also defines a link between the `FulfillmentProvider` and `StockLocation` data models to indicate the providers that can be used in a location.
+
+![A diagram showcasing an example of how data models from the Fulfillment and Stock Location modules are linked](https://res.cloudinary.com/dza7lstvk/image/upload/v1728399492/Medusa%20Resources/fulfillment-provider-stock-location_b0mulo.jpg)
+
+### 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",
+  },
+})
+```
+
+
+# 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.
+
+![A diagram showcasing the relation between shipping options and service zones.](https://res.cloudinary.com/dza7lstvk/image/upload/v1712330831/Medusa%20Resources/shipping-option-service-zone_pobh6k.jpg)
+
+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).
+
+![A diagram showcasing the relation between shipping options, service zones, and geo zones](https://res.cloudinary.com/dza7lstvk/image/upload/v1712331186/Medusa%20Resources/shipping-option-service-zone-city_m5sxod.jpg)
+
+***
+
+## 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 diagram showcasing the relation between shipping option and shipping option rules.](https://res.cloudinary.com/dza7lstvk/image/upload/v1712331340/Medusa%20Resources/shipping-option-rule_oosopf.jpg)
+
+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.
+
+![A diagram showcasing how a shipping option can have multiple rules.](https://res.cloudinary.com/dza7lstvk/image/upload/v1712331462/Medusa%20Resources/shipping-option-rule-2_ylaqdb.jpg)
+
+***
+
+## 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.
+
+
+# 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.
 
 
 # Order Claim
@@ -24600,6 +24555,55 @@ The [Transaction data model](https://docs.medusajs.com/references/order/models/O
 When a claim is confirmed, the order’s version is incremented.
 
 
+# Order Concepts
+
+In this document, you’ll learn about orders and related concepts
+
+## Order Items
+
+The items purchased in the order are represented by the [OrderItem data model](https://docs.medusajs.com/references/order/models/OrderItem/index.html.md). An order can have multiple items.
+
+![A diagram showcasing the relation between an order and its items.](https://res.cloudinary.com/dza7lstvk/image/upload/v1712304722/Medusa%20Resources/order-order-items_uvckxd.jpg)
+
+### Item’s Product Details
+
+The details of the purchased products are represented by the [LineItem data model](https://docs.medusajs.com/references/order/models/OrderLineItem/index.html.md). Not only does a line item hold the details of the product, but also details related to its price, adjustments due to promotions, and taxes.
+
+***
+
+## Order’s Shipping Method
+
+An order has one or more shipping methods used to handle item shipment.
+
+Each shipping method is represented by the [OrderShippingMethod data model](https://docs.medusajs.com/references/order/models/OrderShippingMethod/index.html.md) that holds its details. The shipping method is linked to the order through the [OrderShipping data model](https://docs.medusajs.com/references/order/models/OrderShipping/index.html.md).
+
+![A diagram showcasing the relation between an order and its items.](https://res.cloudinary.com/dza7lstvk/image/upload/v1719570409/Medusa%20Resources/order-shipping-method_tkggvd.jpg)
+
+### data Property
+
+When fulfilling the order, you can use a third-party fulfillment provider that requires additional custom data to be passed along from the order creation process.
+
+The `OrderShippingMethod` data model has a `data` property. It’s an object used to store custom data relevant later for fulfillment.
+
+The Medusa application passes the `data` property to the Fulfillment Module when fulfilling items.
+
+***
+
+## Order Totals
+
+The order’s total amounts (including tax total, total after an item is returned, etc…) are represented by the [OrderSummary data model](https://docs.medusajs.com/references/order/models/OrderSummary/index.html.md).
+
+***
+
+## Order Payments
+
+Payments made on an order, whether they’re capture or refund payments, are recorded as transactions represented by the [OrderTransaction data model](https://docs.medusajs.com/references/order/models/OrderTransaction/index.html.md).
+
+An order can have multiple transactions. The sum of these transactions must be equal to the order summary’s total. Otherwise, there’s an outstanding amount.
+
+Learn more about transactions in [this guide](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/order/transactions/index.html.md).
+
+
 # Order Edit
 
 In this document, you'll learn about order edits.
@@ -25234,6 +25238,36 @@ const { data: orders } = useQueryGraphStep({
 ```
 
 
+# Order Versioning
+
+In this document, you’ll learn how an order and its details are versioned.
+
+## What's Versioning?
+
+Versioning means assigning a version number to a record, such as an order and its items. This is useful to view the different versions of the order following changes in its lifetime.
+
+When changes are made on an order, such as an item is added or returned, the order's version changes.
+
+***
+
+## version Property
+
+The `Order` and `OrderSummary` data models have a `version` property that indicates the current version. By default, its value is `1`.
+
+Other order-related data models, such as `OrderItem`, also has a `version` property, but it indicates the version it belongs to.
+
+***
+
+## How the Version Changes
+
+When the order is changed, such as an item is exchanged, this changes the version of the order and its related data:
+
+1. The version of the order and its summary is incremented.
+2. Related order data that have a `version` property, such as the `OrderItem`, are duplicated. The duplicated item has the new version, whereas the original item has the previous version.
+
+When the order is retrieved, only the related data having the same version is retrieved.
+
+
 # Order Change
 
 In this document, you'll learn about the Order Change data model and possible actions in it.
@@ -25273,36 +25307,6 @@ The following table lists the possible `action` values that Medusa uses and what
 |\`WRITE\_OFF\_ITEM\`|Remove an item's quantity as part of the claim, without adding the quantity back to the item variant's inventory.|\`details\`|
 
 
-# Order Versioning
-
-In this document, you’ll learn how an order and its details are versioned.
-
-## What's Versioning?
-
-Versioning means assigning a version number to a record, such as an order and its items. This is useful to view the different versions of the order following changes in its lifetime.
-
-When changes are made on an order, such as an item is added or returned, the order's version changes.
-
-***
-
-## version Property
-
-The `Order` and `OrderSummary` data models have a `version` property that indicates the current version. By default, its value is `1`.
-
-Other order-related data models, such as `OrderItem`, also has a `version` property, but it indicates the version it belongs to.
-
-***
-
-## How the Version Changes
-
-When the order is changed, such as an item is exchanged, this changes the version of the order and its related data:
-
-1. The version of the order and its summary is incremented.
-2. Related order data that have a `version` property, such as the `OrderItem`, are duplicated. The duplicated item has the new version, whereas the original item has the previous version.
-
-When the order is retrieved, only the related data having the same version is retrieved.
-
-
 # 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.
@@ -25425,35 +25429,6 @@ await orderModuleService.setOrderShippingMethodAdjustments(
 ```
 
 
-# Tax Lines in Order Module
-
-In this document, you’ll learn about tax lines in an order.
-
-## What are Tax Lines?
-
-A tax line indicates the tax rate of a line item or a shipping method.
-
-The [OrderLineItemTaxLine data model](https://docs.medusajs.com/references/order/models/OrderLineItemTaxLine/index.html.md) represents a line item’s tax line, and the [OrderShippingMethodTaxLine data model](https://docs.medusajs.com/references/order/models/OrderShippingMethodTaxLine/index.html.md) represents a shipping method’s tax line.
-
-![A diagram showcasing the relation between orders, items and shipping methods, and tax lines](https://res.cloudinary.com/dza7lstvk/image/upload/v1712307225/Medusa%20Resources/order-tax-lines_sixujd.jpg)
-
-***
-
-## Tax Inclusivity
-
-By default, the tax amount is calculated by taking the tax rate from the line item or shipping method’s amount and then adding it to the item/method’s subtotal.
-
-However, line items and shipping methods have an `is_tax_inclusive` property that, when enabled, indicates that the item or method’s price already includes taxes.
-
-So, instead of calculating the tax rate and adding it to the item/method’s subtotal, it’s calculated as part of the subtotal.
-
-The following diagram is a simplified showcase of how a subtotal is calculated from the tax perspective.
-
-![A diagram showcasing how a subtotal is calculated from the tax perspective](https://res.cloudinary.com/dza7lstvk/image/upload/v1712307395/Medusa%20Resources/order-tax-inclusive_oebdnm.jpg)
-
-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`.
-
-
 # Order Return
 
 In this document, you’ll learn about order returns.
@@ -25563,6 +25538,35 @@ 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`.
 
 
+# Tax Lines in Order Module
+
+In this document, you’ll learn about tax lines in an order.
+
+## What are Tax Lines?
+
+A tax line indicates the tax rate of a line item or a shipping method.
+
+The [OrderLineItemTaxLine data model](https://docs.medusajs.com/references/order/models/OrderLineItemTaxLine/index.html.md) represents a line item’s tax line, and the [OrderShippingMethodTaxLine data model](https://docs.medusajs.com/references/order/models/OrderShippingMethodTaxLine/index.html.md) represents a shipping method’s tax line.
+
+![A diagram showcasing the relation between orders, items and shipping methods, and tax lines](https://res.cloudinary.com/dza7lstvk/image/upload/v1712307225/Medusa%20Resources/order-tax-lines_sixujd.jpg)
+
+***
+
+## Tax Inclusivity
+
+By default, the tax amount is calculated by taking the tax rate from the line item or shipping method’s amount and then adding it to the item/method’s subtotal.
+
+However, line items and shipping methods have an `is_tax_inclusive` property that, when enabled, indicates that the item or method’s price already includes taxes.
+
+So, instead of calculating the tax rate and adding it to the item/method’s subtotal, it’s calculated as part of the subtotal.
+
+The following diagram is a simplified showcase of how a subtotal is calculated from the tax perspective.
+
+![A diagram showcasing how a subtotal is calculated from the tax perspective](https://res.cloudinary.com/dza7lstvk/image/upload/v1712307395/Medusa%20Resources/order-tax-inclusive_oebdnm.jpg)
+
+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.
@@ -25770,163 +25774,6 @@ createRemoteLinkStep({
 ```
 
 
-# Price Rules
-
-In this Pricing Module guide, you'll learn about price rules for price sets and price lists, and how to add rules to a price.
-
-## Price Rule
-
-You can restrict prices by rules. Each rule of a price is represented by the [PriceRule data model](https://docs.medusajs.com/references/pricing/models/PriceRule/index.html.md).
-
-The `Price` data model has a `rules_count` property, which indicates how many rules, represented by `PriceRule`, are applied to the price.
-
-For exmaple, you create a price restricted to `10557` zip codes.
-
-![A diagram showcasing the relation between the PriceRule and Price](https://res.cloudinary.com/dza7lstvk/image/upload/v1709648772/Medusa%20Resources/price-rule-1_vy8bn9.jpg)
-
-A price can have multiple price rules.
-
-For example, a price can be restricted by a region and a zip code.
-
-![A diagram showcasing the relation between the PriceRule and Price with multiple rules.](https://res.cloudinary.com/dza7lstvk/image/upload/v1709649296/Medusa%20Resources/price-rule-3_pwpocz.jpg)
-
-***
-
-## Price List Rules
-
-Rules applied to a price list are represented by the [PriceListRule data model](https://docs.medusajs.com/references/pricing/models/PriceListRule/index.html.md).
-
-The `rules_count` property of a `PriceList` indicates how many rules are applied to it.
-
-![A diagram showcasing the relation between the PriceSet, PriceList, Price, RuleType, and PriceListRuleValue](https://res.cloudinary.com/dza7lstvk/image/upload/v1709641999/Medusa%20Resources/price-list_zd10yd.jpg)
-
-***
-
-## How to Set Rules on a Price?
-
-### Using Workflows
-
-Medusa uses the Pricing Module to store prices of different resources, such as product variants and shipping options.
-
-When you manage one of these resources using [Medusa's workflows](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/medusa-workflows-reference/index.html.md) or using the API routes that use them, you can set rules on a price using the `rules` property of the price object.
-
-For example, when creating a shipping option using the [createShippingOptionsWorkflow](https://docs.medusajs.com/resources/references/medusa-workflows/createShippingOptionsWorkflow/index.html.md) to create a shipping option, you can make the shipping price free based on the cart total:
-
-```ts highlights={workflowHighlights}
-const { result } = await createShippingOptionsWorkflow(container)
-  .run({
-    input: [{
-      name: "Standard Shipping",
-      service_zone_id: "serzo_123",
-      shipping_profile_id: "sp_123",
-      provider_id: "prov_123",
-      type: {
-        label: "Standard",
-        description: "Standard shipping",
-        code: "standard",
-      },
-      price_type: "flat",
-      prices: [
-        // default price
-        {
-          currency_code: "usd",
-          amount: 10,
-          rules: {},
-        },
-        // price if cart total >= $100
-        {
-          currency_code: "usd",
-          amount: 0,
-          rules: {
-            item_total: {
-              operator: "gte",
-              value: 100,
-            },
-          },
-        },
-      ],
-    }],
-  })
-```
-
-In this example, you create a shipping option whose default price is `$10`. When the total of the cart or order using this shipping option is greater than `$100`, the shipping option's price becomes free.
-
-### Using Pricing Module's Service
-
-For most use cases, it's recommended to use [workflows](#using-workflows) instead of directly using the module's service.
-
-When adding a price using the [addPrices](https://docs.medusajs.com/resources/references/pricing/addPrices/index.html.md) method of the Pricing Module's service, pass the `rules` property to a price object.
-
-For example:
-
-```ts
-const priceSet = await pricingModule.addPrices({
-  priceSetId: "pset_1",
-  prices: [
-    // default price
-    {
-      currency_code: "usd",
-      amount: 10,
-      rules: {},
-    },
-    // price if cart total >= $100
-    {
-      currency_code: "usd",
-      amount: 0,
-      rules: {
-        item_total: {
-          operator: "gte",
-          value: 100,
-        },
-      },
-    },
-  ],
-})
-```
-
-In this example, you set the default price of a resource (for example, a shipping option), to `$10`. You also add a conditioned price that sets the price to `0` when the cart or order's total is greater than or equal to `$100`.
-
-### How is the Price Rule Applied?
-
-The [price calculation](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/pricing/price-calculation/index.html.md) mechanism considers a price applicable when the resource that this price is in matches the specified rules.
-
-For example, a [cart object](https://docs.medusajs.com/api/store#carts_cart_schema) has an `item_total` property. So, if a shipping option has the following price:
-
-```json
-{
-  "currency_code": "usd",
-  "amount": 0,
-  "rules": {
-    "item_total": {
-      "operator": "gte",
-      "value": 100,
-    }
-  }
-}
-```
-
-The shipping option's price is applied when the cart's `item_total` is greater than or equal to `$100`.
-
-You can also apply the rule on nested relations and properties. For example, to apply a shipping option's price based on the customer's group, you can apply a rule on the `customer.group.id` attribute:
-
-```json
-{
-  "currency_code": "usd",
-  "amount": 0,
-  "rules": {
-    "customer.group.id": {
-      "operator": "eq",
-      "value": "cusgrp_123"
-    }
-  }
-}
-```
-
-In this example, the price is only applied if a cart's customer belongs to the customer group of ID `cusgrp_123`.
-
-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.
@@ -26120,53 +25967,161 @@ const price = await pricingModuleService.calculatePrices(
 ### Result
 
 
-# Account Holders and Saved Payment Methods
+# Price Rules
 
-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 Pricing Module guide, you'll learn about price rules for price sets and price lists, and how to add rules to a price.
 
-Account holders are available starting from Medusa `v2.5.0`.
+## Price Rule
 
-## What's an Account Holder?
+You can restrict prices by rules. Each rule of a price is represented by the [PriceRule data model](https://docs.medusajs.com/references/pricing/models/PriceRule/index.html.md).
 
-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.
+The `Price` data model has a `rules_count` property, which indicates how many rules, represented by `PriceRule`, are applied to the price.
 
-It holds fields retrieved from the third-party provider, such as:
+For exmaple, you create a price restricted to `10557` zip codes.
 
-- `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 diagram showcasing the relation between the PriceRule and Price](https://res.cloudinary.com/dza7lstvk/image/upload/v1709648772/Medusa%20Resources/price-rule-1_vy8bn9.jpg)
 
-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.
+A price can have multiple price rules.
 
-### Relation between Account Holder and Customer
+For example, a price can be restricted by a region and a zip code.
 
-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 diagram showcasing the relation between the PriceRule and Price with multiple rules.](https://res.cloudinary.com/dza7lstvk/image/upload/v1709649296/Medusa%20Resources/price-rule-3_pwpocz.jpg)
 
 ***
 
-## Save Payment Methods
+## Price List Rules
 
-If a payment provider supports saving payment methods for a customer, they must implement the following methods:
+Rules applied to a price list are represented by the [PriceListRule data model](https://docs.medusajs.com/references/pricing/models/PriceListRule/index.html.md).
 
-- `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 `rules_count` property of a `PriceList` indicates how many rules are applied to it.
 
-Learn more about implementing these methods in the [Create Payment Provider guide](https://docs.medusajs.com/references/payment/provider/index.html.md).
+![A diagram showcasing the relation between the PriceSet, PriceList, Price, RuleType, and PriceListRuleValue](https://res.cloudinary.com/dza7lstvk/image/upload/v1709641999/Medusa%20Resources/price-list_zd10yd.jpg)
 
 ***
 
-## Account Holder in Medusa Payment Flows
+## How to Set Rules on a Price?
 
-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.
+### Using Workflows
 
-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.
+Medusa uses the Pricing Module to store prices of different resources, such as product variants and shipping options.
 
-This flow is only supported if the chosen payment provider has implemented the necessary [save payment methods](#save-payment-methods).
+When you manage one of these resources using [Medusa's workflows](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/medusa-workflows-reference/index.html.md) or using the API routes that use them, you can set rules on a price using the `rules` property of the price object.
+
+For example, when creating a shipping option using the [createShippingOptionsWorkflow](https://docs.medusajs.com/resources/references/medusa-workflows/createShippingOptionsWorkflow/index.html.md) to create a shipping option, you can make the shipping price free based on the cart total:
+
+```ts highlights={workflowHighlights}
+const { result } = await createShippingOptionsWorkflow(container)
+  .run({
+    input: [{
+      name: "Standard Shipping",
+      service_zone_id: "serzo_123",
+      shipping_profile_id: "sp_123",
+      provider_id: "prov_123",
+      type: {
+        label: "Standard",
+        description: "Standard shipping",
+        code: "standard",
+      },
+      price_type: "flat",
+      prices: [
+        // default price
+        {
+          currency_code: "usd",
+          amount: 10,
+          rules: {},
+        },
+        // price if cart total >= $100
+        {
+          currency_code: "usd",
+          amount: 0,
+          rules: {
+            item_total: {
+              operator: "gte",
+              value: 100,
+            },
+          },
+        },
+      ],
+    }],
+  })
+```
+
+In this example, you create a shipping option whose default price is `$10`. When the total of the cart or order using this shipping option is greater than `$100`, the shipping option's price becomes free.
+
+### Using Pricing Module's Service
+
+For most use cases, it's recommended to use [workflows](#using-workflows) instead of directly using the module's service.
+
+When adding a price using the [addPrices](https://docs.medusajs.com/resources/references/pricing/addPrices/index.html.md) method of the Pricing Module's service, pass the `rules` property to a price object.
+
+For example:
+
+```ts
+const priceSet = await pricingModule.addPrices({
+  priceSetId: "pset_1",
+  prices: [
+    // default price
+    {
+      currency_code: "usd",
+      amount: 10,
+      rules: {},
+    },
+    // price if cart total >= $100
+    {
+      currency_code: "usd",
+      amount: 0,
+      rules: {
+        item_total: {
+          operator: "gte",
+          value: 100,
+        },
+      },
+    },
+  ],
+})
+```
+
+In this example, you set the default price of a resource (for example, a shipping option), to `$10`. You also add a conditioned price that sets the price to `0` when the cart or order's total is greater than or equal to `$100`.
+
+### How is the Price Rule Applied?
+
+The [price calculation](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/pricing/price-calculation/index.html.md) mechanism considers a price applicable when the resource that this price is in matches the specified rules.
+
+For example, a [cart object](https://docs.medusajs.com/api/store#carts_cart_schema) has an `item_total` property. So, if a shipping option has the following price:
+
+```json
+{
+  "currency_code": "usd",
+  "amount": 0,
+  "rules": {
+    "item_total": {
+      "operator": "gte",
+      "value": 100,
+    }
+  }
+}
+```
+
+The shipping option's price is applied when the cart's `item_total` is greater than or equal to `$100`.
+
+You can also apply the rule on nested relations and properties. For example, to apply a shipping option's price based on the customer's group, you can apply a rule on the `customer.group.id` attribute:
+
+```json
+{
+  "currency_code": "usd",
+  "amount": 0,
+  "rules": {
+    "customer.group.id": {
+      "operator": "eq",
+      "value": "cusgrp_123"
+    }
+  }
+}
+```
+
+In this example, the price is only applied if a cart's customer belongs to the customer group of ID `cusgrp_123`.
+
+These same rules apply to product variant prices as well, or any other resource that has a price.
 
 
 # Tax-Inclusive Pricing
@@ -26237,6 +26192,55 @@ 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).
+
+
 # Links between Payment Module and Other Modules
 
 This document showcases the module links defined between the Payment Module and other Commerce Modules.
@@ -26583,6 +26587,61 @@ createRemoteLinkStep({
 ```
 
 
+# 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.
+
+
 # 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.
@@ -26750,59 +26809,39 @@ You can then:
 Some payment providers allow capturing the payment automatically once it’s authorized. In that case, you don’t need to do it manually.
 
 
-# Payment Module Options
+# Payment
 
-In this document, you'll learn about the options of the Payment Module.
+In this document, you’ll learn what a payment is and how it's created, captured, and refunded.
 
-## All Module Options
+## What's a Payment?
 
-|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|-|
+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.
 
 ***
 
-## providers Option
+## Capture Payments
 
-The `providers` option is an array of payment module providers.
+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.
 
-When the Medusa application starts, these providers are registered and can be used to process payments.
+The payment can also be captured incrementally, each time a capture record is created for that amount.
 
-For example:
+![A diagram showcasing how a payment's multiple captures are stored](https://res.cloudinary.com/dza7lstvk/image/upload/v1711565445/Medusa%20Resources/payment-capture_f5fve1.jpg)
 
-```ts title="medusa-config.ts"
-import { Modules } from "@medusajs/framework/utils"
+***
 
-// ...
+## Refund Payments
 
-module.exports = defineConfig({
-  // ...
-  modules: [
-    {
-      resolve: "@medusajs/medusa/payment",
-      options: {
-        providers: [
-          {
-            resolve: "@medusajs/medusa/payment-stripe",
-            id: "stripe",
-            options: {
-              // ...
-            },
-          },
-        ],
-      },
-    },
-  ],
-})
-```
+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.
 
-The `providers` option is an array of objects that accept the following properties:
+A payment can be refunded multiple times, and each time a refund record is created.
 
-- `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.
+![A diagram showcasing how a payment's multiple refunds are stored](https://res.cloudinary.com/dza7lstvk/image/upload/v1711565555/Medusa%20Resources/payment-refund_lgfvyy.jpg)
 
 
 # Payment Collection
@@ -26842,41 +26881,6 @@ It also implements the payment flow during checkout as explained in [this docume
 ![Diagram showcasing the relation between the Payment and Cart modules](https://res.cloudinary.com/dza7lstvk/image/upload/v1711537849/Medusa%20Resources/cart-payment_ixziqm.jpg)
 
 
-# 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.
-
-![A diagram showcasing how a payment's multiple captures are stored](https://res.cloudinary.com/dza7lstvk/image/upload/v1711565445/Medusa%20Resources/payment-capture_f5fve1.jpg)
-
-***
-
-## 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.
-
-![A diagram showcasing how a payment's multiple refunds are stored](https://res.cloudinary.com/dza7lstvk/image/upload/v1711565555/Medusa%20Resources/payment-refund_lgfvyy.jpg)
-
-
 # Payment Module Provider
 
 In this document, you’ll learn what a payment module provider is.
@@ -26928,6 +26932,39 @@ When the Medusa application starts and registers the payment providers, it also
 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.
+
+![Diagram showcasing how every payment session has a different payment provider](https://res.cloudinary.com/dza7lstvk/image/upload/v1711565056/Medusa%20Resources/payment-session-provider_guxzqt.jpg)
+
+***
+
+## 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.
+
+
 # Webhook Events
 
 In this document, you’ll learn how the Payment Module supports listening to webhook events.
@@ -26964,76 +27001,385 @@ If the event's details indicate that the payment should be captured, then the [c
 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.
 
 
-# Payment Session
+# Promotion Actions
 
-In this document, you’ll learn what a payment session is.
+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).
 
-## What's a Payment Session?
+## computeActions Method
 
-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.
+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.
 
-A payment collection can have multiple payment sessions. Using this feature, you can implement payment in installments or payments using multiple providers.
-
-![Diagram showcasing how every payment session has a different payment provider](https://res.cloudinary.com/dza7lstvk/image/upload/v1711565056/Medusa%20Resources/payment-session-provider_guxzqt.jpg)
+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.
 
 ***
 
-## data Property
+## Action Types
 
-Payment providers may need additional data to process the payment later. The `PaymentSession` data model has a `data` property used to store that data.
+### `addItemAdjustment` Action
 
-For example, the customer's ID in Stripe is stored in the `data` property.
+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.
+
+![A diagram showcasing the target\_rules relation between the ApplicationMethod and PromotionRule data models](https://res.cloudinary.com/dza7lstvk/image/upload/v1709898273/Medusa%20Resources/application-method-target-rules_hqaymz.jpg)
+
+In this example, the promotion is only applied on products in the cart having the SKU `SHIRT`.
 
 ***
 
-## Payment Session Status
+## Buy Promotion Rules
 
-The `status` property of a payment session indicates its current status. Its value can be:
+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.
 
-- `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 application method has a collection of `PromotionRule` items to define the “buy X” rule. The `buy_rules` property represents this relation.
+
+![A diagram showcasing the buy\_rules relation between the ApplicationMethod and PromotionRule data models](https://res.cloudinary.com/dza7lstvk/image/upload/v1709898453/Medusa%20Resources/application-method-buy-rules_djjuhw.jpg)
+
+In this example, the cart must have two products with the SKU `SHIRT` for the promotion to be applied.
 
 
-# Links between Region Module and Other Modules
+# Campaign
 
-This document showcases the module links defined between the Region Module and other Commerce Modules.
+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.
+
+![A diagram showcasing the relation between the Campaign and Promotion data models](https://res.cloudinary.com/dza7lstvk/image/upload/v1709899225/Medusa%20Resources/campagin-promotion_hh3qsi.jpg)
+
+***
+
+## 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.
+
+![A diagram showcasing the relation between the Campaign and CampaignBudget data models](https://res.cloudinary.com/dza7lstvk/image/upload/v1709899463/Medusa%20Resources/campagin-budget_rvqlmi.jpg)
+
+
+# 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 diagram showcasing the relation between Promotion and PromotionRule](https://res.cloudinary.com/dza7lstvk/image/upload/v1709833196/Medusa%20Resources/promotion-promotion-rule_msbx0w.jpg)
+
+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`.
+
+![A diagram showcasing the relation between PromotionRule and PromotionRuleValue when a rule has multiple values](https://res.cloudinary.com/dza7lstvk/image/upload/v1709897383/Medusa%20Resources/promotion-promotion-rule-multiple_hctpmt.jpg)
+
+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 Region Module has the following links to other modules:
+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|
 |---|---|---|---|
+| in ||Stored - many-to-many||
 | in ||Read-only - has one||
-| in ||Read-only - has one||
-|| in |Stored - many-to-many||
+| in ||Stored - many-to-many||
 
 ***
 
 ## 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 `Region` data model. Because the link is read-only from the `Cart`'s side, you can only retrieve the region of a cart, and not the other way around.
+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.
+
+![A diagram showcasing an example of how data models from the Cart and Promotion modules are linked](https://res.cloudinary.com/dza7lstvk/image/upload/v1711538015/Medusa%20Resources/cart-promotion_kuh9vm.jpg)
+
+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 region of a cart with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `region.*` in `fields`:
+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: carts } = await query.graph({
-  entity: "cart",
+const { data: promotions } = await query.graph({
+  entity: "promotion",
   fields: [
-    "region.*",
+    "carts.*",
   ],
 })
 
-// carts[0].region
+// promotions[0].carts
 ```
 
 ### useQueryGraphStep
@@ -27043,103 +27389,19 @@ import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
 
 // ...
 
-const { data: carts } = useQueryGraphStep({
-  entity: "cart",
+const { data: promotions } = useQueryGraphStep({
+  entity: "promotion",
   fields: [
-    "region.*",
+    "carts.*",
   ],
 })
 
-// carts[0].region
-```
-
-***
-
-## 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 `Region` data model. Because the link is read-only from the `Order`'s side, you can only retrieve the region of an order, and not the other way around.
-
-### Retrieve with Query
-
-To retrieve the region of an order with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `region.*` in `fields`:
-
-### query.graph
-
-```ts
-const { data: orders } = await query.graph({
-  entity: "order",
-  fields: [
-    "region.*",
-  ],
-})
-
-// orders[0].region
-```
-
-### useQueryGraphStep
-
-```ts
-import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
-
-// ...
-
-const { data: orders } = useQueryGraphStep({
-  entity: "order",
-  fields: [
-    "region.*",
-  ],
-})
-
-// orders[0].region
-```
-
-***
-
-## Payment Module
-
-You can specify for each region which payment providers are available for use.
-
-Medusa defines a module link between the `PaymentProvider` and the `Region` data models.
-
-![A diagram showcasing an example of how resources from the Payment and Region modules are linked](https://res.cloudinary.com/dza7lstvk/image/upload/v1711569520/Medusa%20Resources/payment-region_jyo2dz.jpg)
-
-### Retrieve with Query
-
-To retrieve the payment providers of a region with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `payment_providers.*` in `fields`:
-
-### query.graph
-
-```ts
-const { data: regions } = await query.graph({
-  entity: "region",
-  fields: [
-    "payment_providers.*",
-  ],
-})
-
-// regions[0].payment_providers
-```
-
-### useQueryGraphStep
-
-```ts
-import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
-
-// ...
-
-const { data: regions } = useQueryGraphStep({
-  entity: "region",
-  fields: [
-    "payment_providers.*",
-  ],
-})
-
-// regions[0].payment_providers
+// promotions[0].carts
 ```
 
 ### 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):
+To manage the promotions of a cart, use [Link](https://docs.medusajs.com/docs/learn/fundamentals/module-links/link/index.html.md):
 
 ### link.create
 
@@ -27149,11 +27411,11 @@ import { Modules } from "@medusajs/framework/utils"
 // ...
 
 await link.create({
-  [Modules.REGION]: {
-    region_id: "reg_123",
+  [Modules.CART]: {
+    cart_id: "cart_123",
   },
-  [Modules.PAYMENT]: {
-    payment_provider_id: "pp_stripe_stripe",
+  [Modules.PROMOTION]: {
+    promotion_id: "promo_123",
   },
 })
 ```
@@ -27167,15 +27429,468 @@ import { createRemoteLinkStep } from "@medusajs/medusa/core-flows"
 // ...
 
 createRemoteLinkStep({
-  [Modules.REGION]: {
-    region_id: "reg_123",
+  [Modules.CART]: {
+    cart_id: "cart_123",
   },
-  [Modules.PAYMENT]: {
-    payment_provider_id: "pp_stripe_stripe",
+  [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.
+
+![A diagram showcasing an example of how data models from the Order and Promotion modules are linked](https://res.cloudinary.com/dza7lstvk/image/upload/v1716555015/Medusa%20Resources/order-promotion_dgjzzd.jpg)
+
+### 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",
+  },
+})
+```
+
+
+# Links between Sales Channel Module and Other Modules
+
+This document showcases the module links defined between the Sales Channel Module and other Commerce Modules.
+
+## Summary
+
+The Sales Channel 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|
+|---|---|---|---|
+| in ||Stored - many-to-many||
+| in ||Read-only - has one||
+| in ||Read-only - has one||
+| in ||Stored - many-to-many||
+|| in |Stored - many-to-many||
+
+***
+
+## API Key Module
+
+A publishable API key allows you to easily specify the sales channel scope in a client request.
+
+Medusa defines a link between the `ApiKey` and the `SalesChannel` data models.
+
+![A diagram showcasing an example of how resources from the Sales Channel and API Key modules are linked](https://res.cloudinary.com/dza7lstvk/image/upload/v1709812064/Medusa%20Resources/sales-channel-api-key_zmqi2l.jpg)
+
+### Retrieve with Query
+
+To retrieve the API keys associated with a sales channel with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `publishable_api_keys.*` in `fields`:
+
+### query.graph
+
+```ts
+const { data: salesChannels } = await query.graph({
+  entity: "sales_channel",
+  fields: [
+    "publishable_api_keys.*",
+  ],
+})
+
+// salesChannels[0].publishable_api_keys
+```
+
+### useQueryGraphStep
+
+```ts
+import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
+
+// ...
+
+const { data: salesChannels } = useQueryGraphStep({
+  entity: "sales_channel",
+  fields: [
+    "publishable_api_keys.*",
+  ],
+})
+
+// salesChannels[0].publishable_api_keys
+```
+
+### Manage with Link
+
+To manage the sales channels of an API key, 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.API_KEY]: {
+    publishable_key_id: "apk_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.API_KEY]: {
+    publishable_key_id: "apk_123",
+  },
+  [Modules.SALES_CHANNEL]: {
+    sales_channel_id: "sc_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 `SalesChannel` data model. Because the link is read-only from the `Cart`'s side, you can only retrieve the sales channel of a cart, and not the other way around.
+
+### Retrieve with Query
+
+To retrieve the sales channel of a cart with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `sales_channel.*` in `fields`:
+
+### query.graph
+
+```ts
+const { data: carts } = await query.graph({
+  entity: "cart",
+  fields: [
+    "sales_channel.*",
+  ],
+})
+
+// carts[0].sales_channel
+```
+
+### useQueryGraphStep
+
+```ts
+import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
+
+// ...
+
+const { data: carts } = useQueryGraphStep({
+  entity: "cart",
+  fields: [
+    "sales_channel.*",
+  ],
+})
+
+// carts[0].sales_channel
+```
+
+***
+
+## 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 `SalesChannel` data model. Because the link is read-only from the `Order`'s side, you can only retrieve the sales channel of an order, and not the other way around.
+
+### Retrieve with Query
+
+To retrieve the sales channel of an order with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `sales_channel.*` in `fields`:
+
+### query.graph
+
+```ts
+const { data: orders } = await query.graph({
+  entity: "order",
+  fields: [
+    "sales_channel.*",
+  ],
+})
+
+// orders.sales_channel
+```
+
+### useQueryGraphStep
+
+```ts
+import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
+
+// ...
+
+const { data: orders } = useQueryGraphStep({
+  entity: "order",
+  fields: [
+    "sales_channel.*",
+  ],
+})
+
+// orders.sales_channel
+```
+
+***
+
+## Product Module
+
+A product has different availability for different sales channels. Medusa defines a link between the `Product` and the `SalesChannel` data models.
+
+![A diagram showcasing an example of how resources from the Sales Channel and Product modules are linked](https://res.cloudinary.com/dza7lstvk/image/upload/v1709809833/Medusa%20Resources/product-sales-channel_t848ik.jpg)
+
+A product can be available in more than one sales channel. You can retrieve only the products of a sales channel.
+
+### Retrieve with Query
+
+To retrieve the products of a sales channel with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `products.*` in `fields`:
+
+### query.graph
+
+```ts
+const { data: salesChannels } = await query.graph({
+  entity: "sales_channel",
+  fields: [
+    "products.*",
+  ],
+})
+
+// salesChannels[0].products
+```
+
+### useQueryGraphStep
+
+```ts
+import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
+
+// ...
+
+const { data: salesChannels } = useQueryGraphStep({
+  entity: "sales_channel",
+  fields: [
+    "products.*",
+  ],
+})
+
+// salesChannels[0].products
+```
+
+### 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",
+  },
+})
+```
+
+***
+
+## Stock Location Module
+
+A stock location is associated with a sales channel. This scopes inventory quantities associated with that stock location by the associated sales channel.
+
+Medusa defines a link between the `SalesChannel` and `StockLocation` data models.
+
+![A diagram showcasing an example of how resources from the Sales Channel and Stock Location modules are linked](https://res.cloudinary.com/dza7lstvk/image/upload/v1716796872/Medusa%20Resources/sales-channel-location_cqrih1.jpg)
+
+### Retrieve with Query
+
+To retrieve the stock locations of a sales channel 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: salesChannels } = await query.graph({
+  entity: "sales_channel",
+  fields: [
+    "stock_locations.*",
+  ],
+})
+
+// salesChannels[0].stock_locations
+```
+
+### useQueryGraphStep
+
+```ts
+import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
+
+// ...
+
+const { data: salesChannels } = useQueryGraphStep({
+  entity: "sales_channel",
+  fields: [
+    "stock_locations.*",
+  ],
+})
+
+// salesChannels[0].stock_locations
+```
+
+### 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.
+
+## Publishable API Keys with Sales Channels
+
+A publishable API key, provided by the API Key Module, is a client key scoped to one or more sales channels.
+
+When sending a request to a Store API route, you must pass a publishable API key in the header of the request:
+
+```bash
+curl http://localhost:9000/store/products \
+  x-publishable-api-key: {your_publishable_api_key}
+```
+
+The Medusa application infers the associated sales channels and ensures that only data relevant to the sales channel are used.
+
+***
+
+## How to Create a Publishable API Key?
+
+To create a publishable API key, either use the [Medusa Admin](https://docs.medusajs.com/user-guide/settings/developer/publishable-api-keys/index.html.md) or the [Admin API Routes](https://docs.medusajs.com/api/admin#publishable-api-keys).
+
 
 # Links between Product Module and Other Modules
 
@@ -27740,659 +28455,31 @@ The following guides provide more details on inventory management in the Medusa
 - [Storefront guide: how to retrieve a product variant's inventory details](https://docs.medusajs.com/resources/storefront-development/products/inventory/index.html.md).
 
 
-# Application Method
+# Links between Region Module and Other Modules
 
-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.
-
-![A diagram showcasing the target\_rules relation between the ApplicationMethod and PromotionRule data models](https://res.cloudinary.com/dza7lstvk/image/upload/v1709898273/Medusa%20Resources/application-method-target-rules_hqaymz.jpg)
-
-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.
-
-![A diagram showcasing the buy\_rules relation between the ApplicationMethod and PromotionRule data models](https://res.cloudinary.com/dza7lstvk/image/upload/v1709898453/Medusa%20Resources/application-method-buy-rules_djjuhw.jpg)
-
-In this example, the cart must have two products with the SKU `SHIRT` for the promotion to be applied.
-
-
-# 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.
-
-
-# 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.
-
-![A diagram showcasing the relation between the Campaign and Promotion data models](https://res.cloudinary.com/dza7lstvk/image/upload/v1709899225/Medusa%20Resources/campagin-promotion_hh3qsi.jpg)
-
-***
-
-## 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.
-
-![A diagram showcasing the relation between the Campaign and CampaignBudget data models](https://res.cloudinary.com/dza7lstvk/image/upload/v1709899463/Medusa%20Resources/campagin-budget_rvqlmi.jpg)
-
-
-# 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 diagram showcasing the relation between Promotion and PromotionRule](https://res.cloudinary.com/dza7lstvk/image/upload/v1709833196/Medusa%20Resources/promotion-promotion-rule_msbx0w.jpg)
-
-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`.
-
-![A diagram showcasing the relation between PromotionRule and PromotionRuleValue when a rule has multiple values](https://res.cloudinary.com/dza7lstvk/image/upload/v1709897383/Medusa%20Resources/promotion-promotion-rule-multiple_hctpmt.jpg)
-
-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.
+This document showcases the module links defined between the Region Module and other Commerce Modules.
 
 ## Summary
 
-The Promotion Module has the following links to other modules:
+The Region 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|
 |---|---|---|---|
-| in ||Stored - many-to-many||
-| in ||Read-only - has one||
-| in ||Stored - many-to-many||
-
-***
-
-## 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.
-
-![A diagram showcasing an example of how data models from the Cart and Promotion modules are linked](https://res.cloudinary.com/dza7lstvk/image/upload/v1711538015/Medusa%20Resources/cart-promotion_kuh9vm.jpg)
-
-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.
-
-![A diagram showcasing an example of how data models from the Order and Promotion modules are linked](https://res.cloudinary.com/dza7lstvk/image/upload/v1716555015/Medusa%20Resources/order-promotion_dgjzzd.jpg)
-
-### 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",
-  },
-})
-```
-
-
-# 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.
-
-## Publishable API Keys with Sales Channels
-
-A publishable API key, provided by the API Key Module, is a client key scoped to one or more sales channels.
-
-When sending a request to a Store API route, you must pass a publishable API key in the header of the request:
-
-```bash
-curl http://localhost:9000/store/products \
-  x-publishable-api-key: {your_publishable_api_key}
-```
-
-The Medusa application infers the associated sales channels and ensures that only data relevant to the sales channel are used.
-
-***
-
-## How to Create a Publishable API Key?
-
-To create a publishable API key, either use the [Medusa Admin](https://docs.medusajs.com/user-guide/settings/developer/publishable-api-keys/index.html.md) or the [Admin API Routes](https://docs.medusajs.com/api/admin#publishable-api-keys).
-
-
-# Links between Sales Channel Module and Other Modules
-
-This document showcases the module links defined between the Sales Channel Module and other Commerce Modules.
-
-## Summary
-
-The Sales Channel 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|
-|---|---|---|---|
-| in ||Stored - many-to-many||
 | in ||Read-only - has one||
 | in ||Read-only - has one||
-| in ||Stored - many-to-many||
 || in |Stored - many-to-many||
 
 ***
 
-## API Key Module
-
-A publishable API key allows you to easily specify the sales channel scope in a client request.
-
-Medusa defines a link between the `ApiKey` and the `SalesChannel` data models.
-
-![A diagram showcasing an example of how resources from the Sales Channel and API Key modules are linked](https://res.cloudinary.com/dza7lstvk/image/upload/v1709812064/Medusa%20Resources/sales-channel-api-key_zmqi2l.jpg)
-
-### Retrieve with Query
-
-To retrieve the API keys associated with a sales channel with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `publishable_api_keys.*` in `fields`:
-
-### query.graph
-
-```ts
-const { data: salesChannels } = await query.graph({
-  entity: "sales_channel",
-  fields: [
-    "publishable_api_keys.*",
-  ],
-})
-
-// salesChannels[0].publishable_api_keys
-```
-
-### useQueryGraphStep
-
-```ts
-import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
-
-// ...
-
-const { data: salesChannels } = useQueryGraphStep({
-  entity: "sales_channel",
-  fields: [
-    "publishable_api_keys.*",
-  ],
-})
-
-// salesChannels[0].publishable_api_keys
-```
-
-### Manage with Link
-
-To manage the sales channels of an API key, 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.API_KEY]: {
-    publishable_key_id: "apk_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.API_KEY]: {
-    publishable_key_id: "apk_123",
-  },
-  [Modules.SALES_CHANNEL]: {
-    sales_channel_id: "sc_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 `SalesChannel` data model. Because the link is read-only from the `Cart`'s side, you can only retrieve the sales channel of a cart, and not the other way around.
+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 `Region` data model. Because the link is read-only from the `Cart`'s side, you can only retrieve the region of a cart, and not the other way around.
 
 ### Retrieve with Query
 
-To retrieve the sales channel of a cart with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `sales_channel.*` in `fields`:
+To retrieve the region of a cart with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `region.*` in `fields`:
 
 ### query.graph
 
@@ -28400,11 +28487,11 @@ To retrieve the sales channel of a cart with [Query](https://docs.medusajs.com/d
 const { data: carts } = await query.graph({
   entity: "cart",
   fields: [
-    "sales_channel.*",
+    "region.*",
   ],
 })
 
-// carts[0].sales_channel
+// carts[0].region
 ```
 
 ### useQueryGraphStep
@@ -28417,22 +28504,22 @@ import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
 const { data: carts } = useQueryGraphStep({
   entity: "cart",
   fields: [
-    "sales_channel.*",
+    "region.*",
   ],
 })
 
-// carts[0].sales_channel
+// carts[0].region
 ```
 
 ***
 
 ## 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 `SalesChannel` data model. Because the link is read-only from the `Order`'s side, you can only retrieve the sales channel of an order, and not the other way around.
+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 `Region` data model. Because the link is read-only from the `Order`'s side, you can only retrieve the region of an order, and not the other way around.
 
 ### Retrieve with Query
 
-To retrieve the sales channel of an order with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `sales_channel.*` in `fields`:
+To retrieve the region of an order with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `region.*` in `fields`:
 
 ### query.graph
 
@@ -28440,11 +28527,11 @@ To retrieve the sales channel of an order with [Query](https://docs.medusajs.com
 const { data: orders } = await query.graph({
   entity: "order",
   fields: [
-    "sales_channel.*",
+    "region.*",
   ],
 })
 
-// orders.sales_channel
+// orders[0].region
 ```
 
 ### useQueryGraphStep
@@ -28457,38 +28544,38 @@ import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
 const { data: orders } = useQueryGraphStep({
   entity: "order",
   fields: [
-    "sales_channel.*",
+    "region.*",
   ],
 })
 
-// orders.sales_channel
+// orders[0].region
 ```
 
 ***
 
-## Product Module
+## Payment Module
 
-A product has different availability for different sales channels. Medusa defines a link between the `Product` and the `SalesChannel` data models.
+You can specify for each region which payment providers are available for use.
 
-![A diagram showcasing an example of how resources from the Sales Channel and Product modules are linked](https://res.cloudinary.com/dza7lstvk/image/upload/v1709809833/Medusa%20Resources/product-sales-channel_t848ik.jpg)
+Medusa defines a module link between the `PaymentProvider` and the `Region` data models.
 
-A product can be available in more than one sales channel. You can retrieve only the products of a sales channel.
+![A diagram showcasing an example of how resources from the Payment and Region modules are linked](https://res.cloudinary.com/dza7lstvk/image/upload/v1711569520/Medusa%20Resources/payment-region_jyo2dz.jpg)
 
 ### Retrieve with Query
 
-To retrieve the products of a sales channel with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `products.*` in `fields`:
+To retrieve the payment providers of a region with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `payment_providers.*` in `fields`:
 
 ### query.graph
 
 ```ts
-const { data: salesChannels } = await query.graph({
-  entity: "sales_channel",
+const { data: regions } = await query.graph({
+  entity: "region",
   fields: [
-    "products.*",
+    "payment_providers.*",
   ],
 })
 
-// salesChannels[0].products
+// regions[0].payment_providers
 ```
 
 ### useQueryGraphStep
@@ -28498,19 +28585,19 @@ import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
 
 // ...
 
-const { data: salesChannels } = useQueryGraphStep({
-  entity: "sales_channel",
+const { data: regions } = useQueryGraphStep({
+  entity: "region",
   fields: [
-    "products.*",
+    "payment_providers.*",
   ],
 })
 
-// salesChannels[0].products
+// regions[0].payment_providers
 ```
 
 ### 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):
+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
 
@@ -28520,11 +28607,11 @@ import { Modules } from "@medusajs/framework/utils"
 // ...
 
 await link.create({
-  [Modules.PRODUCT]: {
-    product_id: "prod_123",
+  [Modules.REGION]: {
+    region_id: "reg_123",
   },
-  [Modules.SALES_CHANNEL]: {
-    sales_channel_id: "sc_123",
+  [Modules.PAYMENT]: {
+    payment_provider_id: "pp_stripe_stripe",
   },
 })
 ```
@@ -28538,94 +28625,11 @@ import { createRemoteLinkStep } from "@medusajs/medusa/core-flows"
 // ...
 
 createRemoteLinkStep({
-  [Modules.PRODUCT]: {
-    product_id: "prod_123",
+  [Modules.REGION]: {
+    region_id: "reg_123",
   },
-  [Modules.SALES_CHANNEL]: {
-    sales_channel_id: "sc_123",
-  },
-})
-```
-
-***
-
-## Stock Location Module
-
-A stock location is associated with a sales channel. This scopes inventory quantities associated with that stock location by the associated sales channel.
-
-Medusa defines a link between the `SalesChannel` and `StockLocation` data models.
-
-![A diagram showcasing an example of how resources from the Sales Channel and Stock Location modules are linked](https://res.cloudinary.com/dza7lstvk/image/upload/v1716796872/Medusa%20Resources/sales-channel-location_cqrih1.jpg)
-
-### Retrieve with Query
-
-To retrieve the stock locations of a sales channel 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: salesChannels } = await query.graph({
-  entity: "sales_channel",
-  fields: [
-    "stock_locations.*",
-  ],
-})
-
-// salesChannels[0].stock_locations
-```
-
-### useQueryGraphStep
-
-```ts
-import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
-
-// ...
-
-const { data: salesChannels } = useQueryGraphStep({
-  entity: "sales_channel",
-  fields: [
-    "stock_locations.*",
-  ],
-})
-
-// salesChannels[0].stock_locations
-```
-
-### 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",
+  [Modules.PAYMENT]: {
+    payment_provider_id: "pp_stripe_stripe",
   },
 })
 ```
@@ -29055,6 +29059,21 @@ TODO add once tax provider guide is updated + add module providers match other m
 Refer to [this guide](/modules/tax/provider) to learn more about creating a tax provider. */}
 
 
+# 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.
+
+
 # Tax Rates and Rules
 
 In this document, you’ll learn about tax rates and rules.
@@ -29093,21 +29112,6 @@ These two properties of the data model identify the rule’s target:
 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.
-
-
 # User Module Options
 
 In this document, you'll learn about the options of the User Module.
@@ -29833,238 +29837,244 @@ For each product variant, you:
 
 ## Workflows
 
-- [createApiKeysWorkflow](https://docs.medusajs.com/references/medusa-workflows/createApiKeysWorkflow/index.html.md)
 - [linkSalesChannelsToApiKeyWorkflow](https://docs.medusajs.com/references/medusa-workflows/linkSalesChannelsToApiKeyWorkflow/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)
+- [createApiKeysWorkflow](https://docs.medusajs.com/references/medusa-workflows/createApiKeysWorkflow/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)
 - [generateResetPasswordTokenWorkflow](https://docs.medusajs.com/references/medusa-workflows/generateResetPasswordTokenWorkflow/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)
-- [deleteCustomersWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteCustomersWorkflow/index.html.md)
-- [deleteCustomerAddressesWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteCustomerAddressesWorkflow/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)
-- [updateCustomerAddressesWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateCustomerAddressesWorkflow/index.html.md)
-- [createCustomersWorkflow](https://docs.medusajs.com/references/medusa-workflows/createCustomersWorkflow/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)
 - [batchLinksWorkflow](https://docs.medusajs.com/references/medusa-workflows/batchLinksWorkflow/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)
-- [updateCustomerGroupsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateCustomerGroupsWorkflow/index.html.md)
-- [linkCustomersToCustomerGroupWorkflow](https://docs.medusajs.com/references/medusa-workflows/linkCustomersToCustomerGroupWorkflow/index.html.md)
-- [linkCustomerGroupsToCustomerWorkflow](https://docs.medusajs.com/references/medusa-workflows/linkCustomerGroupsToCustomerWorkflow/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)
+- [updateLinksWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateLinksWorkflow/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)
+- [confirmVariantInventoryWorkflow](https://docs.medusajs.com/references/medusa-workflows/confirmVariantInventoryWorkflow/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)
+- [listShippingOptionsForCartWorkflow](https://docs.medusajs.com/references/medusa-workflows/listShippingOptionsForCartWorkflow/index.html.md)
+- [refreshCartItemsWorkflow](https://docs.medusajs.com/references/medusa-workflows/refreshCartItemsWorkflow/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)
+- [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)
+- [updateTaxLinesWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateTaxLinesWorkflow/index.html.md)
+- [validateExistingPaymentCollectionStep](https://docs.medusajs.com/references/medusa-workflows/validateExistingPaymentCollectionStep/index.html.md)
 - [createDefaultsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createDefaultsWorkflow/index.html.md)
 - [addDraftOrderItemsWorkflow](https://docs.medusajs.com/references/medusa-workflows/addDraftOrderItemsWorkflow/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)
+- [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)
-- [removeDraftOrderActionItemWorkflow](https://docs.medusajs.com/references/medusa-workflows/removeDraftOrderActionItemWorkflow/index.html.md)
 - [cancelDraftOrderEditWorkflow](https://docs.medusajs.com/references/medusa-workflows/cancelDraftOrderEditWorkflow/index.html.md)
-- [removeDraftOrderPromotionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/removeDraftOrderPromotionsWorkflow/index.html.md)
+- [convertDraftOrderWorkflow](https://docs.medusajs.com/references/medusa-workflows/convertDraftOrderWorkflow/index.html.md)
+- [convertDraftOrderStep](https://docs.medusajs.com/references/medusa-workflows/convertDraftOrderStep/index.html.md)
+- [removeDraftOrderActionItemWorkflow](https://docs.medusajs.com/references/medusa-workflows/removeDraftOrderActionItemWorkflow/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)
-- [updateDraftOrderActionItemWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateDraftOrderActionItemWorkflow/index.html.md)
-- [updateDraftOrderActionShippingMethodWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateDraftOrderActionShippingMethodWorkflow/index.html.md)
+- [removeDraftOrderPromotionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/removeDraftOrderPromotionsWorkflow/index.html.md)
 - [removeDraftOrderShippingMethodWorkflow](https://docs.medusajs.com/references/medusa-workflows/removeDraftOrderShippingMethodWorkflow/index.html.md)
-- [updateDraftOrderItemWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateDraftOrderItemWorkflow/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)
-- [updateDraftOrderWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateDraftOrderWorkflow/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)
+- [updateDraftOrderWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateDraftOrderWorkflow/index.html.md)
 - [deleteFilesWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteFilesWorkflow/index.html.md)
 - [uploadFilesWorkflow](https://docs.medusajs.com/references/medusa-workflows/uploadFilesWorkflow/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)
-- [deleteInvitesWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteInvitesWorkflow/index.html.md)
-- [refreshInviteTokensWorkflow](https://docs.medusajs.com/references/medusa-workflows/refreshInviteTokensWorkflow/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)
-- [createInventoryLevelsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createInventoryLevelsWorkflow/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)
-- [deleteInventoryLevelsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteInventoryLevelsWorkflow/index.html.md)
-- [updateInventoryLevelsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateInventoryLevelsWorkflow/index.html.md)
 - [updateInventoryItemsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateInventoryItemsWorkflow/index.html.md)
+- [updateInventoryLevelsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateInventoryLevelsWorkflow/index.html.md)
+- [deleteInventoryLevelsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteInventoryLevelsWorkflow/index.html.md)
 - [validateInventoryLevelsDelete](https://docs.medusajs.com/references/medusa-workflows/validateInventoryLevelsDelete/index.html.md)
-- [deleteLineItemsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteLineItemsWorkflow/index.html.md)
 - [batchShippingOptionRulesWorkflow](https://docs.medusajs.com/references/medusa-workflows/batchShippingOptionRulesWorkflow/index.html.md)
-- [cancelFulfillmentWorkflow](https://docs.medusajs.com/references/medusa-workflows/cancelFulfillmentWorkflow/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)
+- [cancelFulfillmentWorkflow](https://docs.medusajs.com/references/medusa-workflows/cancelFulfillmentWorkflow/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)
 - [createShipmentWorkflow](https://docs.medusajs.com/references/medusa-workflows/createShipmentWorkflow/index.html.md)
+- [createServiceZonesWorkflow](https://docs.medusajs.com/references/medusa-workflows/createServiceZonesWorkflow/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)
-- [deleteFulfillmentSetsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteFulfillmentSetsWorkflow/index.html.md)
 - [createShippingProfilesWorkflow](https://docs.medusajs.com/references/medusa-workflows/createShippingProfilesWorkflow/index.html.md)
+- [deleteFulfillmentSetsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteFulfillmentSetsWorkflow/index.html.md)
+- [deleteServiceZonesWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteServiceZonesWorkflow/index.html.md)
 - [deleteShippingOptionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteShippingOptionsWorkflow/index.html.md)
 - [markFulfillmentAsDeliveredWorkflow](https://docs.medusajs.com/references/medusa-workflows/markFulfillmentAsDeliveredWorkflow/index.html.md)
 - [updateFulfillmentWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateFulfillmentWorkflow/index.html.md)
-- [deleteServiceZonesWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteServiceZonesWorkflow/index.html.md)
 - [updateServiceZonesWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateServiceZonesWorkflow/index.html.md)
-- [updateShippingOptionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateShippingOptionsWorkflow/index.html.md)
 - [updateShippingProfilesWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateShippingProfilesWorkflow/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)
-- [capturePaymentWorkflow](https://docs.medusajs.com/references/medusa-workflows/capturePaymentWorkflow/index.html.md)
-- [refundPaymentWorkflow](https://docs.medusajs.com/references/medusa-workflows/refundPaymentWorkflow/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)
-- [refundPaymentsWorkflow](https://docs.medusajs.com/references/medusa-workflows/refundPaymentsWorkflow/index.html.md)
-- [validateRefundStep](https://docs.medusajs.com/references/medusa-workflows/validateRefundStep/index.html.md)
-- [createRefundReasonsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createRefundReasonsWorkflow/index.html.md)
+- [deleteLineItemsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteLineItemsWorkflow/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)
+- [deleteInvitesWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteInvitesWorkflow/index.html.md)
+- [refreshInviteTokensWorkflow](https://docs.medusajs.com/references/medusa-workflows/refreshInviteTokensWorkflow/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)
 - [deletePaymentSessionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deletePaymentSessionsWorkflow/index.html.md)
-- [updateRefundReasonsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateRefundReasonsWorkflow/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)
+- [capturePaymentWorkflow](https://docs.medusajs.com/references/medusa-workflows/capturePaymentWorkflow/index.html.md)
+- [processPaymentWorkflow](https://docs.medusajs.com/references/medusa-workflows/processPaymentWorkflow/index.html.md)
+- [refundPaymentsWorkflow](https://docs.medusajs.com/references/medusa-workflows/refundPaymentsWorkflow/index.html.md)
+- [validatePaymentsRefundStep](https://docs.medusajs.com/references/medusa-workflows/validatePaymentsRefundStep/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)
 - [acceptOrderTransferValidationStep](https://docs.medusajs.com/references/medusa-workflows/acceptOrderTransferValidationStep/index.html.md)
 - [acceptOrderTransferWorkflow](https://docs.medusajs.com/references/medusa-workflows/acceptOrderTransferWorkflow/index.html.md)
 - [addOrderLineItemsWorkflow](https://docs.medusajs.com/references/medusa-workflows/addOrderLineItemsWorkflow/index.html.md)
-- [archiveOrderWorkflow](https://docs.medusajs.com/references/medusa-workflows/archiveOrderWorkflow/index.html.md)
-- [beginClaimOrderValidationStep](https://docs.medusajs.com/references/medusa-workflows/beginClaimOrderValidationStep/index.html.md)
 - [beginClaimOrderWorkflow](https://docs.medusajs.com/references/medusa-workflows/beginClaimOrderWorkflow/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)
-- [beginOrderEditValidationStep](https://docs.medusajs.com/references/medusa-workflows/beginOrderEditValidationStep/index.html.md)
-- [beginOrderExchangeValidationStep](https://docs.medusajs.com/references/medusa-workflows/beginOrderExchangeValidationStep/index.html.md)
-- [beginReceiveReturnValidationStep](https://docs.medusajs.com/references/medusa-workflows/beginReceiveReturnValidationStep/index.html.md)
 - [beginOrderEditOrderWorkflow](https://docs.medusajs.com/references/medusa-workflows/beginOrderEditOrderWorkflow/index.html.md)
+- [beginOrderExchangeValidationStep](https://docs.medusajs.com/references/medusa-workflows/beginOrderExchangeValidationStep/index.html.md)
+- [beginOrderEditValidationStep](https://docs.medusajs.com/references/medusa-workflows/beginOrderEditValidationStep/index.html.md)
+- [beginClaimOrderValidationStep](https://docs.medusajs.com/references/medusa-workflows/beginClaimOrderValidationStep/index.html.md)
+- [beginReceiveReturnValidationStep](https://docs.medusajs.com/references/medusa-workflows/beginReceiveReturnValidationStep/index.html.md)
 - [beginReturnOrderValidationStep](https://docs.medusajs.com/references/medusa-workflows/beginReturnOrderValidationStep/index.html.md)
 - [beginReceiveReturnWorkflow](https://docs.medusajs.com/references/medusa-workflows/beginReceiveReturnWorkflow/index.html.md)
 - [cancelBeginOrderClaimValidationStep](https://docs.medusajs.com/references/medusa-workflows/cancelBeginOrderClaimValidationStep/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)
-- [cancelBeginOrderEditWorkflow](https://docs.medusajs.com/references/medusa-workflows/cancelBeginOrderEditWorkflow/index.html.md)
-- [cancelBeginOrderExchangeValidationStep](https://docs.medusajs.com/references/medusa-workflows/cancelBeginOrderExchangeValidationStep/index.html.md)
 - [cancelBeginOrderEditValidationStep](https://docs.medusajs.com/references/medusa-workflows/cancelBeginOrderEditValidationStep/index.html.md)
-- [cancelExchangeValidateOrder](https://docs.medusajs.com/references/medusa-workflows/cancelExchangeValidateOrder/index.html.md)
+- [cancelBeginOrderExchangeValidationStep](https://docs.medusajs.com/references/medusa-workflows/cancelBeginOrderExchangeValidationStep/index.html.md)
+- [cancelBeginOrderEditWorkflow](https://docs.medusajs.com/references/medusa-workflows/cancelBeginOrderEditWorkflow/index.html.md)
 - [cancelClaimValidateOrderStep](https://docs.medusajs.com/references/medusa-workflows/cancelClaimValidateOrderStep/index.html.md)
+- [cancelExchangeValidateOrder](https://docs.medusajs.com/references/medusa-workflows/cancelExchangeValidateOrder/index.html.md)
 - [cancelBeginOrderExchangeWorkflow](https://docs.medusajs.com/references/medusa-workflows/cancelBeginOrderExchangeWorkflow/index.html.md)
 - [cancelOrderClaimWorkflow](https://docs.medusajs.com/references/medusa-workflows/cancelOrderClaimWorkflow/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)
-- [cancelOrderFulfillmentValidateOrder](https://docs.medusajs.com/references/medusa-workflows/cancelOrderFulfillmentValidateOrder/index.html.md)
+- [cancelOrderChangeWorkflow](https://docs.medusajs.com/references/medusa-workflows/cancelOrderChangeWorkflow/index.html.md)
 - [cancelOrderFulfillmentWorkflow](https://docs.medusajs.com/references/medusa-workflows/cancelOrderFulfillmentWorkflow/index.html.md)
 - [cancelOrderTransferRequestWorkflow](https://docs.medusajs.com/references/medusa-workflows/cancelOrderTransferRequestWorkflow/index.html.md)
+- [cancelOrderFulfillmentValidateOrder](https://docs.medusajs.com/references/medusa-workflows/cancelOrderFulfillmentValidateOrder/index.html.md)
+- [cancelRequestReturnValidationStep](https://docs.medusajs.com/references/medusa-workflows/cancelRequestReturnValidationStep/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)
-- [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)
+- [cancelReturnRequestWorkflow](https://docs.medusajs.com/references/medusa-workflows/cancelReturnRequestWorkflow/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)
 - [cancelReturnValidateOrder](https://docs.medusajs.com/references/medusa-workflows/cancelReturnValidateOrder/index.html.md)
-- [cancelTransferOrderRequestValidationStep](https://docs.medusajs.com/references/medusa-workflows/cancelTransferOrderRequestValidationStep/index.html.md)
 - [cancelValidateOrder](https://docs.medusajs.com/references/medusa-workflows/cancelValidateOrder/index.html.md)
 - [completeOrderWorkflow](https://docs.medusajs.com/references/medusa-workflows/completeOrderWorkflow/index.html.md)
-- [confirmClaimRequestWorkflow](https://docs.medusajs.com/references/medusa-workflows/confirmClaimRequestWorkflow/index.html.md)
-- [confirmExchangeRequestWorkflow](https://docs.medusajs.com/references/medusa-workflows/confirmExchangeRequestWorkflow/index.html.md)
-- [confirmExchangeRequestValidationStep](https://docs.medusajs.com/references/medusa-workflows/confirmExchangeRequestValidationStep/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)
+- [confirmExchangeRequestWorkflow](https://docs.medusajs.com/references/medusa-workflows/confirmExchangeRequestWorkflow/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)
+- [confirmReturnReceiveWorkflow](https://docs.medusajs.com/references/medusa-workflows/confirmReturnReceiveWorkflow/index.html.md)
+- [confirmReturnRequestValidationStep](https://docs.medusajs.com/references/medusa-workflows/confirmReturnRequestValidationStep/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)
 - [createAndCompleteReturnOrderWorkflow](https://docs.medusajs.com/references/medusa-workflows/createAndCompleteReturnOrderWorkflow/index.html.md)
-- [confirmReturnRequestValidationStep](https://docs.medusajs.com/references/medusa-workflows/confirmReturnRequestValidationStep/index.html.md)
-- [createClaimShippingMethodValidationStep](https://docs.medusajs.com/references/medusa-workflows/createClaimShippingMethodValidationStep/index.html.md)
 - [createClaimShippingMethodWorkflow](https://docs.medusajs.com/references/medusa-workflows/createClaimShippingMethodWorkflow/index.html.md)
+- [createClaimShippingMethodValidationStep](https://docs.medusajs.com/references/medusa-workflows/createClaimShippingMethodValidationStep/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)
-- [confirmReturnReceiveWorkflow](https://docs.medusajs.com/references/medusa-workflows/confirmReturnReceiveWorkflow/index.html.md)
 - [createFulfillmentValidateOrder](https://docs.medusajs.com/references/medusa-workflows/createFulfillmentValidateOrder/index.html.md)
 - [createOrderChangeWorkflow](https://docs.medusajs.com/references/medusa-workflows/createOrderChangeWorkflow/index.html.md)
 - [createOrderCreditLinesWorkflow](https://docs.medusajs.com/references/medusa-workflows/createOrderCreditLinesWorkflow/index.html.md)
-- [createOrUpdateOrderPaymentCollectionWorkflow](https://docs.medusajs.com/references/medusa-workflows/createOrUpdateOrderPaymentCollectionWorkflow/index.html.md)
 - [createOrderEditShippingMethodWorkflow](https://docs.medusajs.com/references/medusa-workflows/createOrderEditShippingMethodWorkflow/index.html.md)
-- [createOrderChangeActionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createOrderChangeActionsWorkflow/index.html.md)
 - [createOrderEditShippingMethodValidationStep](https://docs.medusajs.com/references/medusa-workflows/createOrderEditShippingMethodValidationStep/index.html.md)
-- [createOrderFulfillmentWorkflow](https://docs.medusajs.com/references/medusa-workflows/createOrderFulfillmentWorkflow/index.html.md)
+- [createOrUpdateOrderPaymentCollectionWorkflow](https://docs.medusajs.com/references/medusa-workflows/createOrUpdateOrderPaymentCollectionWorkflow/index.html.md)
+- [createOrderChangeActionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createOrderChangeActionsWorkflow/index.html.md)
 - [createOrderPaymentCollectionWorkflow](https://docs.medusajs.com/references/medusa-workflows/createOrderPaymentCollectionWorkflow/index.html.md)
+- [createOrderFulfillmentWorkflow](https://docs.medusajs.com/references/medusa-workflows/createOrderFulfillmentWorkflow/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)
 - [createOrdersWorkflow](https://docs.medusajs.com/references/medusa-workflows/createOrdersWorkflow/index.html.md)
+- [createReturnShippingMethodValidationStep](https://docs.medusajs.com/references/medusa-workflows/createReturnShippingMethodValidationStep/index.html.md)
+- [createOrderWorkflow](https://docs.medusajs.com/references/medusa-workflows/createOrderWorkflow/index.html.md)
 - [createShipmentValidateOrder](https://docs.medusajs.com/references/medusa-workflows/createShipmentValidateOrder/index.html.md)
-- [createReturnShippingMethodWorkflow](https://docs.medusajs.com/references/medusa-workflows/createReturnShippingMethodWorkflow/index.html.md)
 - [declineOrderTransferRequestWorkflow](https://docs.medusajs.com/references/medusa-workflows/declineOrderTransferRequestWorkflow/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)
-- [deleteOrderChangeActionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteOrderChangeActionsWorkflow/index.html.md)
 - [declineTransferOrderRequestValidationStep](https://docs.medusajs.com/references/medusa-workflows/declineTransferOrderRequestValidationStep/index.html.md)
-- [deleteOrderChangeWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteOrderChangeWorkflow/index.html.md)
-- [dismissItemReturnRequestValidationStep](https://docs.medusajs.com/references/medusa-workflows/dismissItemReturnRequestValidationStep/index.html.md)
+- [deleteOrderChangeActionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteOrderChangeActionsWorkflow/index.html.md)
 - [deleteOrderPaymentCollections](https://docs.medusajs.com/references/medusa-workflows/deleteOrderPaymentCollections/index.html.md)
 - [dismissItemReturnRequestWorkflow](https://docs.medusajs.com/references/medusa-workflows/dismissItemReturnRequestWorkflow/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)
+- [deleteOrderChangeWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteOrderChangeWorkflow/index.html.md)
 - [exchangeRequestItemReturnValidationStep](https://docs.medusajs.com/references/medusa-workflows/exchangeRequestItemReturnValidationStep/index.html.md)
-- [getOrdersListWorkflow](https://docs.medusajs.com/references/medusa-workflows/getOrdersListWorkflow/index.html.md)
+- [exchangeAddNewItemValidationStep](https://docs.medusajs.com/references/medusa-workflows/exchangeAddNewItemValidationStep/index.html.md)
 - [getOrderDetailWorkflow](https://docs.medusajs.com/references/medusa-workflows/getOrderDetailWorkflow/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)
+- [markPaymentCollectionAsPaid](https://docs.medusajs.com/references/medusa-workflows/markPaymentCollectionAsPaid/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)
-- [orderClaimItemWorkflow](https://docs.medusajs.com/references/medusa-workflows/orderClaimItemWorkflow/index.html.md)
+- [getOrdersListWorkflow](https://docs.medusajs.com/references/medusa-workflows/getOrdersListWorkflow/index.html.md)
 - [orderClaimItemValidationStep](https://docs.medusajs.com/references/medusa-workflows/orderClaimItemValidationStep/index.html.md)
 - [orderClaimRequestItemReturnWorkflow](https://docs.medusajs.com/references/medusa-workflows/orderClaimRequestItemReturnWorkflow/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)
-- [orderEditAddNewItemWorkflow](https://docs.medusajs.com/references/medusa-workflows/orderEditAddNewItemWorkflow/index.html.md)
 - [orderEditAddNewItemValidationStep](https://docs.medusajs.com/references/medusa-workflows/orderEditAddNewItemValidationStep/index.html.md)
-- [orderEditUpdateItemQuantityValidationStep](https://docs.medusajs.com/references/medusa-workflows/orderEditUpdateItemQuantityValidationStep/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)
+- [orderEditUpdateItemQuantityValidationStep](https://docs.medusajs.com/references/medusa-workflows/orderEditUpdateItemQuantityValidationStep/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)
 - [orderExchangeAddNewItemWorkflow](https://docs.medusajs.com/references/medusa-workflows/orderExchangeAddNewItemWorkflow/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)
 - [receiveCompleteReturnValidationStep](https://docs.medusajs.com/references/medusa-workflows/receiveCompleteReturnValidationStep/index.html.md)
+- [receiveItemReturnRequestWorkflow](https://docs.medusajs.com/references/medusa-workflows/receiveItemReturnRequestWorkflow/index.html.md)
+- [removeClaimAddItemActionValidationStep](https://docs.medusajs.com/references/medusa-workflows/removeClaimAddItemActionValidationStep/index.html.md)
 - [removeAddItemClaimActionWorkflow](https://docs.medusajs.com/references/medusa-workflows/removeAddItemClaimActionWorkflow/index.html.md)
 - [removeClaimItemActionValidationStep](https://docs.medusajs.com/references/medusa-workflows/removeClaimItemActionValidationStep/index.html.md)
-- [removeClaimAddItemActionValidationStep](https://docs.medusajs.com/references/medusa-workflows/removeClaimAddItemActionValidationStep/index.html.md)
-- [receiveItemReturnRequestWorkflow](https://docs.medusajs.com/references/medusa-workflows/receiveItemReturnRequestWorkflow/index.html.md)
 - [removeClaimShippingMethodValidationStep](https://docs.medusajs.com/references/medusa-workflows/removeClaimShippingMethodValidationStep/index.html.md)
 - [removeClaimShippingMethodWorkflow](https://docs.medusajs.com/references/medusa-workflows/removeClaimShippingMethodWorkflow/index.html.md)
 - [removeExchangeItemActionValidationStep](https://docs.medusajs.com/references/medusa-workflows/removeExchangeItemActionValidationStep/index.html.md)
-- [removeExchangeShippingMethodValidationStep](https://docs.medusajs.com/references/medusa-workflows/removeExchangeShippingMethodValidationStep/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)
 - [removeItemExchangeActionWorkflow](https://docs.medusajs.com/references/medusa-workflows/removeItemExchangeActionWorkflow/index.html.md)
-- [removeItemReceiveReturnActionValidationStep](https://docs.medusajs.com/references/medusa-workflows/removeItemReceiveReturnActionValidationStep/index.html.md)
-- [removeItemReceiveReturnActionWorkflow](https://docs.medusajs.com/references/medusa-workflows/removeItemReceiveReturnActionWorkflow/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)
 - [removeItemOrderEditActionWorkflow](https://docs.medusajs.com/references/medusa-workflows/removeItemOrderEditActionWorkflow/index.html.md)
+- [removeItemReceiveReturnActionWorkflow](https://docs.medusajs.com/references/medusa-workflows/removeItemReceiveReturnActionWorkflow/index.html.md)
+- [removeItemReceiveReturnActionValidationStep](https://docs.medusajs.com/references/medusa-workflows/removeItemReceiveReturnActionValidationStep/index.html.md)
 - [removeItemReturnActionWorkflow](https://docs.medusajs.com/references/medusa-workflows/removeItemReturnActionWorkflow/index.html.md)
 - [removeOrderEditItemActionValidationStep](https://docs.medusajs.com/references/medusa-workflows/removeOrderEditItemActionValidationStep/index.html.md)
-- [removeReturnItemActionValidationStep](https://docs.medusajs.com/references/medusa-workflows/removeReturnItemActionValidationStep/index.html.md)
-- [removeOrderEditShippingMethodValidationStep](https://docs.medusajs.com/references/medusa-workflows/removeOrderEditShippingMethodValidationStep/index.html.md)
-- [removeReturnShippingMethodValidationStep](https://docs.medusajs.com/references/medusa-workflows/removeReturnShippingMethodValidationStep/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)
+- [removeReturnItemActionValidationStep](https://docs.medusajs.com/references/medusa-workflows/removeReturnItemActionValidationStep/index.html.md)
+- [removeReturnShippingMethodValidationStep](https://docs.medusajs.com/references/medusa-workflows/removeReturnShippingMethodValidationStep/index.html.md)
+- [removeOrderEditShippingMethodValidationStep](https://docs.medusajs.com/references/medusa-workflows/removeOrderEditShippingMethodValidationStep/index.html.md)
 - [requestItemReturnValidationStep](https://docs.medusajs.com/references/medusa-workflows/requestItemReturnValidationStep/index.html.md)
+- [removeReturnShippingMethodWorkflow](https://docs.medusajs.com/references/medusa-workflows/removeReturnShippingMethodWorkflow/index.html.md)
+- [requestItemReturnWorkflow](https://docs.medusajs.com/references/medusa-workflows/requestItemReturnWorkflow/index.html.md)
 - [requestOrderEditRequestValidationStep](https://docs.medusajs.com/references/medusa-workflows/requestOrderEditRequestValidationStep/index.html.md)
 - [requestOrderTransferValidationStep](https://docs.medusajs.com/references/medusa-workflows/requestOrderTransferValidationStep/index.html.md)
-- [requestItemReturnWorkflow](https://docs.medusajs.com/references/medusa-workflows/requestItemReturnWorkflow/index.html.md)
 - [requestOrderEditRequestWorkflow](https://docs.medusajs.com/references/medusa-workflows/requestOrderEditRequestWorkflow/index.html.md)
-- [throwUnlessPaymentCollectionNotPaid](https://docs.medusajs.com/references/medusa-workflows/throwUnlessPaymentCollectionNotPaid/index.html.md)
 - [requestOrderTransferWorkflow](https://docs.medusajs.com/references/medusa-workflows/requestOrderTransferWorkflow/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)
 - [throwUnlessStatusIsNotPaid](https://docs.medusajs.com/references/medusa-workflows/throwUnlessStatusIsNotPaid/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)
 - [updateClaimItemWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateClaimItemWorkflow/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)
+- [updateClaimShippingMethodWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateClaimShippingMethodWorkflow/index.html.md)
+- [updateClaimAddItemWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateClaimAddItemWorkflow/index.html.md)
 - [updateExchangeAddItemWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateExchangeAddItemWorkflow/index.html.md)
-- [updateExchangeShippingMethodValidationStep](https://docs.medusajs.com/references/medusa-workflows/updateExchangeShippingMethodValidationStep/index.html.md)
 - [updateExchangeShippingMethodWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateExchangeShippingMethodWorkflow/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)
-- [updateOrderEditItemQuantityValidationStep](https://docs.medusajs.com/references/medusa-workflows/updateOrderEditItemQuantityValidationStep/index.html.md)
+- [updateOrderEditAddItemValidationStep](https://docs.medusajs.com/references/medusa-workflows/updateOrderEditAddItemValidationStep/index.html.md)
 - [updateOrderEditItemQuantityWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateOrderEditItemQuantityWorkflow/index.html.md)
+- [updateOrderEditItemQuantityValidationStep](https://docs.medusajs.com/references/medusa-workflows/updateOrderEditItemQuantityValidationStep/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)
 - [updateOrderTaxLinesWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateOrderTaxLinesWorkflow/index.html.md)
@@ -30072,385 +30082,379 @@ For each product variant, you:
 - [updateRequestItemReturnValidationStep](https://docs.medusajs.com/references/medusa-workflows/updateRequestItemReturnValidationStep/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)
-- [updateRequestItemReturnWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateRequestItemReturnWorkflow/index.html.md)
 - [updateOrderWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateOrderWorkflow/index.html.md)
+- [updateRequestItemReturnWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateRequestItemReturnWorkflow/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)
-- [validateOrderCreditLinesStep](https://docs.medusajs.com/references/medusa-workflows/validateOrderCreditLinesStep/index.html.md)
 - [updateReturnShippingMethodWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateReturnShippingMethodWorkflow/index.html.md)
-- [batchPriceListPricesWorkflow](https://docs.medusajs.com/references/medusa-workflows/batchPriceListPricesWorkflow/index.html.md)
-- [createPriceListPricesWorkflow](https://docs.medusajs.com/references/medusa-workflows/createPriceListPricesWorkflow/index.html.md)
+- [validateOrderCreditLinesStep](https://docs.medusajs.com/references/medusa-workflows/validateOrderCreditLinesStep/index.html.md)
+- [updateReturnValidationStep](https://docs.medusajs.com/references/medusa-workflows/updateReturnValidationStep/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)
+- [linkCustomerGroupsToCustomerWorkflow](https://docs.medusajs.com/references/medusa-workflows/linkCustomerGroupsToCustomerWorkflow/index.html.md)
+- [updateCustomerGroupsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateCustomerGroupsWorkflow/index.html.md)
+- [createCustomersWorkflow](https://docs.medusajs.com/references/medusa-workflows/createCustomersWorkflow/index.html.md)
+- [createCustomerAccountWorkflow](https://docs.medusajs.com/references/medusa-workflows/createCustomerAccountWorkflow/index.html.md)
+- [deleteCustomerAddressesWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteCustomerAddressesWorkflow/index.html.md)
+- [createCustomerAddressesWorkflow](https://docs.medusajs.com/references/medusa-workflows/createCustomerAddressesWorkflow/index.html.md)
+- [deleteCustomersWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteCustomersWorkflow/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)
+- [updateCustomersWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateCustomersWorkflow/index.html.md)
 - [createPriceListsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createPriceListsWorkflow/index.html.md)
-- [removePriceListPricesWorkflow](https://docs.medusajs.com/references/medusa-workflows/removePriceListPricesWorkflow/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)
 - [deletePriceListsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deletePriceListsWorkflow/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)
 - [updatePriceListsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updatePriceListsWorkflow/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)
-- [createCollectionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createCollectionsWorkflow/index.html.md)
-- [createProductTagsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createProductTagsWorkflow/index.html.md)
-- [createProductTypesWorkflow](https://docs.medusajs.com/references/medusa-workflows/createProductTypesWorkflow/index.html.md)
-- [createProductOptionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createProductOptionsWorkflow/index.html.md)
-- [createProductVariantsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createProductVariantsWorkflow/index.html.md)
-- [createProductsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createProductsWorkflow/index.html.md)
-- [deleteProductOptionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteProductOptionsWorkflow/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)
-- [deleteProductTypesWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteProductTypesWorkflow/index.html.md)
-- [deleteProductsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteProductsWorkflow/index.html.md)
-- [deleteProductVariantsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteProductVariantsWorkflow/index.html.md)
-- [importProductsWorkflow](https://docs.medusajs.com/references/medusa-workflows/importProductsWorkflow/index.html.md)
-- [exportProductsWorkflow](https://docs.medusajs.com/references/medusa-workflows/exportProductsWorkflow/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)
-- [updateProductTypesWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateProductTypesWorkflow/index.html.md)
-- [updateCollectionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateCollectionsWorkflow/index.html.md)
-- [updateProductVariantsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateProductVariantsWorkflow/index.html.md)
-- [updateProductsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateProductsWorkflow/index.html.md)
-- [upsertVariantPricesWorkflow](https://docs.medusajs.com/references/medusa-workflows/upsertVariantPricesWorkflow/index.html.md)
-- [validateProductInputStep](https://docs.medusajs.com/references/medusa-workflows/validateProductInputStep/index.html.md)
+- [updatePriceListPricesWorkflow](https://docs.medusajs.com/references/medusa-workflows/updatePriceListPricesWorkflow/index.html.md)
+- [deletePricePreferencesWorkflow](https://docs.medusajs.com/references/medusa-workflows/deletePricePreferencesWorkflow/index.html.md)
 - [createPricePreferencesWorkflow](https://docs.medusajs.com/references/medusa-workflows/createPricePreferencesWorkflow/index.html.md)
 - [updatePricePreferencesWorkflow](https://docs.medusajs.com/references/medusa-workflows/updatePricePreferencesWorkflow/index.html.md)
 - [createProductCategoriesWorkflow](https://docs.medusajs.com/references/medusa-workflows/createProductCategoriesWorkflow/index.html.md)
-- [deletePricePreferencesWorkflow](https://docs.medusajs.com/references/medusa-workflows/deletePricePreferencesWorkflow/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)
 - [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)
-- [addOrRemoveCampaignPromotionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/addOrRemoveCampaignPromotionsWorkflow/index.html.md)
-- [batchPromotionRulesWorkflow](https://docs.medusajs.com/references/medusa-workflows/batchPromotionRulesWorkflow/index.html.md)
-- [createCampaignsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createCampaignsWorkflow/index.html.md)
-- [createPromotionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createPromotionsWorkflow/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)
-- [deletePromotionRulesWorkflow](https://docs.medusajs.com/references/medusa-workflows/deletePromotionRulesWorkflow/index.html.md)
-- [updatePromotionRulesWorkflow](https://docs.medusajs.com/references/medusa-workflows/updatePromotionRulesWorkflow/index.html.md)
-- [deletePromotionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deletePromotionsWorkflow/index.html.md)
-- [updateCampaignsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateCampaignsWorkflow/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)
-- [createReservationsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createReservationsWorkflow/index.html.md)
+- [deleteRegionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteRegionsWorkflow/index.html.md)
 - [deleteReservationsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteReservationsWorkflow/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)
+- [createReturnReasonsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createReturnReasonsWorkflow/index.html.md)
+- [deleteReturnReasonsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteReturnReasonsWorkflow/index.html.md)
+- [updateReturnReasonsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateReturnReasonsWorkflow/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)
+- [batchProductsWorkflow](https://docs.medusajs.com/references/medusa-workflows/batchProductsWorkflow/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)
+- [batchProductVariantsWorkflow](https://docs.medusajs.com/references/medusa-workflows/batchProductVariantsWorkflow/index.html.md)
+- [createProductTagsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createProductTagsWorkflow/index.html.md)
+- [createProductTypesWorkflow](https://docs.medusajs.com/references/medusa-workflows/createProductTypesWorkflow/index.html.md)
+- [createProductsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createProductsWorkflow/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)
+- [deleteProductTagsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteProductTagsWorkflow/index.html.md)
+- [deleteProductTypesWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteProductTypesWorkflow/index.html.md)
+- [deleteCollectionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteCollectionsWorkflow/index.html.md)
+- [deleteProductVariantsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteProductVariantsWorkflow/index.html.md)
+- [exportProductsWorkflow](https://docs.medusajs.com/references/medusa-workflows/exportProductsWorkflow/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)
+- [updateProductTagsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateProductTagsWorkflow/index.html.md)
+- [updateCollectionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateCollectionsWorkflow/index.html.md)
+- [updateProductOptionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateProductOptionsWorkflow/index.html.md)
+- [updateProductsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateProductsWorkflow/index.html.md)
+- [upsertVariantPricesWorkflow](https://docs.medusajs.com/references/medusa-workflows/upsertVariantPricesWorkflow/index.html.md)
+- [updateProductTypesWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateProductTypesWorkflow/index.html.md)
+- [validateProductInputStep](https://docs.medusajs.com/references/medusa-workflows/validateProductInputStep/index.html.md)
+- [updateProductVariantsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateProductVariantsWorkflow/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)
-- [deleteSalesChannelsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteSalesChannelsWorkflow/index.html.md)
 - [updateSalesChannelsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateSalesChannelsWorkflow/index.html.md)
-- [deleteReturnReasonsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteReturnReasonsWorkflow/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)
-- [createLocationFulfillmentSetWorkflow](https://docs.medusajs.com/references/medusa-workflows/createLocationFulfillmentSetWorkflow/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)
-- [updateStockLocationsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateStockLocationsWorkflow/index.html.md)
-- [createStoresWorkflow](https://docs.medusajs.com/references/medusa-workflows/createStoresWorkflow/index.html.md)
-- [deleteStockLocationsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteStockLocationsWorkflow/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)
+- [deleteSalesChannelsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteSalesChannelsWorkflow/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)
-- [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)
-- [confirmVariantInventoryWorkflow](https://docs.medusajs.com/references/medusa-workflows/confirmVariantInventoryWorkflow/index.html.md)
-- [createCartCreditLinesWorkflow](https://docs.medusajs.com/references/medusa-workflows/createCartCreditLinesWorkflow/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)
-- [createCartWorkflow](https://docs.medusajs.com/references/medusa-workflows/createCartWorkflow/index.html.md)
-- [listShippingOptionsForCartWithPricingWorkflow](https://docs.medusajs.com/references/medusa-workflows/listShippingOptionsForCartWithPricingWorkflow/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)
-- [transferCartCustomerWorkflow](https://docs.medusajs.com/references/medusa-workflows/transferCartCustomerWorkflow/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)
-- [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)
-- [updateTaxLinesWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateTaxLinesWorkflow/index.html.md)
-- [validateExistingPaymentCollectionStep](https://docs.medusajs.com/references/medusa-workflows/validateExistingPaymentCollectionStep/index.html.md)
-- [createUserAccountWorkflow](https://docs.medusajs.com/references/medusa-workflows/createUserAccountWorkflow/index.html.md)
+- [createLocationFulfillmentSetWorkflow](https://docs.medusajs.com/references/medusa-workflows/createLocationFulfillmentSetWorkflow/index.html.md)
+- [linkSalesChannelsToStockLocationWorkflow](https://docs.medusajs.com/references/medusa-workflows/linkSalesChannelsToStockLocationWorkflow/index.html.md)
+- [createStockLocationsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createStockLocationsWorkflow/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)
+- [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)
+- [createTaxRatesWorkflow](https://docs.medusajs.com/references/medusa-workflows/createTaxRatesWorkflow/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)
+- [createTaxRegionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createTaxRegionsWorkflow/index.html.md)
+- [deleteTaxRatesWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteTaxRatesWorkflow/index.html.md)
+- [deleteTaxRateRulesWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteTaxRateRulesWorkflow/index.html.md)
+- [setTaxRateRulesWorkflow](https://docs.medusajs.com/references/medusa-workflows/setTaxRateRulesWorkflow/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)
+- [maybeListTaxRateRuleIdsStep](https://docs.medusajs.com/references/medusa-workflows/maybeListTaxRateRuleIdsStep/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)
+- [createUserAccountWorkflow](https://docs.medusajs.com/references/medusa-workflows/createUserAccountWorkflow/index.html.md)
 - [updateUsersWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateUsersWorkflow/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)
-- [createTaxRegionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createTaxRegionsWorkflow/index.html.md)
-- [deleteTaxRateRulesWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteTaxRateRulesWorkflow/index.html.md)
-- [deleteTaxRatesWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteTaxRatesWorkflow/index.html.md)
-- [deleteTaxRegionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteTaxRegionsWorkflow/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)
-- [updateTaxRatesWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateTaxRatesWorkflow/index.html.md)
-- [updateTaxRegionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateTaxRegionsWorkflow/index.html.md)
+- [addOrRemoveCampaignPromotionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/addOrRemoveCampaignPromotionsWorkflow/index.html.md)
+- [createPromotionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createPromotionsWorkflow/index.html.md)
+- [batchPromotionRulesWorkflow](https://docs.medusajs.com/references/medusa-workflows/batchPromotionRulesWorkflow/index.html.md)
+- [deleteCampaignsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteCampaignsWorkflow/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)
+- [deletePromotionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deletePromotionsWorkflow/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)
+- [deletePromotionRulesWorkflow](https://docs.medusajs.com/references/medusa-workflows/deletePromotionRulesWorkflow/index.html.md)
+- [updatePromotionsStatusWorkflow](https://docs.medusajs.com/references/medusa-workflows/updatePromotionsStatusWorkflow/index.html.md)
+- [updatePromotionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updatePromotionsWorkflow/index.html.md)
+- [updatePromotionsValidationStep](https://docs.medusajs.com/references/medusa-workflows/updatePromotionsValidationStep/index.html.md)
 
 
 ## Steps
 
+- [createApiKeysStep](https://docs.medusajs.com/references/medusa-workflows/steps/createApiKeysStep/index.html.md)
+- [deleteApiKeysStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteApiKeysStep/index.html.md)
+- [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)
+- [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)
+- [setAuthAppMetadataStep](https://docs.medusajs.com/references/medusa-workflows/steps/setAuthAppMetadataStep/index.html.md)
+- [emitEventStep](https://docs.medusajs.com/references/medusa-workflows/steps/emitEventStep/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)
+- [removeRemoteLinkStep](https://docs.medusajs.com/references/medusa-workflows/steps/removeRemoteLinkStep/index.html.md)
+- [useRemoteQueryStep](https://docs.medusajs.com/references/medusa-workflows/steps/useRemoteQueryStep/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)
+- [updateRemoteLinksStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateRemoteLinksStep/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)
+- [createPaymentCollectionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createPaymentCollectionsStep/index.html.md)
 - [createLineItemsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createLineItemsStep/index.html.md)
 - [createShippingMethodAdjustmentsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createShippingMethodAdjustmentsStep/index.html.md)
-- [createLineItemAdjustmentsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createLineItemAdjustmentsStep/index.html.md)
-- [createPaymentCollectionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createPaymentCollectionsStep/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)
 - [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)
 - [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)
-- [getVariantPriceSetsStep](https://docs.medusajs.com/references/medusa-workflows/steps/getVariantPriceSetsStep/index.html.md)
-- [getVariantsStep](https://docs.medusajs.com/references/medusa-workflows/steps/getVariantsStep/index.html.md)
 - [prepareAdjustmentsFromPromotionActionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/prepareAdjustmentsFromPromotionActionsStep/index.html.md)
+- [getVariantsStep](https://docs.medusajs.com/references/medusa-workflows/steps/getVariantsStep/index.html.md)
 - [removeLineItemAdjustmentsStep](https://docs.medusajs.com/references/medusa-workflows/steps/removeLineItemAdjustmentsStep/index.html.md)
-- [removeShippingMethodFromCartStep](https://docs.medusajs.com/references/medusa-workflows/steps/removeShippingMethodFromCartStep/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)
 - [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)
+- [reserveInventoryStep](https://docs.medusajs.com/references/medusa-workflows/steps/reserveInventoryStep/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)
-- [validateAndReturnShippingMethodsDataStep](https://docs.medusajs.com/references/medusa-workflows/steps/validateAndReturnShippingMethodsDataStep/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)
+- [updateCartsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateCartsStep/index.html.md)
+- [validateCartShippingOptionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/validateCartShippingOptionsStep/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)
 - [validateCartStep](https://docs.medusajs.com/references/medusa-workflows/steps/validateCartStep/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)
 - [validateShippingStep](https://docs.medusajs.com/references/medusa-workflows/steps/validateShippingStep/index.html.md)
+- [validateLineItemPricesStep](https://docs.medusajs.com/references/medusa-workflows/steps/validateLineItemPricesStep/index.html.md)
 - [validateVariantPricesStep](https://docs.medusajs.com/references/medusa-workflows/steps/validateVariantPricesStep/index.html.md)
-- [setAuthAppMetadataStep](https://docs.medusajs.com/references/medusa-workflows/steps/setAuthAppMetadataStep/index.html.md)
-- [createDefaultStoreStep](https://docs.medusajs.com/references/medusa-workflows/steps/createDefaultStoreStep/index.html.md)
 - [createCustomerAddressesStep](https://docs.medusajs.com/references/medusa-workflows/steps/createCustomerAddressesStep/index.html.md)
 - [createCustomersStep](https://docs.medusajs.com/references/medusa-workflows/steps/createCustomersStep/index.html.md)
-- [deleteCustomersStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteCustomersStep/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)
 - [maybeUnsetDefaultBillingAddressesStep](https://docs.medusajs.com/references/medusa-workflows/steps/maybeUnsetDefaultBillingAddressesStep/index.html.md)
+- [deleteCustomersStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteCustomersStep/index.html.md)
+- [deleteCustomerAddressesStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteCustomerAddressesStep/index.html.md)
+- [maybeUnsetDefaultShippingAddressesStep](https://docs.medusajs.com/references/medusa-workflows/steps/maybeUnsetDefaultShippingAddressesStep/index.html.md)
 - [updateCustomerAddressesStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateCustomerAddressesStep/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)
 - [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)
-- [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)
 - [linkCustomerGroupsToCustomerStep](https://docs.medusajs.com/references/medusa-workflows/steps/linkCustomerGroupsToCustomerStep/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)
+- [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)
-- [cancelFulfillmentStep](https://docs.medusajs.com/references/medusa-workflows/steps/cancelFulfillmentStep/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)
 - [createFulfillmentSets](https://docs.medusajs.com/references/medusa-workflows/steps/createFulfillmentSets/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)
+- [buildPriceSet](https://docs.medusajs.com/references/medusa-workflows/steps/buildPriceSet/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)
+- [createReturnFulfillmentStep](https://docs.medusajs.com/references/medusa-workflows/steps/createReturnFulfillmentStep/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)
+- [createFulfillmentStep](https://docs.medusajs.com/references/medusa-workflows/steps/createFulfillmentStep/index.html.md)
+- [createShippingOptionsPriceSetsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createShippingOptionsPriceSetsStep/index.html.md)
 - [createShippingProfilesStep](https://docs.medusajs.com/references/medusa-workflows/steps/createShippingProfilesStep/index.html.md)
-- [deleteShippingOptionRulesStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteShippingOptionRulesStep/index.html.md)
-- [setShippingOptionsPricesStep](https://docs.medusajs.com/references/medusa-workflows/steps/setShippingOptionsPricesStep/index.html.md)
 - [deleteServiceZonesStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteServiceZonesStep/index.html.md)
+- [deleteShippingOptionRulesStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteShippingOptionRulesStep/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)
-- [updateFulfillmentStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateFulfillmentStep/index.html.md)
-- [updateShippingProfilesStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateShippingProfilesStep/index.html.md)
+- [setShippingOptionsPricesStep](https://docs.medusajs.com/references/medusa-workflows/steps/setShippingOptionsPricesStep/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)
+- [updateFulfillmentStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateFulfillmentStep/index.html.md)
+- [updateShippingProfilesStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateShippingProfilesStep/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)
 - [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)
+- [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)
+- [createInviteStep](https://docs.medusajs.com/references/medusa-workflows/steps/createInviteStep/index.html.md)
+- [deleteInvitesStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteInvitesStep/index.html.md)
+- [refreshInviteTokensStep](https://docs.medusajs.com/references/medusa-workflows/steps/refreshInviteTokensStep/index.html.md)
+- [validateTokenStep](https://docs.medusajs.com/references/medusa-workflows/steps/validateTokenStep/index.html.md)
+- [updateLineItemsStepWithSelector](https://docs.medusajs.com/references/medusa-workflows/steps/updateLineItemsStepWithSelector/index.html.md)
+- [listLineItemsStep](https://docs.medusajs.com/references/medusa-workflows/steps/listLineItemsStep/index.html.md)
+- [deleteLineItemsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteLineItemsStep/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)
 - [attachInventoryItemToVariants](https://docs.medusajs.com/references/medusa-workflows/steps/attachInventoryItemToVariants/index.html.md)
 - [createInventoryItemsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createInventoryItemsStep/index.html.md)
 - [createInventoryLevelsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createInventoryLevelsStep/index.html.md)
+- [adjustInventoryLevelsStep](https://docs.medusajs.com/references/medusa-workflows/steps/adjustInventoryLevelsStep/index.html.md)
 - [deleteInventoryItemStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteInventoryItemStep/index.html.md)
 - [updateInventoryItemsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateInventoryItemsStep/index.html.md)
 - [deleteInventoryLevelsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteInventoryLevelsStep/index.html.md)
 - [updateInventoryLevelsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateInventoryLevelsStep/index.html.md)
-- [validateInventoryItemsForCreate](https://docs.medusajs.com/references/medusa-workflows/steps/validateInventoryItemsForCreate/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)
 - [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)
-- [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)
-- [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)
-- [archiveOrdersStep](https://docs.medusajs.com/references/medusa-workflows/steps/archiveOrdersStep/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)
+- [refundPaymentsStep](https://docs.medusajs.com/references/medusa-workflows/steps/refundPaymentsStep/index.html.md)
+- [deletePriceListsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deletePriceListsStep/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)
+- [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)
+- [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)
+- [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)
 - [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)
 - [cancelOrderClaimStep](https://docs.medusajs.com/references/medusa-workflows/steps/cancelOrderClaimStep/index.html.md)
+- [cancelOrderChangeStep](https://docs.medusajs.com/references/medusa-workflows/steps/cancelOrderChangeStep/index.html.md)
 - [cancelOrderExchangeStep](https://docs.medusajs.com/references/medusa-workflows/steps/cancelOrderExchangeStep/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)
-- [createCompleteReturnStep](https://docs.medusajs.com/references/medusa-workflows/steps/createCompleteReturnStep/index.html.md)
-- [completeOrdersStep](https://docs.medusajs.com/references/medusa-workflows/steps/completeOrdersStep/index.html.md)
+- [cancelOrderFulfillmentStep](https://docs.medusajs.com/references/medusa-workflows/steps/cancelOrderFulfillmentStep/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)
+- [createCompleteReturnStep](https://docs.medusajs.com/references/medusa-workflows/steps/createCompleteReturnStep/index.html.md)
 - [createOrderClaimItemsFromActionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createOrderClaimItemsFromActionsStep/index.html.md)
 - [createOrderClaimsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createOrderClaimsStep/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)
 - [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)
 - [createOrdersStep](https://docs.medusajs.com/references/medusa-workflows/steps/createOrdersStep/index.html.md)
+- [createOrderLineItemsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createOrderLineItemsStep/index.html.md)
+- [declineOrderChangeStep](https://docs.medusajs.com/references/medusa-workflows/steps/declineOrderChangeStep/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)
-- [declineOrderChangeStep](https://docs.medusajs.com/references/medusa-workflows/steps/declineOrderChangeStep/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)
 - [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)
-- [deleteOrderShippingMethods](https://docs.medusajs.com/references/medusa-workflows/steps/deleteOrderShippingMethods/index.html.md)
-- [deleteOrderChangeActionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteOrderChangeActionsStep/index.html.md)
-- [previewOrderChangeStep](https://docs.medusajs.com/references/medusa-workflows/steps/previewOrderChangeStep/index.html.md)
 - [deleteReturnsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteReturnsStep/index.html.md)
+- [deleteOrderShippingMethods](https://docs.medusajs.com/references/medusa-workflows/steps/deleteOrderShippingMethods/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)
-- [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)
 - [registerOrderFulfillmentStep](https://docs.medusajs.com/references/medusa-workflows/steps/registerOrderFulfillmentStep/index.html.md)
-- [updateOrdersStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateOrdersStep/index.html.md)
+- [registerOrderShipmentStep](https://docs.medusajs.com/references/medusa-workflows/steps/registerOrderShipmentStep/index.html.md)
 - [updateOrderChangeActionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateOrderChangeActionsStep/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)
 - [updateReturnItemsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateReturnItemsStep/index.html.md)
-- [updateOrderChangesStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateOrderChangesStep/index.html.md)
+- [updateOrdersStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateOrdersStep/index.html.md)
 - [updateReturnsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateReturnsStep/index.html.md)
-- [createApiKeysStep](https://docs.medusajs.com/references/medusa-workflows/steps/createApiKeysStep/index.html.md)
-- [deleteApiKeysStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteApiKeysStep/index.html.md)
-- [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)
-- [validateSalesChannelsExistStep](https://docs.medusajs.com/references/medusa-workflows/steps/validateSalesChannelsExistStep/index.html.md)
-- [authorizePaymentSessionStep](https://docs.medusajs.com/references/medusa-workflows/steps/authorizePaymentSessionStep/index.html.md)
-- [capturePaymentStep](https://docs.medusajs.com/references/medusa-workflows/steps/capturePaymentStep/index.html.md)
-- [cancelPaymentStep](https://docs.medusajs.com/references/medusa-workflows/steps/cancelPaymentStep/index.html.md)
-- [refundPaymentsStep](https://docs.medusajs.com/references/medusa-workflows/steps/refundPaymentsStep/index.html.md)
-- [refundPaymentStep](https://docs.medusajs.com/references/medusa-workflows/steps/refundPaymentStep/index.html.md)
 - [createPaymentAccountHolderStep](https://docs.medusajs.com/references/medusa-workflows/steps/createPaymentAccountHolderStep/index.html.md)
-- [deletePaymentSessionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deletePaymentSessionsStep/index.html.md)
 - [createRefundReasonStep](https://docs.medusajs.com/references/medusa-workflows/steps/createRefundReasonStep/index.html.md)
 - [createPaymentSessionStep](https://docs.medusajs.com/references/medusa-workflows/steps/createPaymentSessionStep/index.html.md)
-- [updateRefundReasonsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateRefundReasonsStep/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)
-- [validateDeletedPaymentSessionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/validateDeletedPaymentSessionsStep/index.html.md)
+- [updateRefundReasonsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateRefundReasonsStep/index.html.md)
 - [updatePaymentCollectionStep](https://docs.medusajs.com/references/medusa-workflows/steps/updatePaymentCollectionStep/index.html.md)
+- [validateDeletedPaymentSessionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/validateDeletedPaymentSessionsStep/index.html.md)
 - [createPricePreferencesStep](https://docs.medusajs.com/references/medusa-workflows/steps/createPricePreferencesStep/index.html.md)
+- [deletePricePreferencesStep](https://docs.medusajs.com/references/medusa-workflows/steps/deletePricePreferencesStep/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)
-- [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)
-- [removeRemoteLinkStep](https://docs.medusajs.com/references/medusa-workflows/steps/removeRemoteLinkStep/index.html.md)
-- [dismissRemoteLinkStep](https://docs.medusajs.com/references/medusa-workflows/steps/dismissRemoteLinkStep/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)
-- [batchLinkProductsToCategoryStep](https://docs.medusajs.com/references/medusa-workflows/steps/batchLinkProductsToCategoryStep/index.html.md)
 - [batchLinkProductsToCollectionStep](https://docs.medusajs.com/references/medusa-workflows/steps/batchLinkProductsToCollectionStep/index.html.md)
-- [createProductOptionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createProductOptionsStep/index.html.md)
+- [batchLinkProductsToCategoryStep](https://docs.medusajs.com/references/medusa-workflows/steps/batchLinkProductsToCategoryStep/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)
+- [createProductVariantsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createProductVariantsStep/index.html.md)
 - [createVariantPricingLinkStep](https://docs.medusajs.com/references/medusa-workflows/steps/createVariantPricingLinkStep/index.html.md)
-- [deleteProductOptionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteProductOptionsStep/index.html.md)
-- [deleteCollectionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteCollectionsStep/index.html.md)
 - [deleteProductTagsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteProductTagsStep/index.html.md)
-- [deleteProductVariantsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteProductVariantsStep/index.html.md)
+- [deleteCollectionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteCollectionsStep/index.html.md)
 - [deleteProductTypesStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteProductTypesStep/index.html.md)
+- [deleteProductOptionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteProductOptionsStep/index.html.md)
 - [deleteProductsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteProductsStep/index.html.md)
-- [generateProductCsvStep](https://docs.medusajs.com/references/medusa-workflows/steps/generateProductCsvStep/index.html.md)
+- [deleteProductVariantsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteProductVariantsStep/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)
 - [getVariantAvailabilityStep](https://docs.medusajs.com/references/medusa-workflows/steps/getVariantAvailabilityStep/index.html.md)
+- [generateProductCsvStep](https://docs.medusajs.com/references/medusa-workflows/steps/generateProductCsvStep/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)
-- [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)
+- [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)
 - [updateProductVariantsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateProductVariantsStep/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)
-- [createProductCategoriesStep](https://docs.medusajs.com/references/medusa-workflows/steps/createProductCategoriesStep/index.html.md)
+- [updateProductsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateProductsStep/index.html.md)
 - [deleteProductCategoriesStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteProductCategoriesStep/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)
+- [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)
+- [removeCampaignPromotionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/removeCampaignPromotionsStep/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)
+- [updatePromotionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updatePromotionsStep/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)
+- [deleteRegionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteRegionsStep/index.html.md)
 - [updateRegionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateRegionsStep/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)
-- [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)
-- [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)
+- [deleteReservationsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteReservationsStep/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)
 - [canDeleteSalesChannelsOrThrowStep](https://docs.medusajs.com/references/medusa-workflows/steps/canDeleteSalesChannelsOrThrowStep/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)
 - [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)
 - [detachProductsFromSalesChannelsStep](https://docs.medusajs.com/references/medusa-workflows/steps/detachProductsFromSalesChannelsStep/index.html.md)
+- [detachLocationsFromSalesChannelsStep](https://docs.medusajs.com/references/medusa-workflows/steps/detachLocationsFromSalesChannelsStep/index.html.md)
 - [updateSalesChannelsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateSalesChannelsStep/index.html.md)
-- [createStockLocations](https://docs.medusajs.com/references/medusa-workflows/steps/createStockLocations/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)
-- [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)
-- [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)
+- [createReturnReasonsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createReturnReasonsStep/index.html.md)
+- [listShippingOptionsForContextStep](https://docs.medusajs.com/references/medusa-workflows/steps/listShippingOptionsForContextStep/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)
 - [deleteShippingProfilesStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteShippingProfilesStep/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)
 - [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)
 - [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)
-- [createTaxRegionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createTaxRegionsStep/index.html.md)
 - [deleteTaxRateRulesStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteTaxRateRulesStep/index.html.md)
 - [deleteTaxRatesStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteTaxRatesStep/index.html.md)
+- [createTaxRegionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createTaxRegionsStep/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)
 - [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)
-- [addCampaignPromotionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/addCampaignPromotionsStep/index.html.md)
-- [createCampaignsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createCampaignsStep/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)
-- [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)
-- [removeCampaignPromotionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/removeCampaignPromotionsStep/index.html.md)
-- [updateCampaignsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateCampaignsStep/index.html.md)
-- [deleteCampaignsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteCampaignsStep/index.html.md)
-- [updatePromotionRulesStep](https://docs.medusajs.com/references/medusa-workflows/steps/updatePromotionRulesStep/index.html.md)
-- [updatePromotionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updatePromotionsStep/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)
+- [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)
 
 
@@ -30555,35 +30559,6 @@ npx medusa exec [file] [args...]
 |\`args\`|A list of arguments to pass to the function. These arguments are passed in the |No|
 
 
-# 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 [<dir_name> [<starter_url>]]
-```
-
-## 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 \<user>\`|The database user to use for database setup.|
-|\`--db-database \<database>\`|The name of the database used for database setup.|
-|\`--db-pass \<password>\`|The database password to use for database setup.|
-|\`--db-port \<port>\`|The database port to use for database setup.|
-|\`--db-host \<host>\`|The database host to use for database setup.|
-
-
 # db Commands - Medusa CLI Reference
 
 Commands starting with `db:` perform actions on the database.
@@ -30704,6 +30679,84 @@ 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 \<host>\`|Set host of the Medusa server.|\`localhost\`|
+|\`-p \<port>\`|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 [<dir_name> [<starter_url>]]
+```
+
+## 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 \<user>\`|The database user to use for database setup.|
+|\`--db-database \<database>\`|The name of the database used for database setup.|
+|\`--db-pass \<password>\`|The database password to use for database setup.|
+|\`--db-port \<port>\`|The database port to use for database setup.|
+|\`--db-host \<host>\`|The database host to use for database setup.|
+
+
+# start Command - Medusa CLI Reference
+
+Start the Medusa application in production.
+
+```bash
+npx medusa start
+```
+
+## Options
+
+|Option|Description|Default|
+|---|---|---|---|---|
+|\`-H \<host>\`|Set host of the Medusa server.|\`localhost\`|
+|\`-p \<port>\`|Set port of the Medusa server.|\`9000\`|
+|\`--cluster \<number>\`|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.
+
+```bash
+npx medusa telemetry
+```
+
+#### Options
+
+|Option|Description|
+|---|---|---|
+|\`--enable\`|Enable telemetry (default).|
+|\`--disable\`|Disable telemetry.|
+
+
 # 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.
@@ -30765,55 +30818,6 @@ npx medusa plugin:build
 ```
 
 
-# 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 \<host>\`|Set host of the Medusa server.|\`localhost\`|
-|\`-p \<port>\`|Set port of the Medusa server.|\`9000\`|
-
-
-# start Command - Medusa CLI Reference
-
-Start the Medusa application in production.
-
-```bash
-npx medusa start
-```
-
-## Options
-
-|Option|Description|Default|
-|---|---|---|---|---|
-|\`-H \<host>\`|Set host of the Medusa server.|\`localhost\`|
-|\`-p \<port>\`|Set port of the Medusa server.|\`9000\`|
-|\`--cluster \<number>\`|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.
-
-```bash
-npx medusa telemetry
-```
-
-#### Options
-
-|Option|Description|
-|---|---|---|
-|\`--enable\`|Enable telemetry (default).|
-|\`--disable\`|Disable telemetry.|
-
-
 # user Command - Medusa CLI Reference
 
 Create a new admin user.
@@ -30976,67 +30980,6 @@ 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 \<host>\`|Set host of the Medusa server.|\`localhost\`|
-|\`-p \<port>\`|Set port of the Medusa server.|\`9000\`|
-
-
-# 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|
-
-
-# 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 [<dir_name> [<starter_url>]]
-```
-
-## 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 \<user>\`|The database user to use for database setup.|
-|\`--db-database \<database>\`|The name of the database used for database setup.|
-|\`--db-pass \<password>\`|The database password to use for database setup.|
-|\`--db-port \<port>\`|The database port to use for database setup.|
-|\`--db-host \<host>\`|The database host to use for database setup.|
-
-
 # build Command - Medusa CLI Reference
 
 Create a standalone build of the Medusa application.
@@ -31099,56 +31042,33 @@ 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.
 
 
-# start Command - Medusa CLI Reference
+# new Command - Medusa CLI Reference
 
-Start the Medusa application in production.
+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 start
+medusa new [<dir_name> [<starter_url>]]
 ```
 
+## 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|Default|
-|---|---|---|---|---|
-|\`-H \<host>\`|Set host of the Medusa server.|\`localhost\`|
-|\`-p \<port>\`|Set port of the Medusa server.|\`9000\`|
-|\`--cluster \<number>\`|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.
-
-```bash
-npx medusa telemetry
-```
-
-#### Options
-
 |Option|Description|
 |---|---|---|
-|\`--enable\`|Enable telemetry (default).|
-|\`--disable\`|Disable telemetry.|
-
-
-# user Command - Medusa CLI Reference
-
-Create a new admin user.
-
-```bash
-npx medusa user --email <email> [--password <password>]
-```
-
-## Options
-
-|Option|Description|Required|Default|
-|---|---|---|---|---|---|---|
-|\`-e \<email>\`|The user's email.|Yes|-|
-|\`-p \<password>\`|The user's password.|No|-|
-|\`-i \<id>\`|The user's ID.|No|An automatically generated ID.|
-|\`--invite\`|Whether to create an invite instead of a user. When using this option, you don't need to specify a password.
-If ran successfully, you'll receive the invite token in the output.|No|\`false\`|
+|\`-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 \<user>\`|The database user to use for database setup.|
+|\`--db-database \<database>\`|The name of the database used for database setup.|
+|\`--db-pass \<password>\`|The database password to use for database setup.|
+|\`--db-port \<port>\`|The database port to use for database setup.|
+|\`--db-host \<host>\`|The database host to use for database setup.|
 
 
 # plugin Commands - Medusa CLI Reference
@@ -31212,6 +31132,90 @@ npx medusa plugin:build
 ```
 
 
+# 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 \<host>\`|Set host of the Medusa server.|\`localhost\`|
+|\`-p \<port>\`|Set port of the Medusa server.|\`9000\`|
+
+
+# start Command - Medusa CLI Reference
+
+Start the Medusa application in production.
+
+```bash
+npx medusa start
+```
+
+## Options
+
+|Option|Description|Default|
+|---|---|---|---|---|
+|\`-H \<host>\`|Set host of the Medusa server.|\`localhost\`|
+|\`-p \<port>\`|Set port of the Medusa server.|\`9000\`|
+|\`--cluster \<number>\`|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|
+
+
+# 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.
+
+```bash
+npx medusa telemetry
+```
+
+#### Options
+
+|Option|Description|
+|---|---|---|
+|\`--enable\`|Enable telemetry (default).|
+|\`--disable\`|Disable telemetry.|
+
+
+# user Command - Medusa CLI Reference
+
+Create a new admin user.
+
+```bash
+npx medusa user --email <email> [--password <password>]
+```
+
+## Options
+
+|Option|Description|Required|Default|
+|---|---|---|---|---|---|---|
+|\`-e \<email>\`|The user's email.|Yes|-|
+|\`-p \<password>\`|The user's password.|No|-|
+|\`-i \<id>\`|The user's ID.|No|An automatically generated ID.|
+|\`--invite\`|Whether to create an invite instead of a user. When using this option, you don't need to specify a password.
+If ran successfully, you'll receive the invite token in the output.|No|\`false\`|
+
+
 # Medusa JS SDK
 
 In this documentation, you'll learn how to install and use Medusa's JS SDK.
@@ -40351,1876 +40355,6 @@ 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.
-
-![Diagram showcasing the product review features in the storefront and admin](https://res.cloudinary.com/dza7lstvk/image/upload/v1741941058/Medusa%20Resources/reviews-overview_nufybf.jpg)
-
-- [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/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/review/models/review.ts` with the following content:
-
-```ts title="src/modules/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/review/service.ts` with the following content:
-
-```ts title="src/modules/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/review/index.ts` with the following content:
-
-```ts title="src/modules/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 review
-```
-
-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/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 `createReview` 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<typeof PostStoreReviewSchema>
-
-export const POST = async (
-  req: AuthenticatedMedusaRequest<PostStoreReviewReq>,
-  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<Review>()
-
-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 (
-        <StatusBadge color={color}>
-          {row.original.status.charAt(0).toUpperCase() + row.original.status.slice(1)}
-          </StatusBadge>
-      )
-    },
-  }),
-  columnHelper.accessor("product", {
-    header: "Product",
-    cell: ({ row }) => {
-      return (
-        <Link
-          to={`/products/${row.original.product_id}`}
-        >
-          {row.original.product?.title}
-        </Link>
-      )
-    },
-  }),
-]
-
-// 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<DataTablePaginationState>({
-    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 (
-    <Container>
-      <DataTable instance={table}>
-        <DataTable.Toolbar className="flex flex-col items-start justify-between gap-2 md:flex-row md:items-center">
-          <Heading>
-            Reviews
-          </Heading>
-        </DataTable.Toolbar>
-        <DataTable.Table />
-        <DataTable.Pagination />
-      </DataTable>
-      <Toaster />
-    </Container>
-  )
-}
-
-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.
-
-![Reviews page showing list of reviews](https://res.cloudinary.com/dza7lstvk/image/upload/v1741935325/Medusa%20Resources/Screenshot_2025-03-14_at_8.54.14_AM_tfhnyu.png)
-
-***
-
-## 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<z.infer<typeof PostAdminUpdateReviewsStatusSchema>>, 
-  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<DataTableRowSelectionState>({})
-```
-
-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"
-<DataTable.CommandBar selectedLabel={(count) => `${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.
-
-![Checkboxes are now shown next to the items in the table, and when you click on them the command bar shows at the bottom of the page with Approve and Reject commands](https://res.cloudinary.com/dza7lstvk/image/upload/v1741937101/Medusa%20Resources/Screenshot_2025-03-14_at_9.24.29_AM_y9vhac.png)
-
-***
-
-## 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/review/service.ts`, add the following methods to the `ProductReviewModuleService` class:
-
-```ts title="src/modules/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<EntityManager>
-  ): Promise<number> { 
-    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<HttpTypes.StoreCustomer | null>(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<HTMLFormElement>) => {
-    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 (
-  <div className="product-page-constraint mt-8">
-    {!showForm && (
-      <div className="flex justify-center">
-        <Button variant="secondary" onClick={() => setShowForm(true)}>Add a review</Button>
-      </div>
-    )}
-    {showForm && (
-      <div className="flex flex-col gap-y-4">
-        <div className="flex flex-col gap-y-2">
-          <span className="text-xl-regular text-ui-fg-base">
-          Add a review
-        </span>
-        
-        <form onSubmit={handleSubmit} className="flex flex-col gap-y-4">
-          <div className="flex flex-col gap-y-2">
-            <Label>Title</Label>
-            <Input name="title" value={title} onChange={(e) => setTitle(e.target.value)} placeholder="Title" />
-          </div>
-          <div className="flex flex-col gap-y-2">
-            <Label>Content</Label>
-            <Textarea name="content" value={content} onChange={(e) => setContent(e.target.value)} placeholder="Content" />
-          </div>
-          <div className="flex flex-col gap-y-2">
-            <Label>Rating</Label>
-            <div className="flex gap-x-1">
-              {Array.from({ length: 5 }).map((_, index) => (
-                <Button key={index} variant="transparent" onClick={(e) => {
-                  e.preventDefault()
-                  setRating(index + 1)
-                }} className="p-0">
-                  {rating >= index + 1 ? <StarSolid className="text-ui-tag-orange-icon" /> : <Star />}
-                </Button>
-              ))}
-            </div>
-          </div>
-          <Button type="submit" disabled={isLoading} variant="primary">Submit</Button>
-        </form>
-        </div>
-      </div>
-    )}
-    <Toaster />
-  </div>
-)
-```
-
-In the return statement, you:
-
-- Show an "Add a review" button. When clicked, the form is displayed.
-- In the form, you show the customer fields for the title, content, and rating for the review. The rating input is displayed as stars, and the customer can click on a star to set the rating.
-- When the form is submitted, you call the `handleSubmit` function to submit the review.
-
-### Display Product Reviews
-
-Now, you'll add the components to display the product reviews and the product review form on the product's page.
-
-Create the file `src/modules/products/components/product-reviews/index.tsx` with the following content:
-
-```tsx title="src/modules/products/components/product-reviews/index.tsx" badgeLabel="Storefront" badgeColor="blue"
-"use client"
-
-import { getProductReviews } from "../../../../lib/data/products"
-import { Star, StarSolid } from "@medusajs/icons"
-import { StoreProductReview } from "../../../../types/global"
-import { Button } from "@medusajs/ui"
-import { useState, useEffect } from "react"
-import ProductReviewsForm from "./form"
-type ProductReviewsProps = {
-  productId: string
-}
-
-export default function ProductReviews({
-  productId,
-}: ProductReviewsProps) {
-  const [page, setPage] = useState(1)
-  const defaultLimit = 10
-  const [reviews, setReviews] = useState<StoreProductReview[]>([])
-  const [rating, setRating] = useState(0)
-  const [hasMoreReviews, setHasMoreReviews] = useState(false)
-  const [count, setCount] = useState(0)
-
-  useEffect(() => {
-    getProductReviews({
-      productId,
-      limit: defaultLimit,
-      offset: (page - 1) * defaultLimit,
-    }).then(({ reviews: paginatedReviews, average_rating, count, limit }) => {
-      setReviews((prev) => {
-        const newReviews = paginatedReviews.filter(
-          (review) => !prev.some((r) => r.id === review.id)
-        )
-        return [...prev, ...newReviews]
-      })
-      setRating(Math.round(average_rating))
-      console.log(count, limit, page, count > limit * page)
-      setHasMoreReviews(count > limit * page)
-      setCount(count)
-    })
-  }, [page])
-
-  // TODO add return statement
-}
-```
-
-You create a `ProductReviews` component that accepts the product's ID as a prop. In the component, you:
-
-- Define state variables related to the reviews and pagination.
-- When the page changes, you fetch the reviews of the product with the given ID.
-
-Before adding the return statement that will show the reviews and the create-review form, you'll add a component that renders a single review.
-
-Add the following component after the `ProductReviews` component:
-
-```tsx title="src/modules/products/components/product-reviews/index.tsx" badgeLabel="Storefront" badgeColor="blue"
-function Review({ review }: { review: StoreProductReview }) {
-  return (
-    <div className="flex flex-col gap-y-2 text-base-regular text-ui-fg-base">
-      <div className="flex gap-x-2 items-center">
-        {review.title && <strong>{review.title}</strong>}
-        <div className="flex gap-x-1">
-          {Array.from({ length: 5 }).map((_, index) => (
-            <span key={index}>
-              {index <= review.rating ? (
-                <StarSolid className="text-ui-tag-orange-icon" />
-              ) : (
-                <Star />
-              )}
-            </span>
-          ))}
-        </div>
-      </div>
-      <div>{review.content}</div>
-      <div className="border-t border-ui-border-base pt-4 text-sm-regular">
-        {review.first_name} {review.last_name}
-      </div>
-    </div>
-  )
-}
-```
-
-You add a `Review` component that accepts a review object as a prop. In the component, you render the review's title, rating, content, and the reviewer's name.
-
-Next, replace the `TODO` in the `ProductReviews` component with the following:
-
-```tsx title="src/modules/products/components/product-reviews/index.tsx" badgeLabel="Storefront" badgeColor="blue"
-return (
-  <div className="product-page-constraint">
-    <div className="flex flex-col items-center text-center mb-16">
-      <span className="text-base-regular text-gray-600 mb-6">
-        Product Reviews
-      </span>
-      <p className="text-2xl-regular text-ui-fg-base max-w-lg">
-        See what our customers are saying about this product.
-      </p>
-      <div className="flex gap-x-2 justify-center items-center">
-        <div className="flex gap-x-2">
-          {Array.from({ length: 5 }).map((_, index) => (
-            <span key={index}>
-              {!rating || index > rating ? (
-                <Star />
-              ) : (
-                <StarSolid className="text-ui-tag-orange-icon" />
-              )}
-            </span>
-          ))}
-        </div>
-        <span className="text-base-regular text-gray-600">
-          {count} reviews
-        </span>
-      </div>
-    </div>
-
-    <div className="grid grid-cols-1 small:grid-cols-2 gap-x-6 gap-y-8">
-      {reviews.map((review) => (
-        <Review key={review.id} review={review} />
-      ))}
-    </div>
-
-    {hasMoreReviews && (
-      <div className="flex justify-center mt-8">
-        <Button variant="secondary" onClick={() => setPage(page + 1)}>
-          Load more reviews
-        </Button>
-      </div>
-    )}
-
-    <ProductReviewsForm productId={productId} />
-  </div>
-)
-```
-
-You show the average rating of the product and the number of reviews. Then, you show every review loaded. You also show a "Load more reviews" button if there are more reviews to load, which changes the `page` and fetches more reviews.
-
-After the reviews, you show the `ProductReviewsForm` component to allow authenticated customers to submit a review.
-
-### Display Product Reviews on Product Page
-
-Finally, you'll customize the product's page to show the `ProductReviews` component.
-
-In `src/modules/products/templates/index.tsx`, import the `ProductReviews` component at the top of the file:
-
-```tsx title="src/modules/products/templates/index.tsx" badgeLabel="Storefront" badgeColor="blue"
-import ProductReviews from "../components/product-reviews"
-```
-
-Then, add the `ProductReviews` component before the `div` wrapping the `RelatedProducts` component:
-
-```tsx title="src/modules/products/templates/index.tsx" badgeLabel="Storefront" badgeColor="blue"
-<div className="content-container my-16 small:my-32">
-  <ProductReviews productId={product.id} />
-</div>
-```
-
-This will show the product reviews after the product's image and details, but before the related products.
-
-### Test the Customizations
-
-To test out both the server and storefront customizations, first, start the Medusa application by running the following command in its directory:
-
-```bash npm2yarn
-npm run dev
-```
-
-Then, start the Next.js Starter Storefront by running the following command in its directory:
-
-```bash npm2yarn
-npm run dev
-```
-
-The storefront will run at `http://localhost:8000`. Open it, then click on Menu -> Store. This will show you the list of products.
-
-If you click on one of them and scroll down below the images, you'll find a section showing the average rating and reviews of the product.
-
-![Product page showing the average rating and reviews of the product](https://res.cloudinary.com/dza7lstvk/image/upload/v1741937534/Medusa%20Resources/Screenshot_2025-03-14_at_9.31.58_AM_tw9vui.png)
-
-To add a review, you first need to log in as a customer. You can do so by clicking on Account at the top right of the page. In the new page, either enter the credentials of the customer you created earlier, or create a new customer.
-
-Afterwards, go back to the product's page, you'll see the "Add a review" button below the reviews.
-
-![Product page showing the Add a review button](https://res.cloudinary.com/dza7lstvk/image/upload/v1741937731/Medusa%20Resources/Screenshot_2025-03-14_at_9.35.11_AM_w1wzdp.png)
-
-If you click on the button, a form will appear where you can fill in the review's details and submit it.
-
-![Product page showing the Add a review form](https://res.cloudinary.com/dza7lstvk/image/upload/v1741938961/Medusa%20Resources/Screenshot_2025-03-14_at_9.55.37_AM_epnfz0.png)
-
-After submitting the review, you can approve or reject it from the Medusa Admin dashboard.
-
-***
-
-## Next Steps
-
-You've now implemented product-review features in Medusa. There's still more that you can implement to enhance these features:
-
-- Link a Review to a customer as you did in [Step 3](#step-3-define-review--product-link) and customize the storefront to show the customer's reviews on their profile.
-- Add a feature to allow customers to upvote or downvote reviews.
-- Allow customers to add images to their reviews.
-
-If you're new to Medusa, check out the [main documentation](https://docs.medusajs.com/docs/learn/index.html.md), where you'll get a more in-depth learning of all the concepts you've used in this guide and more.
-
-To learn more about the commerce features that Medusa provides, check out Medusa's [Commerce Modules](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/index.html.md).
-
-
 # Send Abandoned Cart Notifications in Medusa
 
 In this tutorial, you will learn how to send notifications to customers who have abandoned their carts.
@@ -44643,6 +42777,1876 @@ If you're new to Medusa, check out the [main documentation](https://docs.medusaj
 To learn more about the commerce features that Medusa provides, check out Medusa's [Commerce Modules](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/index.html.md).
 
 
+# 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.
+
+![Diagram showcasing the product review features in the storefront and admin](https://res.cloudinary.com/dza7lstvk/image/upload/v1741941058/Medusa%20Resources/reviews-overview_nufybf.jpg)
+
+- [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/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/review/models/review.ts` with the following content:
+
+```ts title="src/modules/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/review/service.ts` with the following content:
+
+```ts title="src/modules/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/review/index.ts` with the following content:
+
+```ts title="src/modules/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 review
+```
+
+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/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 `createReview` 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<typeof PostStoreReviewSchema>
+
+export const POST = async (
+  req: AuthenticatedMedusaRequest<PostStoreReviewReq>,
+  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<Review>()
+
+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 (
+        <StatusBadge color={color}>
+          {row.original.status.charAt(0).toUpperCase() + row.original.status.slice(1)}
+          </StatusBadge>
+      )
+    },
+  }),
+  columnHelper.accessor("product", {
+    header: "Product",
+    cell: ({ row }) => {
+      return (
+        <Link
+          to={`/products/${row.original.product_id}`}
+        >
+          {row.original.product?.title}
+        </Link>
+      )
+    },
+  }),
+]
+
+// 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<DataTablePaginationState>({
+    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 (
+    <Container>
+      <DataTable instance={table}>
+        <DataTable.Toolbar className="flex flex-col items-start justify-between gap-2 md:flex-row md:items-center">
+          <Heading>
+            Reviews
+          </Heading>
+        </DataTable.Toolbar>
+        <DataTable.Table />
+        <DataTable.Pagination />
+      </DataTable>
+      <Toaster />
+    </Container>
+  )
+}
+
+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.
+
+![Reviews page showing list of reviews](https://res.cloudinary.com/dza7lstvk/image/upload/v1741935325/Medusa%20Resources/Screenshot_2025-03-14_at_8.54.14_AM_tfhnyu.png)
+
+***
+
+## 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<z.infer<typeof PostAdminUpdateReviewsStatusSchema>>, 
+  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<DataTableRowSelectionState>({})
+```
+
+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"
+<DataTable.CommandBar selectedLabel={(count) => `${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.
+
+![Checkboxes are now shown next to the items in the table, and when you click on them the command bar shows at the bottom of the page with Approve and Reject commands](https://res.cloudinary.com/dza7lstvk/image/upload/v1741937101/Medusa%20Resources/Screenshot_2025-03-14_at_9.24.29_AM_y9vhac.png)
+
+***
+
+## 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/review/service.ts`, add the following methods to the `ProductReviewModuleService` class:
+
+```ts title="src/modules/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<EntityManager>
+  ): Promise<number> { 
+    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<HttpTypes.StoreCustomer | null>(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<HTMLFormElement>) => {
+    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 (
+  <div className="product-page-constraint mt-8">
+    {!showForm && (
+      <div className="flex justify-center">
+        <Button variant="secondary" onClick={() => setShowForm(true)}>Add a review</Button>
+      </div>
+    )}
+    {showForm && (
+      <div className="flex flex-col gap-y-4">
+        <div className="flex flex-col gap-y-2">
+          <span className="text-xl-regular text-ui-fg-base">
+          Add a review
+        </span>
+        
+        <form onSubmit={handleSubmit} className="flex flex-col gap-y-4">
+          <div className="flex flex-col gap-y-2">
+            <Label>Title</Label>
+            <Input name="title" value={title} onChange={(e) => setTitle(e.target.value)} placeholder="Title" />
+          </div>
+          <div className="flex flex-col gap-y-2">
+            <Label>Content</Label>
+            <Textarea name="content" value={content} onChange={(e) => setContent(e.target.value)} placeholder="Content" />
+          </div>
+          <div className="flex flex-col gap-y-2">
+            <Label>Rating</Label>
+            <div className="flex gap-x-1">
+              {Array.from({ length: 5 }).map((_, index) => (
+                <Button key={index} variant="transparent" onClick={(e) => {
+                  e.preventDefault()
+                  setRating(index + 1)
+                }} className="p-0">
+                  {rating >= index + 1 ? <StarSolid className="text-ui-tag-orange-icon" /> : <Star />}
+                </Button>
+              ))}
+            </div>
+          </div>
+          <Button type="submit" disabled={isLoading} variant="primary">Submit</Button>
+        </form>
+        </div>
+      </div>
+    )}
+    <Toaster />
+  </div>
+)
+```
+
+In the return statement, you:
+
+- Show an "Add a review" button. When clicked, the form is displayed.
+- In the form, you show the customer fields for the title, content, and rating for the review. The rating input is displayed as stars, and the customer can click on a star to set the rating.
+- When the form is submitted, you call the `handleSubmit` function to submit the review.
+
+### Display Product Reviews
+
+Now, you'll add the components to display the product reviews and the product review form on the product's page.
+
+Create the file `src/modules/products/components/product-reviews/index.tsx` with the following content:
+
+```tsx title="src/modules/products/components/product-reviews/index.tsx" badgeLabel="Storefront" badgeColor="blue"
+"use client"
+
+import { getProductReviews } from "../../../../lib/data/products"
+import { Star, StarSolid } from "@medusajs/icons"
+import { StoreProductReview } from "../../../../types/global"
+import { Button } from "@medusajs/ui"
+import { useState, useEffect } from "react"
+import ProductReviewsForm from "./form"
+type ProductReviewsProps = {
+  productId: string
+}
+
+export default function ProductReviews({
+  productId,
+}: ProductReviewsProps) {
+  const [page, setPage] = useState(1)
+  const defaultLimit = 10
+  const [reviews, setReviews] = useState<StoreProductReview[]>([])
+  const [rating, setRating] = useState(0)
+  const [hasMoreReviews, setHasMoreReviews] = useState(false)
+  const [count, setCount] = useState(0)
+
+  useEffect(() => {
+    getProductReviews({
+      productId,
+      limit: defaultLimit,
+      offset: (page - 1) * defaultLimit,
+    }).then(({ reviews: paginatedReviews, average_rating, count, limit }) => {
+      setReviews((prev) => {
+        const newReviews = paginatedReviews.filter(
+          (review) => !prev.some((r) => r.id === review.id)
+        )
+        return [...prev, ...newReviews]
+      })
+      setRating(Math.round(average_rating))
+      console.log(count, limit, page, count > limit * page)
+      setHasMoreReviews(count > limit * page)
+      setCount(count)
+    })
+  }, [page])
+
+  // TODO add return statement
+}
+```
+
+You create a `ProductReviews` component that accepts the product's ID as a prop. In the component, you:
+
+- Define state variables related to the reviews and pagination.
+- When the page changes, you fetch the reviews of the product with the given ID.
+
+Before adding the return statement that will show the reviews and the create-review form, you'll add a component that renders a single review.
+
+Add the following component after the `ProductReviews` component:
+
+```tsx title="src/modules/products/components/product-reviews/index.tsx" badgeLabel="Storefront" badgeColor="blue"
+function Review({ review }: { review: StoreProductReview }) {
+  return (
+    <div className="flex flex-col gap-y-2 text-base-regular text-ui-fg-base">
+      <div className="flex gap-x-2 items-center">
+        {review.title && <strong>{review.title}</strong>}
+        <div className="flex gap-x-1">
+          {Array.from({ length: 5 }).map((_, index) => (
+            <span key={index}>
+              {index <= review.rating ? (
+                <StarSolid className="text-ui-tag-orange-icon" />
+              ) : (
+                <Star />
+              )}
+            </span>
+          ))}
+        </div>
+      </div>
+      <div>{review.content}</div>
+      <div className="border-t border-ui-border-base pt-4 text-sm-regular">
+        {review.first_name} {review.last_name}
+      </div>
+    </div>
+  )
+}
+```
+
+You add a `Review` component that accepts a review object as a prop. In the component, you render the review's title, rating, content, and the reviewer's name.
+
+Next, replace the `TODO` in the `ProductReviews` component with the following:
+
+```tsx title="src/modules/products/components/product-reviews/index.tsx" badgeLabel="Storefront" badgeColor="blue"
+return (
+  <div className="product-page-constraint">
+    <div className="flex flex-col items-center text-center mb-16">
+      <span className="text-base-regular text-gray-600 mb-6">
+        Product Reviews
+      </span>
+      <p className="text-2xl-regular text-ui-fg-base max-w-lg">
+        See what our customers are saying about this product.
+      </p>
+      <div className="flex gap-x-2 justify-center items-center">
+        <div className="flex gap-x-2">
+          {Array.from({ length: 5 }).map((_, index) => (
+            <span key={index}>
+              {!rating || index > rating ? (
+                <Star />
+              ) : (
+                <StarSolid className="text-ui-tag-orange-icon" />
+              )}
+            </span>
+          ))}
+        </div>
+        <span className="text-base-regular text-gray-600">
+          {count} reviews
+        </span>
+      </div>
+    </div>
+
+    <div className="grid grid-cols-1 small:grid-cols-2 gap-x-6 gap-y-8">
+      {reviews.map((review) => (
+        <Review key={review.id} review={review} />
+      ))}
+    </div>
+
+    {hasMoreReviews && (
+      <div className="flex justify-center mt-8">
+        <Button variant="secondary" onClick={() => setPage(page + 1)}>
+          Load more reviews
+        </Button>
+      </div>
+    )}
+
+    <ProductReviewsForm productId={productId} />
+  </div>
+)
+```
+
+You show the average rating of the product and the number of reviews. Then, you show every review loaded. You also show a "Load more reviews" button if there are more reviews to load, which changes the `page` and fetches more reviews.
+
+After the reviews, you show the `ProductReviewsForm` component to allow authenticated customers to submit a review.
+
+### Display Product Reviews on Product Page
+
+Finally, you'll customize the product's page to show the `ProductReviews` component.
+
+In `src/modules/products/templates/index.tsx`, import the `ProductReviews` component at the top of the file:
+
+```tsx title="src/modules/products/templates/index.tsx" badgeLabel="Storefront" badgeColor="blue"
+import ProductReviews from "../components/product-reviews"
+```
+
+Then, add the `ProductReviews` component before the `div` wrapping the `RelatedProducts` component:
+
+```tsx title="src/modules/products/templates/index.tsx" badgeLabel="Storefront" badgeColor="blue"
+<div className="content-container my-16 small:my-32">
+  <ProductReviews productId={product.id} />
+</div>
+```
+
+This will show the product reviews after the product's image and details, but before the related products.
+
+### Test the Customizations
+
+To test out both the server and storefront customizations, first, start the Medusa application by running the following command in its directory:
+
+```bash npm2yarn
+npm run dev
+```
+
+Then, start the Next.js Starter Storefront by running the following command in its directory:
+
+```bash npm2yarn
+npm run dev
+```
+
+The storefront will run at `http://localhost:8000`. Open it, then click on Menu -> Store. This will show you the list of products.
+
+If you click on one of them and scroll down below the images, you'll find a section showing the average rating and reviews of the product.
+
+![Product page showing the average rating and reviews of the product](https://res.cloudinary.com/dza7lstvk/image/upload/v1741937534/Medusa%20Resources/Screenshot_2025-03-14_at_9.31.58_AM_tw9vui.png)
+
+To add a review, you first need to log in as a customer. You can do so by clicking on Account at the top right of the page. In the new page, either enter the credentials of the customer you created earlier, or create a new customer.
+
+Afterwards, go back to the product's page, you'll see the "Add a review" button below the reviews.
+
+![Product page showing the Add a review button](https://res.cloudinary.com/dza7lstvk/image/upload/v1741937731/Medusa%20Resources/Screenshot_2025-03-14_at_9.35.11_AM_w1wzdp.png)
+
+If you click on the button, a form will appear where you can fill in the review's details and submit it.
+
+![Product page showing the Add a review form](https://res.cloudinary.com/dza7lstvk/image/upload/v1741938961/Medusa%20Resources/Screenshot_2025-03-14_at_9.55.37_AM_epnfz0.png)
+
+After submitting the review, you can approve or reject it from the Medusa Admin dashboard.
+
+***
+
+## Next Steps
+
+You've now implemented product-review features in Medusa. There's still more that you can implement to enhance these features:
+
+- Link a Review to a customer as you did in [Step 3](#step-3-define-review--product-link) and customize the storefront to show the customer's reviews on their profile.
+- Add a feature to allow customers to upvote or downvote reviews.
+- Allow customers to add images to their reviews.
+
+If you're new to Medusa, check out the [main documentation](https://docs.medusajs.com/docs/learn/index.html.md), where you'll get a more in-depth learning of all the concepts you've used in this guide and more.
+
+To learn more about the commerce features that Medusa provides, check out Medusa's [Commerce Modules](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/index.html.md).
+
+
 # Integrations
 
 You can integrate any third-party service to Medusa, including storage services, notification systems, Content-Management Systems (CMS), etc… By integrating third-party services, you build flows and synchronize data around these integrations, making Medusa not only your commerce application, but a middleware layer between your data sources and operations.
@@ -44728,6 +44732,1805 @@ Integrate a search engine to index and search products or other types of data in
 - [Algolia](https://docs.medusajs.com/integrations/guides/algolia/index.html.md)
 
 
+# How to Build Magento Data Migration Plugin
+
+In this tutorial, you'll learn how to build a [plugin](https://docs.medusajs.com/docs/learn/fundamentals/plugins/index.html.md) that migrates data, such as products, from Magento to Medusa.
+
+Magento is known for its customization capabilities. However, its monolithic architecture imposes limitations on business requirements, often forcing development teams to implement hacky workarounds. Over time, these customizations become challenging to maintain, especially as the business scales, leading to increased technical debt and slower feature delivery.
+
+Medusa's modular architecture allows you to build a custom digital commerce platform that meets your business requirements without the limitations of a monolithic system. By migrating from Magento to Medusa, you can take advantage of Medusa's modern technology stack to build a scalable and flexible commerce platform that grows with your business.
+
+By following this tutorial, you'll create a Medusa plugin that migrates data from a Magento server to a Medusa application in minimal time. You can re-use this plugin across multiple Medusa applications, allowing you to adopt Medusa across your projects.
+
+## Summary
+
+### Prerequisites
+
+
+
+This tutorial will teach you how to:
+
+- Install and set up a Medusa application project.
+- Install and set up a Medusa plugin.
+- Implement a Magento Module in the plugin to connect to Magento's APIs and retrieve products.
+  - This guide will only focus on migrating product data from Magento to Medusa. You can extend the implementation to migrate other data, such as customers, orders, and more.
+- Trigger data migration from Magento to Medusa in a scheduled job.
+
+You can follow this tutorial whether you're new to Medusa or an advanced Medusa developer.
+
+![Diagram showcasing the flow of migrating data from Magento to Medusa](https://res.cloudinary.com/dza7lstvk/image/upload/v1739360550/Medusa%20Resources/magento-summary_hsewci.jpg)
+
+[Example Repository](https://github.com/medusajs/examples/tree/main/migrate-from-magento): Find the full code of the guide in this repository. The repository also includes additional features, such as triggering migrations from the Medusa Admin dashboard.
+
+***
+
+## Step 1: Install a Medusa Application
+
+You'll first install a Medusa application that exposes core commerce features through REST APIs. You'll later install the Magento plugin in this application to test it out.
+
+### 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 be asked for the project's name. You can also optionally choose to install the [Next.js starter storefront](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/nextjs-starter/index.html.md).
+
+Afterward, the installation process will start, which will install the Medusa application in a directory with your project's name. If you chose to install the Next.js starter, it'll be installed 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). Refer to the [Medusa Architecture](https://docs.medusajs.com/docs/learn/introduction/architecture/index.html.md) documentation to learn more.
+
+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. Afterward, 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: Install a Medusa Plugin Project
+
+A plugin is a package of reusable Medusa customizations that you can install in any Medusa application. You can add in the plugin [API Routes](https://docs.medusajs.com/docs/learn/fundamentals/api-routes/index.html.md), [Workflows](https://docs.medusajs.com/docs/learn/fundamentals/workflows/index.html.md), and other customizations, as you'll see in this guide. Afterward, you can test it out locally in a Medusa application, then publish it to npm to install and use it in any Medusa application.
+
+Refer to the [Plugins](https://docs.medusajs.com/docs/learn/fundamentals/plugins/index.html.md) documentation to learn more about plugins.
+
+A Medusa plugin is set up in a different project, giving you the flexibility in building and publishing it, while providing you with the tools to test it out locally in a Medusa application.
+
+To create a new Medusa plugin project, run the following command in a directory different than that of the Medusa application:
+
+```bash npm2yarn
+npx create-medusa-app@latest medusa-plugin-magento --plugin
+```
+
+Where `medusa-plugin-magento` is the name of the plugin's directory and the name set in the plugin's `package.json`. So, if you wish to publish it to NPM later under a different name, you can change it here in the command or later in `package.json`.
+
+Once the installation process is done, a new directory named `medusa-plugin-magento` will be created with the plugin project files.
+
+![Directory structure of a plugin project](https://res.cloudinary.com/dza7lstvk/image/upload/v1737019441/Medusa%20Book/project-dir_q4xtri.jpg)
+
+***
+
+## Step 3: Set up Plugin in Medusa Application
+
+Before you start your development, you'll set up the plugin in the Medusa application you installed in the first step. This will allow you to test the plugin during your development process.
+
+In the plugin's directory, run the following command to publish the plugin to the local package registry:
+
+```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, you'll install the plugin in the Medusa application from the local registry.
+
+If you've installed your Medusa project before v2.3.1, you must install [yalc](https://github.com/wclr/yalc) as a development dependency first.
+
+Run the following command in the Medusa application's directory to install the plugin:
+
+```bash title="Medusa application"
+npx medusa plugin:add medusa-plugin-magento
+```
+
+This command installs the plugin in the Medusa application from the local package registry.
+
+Next, register the plugin in the `medusa-config.ts` file of the Medusa application:
+
+```ts title="medusa-config.ts"
+module.exports = defineConfig({
+  // ...
+  plugins: [
+    {
+      resolve: "medusa-plugin-magento",
+      options: {
+        // TODO add options
+      },
+    },
+  ],
+})
+```
+
+You add the plugin to the array of plugins. Later, you'll pass options useful to retrieve data from Magento.
+
+Finally, to ensure your plugin's changes are constantly published to the local registry, simplifying your testing process, keep the following command running in the plugin project during development:
+
+```bash title="Plugin project"
+npx medusa plugin:develop
+```
+
+***
+
+## Step 4: Implement Magento Module
+
+To connect to external applications in Medusa, you create a custom module. 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 this step, you'll create a Magento Module in the Magento plugin that connects to a Magento server's REST APIs and retrieves data, such as products.
+
+Refer to the [Modules](https://docs.medusajs.com/docs/learn/fundamentals/modules/index.html.md) documentation to learn more about modules.
+
+### Create Module Directory
+
+A module is created under the `src/modules` directory of your plugin. So, create the directory `src/modules/magento`.
+
+![Diagram showcasing the module directory to create](https://res.cloudinary.com/dza7lstvk/image/upload/v1739272368/magento-1_ikev4x.jpg)
+
+### Create Module's Service
+
+You define a module's functionalities in a service. A service is a TypeScript or JavaScript class that the module exports. In the service's methods, you can connect to external systems or the database, which is useful if your module defines tables in the database.
+
+In this section, you'll create the Magento Module's service that connects to Magento's REST APIs and retrieves data.
+
+Start by creating the file `src/modules/magento/service.ts` in the plugin with the following content:
+
+![Diagram showcasing the service file to create](https://res.cloudinary.com/dza7lstvk/image/upload/v1739272483/magento-2_ajetpr.jpg)
+
+```ts title="src/modules/magento/service.ts"
+type Options = {
+  baseUrl: string
+  storeCode?: string
+  username: string
+  password: string
+  migrationOptions?: {
+    imageBaseUrl?: string
+  }
+}
+
+export default class MagentoModuleService {
+  private options: Options
+
+  constructor({}, options: Options) {
+    this.options = {
+      ...options,
+      storeCode: options.storeCode || "default",
+    }
+  }
+}
+```
+
+You create a `MagentoModuleService` that has an `options` property to store the module's options. These options include:
+
+- `baseUrl`: The base URL of the Magento server.
+- `storeCode`: The store code of the Magento store, which is `default` by default.
+- `username`: The username of a Magento admin user to authenticate with the Magento server.
+- `password`: The password of the Magento admin user.
+- `migrationOptions`: Additional options useful for migrating data, such as the base URL to use for product images.
+
+The service's constructor accepts as a first parameter the [Module Container](https://docs.medusajs.com/docs/learn/fundamentals/modules/container/index.html.md), which allows you to access resources available for the module. As a second parameter, it accepts the module's options.
+
+### Add Authentication Logic
+
+To authenticate with the Magento server, you'll add a method to the service that retrieves an access token from Magento using the username and password in the options. This access token is used in subsequent requests to the Magento server.
+
+First, add the following property to the `MagentoModuleService` class:
+
+```ts title="src/modules/magento/service.ts"
+export default class MagentoModuleService {
+  private accessToken: {
+    token: string
+    expiresAt: Date
+  }
+  // ...
+}
+```
+
+You add an `accessToken` property to store the access token and its expiration date. The access token Magento returns expires after four hours, so you store the expiration date to know when to refresh the token.
+
+Next, add the following `authenticate` method to the `MagentoModuleService` class:
+
+```ts title="src/modules/magento/service.ts"
+import { MedusaError } from "@medusajs/framework/utils"
+
+export default class MagentoModuleService {
+  // ...
+  async authenticate() {
+    const response = await fetch(`${this.options.baseUrl}/rest/${this.options.storeCode}/V1/integration/admin/token`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({ username: this.options.username, password: this.options.password }),
+    })
+
+    const token = await response.text()
+
+    if (!response.ok) {
+      throw new MedusaError(MedusaError.Types.UNAUTHORIZED, `Failed to authenticate with Magento: ${token}`)
+    }
+
+    this.accessToken = {
+      token: token.replaceAll("\"", ""),
+      expiresAt: new Date(Date.now() + 4 * 60 * 60 * 1000), // 4 hours in milliseconds
+    }
+  }
+}
+```
+
+You create an `authenticate` method that sends a POST request to the Magento server's `/rest/{storeCode}/V1/integration/admin/token` endpoint, passing the username and password in the request body.
+
+If the request is successful, you store the access token and its expiration date in the `accessToken` property. If the request fails, you throw a `MedusaError` with the error message returned by Magento.
+
+Lastly, add an `isAccessTokenExpired` method that checks if the access token has expired:
+
+```ts title="src/modules/magento/service.ts"
+export default class MagentoModuleService {
+  // ...
+  async isAccessTokenExpired(): Promise<boolean> {
+    return !this.accessToken || this.accessToken.expiresAt < new Date()
+  }
+}
+```
+
+In the `isAccessTokenExpired` method, you return a boolean indicating whether the access token has expired. You'll use this in later methods to check if you need to refresh the access token.
+
+### Retrieve Products from Magento
+
+Next, you'll add a method that retrieves products from Magento. Due to limitations in Magento's API that makes it difficult to differentiate between simple products that don't belong to a configurable product and those that do, you'll only retrieve configurable products and their children. You'll also retrieve the configurable attributes of the product, such as color and size.
+
+First, you'll add some types to represent a Magento product and its attributes. Create the file `src/modules/magento/types.ts` in the plugin with the following content:
+
+![Diagram showcasing the types file to create](https://res.cloudinary.com/dza7lstvk/image/upload/v1739346287/Medusa%20Resources/magento-3_fpghog.jpg)
+
+```ts title="src/modules/magento/types.ts"
+export type MagentoProduct = {
+  id: number
+  sku: string
+  name: string
+  price: number
+  status: number
+  // not handling other types
+  type_id: "simple" | "configurable"
+  created_at: string
+  updated_at: string
+  extension_attributes: {
+    category_links: {
+      category_id: string
+    }[]
+    configurable_product_links?: number[] 
+    configurable_product_options?: {
+      id: number
+      attribute_id: string
+      label: string
+      position: number
+      values: {
+        value_index: number
+      }[]
+    }[]
+  }
+  media_gallery_entries: {
+    id: number
+    media_type: string
+    label: string
+    position: number
+    disabled: boolean
+    types: string[]
+    file: string
+  }[]
+  custom_attributes: {
+    attribute_code: string
+    value: string
+  }[]
+  // added by module
+  children?: MagentoProduct[]
+}
+
+export type MagentoAttribute = {
+  attribute_code: string
+  attribute_id: number
+  default_frontend_label: string
+  options: {
+    label: string
+    value: string
+  }[]
+}
+
+export type MagentoPagination = {
+  search_criteria: {
+    filter_groups: [],
+    page_size: number
+    current_page: number
+  }
+  total_count: number
+}
+
+export type MagentoPaginatedResponse<TData> = {
+  items: TData[]
+} & MagentoPagination
+```
+
+You define the following types:
+
+- `MagentoProduct`: Represents a product in Magento.
+- `MagentoAttribute`: Represents an attribute in Magento.
+- `MagentoPagination`: Represents the pagination information returned by Magento's API.
+- `MagentoPaginatedResponse`: Represents a paginated response from Magento's API for a specific item type, such as products.
+
+Next, add the `getProducts` method to the `MagentoModuleService` class:
+
+```ts title="src/modules/magento/service.ts"
+export default class MagentoModuleService {
+  // ...
+  async getProducts(options?: {
+    currentPage?: number
+    pageSize?: number
+  }): Promise<{
+    products: MagentoProduct[]
+    attributes: MagentoAttribute[]
+    pagination: MagentoPagination
+  }> {
+    const { currentPage = 1, pageSize = 100 } = options || {}
+    const getAccessToken = await this.isAccessTokenExpired()
+    if (getAccessToken) {
+      await this.authenticate()
+    }
+
+    // TODO prepare query params
+  }
+}
+```
+
+The `getProducts` method receives an optional `options` object with the `currentPage` and `pageSize` properties. So far, you check if the access token has expired and, if so, retrieve a new one using the `authenticate` method.
+
+Next, you'll prepare the query parameters to pass in the request that retrieves products. Replace the `TODO` with the following:
+
+```ts title="src/modules/magento/service.ts"
+const searchQuery = new URLSearchParams()
+// pass pagination parameters
+searchQuery.append(
+  "searchCriteria[currentPage]", 
+  currentPage?.toString() || "1"
+)
+searchQuery.append(
+  "searchCriteria[pageSize]", 
+  pageSize?.toString() || "100"
+)
+
+// retrieve only configurable products
+searchQuery.append(
+  "searchCriteria[filter_groups][1][filters][0][field]", 
+  "type_id"
+)
+searchQuery.append(
+  "searchCriteria[filter_groups][1][filters][0][value]", 
+  "configurable"
+)
+searchQuery.append(
+  "searchCriteria[filter_groups][1][filters][0][condition_type]", 
+  "in"
+)
+
+// TODO send request to retrieve products
+```
+
+You create a `searchQuery` object to store the query parameters to pass in the request. Then, you add the pagination parameters and the filter to retrieve only configurable products.
+
+Next, you'll send the request to retrieve products from Magento. Replace the `TODO` with the following:
+
+```ts title="src/modules/magento/service.ts"
+const { items: products, ...pagination }: MagentoPaginatedResponse<MagentoProduct> = await fetch(
+  `${this.options.baseUrl}/rest/${this.options.storeCode}/V1/products?${searchQuery}`, 
+  {
+    headers: {
+      "Authorization": `Bearer ${this.accessToken.token}`,
+    },
+  }
+).then((res) => res.json())
+.catch((err) => {
+  console.log(err)
+  throw new MedusaError(
+    MedusaError.Types.INVALID_DATA, 
+    `Failed to get products from Magento: ${err.message}`
+  )
+})
+
+// TODO prepare products
+```
+
+You send a `GET` request to the Magento server's `/rest/{storeCode}/V1/products` endpoint, passing the query parameters in the URL. You also pass the access token in the `Authorization` header.
+
+Next, you'll prepare the retrieved products by retrieving their children, configurable attributes, and modifying their image URLs. Replace the `TODO` with the following:
+
+```ts title="src/modules/magento/service.ts"
+const attributeIds: string[] = []
+
+await promiseAll(
+  products.map(async (product) => {
+    // retrieve its children
+    product.children = await fetch(
+      `${this.options.baseUrl}/rest/${this.options.storeCode}/V1/configurable-products/${product.sku}/children`,
+      {
+        headers: {
+          "Authorization": `Bearer ${this.accessToken.token}`,
+        },
+      }
+    ).then((res) => res.json())
+    .catch((err) => {
+      throw new MedusaError(
+        MedusaError.Types.INVALID_DATA, 
+        `Failed to get product children from Magento: ${err.message}`
+      )
+    })
+
+    product.media_gallery_entries = product.media_gallery_entries.map(
+      (entry) => ({
+        ...entry,
+        file: `${this.options.migrationOptions?.imageBaseUrl}${entry.file}`,
+      }
+    ))
+
+    attributeIds.push(...(
+      product.extension_attributes.configurable_product_options?.map(
+        (option) => option.attribute_id) || []
+      )
+    )
+  })
+)
+
+// TODO retrieve attributes
+```
+
+You loop over the retrieved products and retrieve their children using the `/rest/{storeCode}/V1/configurable-products/{sku}/children` endpoint. You also modify the image URLs to use the base URL in the migration options, if provided.
+
+In addition, you store the IDs of the configurable products' attributes in the `attributeIds` array. You'll add a method that retrieves these attributes.
+
+Add the new method `getAttributes` to the `MagentoModuleService` class:
+
+```ts title="src/modules/magento/service.ts"
+export default class MagentoModuleService {
+  // ...
+  async getAttributes({
+    ids,
+  }: {
+    ids: string[]
+  }): Promise<MagentoAttribute[]> {
+    const getAccessToken = await this.isAccessTokenExpired()
+    if (getAccessToken) {
+      await this.authenticate()
+    }
+
+    // filter by attribute IDs
+    const searchQuery = new URLSearchParams()
+    searchQuery.append(
+      "searchCriteria[filter_groups][0][filters][0][field]", 
+      "attribute_id"
+    )
+    searchQuery.append(
+      "searchCriteria[filter_groups][0][filters][0][value]", 
+      ids.join(",")
+    )
+    searchQuery.append(
+      "searchCriteria[filter_groups][0][filters][0][condition_type]", 
+      "in"
+    )
+
+    const { 
+      items: attributes,
+    }: MagentoPaginatedResponse<MagentoAttribute> = await fetch(
+      `${this.options.baseUrl}/rest/${this.options.storeCode}/V1/products/attributes?${searchQuery}`, 
+      {
+        headers: {
+          "Authorization": `Bearer ${this.accessToken.token}`,
+        },
+      }
+    ).then((res) => res.json())
+    .catch((err) => {
+      throw new MedusaError(
+        MedusaError.Types.INVALID_DATA, 
+        `Failed to get attributes from Magento: ${err.message}`
+      )
+    })
+
+    return attributes
+  }
+}
+```
+
+The `getAttributes` method receives an object with the `ids` property, which is an array of attribute IDs. You check if the access token has expired and, if so, retrieve a new one using the `authenticate` method.
+
+Next, you prepare the query parameters to pass in the request to retrieve attributes. You send a `GET` request to the Magento server's `/rest/{storeCode}/V1/products/attributes` endpoint, passing the query parameters in the URL. You also pass the access token in the `Authorization` header.
+
+Finally, you return the retrieved attributes.
+
+Now, go back to the `getProducts` method and replace the `TODO` with the following:
+
+```ts title="src/modules/magento/service.ts"
+const attributes = await this.getAttributes({ ids: attributeIds })
+    
+return { products, attributes, pagination }
+```
+
+You retrieve the configurable products' attributes using the `getAttributes` method and return the products, attributes, and pagination information.
+
+You'll use this method in a later step to retrieve products from Magento.
+
+### 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/magento/index.ts` with the following content:
+
+![Diagram showcasing the module definition file to create](https://res.cloudinary.com/dza7lstvk/image/upload/v1739348316/Medusa%20Resources/magento-4_bmepvh.jpg)
+
+```ts title="src/modules/magento/index.ts"
+import { Module } from "@medusajs/framework/utils"
+import MagentoModuleService from "./service"
+
+export const MAGENTO_MODULE = "magento"
+
+export default Module(MAGENTO_MODULE, {
+  service: MagentoModuleService,
+})
+```
+
+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 `magento`.
+2. An object with a required property `service` indicating the module's service.
+
+You'll later use the module's service to retrieve products from Magento.
+
+### Pass Options to Plugin
+
+As mentioned earlier when you registered the plugin in the Medusa Application's `medusa-config.ts` file, you can pass options to the plugin. These options are then passed to the modules in the plugin.
+
+So, add the following options to the plugin's registration in the `medusa-config.ts` file of the Medusa application:
+
+```ts title="medusa-config.ts"
+module.exports = defineConfig({
+  // ...
+  plugins: [
+    {
+      resolve: "medusa-plugin-magento",
+      options: {
+        baseUrl: process.env.MAGENTO_BASE_URL,
+        username: process.env.MAGENTO_USERNAME,
+        password: process.env.MAGENTO_PASSWORD,
+        migrationOptions: {
+          imageBaseUrl: process.env.MAGENTO_IMAGE_BASE_URL,
+        },
+      },
+    },
+  ],
+})
+```
+
+You pass the options that you defined in the `MagentoModuleService`. Make sure to also set their environment variables in the `.env` file:
+
+```bash
+MAGENTO_BASE_URL=https://magento.example.com
+MAGENTO_USERNAME=admin
+MAGENTO_PASSWORD=password
+MAGENTO_IMAGE_BASE_URL=https://magento.example.com/pub/media/catalog/product
+```
+
+Where:
+
+- `MAGENTO_BASE_URL`: The base URL of the Magento server. It can also be a local URL, such as `http://localhost:8080`.
+- `MAGENTO_USERNAME`: The username of a Magento admin user to authenticate with the Magento server.
+- `MAGENTO_PASSWORD`: The password of the Magento admin user.
+- `MAGENTO_IMAGE_BASE_URL`: The base URL to use for product images. Magento stores product images in the `pub/media/catalog/product` directory, so you can reference them directly or use a CDN URL. If the URLs of product images in the Medusa server already have a different base URL, you can omit this option.
+
+Medusa supports integrating third-party services, such as [S3](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/infrastructure-modules/file/s3/index.html.md), in a File Module Provider. Refer to the [File Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/infrastructure-modules/file/index.html.md) documentation to find other module providers and how to create a custom provider.
+
+You can now use the Magento Module to migrate data, which you'll do in the next steps.
+
+***
+
+## Step 5: Build Product Migration Workflow
+
+In this section, you'll add the feature to migrate products from Magento to Medusa. To implement this feature, you'll use a workflow.
+
+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 API route or a scheduled job.
+
+By implementing the migration feature in a workflow, you ensure that the data remains consistent and that the migration process can be rolled back if an error occurs.
+
+Refer to the [Workflows](https://docs.medusajs.com/docs/learn/fundamentals/workflows/index.html.md) documentation to learn more about workflows.
+
+### Workflow Steps
+
+The workflow you'll create will have the following steps:
+
+- [getMagentoProductsStep](#getMagentoProductsStep): Retrieve products from Magento using the Magento Module.
+- [useQueryGraphStep](https://docs.medusajs.com/references/helper-steps/useQueryGraphStep/index.html.md): Retrieve Medusa store details, which you'll need when creating the products.
+- [useQueryGraphStep](https://docs.medusajs.com/references/helper-steps/useQueryGraphStep/index.html.md): Retrieve a shipping profile, which you'll associate the created products with.
+- [useQueryGraphStep](https://docs.medusajs.com/references/helper-steps/useQueryGraphStep/index.html.md): Retrieve Magento products that are already in Medusa to update them, instead of creating them.
+- [createProductsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createProductsWorkflow/index.html.md): Create products in the Medusa application.
+- [updateProductsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateProductsWorkflow/index.html.md): Update existing products in the Medusa application.
+
+You only need to implement the `getMagentoProductsStep` step, which retrieves the products from Magento. The other steps and workflows are provided by Medusa's `@medusajs/medusa/core-flows` package.
+
+### getMagentoProductsStep
+
+The first step of the workflow retrieves and returns the products from Magento.
+
+In your plugin, create the file `src/workflows/steps/get-magento-products.ts` with the following content:
+
+![Diagram showcasing the get-magento-products file to create](https://res.cloudinary.com/dza7lstvk/image/upload/v1739349590/Medusa%20Resources/magento-5_ueb4wn.jpg)
+
+```ts title="src/workflows/steps/get-magento-products.ts"
+import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk"
+import { MAGENTO_MODULE } from "../../modules/magento"
+import MagentoModuleService from "../../modules/magento/service"
+
+type GetMagentoProductsInput = {
+  currentPage: number
+  pageSize: number
+}
+
+export const getMagentoProductsStep = createStep(
+  "get-magento-products",
+  async ({ currentPage, pageSize }: GetMagentoProductsInput, { container }) => {
+    const magentoModuleService: MagentoModuleService = 
+      container.resolve(MAGENTO_MODULE)
+
+    const response = await magentoModuleService.getProducts({
+      currentPage,
+      pageSize,
+    })
+
+    return new StepResponse(response)
+  }
+)
+```
+
+You create a step using `createStep` from the Workflows SDK. It accepts two parameters:
+
+1. The step's name, which is `get-magento-products`.
+2. An async function that executes the step's logic. The function receives two parameters:
+   - The input data for the step, which in this case is the pagination parameters.
+   - An object holding the workflow's context, including the [Medusa Container](https://docs.medusajs.com/docslearn/fundamentals/medusa-container/index.html.md) that allows you to resolve Framework and commerce tools.
+
+In the step function, you resolve the Magento Module's service from the container, then use its `getProducts` method to retrieve the products from Magento.
+
+Steps that return data must return them in a `StepResponse` instance. The `StepResponse` constructor accepts as a parameter the data to return.
+
+### Create migrateProductsFromMagentoWorkflow
+
+You'll now create the workflow that migrates products from Magento using the step you created and steps from Medusa's `@medusajs/medusa/core-flows` package.
+
+In your plugin, create the file `src/workflows/migrate-products-from-magento.ts` with the following content:
+
+![Diagram showcasing the migrate-products-from-magento file to create](https://res.cloudinary.com/dza7lstvk/image/upload/v1739349820/Medusa%20Resources/magento-6_jjdaxj.jpg)
+
+```ts title="src/workflows/migrate-products-from-magento.ts"
+import { 
+  createWorkflow, transform, WorkflowResponse,
+} from "@medusajs/framework/workflows-sdk"
+import { 
+  CreateProductWorkflowInputDTO, UpsertProductDTO,
+} from "@medusajs/framework/types"
+import { 
+  createProductsWorkflow, 
+  updateProductsWorkflow, 
+  useQueryGraphStep,
+} from "@medusajs/medusa/core-flows"
+import { getMagentoProductsStep } from "./steps/get-magento-products"
+
+type MigrateProductsFromMagentoWorkflowInput = {
+  currentPage: number
+  pageSize: number
+}
+
+export const migrateProductsFromMagentoWorkflowId = 
+  "migrate-products-from-magento"
+
+export const migrateProductsFromMagentoWorkflow = createWorkflow(
+  {
+    name: migrateProductsFromMagentoWorkflowId,
+    retentionTime: 10000,
+    store: true,
+  },
+  (input: MigrateProductsFromMagentoWorkflowInput) => {
+    const { pagination, products, attributes } = getMagentoProductsStep(
+      input
+    )
+    // TODO prepare data to create and update products
+  }
+)
+```
+
+You create a workflow using `createWorkflow` from the Workflows SDK. It accepts two parameters:
+
+1. An object with the workflow's configuration, including the name and whether to store the workflow's executions. You enable storing the workflow execution so that you can view it later in the Medusa Admin dashboard.
+2. A worflow constructor function, which holds the workflow's implementation. The function receives the input data for the workflow, which is the pagination parameters.
+
+In the workflow constructor function, you use the `getMagentoProductsStep` step to retrieve the products from Magento, passing it the pagination parameters from the workflow's input.
+
+Next, you'll retrieve the Medusa store details and shipping profiles. These are necessary to prepare the data of the products to create or update.
+
+Replace the `TODO` in the workflow function with the following:
+
+```ts title="src/workflows/migrate-products-from-magento.ts"
+const { data: stores } = useQueryGraphStep({
+  entity: "store",
+  fields: ["supported_currencies.*", "default_sales_channel_id"],
+  pagination: {
+    take: 1,
+    skip: 0,
+  },
+})
+
+const { data: shippingProfiles } = useQueryGraphStep({
+  entity: "shipping_profile",
+  fields: ["id"],
+  pagination: {
+    take: 1,
+    skip: 0,
+  },
+}).config({ name: "get-shipping-profiles" })
+
+// TODO retrieve existing products
+```
+
+You use the `useQueryGraphStep` step to retrieve the store details and shipping profiles. `useQueryGraphStep` is a Medusa step that wraps [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), allowing you to use it in a workflow. Query is a tool that retrieves data across modules.
+
+Whe retrieving the store details, you specifically retrieve its supported currencies and default sales channel ID. You'll associate the products with the store's default sales channel, and set their variant prices in the supported currencies. You'll also associate the products with a shipping profile.
+
+Next, you'll retrieve products that were previously migrated from Magento to determine which products to create or update. Replace the `TODO` with the following:
+
+```ts title="src/workflows/migrate-products-from-magento.ts"
+const externalIdFilters = transform({
+  products,
+}, (data) => {
+  return data.products.map((product) => product.id.toString())
+})
+
+const { data: existingProducts } = useQueryGraphStep({
+  entity: "product",
+  fields: ["id", "external_id", "variants.id", "variants.metadata"],
+  filters: {
+    external_id: externalIdFilters,
+  },
+}).config({ name: "get-existing-products" })
+
+// TODO prepare products to create or update
+```
+
+Since the Medusa application creates an internal representation of the workflow's constructor function, you can't manipulate data directly, as variables have no value while creating the internal representation.
+
+Refer to the [Workflows](https://docs.medusajs.com/docs/learn/fundamentals/workflows/constructor-constraints/index.html.md) documentation to learn more about the workflow constructor function's constraints.
+
+Instead, you can manipulate data in a workflow's constructor function using `transform` from the Workflows SDK. `transform` is a function that accepts two parameters:
+
+- The data to transform, which in this case is the Magento products.
+- A function that transforms the data. The function receives the data passed in the first parameter and returns the transformed data.
+
+In the transformation function, you return the IDs of the Magento products. Then, you use the `useQueryGraphStep` to retrieve products in the Medusa application that have an `external_id` property matching the IDs of the Magento products. You'll use this property to store the IDs of the products in Magento.
+
+Next, you'll prepare the data to create and update the products. Replace the `TODO` in the workflow function with the following:
+
+```ts title="src/workflows/migrate-products-from-magento.ts" highlights={prepareHighlights}
+const { 
+  productsToCreate,
+  productsToUpdate,
+} = transform({
+  products,
+  attributes,
+  stores,
+  shippingProfiles,
+  existingProducts,
+}, (data) => {
+  const productsToCreate = new Map<string, CreateProductWorkflowInputDTO>()
+  const productsToUpdate = new Map<string, UpsertProductDTO>()
+
+  data.products.forEach((magentoProduct) => {
+    const productData: CreateProductWorkflowInputDTO | UpsertProductDTO = {
+      title: magentoProduct.name,
+      description: magentoProduct.custom_attributes.find(
+        (attr) => attr.attribute_code === "description"
+      )?.value,
+      status: magentoProduct.status === 1 ? "published" : "draft",
+      handle: magentoProduct.custom_attributes.find(
+        (attr) => attr.attribute_code === "url_key"
+      )?.value,
+      external_id: magentoProduct.id.toString(),
+      thumbnail: magentoProduct.media_gallery_entries.find(
+        (entry) => entry.types.includes("thumbnail")
+      )?.file,
+      sales_channels: [{
+        id: data.stores[0].default_sales_channel_id,
+      }],
+      shipping_profile_id: data.shippingProfiles[0].id,
+    }
+    const existingProduct = data.existingProducts.find((p) => p.external_id === productData.external_id)
+
+    if (existingProduct) {
+      productData.id = existingProduct.id
+    }
+
+    productData.options = magentoProduct.extension_attributes.configurable_product_options?.map((option) => {
+      const attribute = data.attributes.find((attr) => attr.attribute_id === parseInt(option.attribute_id))
+      return {
+        title: option.label,
+        values: attribute?.options.filter((opt) => {
+          return option.values.find((v) => v.value_index === parseInt(opt.value))
+        }).map((opt) => opt.label) || [],
+      }
+    }) || []
+
+    productData.variants = magentoProduct.children?.map((child) => {
+      const childOptions: Record<string, string> = {}
+
+      child.custom_attributes.forEach((attr) => {
+        const attrData = data.attributes.find((a) => a.attribute_code === attr.attribute_code)
+        if (!attrData) {
+          return
+        }
+
+        childOptions[attrData.default_frontend_label] = attrData.options.find((opt) => opt.value === attr.value)?.label || ""
+      })
+
+      const variantExternalId = child.id.toString()
+      const existingVariant = existingProduct.variants.find((v) => v.metadata.external_id === variantExternalId)
+
+      return {
+        title: child.name,
+        sku: child.sku,
+        options: childOptions,
+        prices: data.stores[0].supported_currencies.map(({ currency_code }) => {
+          return {
+            amount: child.price,
+            currency_code,
+          }
+        }),
+        metadata: {
+          external_id: variantExternalId,
+        },
+        id: existingVariant?.id,
+      }
+    })
+
+    productData.images = magentoProduct.media_gallery_entries.filter((entry) => !entry.types.includes("thumbnail")).map((entry) => {
+      return {
+        url: entry.file,
+        metadata: {
+          external_id: entry.id.toString(),
+        },
+      }
+    })
+
+    if (productData.id) {
+      productsToUpdate.set(existingProduct.id, productData)
+    } else {
+      productsToCreate.set(productData.external_id!, productData)
+    }
+  })
+
+  return {
+    productsToCreate: Array.from(productsToCreate.values()),
+    productsToUpdate: Array.from(productsToUpdate.values()),
+  }
+})
+
+// TODO create and update products
+```
+
+You use `transform` again to prepare the data to create and update the products in the Medusa application. For each Magento product, you map its equivalent Medusa product's data:
+
+- You set the product's general details, such as the title, description, status, handle, external ID, and thumbnail using the Magento product's data and custom attributes.
+- You associate the product with the default sales channel and shipping profile retrieved previously.
+- You map the Magento product's configurable product options to Medusa product options. In Medusa, a product's option has a label, such as "Color", and values, such as "Red". To map the option values, you use the attributes retrieved from Magento.
+- You map the Magento product's children to Medusa product variants. For the variant options, you pass an object whose keys is the option's label, such as "Color", and values is the option's value, such as "Red". For the prices, you set the variant's price based on the Magento child's price for every supported currency in the Medusa store. Also, you set the Magento child product's ID in the Medusa variant's `metadata.external_id` property.
+- You map the Magento product's media gallery entries to Medusa product images. You filter out the thumbnail image and set the URL and the Magento image's ID in the Medusa image's `metadata.external_id` property.
+
+In addition, you use the existing products retrieved in the previous step to determine whether a product should be created or updated. If there's an existing product whose `external_id` matches the ID of the magento product, you set the existing product's ID in the `id` property of the product to be updated. You also do the same for its variants.
+
+Finally, you return the products to create and update.
+
+The last steps of the workflow is to create and update the products. Replace the `TODO` in the workflow function with the following:
+
+```ts title="src/workflows/migrate-products-from-magento.ts"
+createProductsWorkflow.runAsStep({
+  input: {
+    products: productsToCreate,
+  },
+})
+
+updateProductsWorkflow.runAsStep({
+  input: {
+    products: productsToUpdate,
+  },
+})
+
+return new WorkflowResponse(pagination)
+```
+
+You use the `createProductsWorkflow` and `updateProductsWorkflow` workflows from Medusa's `@medusajs/medusa/core-flows` package to create and update the products in the Medusa application.
+
+Workflows must return an instance of `WorkflowResponse`, passing as a parameter the data to return to the workflow's executor. This workflow returns the pagination parameters, allowing you to paginate the product migration process.
+
+You can now use this workflow to migrate products from Magento to Medusa. You'll learn how to use it in the next steps.
+
+***
+
+## Step 6: Schedule Product Migration
+
+There are many ways to execute tasks asynchronously in Medusa, such as [scheduling a job](https://docs.medusajs.com/docs/learn/fundamentals/scheduled-jobs/index.html.md) or [handling emitted events](https://docs.medusajs.com/docs/learn/fundamentals/events-and-subscribers/index.html.md).
+
+In this guide, you'll learn how to schedule the product migration at a specified interval using a scheduled job. A scheduled job is an asynchronous function that the Medusa application runs at the interval you specify during the Medusa application's runtime.
+
+Refer to the [Scheduled Jobs](https://docs.medusajs.com/docs/learn/fundamentals/scheduled-jobs/index.html.md) documentation to learn more about scheduled jobs.
+
+To create a scheduled job, in your plugin, create the file `src/jobs/migrate-magento.ts` with the following content:
+
+![Diagram showcasing the migrate-magento file to create](https://res.cloudinary.com/dza7lstvk/image/upload/v1739358924/Medusa%20Resources/magento-7_rqoodo.jpg)
+
+```ts title="src/jobs/migrate-magento.ts"
+import { MedusaContainer } from "@medusajs/framework/types"
+import { migrateProductsFromMagentoWorkflow } from "../workflows"
+
+export default async function migrateMagentoJob(
+  container: MedusaContainer
+) {
+  const logger = container.resolve("logger")
+    logger.info("Migrating products from Magento...")
+    
+    let currentPage = 0
+    const pageSize = 100
+    let totalCount = 0
+  
+    do {
+      currentPage++
+  
+      const { 
+        result: pagination,
+      } = await migrateProductsFromMagentoWorkflow(container).run({
+        input: {
+          currentPage,
+          pageSize,
+        },
+      })
+  
+      totalCount = pagination.total_count
+    } while (currentPage * pageSize < totalCount)
+  
+    logger.info("Finished migrating products from Magento")
+}
+
+export const config = {
+  name: "migrate-magento-job",
+  schedule: "0 0 * * *",
+}
+```
+
+A scheduled job file must export:
+
+- An asynchronous function that executes the job's logic. The function receives the [Medusa container](https://docs.medusajs.com/docs/learn/fundamentals/medusa-container/index.html.md) as a parameter.
+- An object with the job's configuration, including the name and the schedule. The schedule is a cron job pattern as a string.
+
+In the job function, you resolve the [logger](https://docs.medusajs.com/docs/learn/debugging-and-testing/logging/index.html.md) from the container to log messages. Then, you paginate the product migration process by running the `migrateProductsFromMagentoWorkflow` workflow at each page until you've migrated all products. You use the pagination result returned by the workflow to determine whether there are more products to migrate.
+
+Based on the job's configurations, the Medusa application will run the job at midnight every day.
+
+### Test it Out
+
+To test out this scheduled job, first, change the configuration to run the job every minute:
+
+```ts title="src/jobs/migrate-magento.ts"
+export const config = {
+  // ...
+  schedule: "* * * * *",
+}
+```
+
+Then, make sure to run the `plugin:develop` command in the plugin if you haven't already:
+
+```bash
+npx medusa plugin:develop
+```
+
+This ensures that the plugin's latest changes are reflected in the Medusa application.
+
+Finally, start the Medusa application that the plugin is installed in:
+
+```bash npm2yarn
+npm run dev
+```
+
+After a minute, you'll see a message in the terminal indicating that the migration started:
+
+```plain title="Terminal"
+info: Migrating products from Magento...
+```
+
+Once the migration is done, you'll see the following message:
+
+```plain title="Terminal"
+info: Finished migrating products from Magento
+```
+
+To confirm that the products were migrated, open the Medusa Admin dashboard at `http://localhost:9000/app` and log in. Then, click on Products in the sidebar. You'll see your magento products in the list of products.
+
+![Click on products at the sidebar on the right, then view the products in the table in the middle.](https://res.cloudinary.com/dza7lstvk/image/upload/v1739359394/Medusa%20Resources/Screenshot_2025-02-12_at_1.22.44_PM_uva98i.png)
+
+***
+
+## Next Steps
+
+You've now implemented the logic to migrate products from Magento to Medusa. You can re-use the plugin across Medusa applications. You can also expand on the plugin to:
+
+- Migrate other entities, such as orders, customers, and categories. Migrating other entities follows the same pattern as migrating products, using workflows and scheduled jobs. You only need to format the data to be migrated as needed.
+- Allow triggering migrations from the Medusa Admin dashboard using [Admin Customizations](https://docs.medusajs.com/docs/learn/fundamentals/admin/index.html.md). This feature is available in the [Example Repository](https://github.com/medusajs/example-repository/tree/main/src/admin).
+
+If you're new to Medusa, check out the [main documentation](https://docs.medusajs.com/docs/learn/index.html.md), where you'll get a more in-depth learning of all the concepts you've used in this guide and more.
+
+To learn more about the commerce features that Medusa provides, check out Medusa's [Commerce Modules](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/index.html.md).
+
+
+# Integrate Medusa with Resend (Email Notifications)
+
+In this guide, you'll learn how to integrate Medusa with Resend.
+
+When you install a Medusa application, you get a fully-fledged commerce platform with a Framework for customization. Medusa's architecture supports integrating third-party services, such as an email service, that allow you to build your unique requirements around core commerce flows.
+
+[Resend](https://resend.com/docs/introduction) is an email service with an intuitive developer experience to send emails from any application type, including Node.js servers. By integrating Resend with Medusa, you can build flows to send an email when a commerce operation is performed, such as when an order is placed.
+
+This guide will teach you how to:
+
+- Install and set up Medusa.
+- Integrate Resend into Medusa for sending emails.
+- Build a flow to send an email with Resend when a customer places an order.
+
+You can follow this guide whether you're new to Medusa or an advanced Medusa developer.
+
+[Example Repository](https://github.com/medusajs/examples/tree/main/resend-integration): Find the full code of the guide in this repository.
+
+***
+
+## 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 you're asked whether you want to install the Next.js storefront, choose `Y` for 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 storefront in a 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 about Medusa's architecture in [this 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 credential and submit the form. Afterwards, you can login with the new user and explore the dashboard.
+
+The Next.js storefront is also running at `http://localhost:8000`.
+
+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: Prepare Resend Account
+
+If you don't have a Resend Account, create one on [their website](https://resend.com/emails).
+
+In addition, Resend allows you to send emails from the address `onboarding@resend.dev` only to your account's email, which is useful for development purposes. If you have a custom domain to send emails from, add it to your Resend account's domains:
+
+1. Go to Domains from the sidebar.
+2. Click on Add Domain.
+
+![Click on Domains in the sidebar then on the Add Domain button in the middle of the page.](https://res.cloudinary.com/dza7lstvk/image/upload/v1732523238/Medusa%20Resources/Screenshot_2024-11-25_at_10.18.11_AM_pmqgtv.png)
+
+3\. In the form that opens, enter your domain name and select a region close to your users, then click Add.
+
+![A pop-up window with Domain and Region fields.](https://res.cloudinary.com/dza7lstvk/image/upload/v1732523280/Medusa%20Resources/Screenshot_2024-11-25_at_10.18.52_AM_sw2pr4.png)
+
+4\. In the domain's details page that opens, you'll find DNS records to add to your DNS provider. After you add them, click on Verify DNS Records. You can start sending emails from your custom domain once it's verified.
+
+The steps to add DNS records are different for each provider, so refer to your provider's documentation or knowledge base for more details.
+
+![The DNS records to add are in a table under the DNS Records section. Once added, click the Verify DNS Records button at the top right.](https://res.cloudinary.com/dza7lstvk/image/upload/v1732523394/Medusa%20Resources/Screenshot_2024-11-25_at_10.20.56_AM_ktvbse.png)
+
+You also need an API key to connect to your Resend account from Medusa, but you'll create that one in a later section.
+
+***
+
+## Step 3: Install Resend Dependencies
+
+In this step, you'll install two packages useful for your Resend integration:
+
+1. `resend`, which is the Resend SDK:
+
+```bash npm2yarn
+npm install resend
+```
+
+2\. [react-email](https://github.com/resend/react-email),  which is a package created by Resend to create email templates with React:
+
+```bash npm2yarn
+npm install @react-email/components -E
+```
+
+You'll use these packages in the next steps.
+
+***
+
+## Step 4: Create Resend Module Provider
+
+To integrate third-party services into Medusa, you create a custom module. A module is a re-usable 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.
+
+Medusa's Notification Module delegates sending notifications to other modules, called module providers. In this step, you'll create a Resend Module Provider that implements sending notifications through the email channel. In later steps, you'll send email notifications with Resend when an order is placed through this provider.
+
+Learn more about modules in [this documentation](https://docs.medusajs.com/docs/learn/fundamentals/modules/index.html.md).
+
+### Create Module Directory
+
+A module is created under the `src/modules` directory of your Medusa application. So, create the directory `src/modules/resend`.
+
+### Create Service
+
+You define a module's functionalities in a service. A service is a TypeScript or JavaScript class that the module exports. In the service's methods, you can connect to the database, which is useful if your module defines tables in the database, or connect to a third-party service.
+
+In this section, you'll create the Resend Module Provider's service and the methods necessary to send an email with Resend.
+
+Start by creating the file `src/modules/resend/service.ts` with the following content:
+
+```ts title="src/modules/resend/service.ts" highlights={serviceHighlights1}
+import { 
+  AbstractNotificationProviderService,
+} from "@medusajs/framework/utils"
+import { 
+  Logger,
+} from "@medusajs/framework/types"
+import { 
+  Resend,
+} from "resend"
+
+type ResendOptions = {
+  api_key: string
+  from: string
+  html_templates?: Record<string, {
+    subject?: string
+    content: string
+  }>
+}
+
+class ResendNotificationProviderService extends AbstractNotificationProviderService {
+  static identifier = "notification-resend"
+  private resendClient: Resend
+  private options: ResendOptions
+  private logger: Logger
+
+  // ...
+}
+
+export default ResendNotificationProviderService
+```
+
+A Notification Module Provider's service must extend the `AbstractNotificationProviderService`. It has a `send` method that you'll implement soon. The service must also have an `identifier` static property, which is a unique identifier that the Medusa application will use to register the provider in the database.
+
+The `ResendNotificationProviderService` class also has the following properties:
+
+- `resendClient` of type `Resend` (from the Resend SDK you installed in the previous step) to send emails through Resend.
+- `options` of type `ResendOptions`. Modules accept options through Medusa's configurations. This ensures that the module is reusable across applications and you don't use sensitive variables like API keys directly in your code. The options that the Resend Module Provider accepts are:
+  - `api_key`: The Resend API key.
+  - `from`: The email address to send the emails from.
+  - `html_templates`: An optional object to replace the default subject and template that the Resend Module uses. This is also useful to support custom emails in different Medusa application setups.
+- `logger` property, which is an instance of Medusa's [Logger](https://docs.medusajs.com/docs/learn/debugging-and-testing/logging/index.html.md), to log messages.
+
+To send requests using the `resendClient`, you need to initialize it in the class's constructor. So, add the following constructor to `ResendNotificationProviderService`:
+
+```ts title="src/modules/resend/service.ts"
+// ...
+
+type InjectedDependencies = {
+  logger: Logger
+}
+
+class ResendNotificationProviderService extends AbstractNotificationProviderService {
+  // ...
+  constructor(
+    { logger }: InjectedDependencies, 
+    options: ResendOptions
+  ) {
+    super()
+    this.resendClient = new Resend(options.api_key)
+    this.options = options
+    this.logger = logger
+  }
+}
+```
+
+A module's service accepts two parameters:
+
+1. Dependencies resolved from the [Module's container](https://docs.medusajs.com/docs/learn/fundamentals/modules/container/index.html.md), which is the module's local registry that the Medusa application adds Framework tools to. In this service, you resolve the [Logger utility](https://docs.medusajs.com/docs/learn/debugging-and-testing/logging/index.html.md) from the module's container.
+2. The module's options that are passed to the module in Medusa's configuration as you'll see in a later section.
+
+Using the API key passed in the module's options, you initialize the Resend client. You also set the `options` and `logger` properties.
+
+#### Validate Options Method
+
+A Notification Module Provider's service can implement a static `validateOptions` method that ensures the options passed to the module through Medusa's configurations are valid.
+
+So, add to the `ResendNotificationProviderService` the `validateOptions` method:
+
+```ts title="src/modules/resend/service.ts"
+// other imports...
+import { 
+  // other imports...
+  MedusaError,
+} from "@medusajs/framework/utils"
+
+// ...
+
+class ResendNotificationProviderService extends AbstractNotificationProviderService {
+  // ...
+  static validateOptions(options: Record<any, any>) {
+    if (!options.api_key) {
+      throw new MedusaError(
+        MedusaError.Types.INVALID_DATA,
+        "Option `api_key` is required in the provider's options."
+      )
+    }
+    if (!options.from) {
+      throw new MedusaError(
+        MedusaError.Types.INVALID_DATA,
+        "Option `from` is required in the provider's options."
+      )
+    }
+  }
+}
+```
+
+In the `validateOptions` method, you throw an error if the `api_key` or `from` options aren't passed to the module. To throw errors, you use `MedusaError` from the Modules SDK. This ensures errors follow Medusa's conventions and are displayed similar to Medusa's errors.
+
+#### Implement Template Methods
+
+Each email type has a different template and content. For example, order confirmation emails show the order's details, whereas customer confirmation emails show a greeting message to the customer.
+
+So, add two methods to the `ResendNotificationProviderService` class that retrieve the email template and subject of a specified template type:
+
+```ts title="src/modules/resend/service.ts" highlights={serviceHighlights2}
+// imports and types...
+
+enum Templates {
+  ORDER_PLACED = "order-placed",
+}
+
+const templates: {[key in Templates]?: (props: unknown) => React.ReactNode} = {
+  // TODO add templates
+}
+
+class ResendNotificationProviderService extends AbstractNotificationProviderService {
+  // ...
+  getTemplate(template: Templates) {
+    if (this.options.html_templates?.[template]) {
+      return this.options.html_templates[template].content
+    }
+    const allowedTemplates = Object.keys(templates)
+
+    if (!allowedTemplates.includes(template)) {
+      return null
+    }
+
+    return templates[template]
+  }
+
+  getTemplateSubject(template: Templates) {
+    if (this.options.html_templates?.[template]?.subject) {
+      return this.options.html_templates[template].subject
+    }
+    switch(template) {
+      case Templates.ORDER_PLACED:
+        return "Order Confirmation"
+      default:
+        return "New Email"
+    }
+  }
+}
+```
+
+You first define a `Templates` enum, which holds the names of supported template types. You can add more template types to this enum later. You also define a `templates` variable that specifies the React template for each template type. You'll add templates to this variable later.
+
+In the `ResendNotificationProviderService` you add two methods:
+
+- `getTemplate`: Retrieve the template of a template type. If the `html_templates` option is set for the specified template type, you return its `content`'s value. Otherwise, you retrieve the template from the `templates` variable.
+- `getTemplateSubject`: Retrieve the subject of a template type. If a `subject` is passed for the template type in the `html_templates`, you return its value. Otherwise, you return a subject based on the template type.
+
+You'll use these methods in the `send` method next.
+
+#### Implement Send Method
+
+In this section, you'll implement the `send` method of `ResendNotificationProviderService`. When you send a notification through the email channel later using the Notification Module, the Notification Module's service will use this `send` method under the hood to send the email with Resend.
+
+In the `send` method, you'll retrieve the template and subject of the email template, then send the email using the Resend client.
+
+Add the `send` method to the `ResendNotificationProviderService` class:
+
+```ts title="src/modules/resend/service.ts" highlights={serviceHighlights3}
+// other imports...
+import { 
+  // ...
+  ProviderSendNotificationDTO, 
+  ProviderSendNotificationResultsDTO,
+} from "@medusajs/framework/types"
+import { 
+  // ...
+  CreateEmailOptions, 
+} from "resend"
+
+class ResendNotificationProviderService extends AbstractNotificationProviderService {
+  // ...
+  async send(
+    notification: ProviderSendNotificationDTO
+  ): Promise<ProviderSendNotificationResultsDTO> {
+    const template = this.getTemplate(notification.template as Templates)
+
+    if (!template) {
+      this.logger.error(`Couldn't find an email template for ${notification.template}. The valid options are ${Object.values(Templates)}`)
+      return {}
+    }
+
+    const emailOptions: CreateEmailOptions = {
+      from: this.options.from,
+      to: [notification.to],
+      subject: this.getTemplateSubject(notification.template as Templates),
+      html: "",
+    }
+
+    if (typeof template === "string") {
+      emailOptions.html = template
+    } else {
+      emailOptions.react = template(notification.data)
+      delete emailOptions.html
+    }
+
+    const { data, error } = await this.resendClient.emails.send(emailOptions)
+
+    if (error) {
+      this.logger.error(`Failed to send email`, error)
+      return {}
+    }
+
+    return { id: data.id }
+  }
+}
+```
+
+The `send` method receives the notification details object as a parameter. Some of its properties include:
+
+- `to`: The address to send the notification to.
+- `template`: The template type of the notification.
+- `data`: The data useful for the email type. For example, when sending an order-confirmation email, `data` would hold the order's details.
+
+In the method, you retrieve the template and subject of the email using the methods you defined earlier. Then, you put together the data to pass to Resend, such as the email address to send the notification to and the email address to send from. Also, if the email's template is a string, it's passed as an HTML template. Otherwise, it's passed as a React template.
+
+Finally, you use the `emails.send` method of the Resend client to send the email. If an error occurs you log it in the terminal. Otherwise, you return the ID of the send email as received from Resend. Medusa uses this ID when creating the notification in its database.
+
+### Export Module Definition
+
+The `ResendNotificationProviderService` class now has the methods necessary to start sending emails.
+
+Next, you must export the module provider's definition, which lets Medusa know what module this provider belongs to and its service.
+
+Create the file `src/modules/resend/index.ts` with the following content:
+
+```ts title="src/modules/resend/index.ts"
+import { 
+  ModuleProvider, 
+  Modules,
+} from "@medusajs/framework/utils"
+import ResendNotificationProviderService from "./service"
+
+export default ModuleProvider(Modules.NOTIFICATION, {
+  services: [ResendNotificationProviderService],
+})
+```
+
+You export the module provider's definition using `ModuleProvider` from the Modules SDK. It accepts as a first parameter the name of the module that this provider belongs to, which is the Notification Module. It also accepts as a second parameter an object having a `service` property indicating the provider's service.
+
+### Add Module to Configurations
+
+Finally, to register modules and module providers in Medusa, you must add them to Medusa's configurations.
+
+Medusa's configurations are set in the `medusa-config.ts` file, which is at the root directory of your Medusa application. The configuration object accepts a `modules` array, whose value is an array of modules to add to the application.
+
+Add the `modules` property to the exported configurations in `medusa-config.ts`:
+
+```ts title="medusa-config.ts"
+module.exports = defineConfig({
+  // ...
+  modules: [
+    {
+      resolve: "@medusajs/medusa/notification",
+      options: {
+        providers: [
+          {
+            resolve: "./src/modules/resend",
+            id: "resend",
+            options: {
+              channels: ["email"],
+              api_key: process.env.RESEND_API_KEY,
+              from: process.env.RESEND_FROM_EMAIL,
+            },
+          },
+        ],
+      },
+    },
+  ],
+})
+```
+
+In the `modules` array, you pass a module object having the following properties:
+
+- `resolve`: The NPM package of the Notification Module. Since the Resend Module is a Notification Module Provider, it'll be passed in the options of the Notification Module.
+- `options`: An object of options to pass to the module. It has a `providers` property which is an array of module providers to register. Each module provider object has the following properties:
+  - `resolve`: The path to the module provider to register in the application. It can also be the name of an NPM package.
+  - `id`: A unique ID, which Medusa will use along with the `identifier` static property that you set earlier in the class to identify this module provider.
+  - `options`: An object of options to pass to the module provider. These are the options you expect and use in the module provider's service. You must also specify the `channels` option, which indicates the channels that this provider sends notifications through.
+
+Some of the module's options, such as the Resend API key, are set in environment variables. So, add the following environment variables to `.env`:
+
+```shell
+RESEND_FROM_EMAIL=onboarding@resend.dev
+RESEND_API_KEY=
+```
+
+Where:
+
+- `RESEND_FROM_EMAIL`: The email to send emails from. If you've configured the custom domain as explained in [Step 2](#step-2-prepare-resend-account), change this email to an email from your custom domain. Otherwise, you can use `onboarding@resend.dev` for development purposes.
+- `RESEND_API_KEY` is the API key of your Resend account. To retrieve it:
+  - Go to API Keys in the sidebar.
+  - Click on the Create API Key button.
+
+![Click on the API keys in the sidebar, then click on the Create API Key button at the top right](https://res.cloudinary.com/dza7lstvk/image/upload/v1732535399/Medusa%20Resources/Screenshot_2024-11-25_at_10.22.25_AM_v4d09s.png)
+
+- In the form that opens, enter a name for the API key (for example, Medusa). You can keep its permissions to Full Access or change it to Sending Access. Once you're done, click Add.
+
+![The form to create an API key with fields for the API key's name, permissions, and domain](https://res.cloudinary.com/dza7lstvk/image/upload/v1732535464/Medusa%20Resources/Screenshot_2024-11-25_at_10.23.26_AM_g7gcuc.png)
+
+- A new pop-up will show with your API key hidden. Copy it before closing the pop-up, since you can't access the key again afterwards. Use its value for the `RESEND_API_KEY` environment variable.
+
+![Click the copy icon to copy the API key](https://res.cloudinary.com/dza7lstvk/image/upload/v1732535791/Medusa%20Resources/Screenshot_2024-11-25_at_10.23.43_AM_divins.png)
+
+Your Resend Module Provider is all set up. You'll test it out in a later section.
+
+***
+
+## Step 5: Add Order Confirmation Template
+
+In this step, you'll add a React template for order confirmation emails. You'll create it using the [react-email](https://github.com/resend/react-email) package you installed earlier. You can follow the same steps for other email templates, such as for customer confirmation.
+
+Create the directory `src/modules/resend/emails` that will hold the email templates. Then, to add the template for order confirmation, create the file `src/modules/resend/emails/order-placed.tsx` with the following content:
+
+```tsx title="src/modules/resend/emails/order-placed.tsx" highlights={templateHighlights}
+import { Text, Column, Container, Heading, Html, Img, Row, Section } from "@react-email/components"
+import { BigNumberValue, OrderDTO } from "@medusajs/framework/types"
+
+type OrderPlacedEmailProps = {
+  order: OrderDTO
+}
+
+function OrderPlacedEmailComponent({ order }: OrderPlacedEmailProps) {
+  const formatter = new Intl.NumberFormat([], {
+    style: "currency",
+    currencyDisplay: "narrowSymbol",
+    currency: order.currency_code,
+  })
+
+  const formatPrice = (price: BigNumberValue) => {
+    if (typeof price === "number") {
+      return formatter.format(price)
+    }
+
+    if (typeof price === "string") {
+      return formatter.format(parseFloat(price))
+    }
+
+    return price?.toString() || ""
+  }
+
+  return (
+    <Html>
+      <Heading>Thank you for your order</Heading>
+      {order.email}'s Items
+      <Container>
+        {order.items.map((item) => {
+          return (
+            <Section
+              key={item.id}
+              style={{ paddingTop: "40px", paddingBottom: "40px" }}
+            >
+              <Row>
+                <Column>
+                  <Img
+                    src={item.thumbnail}
+                    alt={item.product_title}
+                    style={{ float: "left" }}
+                    width="260px"
+                  />
+                </Column>
+                <Column style={{ verticalAlign: "top", paddingLeft: "12px" }}>
+                  <Text style={{ fontWeight: "500" }}>
+                    {item.product_title}
+                  </Text>
+                  <Text>{item.variant_title}</Text>
+                  <Text>{formatPrice(item.total)}</Text>
+                </Column>
+              </Row>
+            </Section>
+          )
+        })}
+      </Container>
+    </Html>
+  )
+}
+
+export const orderPlacedEmail = (props: OrderPlacedEmailProps) => (
+  <OrderPlacedEmailComponent {...props} />
+)
+```
+
+You define the `OrderPlacedEmailComponent` which is a React email template that shows the order's details, such as items and their totals. The component accepts an `order` object as a prop.
+
+You also export an `orderPlacedEmail` function, which accepts props as an input and returns the `OrderPlacedEmailComponent` passing it the props. Because you can't use JSX syntax in `src/modules/resend/service.ts`, you'll import this function instead.
+
+Next, update the `templates` variable in `src/modules/resend/service.ts` to assign this template to the `order-placed` template type:
+
+```ts title="src/modules/resend/service.ts"
+// other imports...
+import { orderPlacedEmail } from "./emails/order-placed"
+
+const templates: {[key in Templates]?: (props: unknown) => React.ReactNode} = {
+  [Templates.ORDER_PLACED]: orderPlacedEmail,
+}
+```
+
+The `ResendNotificationProviderService` will now use the `OrderPlacedEmailComponent` as the template of order confirmation emails.
+
+***
+
+## Step 6: Send Email when Order is Placed
+
+Medusa has an event system that emits an event when a commerce operation is performed. You can then listen and handle that event in an asynchronous function called a subscriber.
+
+So, to send a confirmation email when a customer places an order, which is a commerce operation that Medusa already implements, you don't need to extend or hack your way into Medusa's implementation as you would do with other commerce platforms.
+
+Instead, you'll create a subscriber that listens to the `order.placed` event and sends an email when the event is emitted.
+
+Learn more about Medusa's event system in [this documentation](https://docs.medusajs.com/docs/learn/fundamentals/events-and-subscribers/index.html.md).
+
+### Send Order Confirmation Email Workflow
+
+To send the order confirmation email, you need to retrieve the order's details first, then use the Notification Module's service to send the email. To implement this flow, you'll create a workflow.
+
+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 a subscriber.
+
+Learn more about workflows in [this documentation](https://docs.medusajs.com/docs/learn/fundamentals/workflows/index.html.md)
+
+#### Send Notification Step
+
+You'll start by implementing the step of the workflow that sends the notification. To do that, create the file `src/workflows/steps/send-notification.ts` with the following content:
+
+```ts title="src/workflows/steps/send-notification.ts"
+import { Modules } from "@medusajs/framework/utils"
+import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk"
+import { CreateNotificationDTO } from "@medusajs/framework/types"
+
+export const sendNotificationStep = createStep(
+  "send-notification",
+  async (data: CreateNotificationDTO[], { container }) => {
+    const notificationModuleService = container.resolve(
+      Modules.NOTIFICATION
+    )
+    const notification = await notificationModuleService.createNotifications(data)
+    return new StepResponse(notification)
+  }
+)
+```
+
+You define the `sendNotificationStep` using the `createStep` function that accepts two parameters:
+
+- A string indicating the step's unique name.
+- The step's function definition as a second parameter. It accepts the step's input as a first parameter, and an object of options as a second.
+
+The `container` property in the second parameter is an instance of the [Medusa container](https://docs.medusajs.com/docs/learn/fundamentals/medusa-container/index.html.md), which is a registry of Framework and commerce tools, such as a module's service, that you can resolve to utilize their functionalities.
+
+The Medusa container is accessible by all customizations, such as workflows and subscribers, except for modules. Each module has its own container with Framework tools like the Logger utility.
+
+In the step function, you resolve the Notification Module's service, and use its `createNotifications` method, passing it the notification's data that the step receives as an input.
+
+The step returns an instance of `StepResponse`, which must be returned by any step. It accepts as a parameter the data to return to the workflow that executed this step.
+
+#### Workflow Implementation
+
+You'll now create the workflow that uses the `sendNotificationStep` to send the order confirmation email.
+
+Create the file `src/workflows/send-order-confirmation.ts` with the following content:
+
+```ts title="src/workflows/send-order-confirmation.ts" highlights={workflowHighlights}
+import { 
+  createWorkflow, 
+  WorkflowResponse,
+} from "@medusajs/framework/workflows-sdk"
+import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
+import { sendNotificationStep } from "./steps/send-notification"
+
+type WorkflowInput = {
+  id: string
+}
+
+export const sendOrderConfirmationWorkflow = createWorkflow(
+  "send-order-confirmation",
+  ({ id }: WorkflowInput) => {
+    // @ts-ignore
+    const { data: orders } = useQueryGraphStep({
+      entity: "order",
+      fields: [
+        "id",
+        "email",
+        "currency_code",
+        "total",
+        "items.*",
+      ],
+      filters: {
+        id,
+      },
+    })
+    
+    const notification = sendNotificationStep([{
+      to: orders[0].email,
+      channel: "email",
+      template: "order-placed",
+      data: {
+        order: orders[0],
+      },
+    }])
+
+    return new WorkflowResponse(notification)
+  }
+)
+```
+
+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 workflow has the following steps:
+
+1. `useQueryGraphStep`, which is a step implemented by Medusa that uses [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), a tool that allows you to retrieve data across modules. You use it to retrieve the order's details.
+2. `sendNotificationStep` which is the step you implemented. You pass it an array with one object, which is the notification's details having following properties:
+   - `to`: The address to send the email to. You pass the customer's email that is stored in the order.
+   - `channel`: The channel to send the notification through, which is `email`. Since you specified `email` in the Resend Module Provider's `channel` option, the Notification Module will delegate the sending to the Resend Module Provider's service.
+   - `template`: The email's template type. You retrieve the template content in the `ResendNotificationProviderService`'s `send` method based on the template specified here.
+   - `data`: The data to pass to the email template, which is the order's details.
+
+A workflow's constructor function has some constraints in implementation. Learn more about them in [this documentation](https://docs.medusajs.com/docs/learn/fundamentals/workflows/constructor-constraints/index.html.md).
+
+You'll execute the workflow when you create the subscriber next.
+
+#### Add the Order Placed Subscriber
+
+Now that you have the workflow to send an order-confirmation email, you'll execute it in a subscriber that's executed whenever an order is placed.
+
+You create a subscriber in a TypeScript or JavaScript file under the `src/subscribers` directory. So, create the file `src/subscribers/order-placed.ts` with the following content:
+
+```ts title="src/subscribers/order-placed.ts" highlights={subscriberHighlights}
+import type {
+  SubscriberArgs,
+  SubscriberConfig,
+} from "@medusajs/framework"
+import { sendOrderConfirmationWorkflow } from "../workflows/send-order-confirmation"
+
+export default async function orderPlacedHandler({
+  event: { data },
+  container,
+}: SubscriberArgs<{ id: string }>) {
+  await sendOrderConfirmationWorkflow(container)
+    .run({
+      input: {
+        id: data.id,
+      },
+    })
+}
+
+export const config: SubscriberConfig = {
+  event: "order.placed",
+}
+```
+
+A subscriber file exports:
+
+- An asynchronous function that's executed whenever the associated event is emitted, which is the `order.placed` event.
+- A configuration object with an `event` property indicating the event the subscriber is listening to.
+
+The subscriber function accepts the event's details as a first paramter which has a `data` property that holds the data payload of the event. For example, Medusa emits the `order.placed` event with the order's ID in the data payload. The function also accepts as a second parameter the [Medusa container](https://docs.medusajs.com/docs/learn/fundamentals/medusa-container/index.html.md).
+
+In the function, you execute the `sendOrderConfirmationWorkflow` by invoking it, passing it the `container`, then using its `run` method. The `run` method accepts an object having an `input` property, which is the input to pass to the workflow. You pass the ID of the placed order as received in the event's data payload.
+
+This subscriber now runs whenever an order is placed. You'll see this in action in the next section.
+
+***
+
+## Test it Out: Place an Order
+
+To test out the Resend integration, you'll place an order using the [Next.js storefront](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/nextjs-starter/index.html.md) that you installed as part of installing Medusa.
+
+Start your Medusa application first:
+
+```bash npm2yarn
+npm run dev
+```
+
+Then, in the Next.js storefront's directory (which was installed in a directory outside of the Medusa application's directory with the name `{project-name}-storefront`, where `{project-name}` is the name of the Medusa application's directory), run the following command to start the storefront:
+
+```bash npm2yarn
+npm run dev
+```
+
+Then, open the storefront in your browser at `http://localhost:8000` and:
+
+1. Go to Menu -> Store.
+
+![Choose Store from Menu](https://res.cloudinary.com/dza7lstvk/image/upload/v1732539139/Medusa%20Resources/Screenshot_2024-11-25_at_2.51.59_PM_fubiwj.png)
+
+2\. Click on a product, select its options, and add it to the cart.
+
+![Choose an option, such as size, then click on the Add to cart button](https://res.cloudinary.com/dza7lstvk/image/upload/v1732539227/Medusa%20Resources/Screenshot_2024-11-25_at_2.53.11_PM_iswcjy.png)
+
+3\. Click on Cart at the top right, then click Go to Cart.
+
+![Cart is at the top right. It opens a dropdown with a Go to Cart button](https://res.cloudinary.com/dza7lstvk/image/upload/v1732539354/Medusa%20Resources/Screenshot_2024-11-25_at_2.54.44_PM_b1pnlu.png)
+
+4\. On the cart's page, click on the "Go to checkout" button.
+
+![The Go to checkout button is at the right side of the page](https://res.cloudinary.com/dza7lstvk/image/upload/v1732539443/Medusa%20Resources/Screenshot_2024-11-25_at_2.56.27_PM_cvqshj.png)
+
+5\. On the checkout page, when entering the shipping address, make sure to set the email to your Resend account's email if you didn't set up a custom domain.
+
+![Enter your Resend account email if you didn't set up a custom domain](https://res.cloudinary.com/dza7lstvk/image/upload/v1732539536/Medusa%20Resources/Screenshot_2024-11-25_at_2.58.31_PM_wmlh60.png)
+
+6\. After entering the shipping address, choose a delivery and payment methods, then click the Place Order button.
+
+Once the order is placed, you'll find the following message logged in the Medusa application's terminal:
+
+```bash
+info:    Processing order.placed which has 1 subscribers
+```
+
+This indicates that the `order.placed` event was emitted and its subscriber, which you added in the previous step, is executed.
+
+If you check the inbox of the email address you specified in the shipping address, you'll find a new email with the order's details.
+
+![Example of order-confirmation email](https://res.cloudinary.com/dza7lstvk/image/upload/v1732551372/Medusa%20Resources/Screenshot_2024-11-25_at_6.15.59_PM_efyuoj.png)
+
+***
+
+## Next Steps
+
+You've now integrated Medusa with Resend. You can add more templates for other emails, such as customer registration confirmation, user invites, and more. Check out the [Events Reference](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/events-reference/index.html.md) for a list of all events that the Medusa application emits.
+
+If you're new to Medusa, check out the [main documentation](https://docs.medusajs.com/docs/learn/index.html.md), where you'll get a more in-depth learning of all the concepts you've used in this guide and more.
+
+To learn more about the commerce features that Medusa provides, check out Medusa's [Commerce Modules](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/index.html.md).
+
+
 # Integrate Algolia (Search) with Medusa
 
 In this tutorial, you'll learn how to integrate Medusa with Algolia.
@@ -45942,1245 +47745,6 @@ If you're new to Medusa, check out the [main documentation](https://docs.medusaj
 To learn more about the commerce features that Medusa provides, check out Medusa's [Commerce Modules](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/index.html.md).
 
 
-# Integrate Medusa with ShipStation (Fulfillment)
-
-In this guide, you'll learn how to integrate Medusa with ShipStation.
-
-Refer your technical team to this guide to integrate ShipStation with your Medusa application. You can then enable it using the Medusa Admin as explained in [this user guide](https://docs.medusajs.com/user-guide/settings/locations-and-shipping/locations#manage-fulfillment-providers/index.html.md).
-
-When you install a Medusa application, you get a fully-fledged commerce platform with support for customizations. Medusa's [Fulfillment Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/fulfillment/index.html.md) provides fulfillment-related resources and functionalities in your store, but it delegates the processing and shipment of order fulfillments to providers that you can integrate.
-
-[ShipStation](https://shipstation.com/) is a shipping toolbox that connects all your shipping providers within one platform. By integrating it with Medusa, you can allow customers to choose from different providers like DHL and FedEx and view price rates retrieved from ShipStation. Admin users will also process the order fulfillment using the ShipStation integration.
-
-This guide will teach you how to:
-
-- Install and set up Medusa.
-- Set up a ShipStation account.
-- Integrate ShipStation as a fulfillment provider in Medusa.
-
-You can follow this guide whether you're new to Medusa or an advanced Medusa developer.
-
-[Example Repository](https://github.com/medusajs/examples/tree/main/shipstation-integration): Find the full code of the guide in this repository.
-
-***
-
-## 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 you're asked whether you want to install the Next.js storefront, choose `Y` for 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 storefront in a 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 about Medusa's architecture in [this 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 credential and submit the form.
-
-Afterwards, you can login with the new user and explore the dashboard. The Next.js storefront is also running at `http://localhost:8000`.
-
-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: Prepare ShipStation Account
-
-In this step, you'll prepare your ShipStation account before integrating it into Medusa. If you don't have an account, create one [here](https://www.shipstation.com/start-a-free-trial).
-
-### Enable Carriers
-
-To create labels for your shipments, you need to enable carriers. This requires you to enter payment and address details.
-
-To enable carriers:
-
-1. On the Onboard page, in the "Enable carriers & see rates" section, click on the "Enable Carriers" button.
-
-![Scroll down to the Enable carriers & see rates section, and find the "Enable Carriers" button.](https://res.cloudinary.com/dza7lstvk/image/upload/v1734523873/Medusa%20Resources/Screenshot_2024-12-18_at_2.10.54_PM_pmvcfr.png)
-
-2. In the pop-up that opens, click on Continue Setup.
-
-![Click on the green Continue Setup button](https://res.cloudinary.com/dza7lstvk/image/upload/v1734524261/Medusa%20Resources/Screenshot_2024-12-18_at_2.11.47_PM_wsl98i.png)
-
-3. In the next section of the form, you have to enter your payment details and billing address. Once done, click on Continue Setup.
-4. After that, click the checkboxes on the Terms of Service section, then click the Finish Setup button.
-
-![Enable the two checkboxes, then click on Finish Setup at the bottom right](https://res.cloudinary.com/dza7lstvk/image/upload/v1734524486/Medusa%20Resources/Screenshot_2024-12-18_at_2.20.12_PM_pkixma.png)
-
-5. Once you're done, you can optionally add funds to your account. If you're not US-based, make sure to disable ParcelGuard insurance. Otherwise, an error will occur while retrieving rates later.
-
-### Add Carriers
-
-You must have at least one carrier (shipping provider) added in your ShipStation account. You'll later provide shipping options for each of these carriers in your Medusa application.
-
-To add carriers:
-
-1. On the Onboard page, in the "Enable carriers & see rates" section, click on the "Add your carrier accounts" link.
-
-![Scroll down to the Enable carriers & see rates section, and find the "Add your carrier accounts" link under the "Enable Carriers" button](https://res.cloudinary.com/dza7lstvk/image/upload/v1734336612/Medusa%20Resources/Screenshot_2024-12-16_at_10.09.08_AM_nqshhg.png)
-
-2. Click on a provider from the pop-up window.
-
-![Click on the provider tiles in the pop-up window](https://res.cloudinary.com/dza7lstvk/image/upload/v1734336826/Medusa%20Resources/Screenshot_2024-12-16_at_10.13.37_AM_og4sdq.png)
-
-Based on the provider you chose, you'll have to enter your account details, then submit the form.
-
-### Activate Shipping API
-
-To integrate ShipStation using their API, you must enable the Shipping API Add-On. To do that:
-
-1. Go to Add-Ons from the navigation bar.
-2. Find Shipping API and activate it.
-
-You'll later retrieve your API key.
-
-***
-
-## Step 3: Create ShipStation Module Provider
-
-To integrate third-party services into Medusa, you create a custom module. A module is a re-usable 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.
-
-Medusa's Fulfillment Module delegates processing fulfillments and shipments to other modules, called module providers. In this step, you'll create a ShipStation Module Provider that implements all functionalities required for fulfillment. In later steps, you'll add into Medusa shipping options for ShipStation, and allow customers to choose it during checkout.
-
-Learn more about modules in [this documentation](https://docs.medusajs.com/docs/learn/fundamentals/modules/index.html.md).
-
-### Create Module Directory
-
-A module is created under the `src/modules` directory of your Medusa application. So, create the directory `src/modules/shipstation`.
-
-![The directory structure of the Medusa application after adding the module's directory](https://res.cloudinary.com/dza7lstvk/image/upload/v1734338950/Medusa%20Resources/shipstation-dir-overview-1_dlsrbv.jpg)
-
-### Create Service
-
-You define a module's functionalities in a service. A service is a TypeScript or JavaScript class that the module exports. In the service's methods, you can connect to the database, which is useful if your module defines tables in the database, or connect to a third-party service.
-
-In this section, you'll create the ShipStation Module Provider's service and the methods necessary to handle fulfillment.
-
-Start by creating the file `src/modules/shipstation/service.ts` with the following content:
-
-![The directory structure of the Medusa application after adding the service](https://res.cloudinary.com/dza7lstvk/image/upload/v1734339042/Medusa%20Resources/shipstation-dir-overview-2_cmgvcj.jpg)
-
-```ts title="src/modules/shipstation/service.ts" highlights={serviceHighlights1}
-import { AbstractFulfillmentProviderService } from "@medusajs/framework/utils"
-
-export type ShipStationOptions = {
-  api_key: string
-}
-
-class ShipStationProviderService extends AbstractFulfillmentProviderService {
-  static identifier = "shipstation"
-  protected options_: ShipStationOptions
-
-  constructor({}, options: ShipStationOptions) {
-    super()
-
-    this.options_ = options
-  }
-
-  // TODO add methods
-}
-
-export default ShipStationProviderService
-```
-
-A Fulfillment Module Provider service must extend the `AbstractFulfillmentProviderService` class. You'll implement the abstract methods of this class in the upcoming sections.
-
-The service must have an `identifier` static property, which is a unique identifier for the provider. You set the identifier to `shipstation`.
-
-A module can receive options that are set when you later add the module to Medusa's configurations. These options allow you to safely store secret values outside of your code.
-
-The ShipStation module requires an `api_key` option, indicating your ShipStation's API key. You receive the options as a second parameter of the service's constructor.
-
-### Create Client
-
-To send requests to ShipStation, you'll create a client class that provides the methods to send requests. You'll then use that class in your service.
-
-Create the file `src/modules/shipstation/client.ts` with the following content:
-
-![The directory structure of the Medusa application after adding the client file](https://res.cloudinary.com/dza7lstvk/image/upload/v1734339519/Medusa%20Resources/shipstation-dir-overview-3_b8im2d.jpg)
-
-```ts title="src/modules/shipstation/client.ts" highlights={clientHighlights1}
-import { ShipStationOptions } from "./service"
-import { MedusaError } from "@medusajs/framework/utils"
-
-export class ShipStationClient {
-  options: ShipStationOptions
-
-  constructor(options) {
-    this.options = options
-  }
-
-  private async sendRequest(url: string, data?: RequestInit): Promise<any> {
-    return fetch(`https://api.shipstation.com/v2${url}`, {
-      ...data,
-      headers: {
-        ...data?.headers,
-        "api-key": this.options.api_key,
-        "Content-Type": "application/json",
-      },
-    }).then((resp) => {
-      const contentType = resp.headers.get("content-type")
-      if (!contentType?.includes("application/json")) {
-        return resp.text()
-      }
-
-      return resp.json()
-    })
-    .then((resp) => {
-      if (typeof resp !== "string" && resp.errors?.length) {
-        throw new MedusaError(
-          MedusaError.Types.INVALID_DATA,
-          `An error occured while sending a request to ShipStation: ${
-            resp.errors.map((error) => error.message)
-          }`
-        )
-      }
-
-      return resp
-    })
-  }
-}
-```
-
-The `ShipStationClient` class accepts the ShipStation options in its constructor and sets those options in the `options` property.
-
-You also add a private `sendRequest` method that accepts a path to send a request to and the request's configurations. In the method, you send a request using the Fetch API, passing the API key from the options in the request header. You also parse the response body based on its content type, and check if there are any errors to be thrown before returning the parsed response.
-
-You'll add more methods to send requests in the upcoming steps.
-
-To use the client in `ShipStationProviderService`, add it as a class property and initialize it in the constructor:
-
-```ts title="src/modules/shipstation/service.ts" highlights={serviceHighlights2}
-// imports...
-import { ShipStationClient } from "./client"
-
-// ...
-
-class ShipStationProviderService extends AbstractFulfillmentProviderService {
-  // properties...
-  protected client: ShipStationClient
-
-  constructor({}, options: ShipStationOptions) {
-    // ...
-    this.client = new ShipStationClient(options)
-  }
-}
-```
-
-You import `ShipStationClient` and add a new `client` property in `ShipStationProviderService`. In the class's constructor, you set the `client` property by initializing `ShipStationProviderService`, passing it the module's options.
-
-You'll use the `client` property when implementing the service's methods.
-
-### Implement Service Methods
-
-In this section, you'll go back to the `ShipStationProviderService` method to implement the abstract methods of `AbstractFulfillmentProviderService`.
-
-Refer to [this guide](https://docs.medusajs.com/references/fulfillment/provider/index.html.md) for a full reference of all methods, their parameters and return types.
-
-#### getFulfillmentOptions
-
-The `getFulfillmentOptions` method returns the options that this fulfillment provider supports. When admin users add shipping options later in the Medusa Admin, they'll select one of these options.
-
-Learn more about shipping options in [this guide](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/fulfillment/shipping-option/index.html.md).
-
-ShipStation requires that a shipment must be associated with a carrier and one of its services. So, in this method, you'll retrieve the list of carriers from ShipStation and return them as fulfillment options. Shipping options created from these fulfillment options will always have access to the option's carrier and service.
-
-Before you start implementing methods, you'll add the expected carrier types returned by ShipStation. Create the file `src/modules/shipstation/types.ts` with the following content:
-
-![The directory structure of the Medusa application after adding the types file](https://res.cloudinary.com/dza7lstvk/image/upload/v1734340402/Medusa%20Resources/shipstation-dir-overview-4_fwsle0.jpg)
-
-```ts title="src/modules/shipstation/types.ts"
-export type Carrier = {
-  carrier_id: string
-  disabled_by_billing_plan: boolean
-  friendly_name: string
-  services: {
-    service_code: string
-    name: string
-  }[]
-  packages: {
-    package_code: string
-  }[]
-  [k: string]: unknown
-}
-
-export type CarriersResponse = {
-  carriers: Carrier[]
-}
-```
-
-You define a `Carrier` type that holds a carrier's details, and a `CarriersResponse` type, which is the response returned by ShipStation.
-
-A carrier has more fields that you can use. Refer to [ShipStation's documentation](https://docs.shipstation.com/openapi/carriers/list_carriers#carriers/list_carriers/t=response\&c=200\&path=carriers) for all carrier fields.
-
-Next, you'll add in `ShipStationClient` the method to retrieve the carriers from ShipStation. So, add to the class defined in `src/modules/shipstation/client.ts` a new method:
-
-```ts title="src/modules/shipstation/client.ts" highlights={clientHighlights2}
-// other imports...
-import { 
-  CarriersResponse,
-} from "./types"
-
-export class ShipStationClient {
-  // ...
-  async getCarriers(): Promise<CarriersResponse> {
-    return await this.sendRequest("/carriers") 
-  }
-}
-```
-
-You added a new `getCarriers` method that uses the `sendRequest` method to send a request to the [ShipStation's List Carriers endpoint](https://docs.shipstation.com/openapi/carriers/list_carriers). The method returns `CarriersResponse` that you defined earlier.
-
-Finally, add the `getFulfillmentOptions` method to `ShipStationProviderService`:
-
-```ts title="src/modules/shipstation/service.ts" highlights={serviceHighlights3}
-// other imports...
-import { 
-  FulfillmentOption,
-} from "@medusajs/framework/types"
-
-class ShipStationProviderService extends AbstractFulfillmentProviderService {
-  // ...
-  async getFulfillmentOptions(): Promise<FulfillmentOption[]> {
-    const { carriers } = await this.client.getCarriers() 
-    const fulfillmentOptions: FulfillmentOption[] = []
-
-    carriers
-      .filter((carrier) => !carrier.disabled_by_billing_plan)
-      .forEach((carrier) => {
-        carrier.services.forEach((service) => {
-          fulfillmentOptions.push({
-            id: `${carrier.carrier_id}__${service.service_code}`,
-            name: service.name,
-            carrier_id: carrier.carrier_id,
-            carrier_service_code: service.service_code,
-          })
-        })
-      })
-
-    return fulfillmentOptions
-  }
-}
-```
-
-In the `getFulfillmentOptions` method, you retrieve the carriers from ShipStation. You then filter out the carriers disabled by your ShipStation billing plan, and loop over the remaining carriers and their services.
-
-You return an array of fulfillment-option objects, where each object represents a carrier and service pairing. Each object has the following properties:
-
-- an `id` property, which you set to a combination of the carrier ID and the service code.
-- a `name` property, which you set to the service's `name`. The admin user will see this name when they create a shipping option for the ShipStation provider.
-- You can pass other data, such as `carrier_id` and `carrier_service_code`, and Medusa will store the fulfillment option in the `data` property of shipping options created later.
-
-Learn more about the shipping option's `data` property in [this guide](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/fulfillment/shipping-option/index.html.md).
-
-You'll see this method in action later when you create a shipping option.
-
-#### canCalculate
-
-When an admin user creates a shipping option for your provider, they can choose whether the price is flat rate or calculated during checkout.
-
-If the user chooses calculated, Medusa validates that your fulfillment provider supports calculated prices using the `canCalculate` method of your provider's service.
-
-This method accepts the shipping option's `data` field, which will hold the data of an option returned by `getFulfillmentOptions`. It returns a boolean value indicating whether the shipping option can have a calculated price.
-
-Add the method to `ShipStationProviderService` in `src/modules/shipstation/service.ts`:
-
-```ts title="src/modules/shipstation/service.ts"
-// other imports...
-import {
-  // ...
-  CreateShippingOptionDTO,
-} from "@medusajs/framework/types"
-
-class ShipStationProviderService extends AbstractFulfillmentProviderService {
-  // ...
-  async canCalculate(data: CreateShippingOptionDTO): Promise<boolean> {
-    return true
-  }
-}
-```
-
-Since all shipping option prices can be calculated with ShipStation based on the chosen carrier and service zone, you always return `true` in this method.
-
-You'll implement the calculation mechanism in a later method.
-
-#### calculatePrice
-
-When the customer views available shipping options during checkout, the Medusa application requests the calculated price from your fulfillment provider using its `calculatePrice` method.
-
-To retrieve shipping prices with ShipStation, you create a shipment first then get its rates. So, in the `calculatePrice` method, you'll either:
-
-- Send a request to [ShipStation's get shipping rates endpoint](https://docs.shipstation.com/openapi/rates/calculate_rates) that creates a shipment and returns its prices;
-- Or, if a shipment was already created before, you'll retrieve its prices using [ShipStation's get shipment rates endpoint](https://docs.shipstation.com/openapi/shipments/list_shipment_rates).
-
-First, add the following types to `src/modules/shipstation/types.ts`:
-
-```ts title="src/modules/shipstation/types.ts" highlights={typesHighlights1}
-export type ShipStationAddress = {
-  name: string
-  phone: string
-  email?: string | null
-  company_name?: string | null
-  address_line1: string
-  address_line2?: string | null
-  address_line3?: string | null
-  city_locality: string
-  state_province: string
-  postal_code: string
-  country_code: string
-  address_residential_indicator: "unknown" | "yes" | "no"
-  instructions?: string | null
-  geolocation?: {
-    type?: string
-    value?: string
-  }[]
-}
-
-export type Rate = {
-  rate_id: string
-  shipping_amount: {
-    currency: string
-    amount: number
-  }
-  insurance_amount: {
-    currency: string
-    amount: number
-  }
-  confirmation_amount: {
-    currency: string
-    amount: number
-  }
-  other_amount: {
-    currency: string
-    amount: number
-  }
-  tax_amount: {
-    currency: string
-    amount: number
-  }
-}
-
-export type RateResponse = {
-  rates: Rate[]
-}
-
-export type GetShippingRatesRequest = {
-  shipment_id?: string
-  shipment?: Omit<Shipment, "shipment_id" | "shipment_status">
-  rate_options: {
-    carrier_ids: string[]
-    service_codes: string[]
-    preferred_currency: string
-  }
-}
-
-export type GetShippingRatesResponse = {
-  shipment_id: string
-  carrier_id?: string
-  service_code?: string
-  external_order_id?: string
-  rate_response: RateResponse
-}
-
-export type Shipment = {
-  shipment_id: string
-  carrier_id: string
-  service_code: string
-  ship_to: ShipStationAddress
-  return_to?: ShipStationAddress
-  is_return?: boolean
-  ship_from: ShipStationAddress
-  items?: [
-    {
-      name?: string
-      quantity?: number
-      sku?: string
-    }
-  ]
-  warehouse_id?: string
-  shipment_status: "pending" | "processing" | "label_purchased" | "cancelled"
-  [k: string]: unknown
-}
-
-```
-
-You add the following types:
-
-- `ShipStationAddress`: an address to ship from or to.
-- `Rate`: a price rate for a specified carrier and service zone.
-- `RateResponse`: The response when retrieving rates.
-- `GetShippingRatesRequest`: The request body data for [ShipStation's get shipping rates endpoint](https://docs.shipstation.com/openapi/rates/calculate_rates). You can refer to their API reference for other accepted parameters.
-- `GetShippingRatesResponse`: The response of the [ShipStation's get shipping rates endpoint](https://docs.shipstation.com/openapi/rates/calculate_rates). You can refer to their API reference for other response fields.
-- `Shipment`: A shipment's details.
-
-Then, add the following methods to `ShipStationClient`:
-
-```ts title="src/modules/shipstation/client.ts" highlights={serviceHighlights7}
-// other imports...
-import { 
-  // ...
-  GetShippingRatesRequest,
-  GetShippingRatesResponse,
-  RateResponse,
-} from "./types"
-
-export class ShipStationClient {
-  // ...
-  async getShippingRates(
-    data: GetShippingRatesRequest
-  ): Promise<GetShippingRatesResponse> {
-    return await this.sendRequest("/rates", {
-      method: "POST",
-      body: JSON.stringify(data),
-    }).then((resp) => {
-      if (resp.rate_response.errors?.length) {
-        throw new MedusaError(
-          MedusaError.Types.INVALID_DATA,
-          `An error occured while retrieving rates from ShipStation: ${
-            resp.rate_response.errors.map((error) => error.message)
-          }`
-        )
-      }
-
-      return resp
-    })
-  }
-
-  async getShipmentRates(id: string): Promise<RateResponse[]> {
-    return await this.sendRequest(`/shipments/${id}/rates`)
-  }
-}
-```
-
-The `getShippingRates` method accepts as a parameter the data to create a shipment and retrieve its rate. In the method, you send the request using the `sendRequest` method, and throw any errors in the rate retrieval before returning the response.
-
-The `getShipmentRates` method accepts the ID of the shipment as a parameter, sends the request using the `sendRequest` method and returns its response holding the shipment's rates.
-
-Next, add to `ShipStationProviderService` a private method that'll be used to create a shipment in ShipStation and get its rates:
-
-```ts title="src/modules/shipstation/service.ts" highlights={serviceHighlights8}
-// other imports...
-import {
-  // ...
-  MedusaError,
-} from "@medusajs/framework/utils"
-import { 
-  // ...
-  CalculateShippingOptionPriceDTO,
-} from "@medusajs/framework/types"
-import {
-  GetShippingRatesResponse,
-  ShipStationAddress,
-} from "./types"
-
-class ShipStationProviderService extends AbstractFulfillmentProviderService {
-  // ...
-  private async createShipment({
-    carrier_id,
-    carrier_service_code,
-    from_address,
-    to_address,
-    items,
-    currency_code,
-  }: {
-    carrier_id: string
-    carrier_service_code: string
-    from_address?: {
-      name?: string
-      address?: Omit<
-        StockLocationAddressDTO, "created_at" | "updated_at" | "deleted_at"
-      >
-    },
-    to_address?: Omit<
-      CartAddressDTO, "created_at" | "updated_at" | "deleted_at" | "id"
-    >,
-    items: CartLineItemDTO[] | OrderLineItemDTO[],
-    currency_code: string
-  }): Promise<GetShippingRatesResponse> {
-    if (!from_address?.address) {
-      throw new MedusaError(
-        MedusaError.Types.INVALID_DATA,
-        "from_location.address is required to calculate shipping rate"
-      )
-    }
-    const ship_from: ShipStationAddress = {
-      name: from_address?.name || "",
-      phone: from_address?.address?.phone || "",
-      address_line1: from_address?.address?.address_1 || "",
-      city_locality: from_address?.address?.city || "",
-      state_province: from_address?.address?.province || "",
-      postal_code: from_address?.address?.postal_code || "",
-      country_code: from_address?.address?.country_code || "",
-      address_residential_indicator: "unknown",
-    }
-    if (!to_address) {
-      throw new MedusaError(
-        MedusaError.Types.INVALID_DATA,
-        "shipping_address is required to calculate shipping rate"
-      )
-    }
-    
-    const ship_to: ShipStationAddress = {
-      name: `${to_address.first_name} ${to_address.last_name}`,
-      phone: to_address.phone || "",
-      address_line1: to_address.address_1 || "",
-      city_locality: to_address.city || "",
-      state_province: to_address.province || "",
-      postal_code: to_address.postal_code || "",
-      country_code: to_address.country_code || "",
-      address_residential_indicator: "unknown",
-    }
-
-    // TODO create shipment
-  }
-}
-```
-
-The `createShipment` method accepts as a parameter an object having the following properties:
-
-- `carrier_id`: The ID of the carrier to create the shipment for.
-- `carrier_service_code`: The code of the carrier's service.
-- `from_address`: The address to ship items from, which is the address of the stock location associated with a shipping option.
-- `to_address`: The address to ship items to, which is the customer's address.
-- `items`: An array of the items in the cart or order (for fulfilling the order later).
-- `currency_code`: The currency code of the cart or order.
-
-In the `createShipment` method, so far you only prepare the data to be sent to ShipStation. ShipStation requires the addresses to ship the items from and to.
-
-To send the request, replace the `TODO` with the following:
-
-```ts title="src/modules/shipstation/service.ts"
-// Sum the package's weight
-// You can instead create different packages for each item
-const packageWeight = items.reduce((sum, item) => {
-  // @ts-ignore
-  return sum + (item.variant.weight || 0)
-}, 0)
-
-return await this.client.getShippingRates({
-  shipment: {
-    carrier_id: carrier_id,
-    service_code: carrier_service_code,
-    ship_to,
-    ship_from,
-    validate_address: "no_validation",
-    items: items?.map((item) => ({
-      name: item.title,
-      quantity: item.quantity,
-      sku: item.variant_sku || "",
-    })),
-    packages: [{
-      weight: {
-        value: packageWeight,
-        unit: "kilogram",
-      },
-    }],
-    customs: {
-      contents: "merchandise",
-      non_delivery: "return_to_sender",
-    },
-  },
-  rate_options: {
-    carrier_ids: [carrier_id],
-    service_codes: [carrier_service_code],
-    preferred_currency: currency_code as string,
-  },
-})
-```
-
-You create a shipment and get its rates using the `getShippingRates` method you added to the client. You pass the method the expected request body parameters by [ShipStation's get shipping rates endpoint](https://docs.shipstation.com/openapi/rates/calculate_rates), including the carrier ID, the items to be shipped, and more.
-
-The above snippet assumes all items are sent in a single package. You can instead pass a package for each item, specifying its weight and optionally its height, width, and length.
-
-Finally, add the `calculatePrice` method to `ShipStationProviderService`:
-
-```ts title="src/modules/shipstation/service.ts" highlights={serviceHighlights5}
-// other imports...
-import { 
-  // ...
-  CalculatedShippingOptionPrice,
-} from "@medusajs/framework/types"
-
-class ShipStationProviderService extends AbstractFulfillmentProviderService {
-  // ...
-  async calculatePrice(
-    optionData: CalculateShippingOptionPriceDTO["optionData"], 
-    data: CalculateShippingOptionPriceDTO["data"], 
-    context: CalculateShippingOptionPriceDTO["context"]
-  ): Promise<CalculatedShippingOptionPrice> {
-    const { shipment_id } = data as {
-      shipment_id?: string
-    } || {}
-    const { carrier_id, carrier_service_code } = optionData as {
-      carrier_id: string
-      carrier_service_code: string
-    }
-    let rate: Rate | undefined
-
-    if (!shipment_id) {
-      const shipment = await this.createShipment({
-        carrier_id,
-        carrier_service_code,
-        from_address: {
-          name: context.from_location?.name,
-          address: context.from_location?.address,
-        },
-        to_address: context.shipping_address,
-        items: context.items || [],
-        currency_code: context.currency_code as string,
-      })
-      rate = shipment.rate_response.rates[0]
-    } else {
-      const rateResponse = await this.client.getShipmentRates(shipment_id)
-      rate = rateResponse[0].rates[0]
-    }
-
-    const calculatedPrice = !rate ? 0 : rate.shipping_amount.amount + rate.insurance_amount.amount + 
-      rate.confirmation_amount.amount + rate.other_amount.amount + 
-      (rate.tax_amount?.amount || 0)
-
-    return {
-      calculated_amount: calculatedPrice,
-      is_calculated_price_tax_inclusive: !!rate?.tax_amount,
-    }
-  }
-}
-```
-
-The `calculatePrice` method accepts the following parameters:
-
-1. The `data` property of the chosen shipping option during checkout.
-2. The `data` property of the shipping method, which will hold the ID of the shipment in ShipStation.
-3. An object of the checkout's context, including the cart's items, the location associated with the shipping option, and more.
-
-In the method, you first check if a `shipment_id` is already stored in the shipping method's `data` property. If so, you retrieve the shipment's rates using the client's `getShipmentRates` method. Otherwise, you use the `createShipment` method to create the shipment and get its rates.
-
-A rate returned by ShipStation has four properties that, when added up, make up the full price: `shipping_amount`, `insurance_amount`, `confirmation_amount`, and `other_amount`. It may have a `tax_amount` property, which is the amount for applied taxes.
-
-Learn more about these fields in [ShipStation's documentation](https://docs.shipstation.com/rate-shopping#about-the-response).
-
-The method returns an object having the following properties:
-
-- `calculated_amount`: The shipping method's price calculated by adding the four rate properties with the tax property, if available.
-- `is_calculated_price_tax_inclusive`: Whether the price includes taxes, which is inferred from whether the `tax_amount` property is set in the rate.
-
-Customers will now see the calculated price of a ShipStation shipping option during checkout.
-
-#### validateFulfillmentData
-
-When a customer chooses a shipping option during checkout, Medusa creates a shipping method from that option. A shipping method has a `data` property to store data relevant for later processing of the method and its fulfillments.
-
-So, in the `validateFulfillmentData` method of your provider, you'll create a shipment in ShipStation if it wasn't already created using their [get shipping rates endpoint](https://docs.shipstation.com/openapi/rates/calculate_rates), and store the ID of that shipment in the created shipping method's `data` property.
-
-Add the `validateFulfillmentData` method to `ShipStationProviderService`:
-
-```ts title="src/modules/shipstation/service.ts" highlights={serviceHighlights4}
-class ShipStationProviderService extends AbstractFulfillmentProviderService {
-  // ...
-  async validateFulfillmentData(
-    optionData: Record<string, unknown>, 
-    data: Record<string, unknown>, 
-    context: Record<string, unknown>
-  ): Promise<any> {
-    let { shipment_id } = data as {
-      shipment_id?: string
-    }
-
-    if (!shipment_id) {
-      const { carrier_id, carrier_service_code } = optionData as {
-        carrier_id: string
-        carrier_service_code: string
-      }
-      const shipment = await this.createShipment({
-        carrier_id,
-        carrier_service_code,
-        from_address: {
-          // @ts-ignore
-          name: context.from_location?.name,
-          // @ts-ignore
-          address: context.from_location?.address,
-        },
-        // @ts-ignore
-        to_address: context.shipping_address,
-        // @ts-ignore
-        items: context.items || [],
-        // @ts-ignore
-        currency_code: context.currency_code,
-      })
-      shipment_id = shipment.shipment_id
-    }
-
-    return {
-      ...data,
-      shipment_id,
-    }
-  }
-}
-```
-
-The `validateFulfillmentData` method accepts the following parameters:
-
-1. The `data` property of the chosen shipping option during checkout. It will hold the carrier ID and its service code.
-2. The `data` property of the shipping method to be created. This can hold custom data sent in the [Add Shipping Method API route](https://docs.medusajs.com/api/store#carts_postcartsidshippingmethods).
-3. An object of the checkout's context, including the cart's items, the location associated with the shipping option, and more.
-
-In the method, you try to retrieve the shipment ID from the shipping method's `data` parameter if it was already created. If not, you create the shipment in ShipStation using the `createShipment` method.
-
-Finally, you return the object to be stored in the shipping method's `data` property. You include in it the ID of the shipment in ShipStation.
-
-#### createFulfillment
-
-After the customer places the order, the admin user can manage its fulfillments. When the admin user creates a fulfillment for the order, Medusa uses the `createFulfillment` method of the associated provider to handle any processing in the third-party provider.
-
-This method supports creating split fulfillments, meaning you can partially fulfill and order's items. So, you'll create a new shipment, then purchase a label for that shipment. You'll use the existing shipment to retrieve details like the address to ship from and to.
-
-First, add a new type to `src/modules/shipstation/types.ts`:
-
-```ts title="src/modules/shipstation/types.ts"
-export type Label = {
-  label_id: string
-  status: "processing" | "completed" | "error" | "voided"
-  shipment_id: string
-  ship_date: Date
-  shipment_cost: {
-    currency: string
-    amount: number
-  }
-  insurance_cost: {
-    currency: string
-    amount: number
-  }
-  confirmation_amount: {
-    currency: string
-    amount: number
-  }
-  tracking_number: string
-  is_return_label: boolean
-  carrier_id: string
-  service_code: string
-  trackable: string
-  tracking_status: "unknown" | "in_transit" | "error" | "delivered"
-  label_download: {
-    href: string
-    pdf: string
-    png: string
-    zpl: string
-  }
-}
-```
-
-You add the `Label` type for the details in a label object. You can find more properties in [ShipStation's documentation](https://docs.shipstation.com/openapi/labels/create_label#labels/create_label/response\&c=200/body).
-
-Then, add the following methods to the `ShipStationClient`:
-
-```ts title="src/modules/shipstation/client.ts"
-// other imports...
-import { 
-  // ...
-  Label,
-  Shipment,
-} from "./types"
-
-export class ShipStationClient {
-  // ...
-
-  async getShipment(id: string): Promise<Shipment> {
-    return await this.sendRequest(`/shipments/${id}`)
-  }
-
-  async purchaseLabelForShipment(id: string): Promise<Label> {
-    return await this.sendRequest(`/labels/shipment/${id}`, {
-      method: "POST",
-      body: JSON.stringify({}),
-    })
-  }
-}
-```
-
-You add the `getShipment` method to retrieve a shipment's details, and the `purchaseLabelForShipment` method to purchase a label in ShipStation for a shipment by its ID.
-
-Finally, add the `createFulfillment` method in `ShipStationProviderService`:
-
-```ts title="src/modules/shipstation/service.ts" highlights={serviceHighlights6}
-class ShipStationProviderService extends AbstractFulfillmentProviderService {
-  // ...
-  async createFulfillment(
-    data: object, 
-    items: object[], 
-    order: object | undefined, 
-    fulfillment: Record<string, unknown>
-  ): Promise<any> {
-    const { shipment_id } = data as {
-      shipment_id: string
-    }
-
-    const originalShipment = await this.client.getShipment(shipment_id)
-
-    const orderItemsToFulfill = []
-
-    items.map((item) => {
-      // @ts-ignore
-      const orderItem = order.items.find((i) => i.id === item.line_item_id)
-
-      if (!orderItem) {
-        return
-      }
-
-      // @ts-ignore
-      orderItemsToFulfill.push({
-        ...orderItem,
-        // @ts-ignore
-        quantity: item.quantity,
-      })
-    })
-
-    const newShipment = await this.createShipment({
-      carrier_id: originalShipment.carrier_id,
-      carrier_service_code: originalShipment.service_code,
-      from_address: {
-        name: originalShipment.ship_from.name,
-        address: {
-          ...originalShipment.ship_from,
-          address_1: originalShipment.ship_from.address_line1,
-          city: originalShipment.ship_from.city_locality,
-          province: originalShipment.ship_from.state_province,
-        },
-      },
-      to_address: {
-        ...originalShipment.ship_to,
-        address_1: originalShipment.ship_to.address_line1,
-        city: originalShipment.ship_to.city_locality,
-        province: originalShipment.ship_to.state_province,
-      },
-      items: orderItemsToFulfill as OrderLineItemDTO[],
-      // @ts-ignore
-      currency_code: order.currency_code,
-    })
-
-    const label = await this.client.purchaseLabelForShipment(newShipment.shipment_id)
-
-    return {
-      data: {
-        ...(fulfillment.data as object || {}),
-        label_id: label.label_id,
-        shipment_id: label.shipment_id,
-      },
-    }
-  }
-}
-```
-
-This method accepts the following parameters:
-
-- `data`: The `data` property of the associated shipping method, which holds the ID of the shipment.
-- `items`: The items to fulfill.
-- `order`: The order's details.
-- `fulfillment`: The details of the fulfillment to be created.
-
-In the method, you:
-
-- Retrieve the details of the shipment originally associated with the fulfillment's shipping method.
-- Filter out the order items to retrieve the items to fulfill.
-- Create a new shipment for the items to fulfill. You use the original shipment for details like the carrier ID or the addresses to ship from and to.
-- Purchase a label for the new shipment.
-
-You return an object whose `data` property will be stored in the created fulfillment's `data` property. You store in it the ID of the purchased label and the ID of its associated shipment.
-
-#### cancelFulfillment
-
-The last method you'll implement is the `cancelFulfillment` method. When an admin user cancels a fulfillment, Medusa uses the associated provider's `cancelFulfillment` method to perform any necessary actions in the third-party provider.
-
-You'll use this method to void the label in ShipStation that was purchased in the `createFulfillment` method and cancel its associated shipment.
-
-Start by adding the following type to `src/modules/shipstation/types.ts`:
-
-```ts title="src/modules/shipstation/types.ts"
-export type VoidLabelResponse = {
-  approved: boolean
-  message: string
-  reason_code?: string
-}
-```
-
-`VoidLabelResponse` is the response type of [ShipStation's void label endpoint](https://docs.shipstation.com/openapi/labels/void_label).
-
-Next, add two methods to `ShipStationClient`:
-
-```ts title="src/modules/shipstation/client.ts" highlights={clientHighlights4}
-// other imports...
-import { 
-  // ...
-  VoidLabelResponse,
-} from "./types"
-
-export class ShipStationClient {
-  // ...
-  async voidLabel(id: string): Promise<VoidLabelResponse> {
-    return await this.sendRequest(`/labels/${id}/void`, {
-      method: "PUT",
-    })
-  }
-
-  async cancelShipment(id: string): Promise<void> {
-    return await this.sendRequest(`/shipments/${id}/cancel`, {
-      method: "PUT",
-    })
-  }
-}
-```
-
-You added two methods:
-
-- `voidLabel` that accepts the ID of a label to void using [ShipStation's endpoint](https://docs.shipstation.com/openapi/labels/void_label).
-- `cancelShipment` that accepts the ID of a shipment to cancel using [ShipStation's endpoint](https://docs.shipstation.com/openapi/shipments/cancel_shipments).
-
-Finally, in `ShipStationProviderService`, add the `cancelFulfillment` method:
-
-```ts title="src/modules/shipstation/service.ts"
-class ShipStationProviderService extends AbstractFulfillmentProviderService {
-  // ...
-  async cancelFulfillment(data: Record<string, unknown>): Promise<any> {
-    const { label_id, shipment_id } = data as {
-      label_id: string
-      shipment_id: string
-    }
-
-    await this.client.voidLabel(label_id)
-    await this.client.cancelShipment(shipment_id)
-  }
-}
-```
-
-This method accepts the fulfillment's `data` property as a parameter. You get the ID of the label and shipment from the `data` parameter.
-
-Then, you use the client's `voidLabel` method to void the label, and `cancelShipment` to cancel the shipment.
-
-Refer to [this guide](https://docs.medusajs.com/references/fulfillment/provider/index.html.md) for a full reference of all methods, their parameters and return types.
-
-### Export Module Definition
-
-The `ShipStationProviderService` class now has the methods necessary to handle fulfillments.
-
-Next, you must export the module provider's definition, which lets Medusa know what module this provider belongs to and its service.
-
-Create the file `src/modules/shipstation/index.ts` with the following content:
-
-![The directory structure of the Medusa application after adding the index file](https://res.cloudinary.com/dza7lstvk/image/upload/v1734350125/Medusa%20Resources/shipstation-dir-overview-5_zs6beg.jpg)
-
-```ts title="src/modules/shipstation/index.ts"
-import ShipStationProviderService from "./service"
-import { 
-  ModuleProvider, 
-  Modules,
-} from "@medusajs/framework/utils"
-
-export default ModuleProvider(Modules.FULFILLMENT, {
-  services: [ShipStationProviderService],
-})
-```
-
-You export the module provider's definition using `ModuleProvider` from the Modules SDK. It accepts as a first parameter the name of the module that this provider belongs to, which is the Fulfillment Module. It also accepts as a second parameter an object having a `service` property indicating the provider's service.
-
-### Add Module to Configurations
-
-Finally, to register modules and module providers in Medusa, you must add them to Medusa's configurations.
-
-Medusa's configurations are set in the `medusa-config.ts` file, which is at the root directory of your Medusa application. The configuration object accepts a `modules` array, whose value is an array of modules to add to the application.
-
-Add the `modules` property to the exported configurations in `medusa-config.ts`:
-
-```ts title="medusa-config.ts"
-module.exports = defineConfig({
-  // ...
-  modules: [
-    {
-      resolve: "@medusajs/medusa/fulfillment",
-      options: {
-        providers: [
-          // default provider
-          {
-            resolve: "@medusajs/medusa/fulfillment-manual",
-            id: "manual",
-          },
-          {
-            resolve: "./src/modules/shipstation",
-            id: "shipstation",
-            options: {
-              api_key: process.env.SHIPSTATION_API_KEY,
-            },
-          },
-        ],
-      },
-    },
-  ],
-})
-```
-
-In the `modules` array, you pass a module object having the following properties:
-
-- `resolve`: The NPM package of the Fulfillment Module. Since the ShipStation Module is a Fulfillment Module Provider, it'll be passed in the options of the Fulfillment Module.
-- `options`: An object of options to pass to the module. It has a `providers` property which is an array of module providers to register. Each module provider object has the following properties:
-  - `resolve`: The path to the module provider to register in the application. It can also be the name of an NPM package.
-  - `id`: A unique ID, which Medusa will use along with the `identifier` static property that you set earlier in the class to identify this module provider.
-  - `options`: An object of options to pass to the module provider. These are the options you expect and use in the module provider's service.
-
-The values of the ShipStation Module's options are set in environment variables. So, add the following environment variables to `.env`:
-
-```shell
-SHIPSTATION_API_KEY=123...
-```
-
-Where `SHIPSTATION_API_KEY` is the ShipStation API key, which you can retrieve on the ShipStation dashboard:
-
-- Click on the cog icon in the navigation bar to go to Settings.
-
-![The cog icon is at the top right of the navigation bar. It's the third icon from the right.](https://res.cloudinary.com/dza7lstvk/image/upload/v1734352047/Medusa%20Resources/Screenshot_2024-12-16_at_2.27.02_PM_nnmwzo.png)
-
-- In the sidebar, expand Account and click on API Settings
-
-![The sidebar has an Account expandable. When you click on it, more items will show. Click on the API Settings](https://res.cloudinary.com/dza7lstvk/image/upload/v1734352145/Medusa%20Resources/Screenshot_2024-12-16_at_2.28.32_PM_wwfc1s.png).
-
-- On the API Settings page, make sure V2 API is selected for "Select API Verion" field, then click the "Generate API Key" button.
-
-![Make sure V2 API is selected in the Select API Version dropdown, then click on the "Generate API Key" button.](https://res.cloudinary.com/dza7lstvk/image/upload/v1734352261/Medusa%20Resources/Screenshot_2024-12-16_at_2.30.31_PM_vbkz4i.png)
-
-- Copy the generated API key and use it as the value of the `SHIPSTATION_API_KEY` environment variable.
-
-***
-
-## Step 4: Add Shipping Options for ShipStation
-
-Now that you've integrated ShipStation, you need to create its shipping options so that customers can choose from them during checkout.
-
-First, start the Medusa application:
-
-```bash npm2yarn
-npm run dev
-```
-
-Then:
-
-1. Open the Medusa Admin at `http://localhost:9000/app` and log in.
-2. Go to Settings -> Locations & Shipping
-
-![After clicking on settings in the main dashboard, a new sidebar will be shown where you can click on Location & Shipping](https://res.cloudinary.com/dza7lstvk/image/upload/v1733923761/Medusa%20Resources/Screenshot_2024-12-11_at_2.41.25_PM_wjbq5f.png)
-
-3. Each location has shipping options. So, either create a new location, or click on the "View details" link at the top-right of a location.
-
-![A location's card has the "View details" link at the top-right.](https://res.cloudinary.com/dza7lstvk/image/upload/v1733923793/Medusa%20Resources/Screenshot_2024-12-11_at_2.41.50_PM_idglsu.png)
-
-4. On the location's page and under the Fulfillment Providers section, click on the three-dots icon and choose Edit from the dropdown.
-
-![The location's page has as a "Fulfillment Providers" section in the side column at the right. Click on the three-dots icon in that section and choose Edit from the dropdown](https://res.cloudinary.com/dza7lstvk/image/upload/v1733923832/Medusa%20Resources/Screenshot_2024-12-11_at_2.42.47_PM_rzbjbf.png)
-
-5. A pop up will open with the list of all integrated fulfillment providers. Click the checkbox at the left of the "Shipstation" provider, then click Save.
-
-![Choose the fulfillment provider from the list and click on the Save button](https://res.cloudinary.com/dza7lstvk/image/upload/v1734517015/Medusa%20Resources/Screenshot_2024-12-18_at_12.06.05_PM_nkmljy.png)
-
-6. Under the Shipping section, click on the "Create option" link.
-
-![The Create Option link is in the Shipping section next to shipping options](https://res.cloudinary.com/dza7lstvk/image/upload/v1734517185/Medusa%20Resources/Screenshot_2024-12-18_at_12.19.26_PM_o3yz4n.png)
-
-7. In the form that opens:
-   - Select Calculated for the price type.
-   - Enter a name for the shipping option. This is the name that customers see in the storefront.
-   - Choose a Shipping Profile.
-   - Choose ShipStation for Fulfillment Provider
-   - This will load in the "Fulfillment option" field the ShipStation provider's options, which are retrieved on the server from the provider's `getFulfillmentOptions` method. Once they're loaded, choose one of the options retrieved from ShipStation.
-   - Click the Save button.
-
-![Select Calculated for price type, and select the correct fulfillment provider and option](https://res.cloudinary.com/dza7lstvk/image/upload/v1734517536/Medusa%20Resources/Screenshot_2024-12-18_at_12.24.44_PM_yk7s3z.png)
-
-You can create a shipping option for each fulfillment option.
-
-Customers can now select this shipping option during checkout, and the fulfillment for their order will be processed by ShipStation.
-
-***
-
-## Test it Out: Place an Order and Fulfill It
-
-To test out the integration, you'll place an order using the Next.js Starter Storefront you installed with the Medusa application. You'll then create a fulfillment for the order's items from the Medusa Admin dashboard.
-
-### Place Order in Storefront
-
-Open the terminal in the Next.js Starter Storefront's directory. It's a sibling directory of the Medusa application with the name `{project-name}-storefront`, where `{project-name}` is the name of the Medusa application's project.
-
-Then, while the Medusa application is running, run the following command in the storefront's directory:
-
-```bash npm2yarn
-npm run dev
-```
-
-This will run the storefront at `http://localhost:8000`. Open it in your browser, then:
-
-1. Click on Menu at the top left of the navigation bar, then choose Store.
-
-![After you click on Menu, choose Store from the side menu.](https://res.cloudinary.com/dza7lstvk/image/upload/v1734518126/Medusa%20Resources/Screenshot_2024-12-18_at_12.35.10_PM_knk46m.png)
-
-2. Click on a product and add it to the cart.
-
-![On a product's page, choose and option then click "add to cart"](https://res.cloudinary.com/dza7lstvk/image/upload/v1734518298/Medusa%20Resources/Screenshot_2024-12-18_at_12.36.18_PM_lrqnsj.png)
-
-3. Click on "Cart" at the top right to go to the cart's page.
-
-![Click on Cart at the top right of the navigation bar.](https://res.cloudinary.com/dza7lstvk/image/upload/v1734518298/Medusa%20Resources/Screenshot_2024-12-18_at_12.36.59_PM_hmvpgb.png)
-
-4. From the cart's page, click on "Go to checkout".
-
-![The "Go to checkout" button is at the bottom right of the page.](https://res.cloudinary.com/dza7lstvk/image/upload/v1734518298/Medusa%20Resources/Screenshot_2024-12-18_at_12.37.52_PM_ma4dij.png)
-
-5. Enter the customer address as a first step of the Checkout. Make sure that the country you choose is the same as the location that the fulfillment provider's options are available in.
-
-If you're entering US-based address, make sure to enter the two-letter code for your state, as that's required by ShipStation.
-
-6. In the Delivery step, you'll find the option you added for ShipStation. There will be a loading indicator while its price is fetched, and the price will be shown afterwards.
-
-![Price is shown next to the ShipStation shipping option](https://res.cloudinary.com/dza7lstvk/image/upload/v1734528106/Medusa%20Resources/Screenshot_2024-12-18_at_3.19.14_PM_smrzae.png)
-
-7. Click on the ShipStation option, then click Continue to Payment.
-8. Finish the payment step, then click Place order in the Review section
-
-You've now created an order that uses a shipping option from ShipStation.
-
-### Fulfill Order in Admin
-
-You'll now manage the order you've created in the admin to fulfill it:
-
-1. Open the admin at `http://localhost:9000/app` and login.
-2. You'll find on the Orders page the order you've created. Click on it to view its details.
-3. On the order's details page, scroll down to the Unfulfilled Items section. Then, click on the three-dots icon at the top right of the section and choose "Fulfill items" from the dropdown.
-
-![In the Unfulfilled Items section, click on the three dots, then Fulfill items from the dropdown](https://res.cloudinary.com/dza7lstvk/image/upload/v1734530779/Medusa%20Resources/Screenshot_2024-12-18_at_4.05.29_PM_z9lwsk.png)
-
-4. In the form that opens, choose the Location to fulfill the item(s) from, then click Create Fulfillment.
-
-![Choose from the dropdown the location to fulfill the items from, then click Create Fulfillment at the bottom right.](https://res.cloudinary.com/dza7lstvk/image/upload/v1734530888/Medusa%20Resources/Screenshot_2024-12-18_at_4.07.35_PM_f4h5o1.png)
-
-5. The created fulfillment will be showing on the order's details page now.
-
-![Created fulfillment with details](https://res.cloudinary.com/dza7lstvk/image/upload/v1734535715/Medusa%20Resources/Screenshot_2024-12-18_at_5.28.06_PM_tsuk4a.png)
-
-You can also cancel the fulfillment by clicking on the three-dots icon, then choosing Cancel from the dropdown. This will void the label in ShipStation and cancel its shipment.
-
-***
-
-## Next Steps
-
-You've now integrated Medusa with ShipStation. You can fulfill orders with many carriers and providers, all from a single integration and platform.
-
-If you're new to Medusa, check out the [main documentation](https://docs.medusajs.com/docs/learn/index.html.md), where you'll get a more in-depth learning of all the concepts you've used in this guide and more.
-
-To learn more about the commerce features that Medusa provides, check out Medusa's [Commerce Modules](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/index.html.md).
-
-
 # Integrate Medusa with Sanity (CMS)
 
 In this guide, you'll learn how to integrate Medusa with Sanity.
@@ -48995,23 +49559,25 @@ If you're new to Medusa, check out the [main documentation](https://docs.medusaj
 To learn more about the commerce features that Medusa provides, check out Medusa's [Commerce Modules](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/index.html.md).
 
 
-# Integrate Medusa with Resend (Email Notifications)
+# Integrate Medusa with ShipStation (Fulfillment)
 
-In this guide, you'll learn how to integrate Medusa with Resend.
+In this guide, you'll learn how to integrate Medusa with ShipStation.
 
-When you install a Medusa application, you get a fully-fledged commerce platform with a Framework for customization. Medusa's architecture supports integrating third-party services, such as an email service, that allow you to build your unique requirements around core commerce flows.
+Refer your technical team to this guide to integrate ShipStation with your Medusa application. You can then enable it using the Medusa Admin as explained in [this user guide](https://docs.medusajs.com/user-guide/settings/locations-and-shipping/locations#manage-fulfillment-providers/index.html.md).
 
-[Resend](https://resend.com/docs/introduction) is an email service with an intuitive developer experience to send emails from any application type, including Node.js servers. By integrating Resend with Medusa, you can build flows to send an email when a commerce operation is performed, such as when an order is placed.
+When you install a Medusa application, you get a fully-fledged commerce platform with support for customizations. Medusa's [Fulfillment Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/fulfillment/index.html.md) provides fulfillment-related resources and functionalities in your store, but it delegates the processing and shipment of order fulfillments to providers that you can integrate.
+
+[ShipStation](https://shipstation.com/) is a shipping toolbox that connects all your shipping providers within one platform. By integrating it with Medusa, you can allow customers to choose from different providers like DHL and FedEx and view price rates retrieved from ShipStation. Admin users will also process the order fulfillment using the ShipStation integration.
 
 This guide will teach you how to:
 
 - Install and set up Medusa.
-- Integrate Resend into Medusa for sending emails.
-- Build a flow to send an email with Resend when a customer places an order.
+- Set up a ShipStation account.
+- Integrate ShipStation as a fulfillment provider in Medusa.
 
 You can follow this guide whether you're new to Medusa or an advanced Medusa developer.
 
-[Example Repository](https://github.com/medusajs/examples/tree/main/resend-integration): Find the full code of the guide in this repository.
+[Example Repository](https://github.com/medusajs/examples/tree/main/shipstation-integration): Find the full code of the guide in this repository.
 
 ***
 
@@ -49035,332 +49601,1010 @@ Afterwards, the installation process will start, which will install the Medusa a
 
 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 about Medusa's architecture in [this 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 credential and submit the form. Afterwards, you can login with the new user and explore the dashboard.
+Once the installation finishes successfully, the Medusa Admin dashboard will open with a form to create a new user. Enter the user's credential and submit the form.
 
-The Next.js storefront is also running at `http://localhost:8000`.
+Afterwards, you can login with the new user and explore the dashboard. The Next.js storefront is also running at `http://localhost:8000`.
 
 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: Prepare Resend Account
+## Step 2: Prepare ShipStation Account
 
-If you don't have a Resend Account, create one on [their website](https://resend.com/emails).
+In this step, you'll prepare your ShipStation account before integrating it into Medusa. If you don't have an account, create one [here](https://www.shipstation.com/start-a-free-trial).
 
-In addition, Resend allows you to send emails from the address `onboarding@resend.dev` only to your account's email, which is useful for development purposes. If you have a custom domain to send emails from, add it to your Resend account's domains:
+### Enable Carriers
 
-1. Go to Domains from the sidebar.
-2. Click on Add Domain.
+To create labels for your shipments, you need to enable carriers. This requires you to enter payment and address details.
 
-![Click on Domains in the sidebar then on the Add Domain button in the middle of the page.](https://res.cloudinary.com/dza7lstvk/image/upload/v1732523238/Medusa%20Resources/Screenshot_2024-11-25_at_10.18.11_AM_pmqgtv.png)
+To enable carriers:
 
-3\. In the form that opens, enter your domain name and select a region close to your users, then click Add.
+1. On the Onboard page, in the "Enable carriers & see rates" section, click on the "Enable Carriers" button.
 
-![A pop-up window with Domain and Region fields.](https://res.cloudinary.com/dza7lstvk/image/upload/v1732523280/Medusa%20Resources/Screenshot_2024-11-25_at_10.18.52_AM_sw2pr4.png)
+![Scroll down to the Enable carriers & see rates section, and find the "Enable Carriers" button.](https://res.cloudinary.com/dza7lstvk/image/upload/v1734523873/Medusa%20Resources/Screenshot_2024-12-18_at_2.10.54_PM_pmvcfr.png)
 
-4\. In the domain's details page that opens, you'll find DNS records to add to your DNS provider. After you add them, click on Verify DNS Records. You can start sending emails from your custom domain once it's verified.
+2. In the pop-up that opens, click on Continue Setup.
 
-The steps to add DNS records are different for each provider, so refer to your provider's documentation or knowledge base for more details.
+![Click on the green Continue Setup button](https://res.cloudinary.com/dza7lstvk/image/upload/v1734524261/Medusa%20Resources/Screenshot_2024-12-18_at_2.11.47_PM_wsl98i.png)
 
-![The DNS records to add are in a table under the DNS Records section. Once added, click the Verify DNS Records button at the top right.](https://res.cloudinary.com/dza7lstvk/image/upload/v1732523394/Medusa%20Resources/Screenshot_2024-11-25_at_10.20.56_AM_ktvbse.png)
+3. In the next section of the form, you have to enter your payment details and billing address. Once done, click on Continue Setup.
+4. After that, click the checkboxes on the Terms of Service section, then click the Finish Setup button.
 
-You also need an API key to connect to your Resend account from Medusa, but you'll create that one in a later section.
+![Enable the two checkboxes, then click on Finish Setup at the bottom right](https://res.cloudinary.com/dza7lstvk/image/upload/v1734524486/Medusa%20Resources/Screenshot_2024-12-18_at_2.20.12_PM_pkixma.png)
+
+5. Once you're done, you can optionally add funds to your account. If you're not US-based, make sure to disable ParcelGuard insurance. Otherwise, an error will occur while retrieving rates later.
+
+### Add Carriers
+
+You must have at least one carrier (shipping provider) added in your ShipStation account. You'll later provide shipping options for each of these carriers in your Medusa application.
+
+To add carriers:
+
+1. On the Onboard page, in the "Enable carriers & see rates" section, click on the "Add your carrier accounts" link.
+
+![Scroll down to the Enable carriers & see rates section, and find the "Add your carrier accounts" link under the "Enable Carriers" button](https://res.cloudinary.com/dza7lstvk/image/upload/v1734336612/Medusa%20Resources/Screenshot_2024-12-16_at_10.09.08_AM_nqshhg.png)
+
+2. Click on a provider from the pop-up window.
+
+![Click on the provider tiles in the pop-up window](https://res.cloudinary.com/dza7lstvk/image/upload/v1734336826/Medusa%20Resources/Screenshot_2024-12-16_at_10.13.37_AM_og4sdq.png)
+
+Based on the provider you chose, you'll have to enter your account details, then submit the form.
+
+### Activate Shipping API
+
+To integrate ShipStation using their API, you must enable the Shipping API Add-On. To do that:
+
+1. Go to Add-Ons from the navigation bar.
+2. Find Shipping API and activate it.
+
+You'll later retrieve your API key.
 
 ***
 
-## Step 3: Install Resend Dependencies
-
-In this step, you'll install two packages useful for your Resend integration:
-
-1. `resend`, which is the Resend SDK:
-
-```bash npm2yarn
-npm install resend
-```
-
-2\. [react-email](https://github.com/resend/react-email),  which is a package created by Resend to create email templates with React:
-
-```bash npm2yarn
-npm install @react-email/components -E
-```
-
-You'll use these packages in the next steps.
-
-***
-
-## Step 4: Create Resend Module Provider
+## Step 3: Create ShipStation Module Provider
 
 To integrate third-party services into Medusa, you create a custom module. A module is a re-usable 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.
 
-Medusa's Notification Module delegates sending notifications to other modules, called module providers. In this step, you'll create a Resend Module Provider that implements sending notifications through the email channel. In later steps, you'll send email notifications with Resend when an order is placed through this provider.
+Medusa's Fulfillment Module delegates processing fulfillments and shipments to other modules, called module providers. In this step, you'll create a ShipStation Module Provider that implements all functionalities required for fulfillment. In later steps, you'll add into Medusa shipping options for ShipStation, and allow customers to choose it during checkout.
 
 Learn more about modules in [this documentation](https://docs.medusajs.com/docs/learn/fundamentals/modules/index.html.md).
 
 ### Create Module Directory
 
-A module is created under the `src/modules` directory of your Medusa application. So, create the directory `src/modules/resend`.
+A module is created under the `src/modules` directory of your Medusa application. So, create the directory `src/modules/shipstation`.
+
+![The directory structure of the Medusa application after adding the module's directory](https://res.cloudinary.com/dza7lstvk/image/upload/v1734338950/Medusa%20Resources/shipstation-dir-overview-1_dlsrbv.jpg)
 
 ### Create Service
 
 You define a module's functionalities in a service. A service is a TypeScript or JavaScript class that the module exports. In the service's methods, you can connect to the database, which is useful if your module defines tables in the database, or connect to a third-party service.
 
-In this section, you'll create the Resend Module Provider's service and the methods necessary to send an email with Resend.
+In this section, you'll create the ShipStation Module Provider's service and the methods necessary to handle fulfillment.
 
-Start by creating the file `src/modules/resend/service.ts` with the following content:
+Start by creating the file `src/modules/shipstation/service.ts` with the following content:
 
-```ts title="src/modules/resend/service.ts" highlights={serviceHighlights1}
-import { 
-  AbstractNotificationProviderService,
-} from "@medusajs/framework/utils"
-import { 
-  Logger,
-} from "@medusajs/framework/types"
-import { 
-  Resend,
-} from "resend"
+![The directory structure of the Medusa application after adding the service](https://res.cloudinary.com/dza7lstvk/image/upload/v1734339042/Medusa%20Resources/shipstation-dir-overview-2_cmgvcj.jpg)
 
-type ResendOptions = {
+```ts title="src/modules/shipstation/service.ts" highlights={serviceHighlights1}
+import { AbstractFulfillmentProviderService } from "@medusajs/framework/utils"
+
+export type ShipStationOptions = {
   api_key: string
-  from: string
-  html_templates?: Record<string, {
-    subject?: string
-    content: string
-  }>
 }
 
-class ResendNotificationProviderService extends AbstractNotificationProviderService {
-  static identifier = "notification-resend"
-  private resendClient: Resend
-  private options: ResendOptions
-  private logger: Logger
+class ShipStationProviderService extends AbstractFulfillmentProviderService {
+  static identifier = "shipstation"
+  protected options_: ShipStationOptions
 
-  // ...
+  constructor({}, options: ShipStationOptions) {
+    super()
+
+    this.options_ = options
+  }
+
+  // TODO add methods
 }
 
-export default ResendNotificationProviderService
+export default ShipStationProviderService
 ```
 
-A Notification Module Provider's service must extend the `AbstractNotificationProviderService`. It has a `send` method that you'll implement soon. The service must also have an `identifier` static property, which is a unique identifier that the Medusa application will use to register the provider in the database.
+A Fulfillment Module Provider service must extend the `AbstractFulfillmentProviderService` class. You'll implement the abstract methods of this class in the upcoming sections.
 
-The `ResendNotificationProviderService` class also has the following properties:
+The service must have an `identifier` static property, which is a unique identifier for the provider. You set the identifier to `shipstation`.
 
-- `resendClient` of type `Resend` (from the Resend SDK you installed in the previous step) to send emails through Resend.
-- `options` of type `ResendOptions`. Modules accept options through Medusa's configurations. This ensures that the module is reusable across applications and you don't use sensitive variables like API keys directly in your code. The options that the Resend Module Provider accepts are:
-  - `api_key`: The Resend API key.
-  - `from`: The email address to send the emails from.
-  - `html_templates`: An optional object to replace the default subject and template that the Resend Module uses. This is also useful to support custom emails in different Medusa application setups.
-- `logger` property, which is an instance of Medusa's [Logger](https://docs.medusajs.com/docs/learn/debugging-and-testing/logging/index.html.md), to log messages.
+A module can receive options that are set when you later add the module to Medusa's configurations. These options allow you to safely store secret values outside of your code.
 
-To send requests using the `resendClient`, you need to initialize it in the class's constructor. So, add the following constructor to `ResendNotificationProviderService`:
+The ShipStation module requires an `api_key` option, indicating your ShipStation's API key. You receive the options as a second parameter of the service's constructor.
 
-```ts title="src/modules/resend/service.ts"
-// ...
+### Create Client
 
-type InjectedDependencies = {
-  logger: Logger
-}
+To send requests to ShipStation, you'll create a client class that provides the methods to send requests. You'll then use that class in your service.
 
-class ResendNotificationProviderService extends AbstractNotificationProviderService {
-  // ...
-  constructor(
-    { logger }: InjectedDependencies, 
-    options: ResendOptions
-  ) {
-    super()
-    this.resendClient = new Resend(options.api_key)
+Create the file `src/modules/shipstation/client.ts` with the following content:
+
+![The directory structure of the Medusa application after adding the client file](https://res.cloudinary.com/dza7lstvk/image/upload/v1734339519/Medusa%20Resources/shipstation-dir-overview-3_b8im2d.jpg)
+
+```ts title="src/modules/shipstation/client.ts" highlights={clientHighlights1}
+import { ShipStationOptions } from "./service"
+import { MedusaError } from "@medusajs/framework/utils"
+
+export class ShipStationClient {
+  options: ShipStationOptions
+
+  constructor(options) {
     this.options = options
-    this.logger = logger
+  }
+
+  private async sendRequest(url: string, data?: RequestInit): Promise<any> {
+    return fetch(`https://api.shipstation.com/v2${url}`, {
+      ...data,
+      headers: {
+        ...data?.headers,
+        "api-key": this.options.api_key,
+        "Content-Type": "application/json",
+      },
+    }).then((resp) => {
+      const contentType = resp.headers.get("content-type")
+      if (!contentType?.includes("application/json")) {
+        return resp.text()
+      }
+
+      return resp.json()
+    })
+    .then((resp) => {
+      if (typeof resp !== "string" && resp.errors?.length) {
+        throw new MedusaError(
+          MedusaError.Types.INVALID_DATA,
+          `An error occured while sending a request to ShipStation: ${
+            resp.errors.map((error) => error.message)
+          }`
+        )
+      }
+
+      return resp
+    })
   }
 }
 ```
 
-A module's service accepts two parameters:
+The `ShipStationClient` class accepts the ShipStation options in its constructor and sets those options in the `options` property.
 
-1. Dependencies resolved from the [Module's container](https://docs.medusajs.com/docs/learn/fundamentals/modules/container/index.html.md), which is the module's local registry that the Medusa application adds Framework tools to. In this service, you resolve the [Logger utility](https://docs.medusajs.com/docs/learn/debugging-and-testing/logging/index.html.md) from the module's container.
-2. The module's options that are passed to the module in Medusa's configuration as you'll see in a later section.
+You also add a private `sendRequest` method that accepts a path to send a request to and the request's configurations. In the method, you send a request using the Fetch API, passing the API key from the options in the request header. You also parse the response body based on its content type, and check if there are any errors to be thrown before returning the parsed response.
 
-Using the API key passed in the module's options, you initialize the Resend client. You also set the `options` and `logger` properties.
+You'll add more methods to send requests in the upcoming steps.
 
-#### Validate Options Method
+To use the client in `ShipStationProviderService`, add it as a class property and initialize it in the constructor:
 
-A Notification Module Provider's service can implement a static `validateOptions` method that ensures the options passed to the module through Medusa's configurations are valid.
+```ts title="src/modules/shipstation/service.ts" highlights={serviceHighlights2}
+// imports...
+import { ShipStationClient } from "./client"
 
-So, add to the `ResendNotificationProviderService` the `validateOptions` method:
+// ...
 
-```ts title="src/modules/resend/service.ts"
+class ShipStationProviderService extends AbstractFulfillmentProviderService {
+  // properties...
+  protected client: ShipStationClient
+
+  constructor({}, options: ShipStationOptions) {
+    // ...
+    this.client = new ShipStationClient(options)
+  }
+}
+```
+
+You import `ShipStationClient` and add a new `client` property in `ShipStationProviderService`. In the class's constructor, you set the `client` property by initializing `ShipStationProviderService`, passing it the module's options.
+
+You'll use the `client` property when implementing the service's methods.
+
+### Implement Service Methods
+
+In this section, you'll go back to the `ShipStationProviderService` method to implement the abstract methods of `AbstractFulfillmentProviderService`.
+
+Refer to [this guide](https://docs.medusajs.com/references/fulfillment/provider/index.html.md) for a full reference of all methods, their parameters and return types.
+
+#### getFulfillmentOptions
+
+The `getFulfillmentOptions` method returns the options that this fulfillment provider supports. When admin users add shipping options later in the Medusa Admin, they'll select one of these options.
+
+Learn more about shipping options in [this guide](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/fulfillment/shipping-option/index.html.md).
+
+ShipStation requires that a shipment must be associated with a carrier and one of its services. So, in this method, you'll retrieve the list of carriers from ShipStation and return them as fulfillment options. Shipping options created from these fulfillment options will always have access to the option's carrier and service.
+
+Before you start implementing methods, you'll add the expected carrier types returned by ShipStation. Create the file `src/modules/shipstation/types.ts` with the following content:
+
+![The directory structure of the Medusa application after adding the types file](https://res.cloudinary.com/dza7lstvk/image/upload/v1734340402/Medusa%20Resources/shipstation-dir-overview-4_fwsle0.jpg)
+
+```ts title="src/modules/shipstation/types.ts"
+export type Carrier = {
+  carrier_id: string
+  disabled_by_billing_plan: boolean
+  friendly_name: string
+  services: {
+    service_code: string
+    name: string
+  }[]
+  packages: {
+    package_code: string
+  }[]
+  [k: string]: unknown
+}
+
+export type CarriersResponse = {
+  carriers: Carrier[]
+}
+```
+
+You define a `Carrier` type that holds a carrier's details, and a `CarriersResponse` type, which is the response returned by ShipStation.
+
+A carrier has more fields that you can use. Refer to [ShipStation's documentation](https://docs.shipstation.com/openapi/carriers/list_carriers#carriers/list_carriers/t=response\&c=200\&path=carriers) for all carrier fields.
+
+Next, you'll add in `ShipStationClient` the method to retrieve the carriers from ShipStation. So, add to the class defined in `src/modules/shipstation/client.ts` a new method:
+
+```ts title="src/modules/shipstation/client.ts" highlights={clientHighlights2}
 // other imports...
 import { 
-  // other imports...
+  CarriersResponse,
+} from "./types"
+
+export class ShipStationClient {
+  // ...
+  async getCarriers(): Promise<CarriersResponse> {
+    return await this.sendRequest("/carriers") 
+  }
+}
+```
+
+You added a new `getCarriers` method that uses the `sendRequest` method to send a request to the [ShipStation's List Carriers endpoint](https://docs.shipstation.com/openapi/carriers/list_carriers). The method returns `CarriersResponse` that you defined earlier.
+
+Finally, add the `getFulfillmentOptions` method to `ShipStationProviderService`:
+
+```ts title="src/modules/shipstation/service.ts" highlights={serviceHighlights3}
+// other imports...
+import { 
+  FulfillmentOption,
+} from "@medusajs/framework/types"
+
+class ShipStationProviderService extends AbstractFulfillmentProviderService {
+  // ...
+  async getFulfillmentOptions(): Promise<FulfillmentOption[]> {
+    const { carriers } = await this.client.getCarriers() 
+    const fulfillmentOptions: FulfillmentOption[] = []
+
+    carriers
+      .filter((carrier) => !carrier.disabled_by_billing_plan)
+      .forEach((carrier) => {
+        carrier.services.forEach((service) => {
+          fulfillmentOptions.push({
+            id: `${carrier.carrier_id}__${service.service_code}`,
+            name: service.name,
+            carrier_id: carrier.carrier_id,
+            carrier_service_code: service.service_code,
+          })
+        })
+      })
+
+    return fulfillmentOptions
+  }
+}
+```
+
+In the `getFulfillmentOptions` method, you retrieve the carriers from ShipStation. You then filter out the carriers disabled by your ShipStation billing plan, and loop over the remaining carriers and their services.
+
+You return an array of fulfillment-option objects, where each object represents a carrier and service pairing. Each object has the following properties:
+
+- an `id` property, which you set to a combination of the carrier ID and the service code.
+- a `name` property, which you set to the service's `name`. The admin user will see this name when they create a shipping option for the ShipStation provider.
+- You can pass other data, such as `carrier_id` and `carrier_service_code`, and Medusa will store the fulfillment option in the `data` property of shipping options created later.
+
+Learn more about the shipping option's `data` property in [this guide](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/fulfillment/shipping-option/index.html.md).
+
+You'll see this method in action later when you create a shipping option.
+
+#### canCalculate
+
+When an admin user creates a shipping option for your provider, they can choose whether the price is flat rate or calculated during checkout.
+
+If the user chooses calculated, Medusa validates that your fulfillment provider supports calculated prices using the `canCalculate` method of your provider's service.
+
+This method accepts the shipping option's `data` field, which will hold the data of an option returned by `getFulfillmentOptions`. It returns a boolean value indicating whether the shipping option can have a calculated price.
+
+Add the method to `ShipStationProviderService` in `src/modules/shipstation/service.ts`:
+
+```ts title="src/modules/shipstation/service.ts"
+// other imports...
+import {
+  // ...
+  CreateShippingOptionDTO,
+} from "@medusajs/framework/types"
+
+class ShipStationProviderService extends AbstractFulfillmentProviderService {
+  // ...
+  async canCalculate(data: CreateShippingOptionDTO): Promise<boolean> {
+    return true
+  }
+}
+```
+
+Since all shipping option prices can be calculated with ShipStation based on the chosen carrier and service zone, you always return `true` in this method.
+
+You'll implement the calculation mechanism in a later method.
+
+#### calculatePrice
+
+When the customer views available shipping options during checkout, the Medusa application requests the calculated price from your fulfillment provider using its `calculatePrice` method.
+
+To retrieve shipping prices with ShipStation, you create a shipment first then get its rates. So, in the `calculatePrice` method, you'll either:
+
+- Send a request to [ShipStation's get shipping rates endpoint](https://docs.shipstation.com/openapi/rates/calculate_rates) that creates a shipment and returns its prices;
+- Or, if a shipment was already created before, you'll retrieve its prices using [ShipStation's get shipment rates endpoint](https://docs.shipstation.com/openapi/shipments/list_shipment_rates).
+
+First, add the following types to `src/modules/shipstation/types.ts`:
+
+```ts title="src/modules/shipstation/types.ts" highlights={typesHighlights1}
+export type ShipStationAddress = {
+  name: string
+  phone: string
+  email?: string | null
+  company_name?: string | null
+  address_line1: string
+  address_line2?: string | null
+  address_line3?: string | null
+  city_locality: string
+  state_province: string
+  postal_code: string
+  country_code: string
+  address_residential_indicator: "unknown" | "yes" | "no"
+  instructions?: string | null
+  geolocation?: {
+    type?: string
+    value?: string
+  }[]
+}
+
+export type Rate = {
+  rate_id: string
+  shipping_amount: {
+    currency: string
+    amount: number
+  }
+  insurance_amount: {
+    currency: string
+    amount: number
+  }
+  confirmation_amount: {
+    currency: string
+    amount: number
+  }
+  other_amount: {
+    currency: string
+    amount: number
+  }
+  tax_amount: {
+    currency: string
+    amount: number
+  }
+}
+
+export type RateResponse = {
+  rates: Rate[]
+}
+
+export type GetShippingRatesRequest = {
+  shipment_id?: string
+  shipment?: Omit<Shipment, "shipment_id" | "shipment_status">
+  rate_options: {
+    carrier_ids: string[]
+    service_codes: string[]
+    preferred_currency: string
+  }
+}
+
+export type GetShippingRatesResponse = {
+  shipment_id: string
+  carrier_id?: string
+  service_code?: string
+  external_order_id?: string
+  rate_response: RateResponse
+}
+
+export type Shipment = {
+  shipment_id: string
+  carrier_id: string
+  service_code: string
+  ship_to: ShipStationAddress
+  return_to?: ShipStationAddress
+  is_return?: boolean
+  ship_from: ShipStationAddress
+  items?: [
+    {
+      name?: string
+      quantity?: number
+      sku?: string
+    }
+  ]
+  warehouse_id?: string
+  shipment_status: "pending" | "processing" | "label_purchased" | "cancelled"
+  [k: string]: unknown
+}
+
+```
+
+You add the following types:
+
+- `ShipStationAddress`: an address to ship from or to.
+- `Rate`: a price rate for a specified carrier and service zone.
+- `RateResponse`: The response when retrieving rates.
+- `GetShippingRatesRequest`: The request body data for [ShipStation's get shipping rates endpoint](https://docs.shipstation.com/openapi/rates/calculate_rates). You can refer to their API reference for other accepted parameters.
+- `GetShippingRatesResponse`: The response of the [ShipStation's get shipping rates endpoint](https://docs.shipstation.com/openapi/rates/calculate_rates). You can refer to their API reference for other response fields.
+- `Shipment`: A shipment's details.
+
+Then, add the following methods to `ShipStationClient`:
+
+```ts title="src/modules/shipstation/client.ts" highlights={serviceHighlights7}
+// other imports...
+import { 
+  // ...
+  GetShippingRatesRequest,
+  GetShippingRatesResponse,
+  RateResponse,
+} from "./types"
+
+export class ShipStationClient {
+  // ...
+  async getShippingRates(
+    data: GetShippingRatesRequest
+  ): Promise<GetShippingRatesResponse> {
+    return await this.sendRequest("/rates", {
+      method: "POST",
+      body: JSON.stringify(data),
+    }).then((resp) => {
+      if (resp.rate_response.errors?.length) {
+        throw new MedusaError(
+          MedusaError.Types.INVALID_DATA,
+          `An error occured while retrieving rates from ShipStation: ${
+            resp.rate_response.errors.map((error) => error.message)
+          }`
+        )
+      }
+
+      return resp
+    })
+  }
+
+  async getShipmentRates(id: string): Promise<RateResponse[]> {
+    return await this.sendRequest(`/shipments/${id}/rates`)
+  }
+}
+```
+
+The `getShippingRates` method accepts as a parameter the data to create a shipment and retrieve its rate. In the method, you send the request using the `sendRequest` method, and throw any errors in the rate retrieval before returning the response.
+
+The `getShipmentRates` method accepts the ID of the shipment as a parameter, sends the request using the `sendRequest` method and returns its response holding the shipment's rates.
+
+Next, add to `ShipStationProviderService` a private method that'll be used to create a shipment in ShipStation and get its rates:
+
+```ts title="src/modules/shipstation/service.ts" highlights={serviceHighlights8}
+// other imports...
+import {
+  // ...
   MedusaError,
 } from "@medusajs/framework/utils"
-
-// ...
-
-class ResendNotificationProviderService extends AbstractNotificationProviderService {
+import { 
   // ...
-  static validateOptions(options: Record<any, any>) {
-    if (!options.api_key) {
+  CalculateShippingOptionPriceDTO,
+} from "@medusajs/framework/types"
+import {
+  GetShippingRatesResponse,
+  ShipStationAddress,
+} from "./types"
+
+class ShipStationProviderService extends AbstractFulfillmentProviderService {
+  // ...
+  private async createShipment({
+    carrier_id,
+    carrier_service_code,
+    from_address,
+    to_address,
+    items,
+    currency_code,
+  }: {
+    carrier_id: string
+    carrier_service_code: string
+    from_address?: {
+      name?: string
+      address?: Omit<
+        StockLocationAddressDTO, "created_at" | "updated_at" | "deleted_at"
+      >
+    },
+    to_address?: Omit<
+      CartAddressDTO, "created_at" | "updated_at" | "deleted_at" | "id"
+    >,
+    items: CartLineItemDTO[] | OrderLineItemDTO[],
+    currency_code: string
+  }): Promise<GetShippingRatesResponse> {
+    if (!from_address?.address) {
       throw new MedusaError(
         MedusaError.Types.INVALID_DATA,
-        "Option `api_key` is required in the provider's options."
+        "from_location.address is required to calculate shipping rate"
       )
     }
-    if (!options.from) {
+    const ship_from: ShipStationAddress = {
+      name: from_address?.name || "",
+      phone: from_address?.address?.phone || "",
+      address_line1: from_address?.address?.address_1 || "",
+      city_locality: from_address?.address?.city || "",
+      state_province: from_address?.address?.province || "",
+      postal_code: from_address?.address?.postal_code || "",
+      country_code: from_address?.address?.country_code || "",
+      address_residential_indicator: "unknown",
+    }
+    if (!to_address) {
       throw new MedusaError(
         MedusaError.Types.INVALID_DATA,
-        "Option `from` is required in the provider's options."
+        "shipping_address is required to calculate shipping rate"
       )
     }
+    
+    const ship_to: ShipStationAddress = {
+      name: `${to_address.first_name} ${to_address.last_name}`,
+      phone: to_address.phone || "",
+      address_line1: to_address.address_1 || "",
+      city_locality: to_address.city || "",
+      state_province: to_address.province || "",
+      postal_code: to_address.postal_code || "",
+      country_code: to_address.country_code || "",
+      address_residential_indicator: "unknown",
+    }
+
+    // TODO create shipment
   }
 }
 ```
 
-In the `validateOptions` method, you throw an error if the `api_key` or `from` options aren't passed to the module. To throw errors, you use `MedusaError` from the Modules SDK. This ensures errors follow Medusa's conventions and are displayed similar to Medusa's errors.
+The `createShipment` method accepts as a parameter an object having the following properties:
 
-#### Implement Template Methods
+- `carrier_id`: The ID of the carrier to create the shipment for.
+- `carrier_service_code`: The code of the carrier's service.
+- `from_address`: The address to ship items from, which is the address of the stock location associated with a shipping option.
+- `to_address`: The address to ship items to, which is the customer's address.
+- `items`: An array of the items in the cart or order (for fulfilling the order later).
+- `currency_code`: The currency code of the cart or order.
 
-Each email type has a different template and content. For example, order confirmation emails show the order's details, whereas customer confirmation emails show a greeting message to the customer.
+In the `createShipment` method, so far you only prepare the data to be sent to ShipStation. ShipStation requires the addresses to ship the items from and to.
 
-So, add two methods to the `ResendNotificationProviderService` class that retrieve the email template and subject of a specified template type:
+To send the request, replace the `TODO` with the following:
 
-```ts title="src/modules/resend/service.ts" highlights={serviceHighlights2}
-// imports and types...
+```ts title="src/modules/shipstation/service.ts"
+// Sum the package's weight
+// You can instead create different packages for each item
+const packageWeight = items.reduce((sum, item) => {
+  // @ts-ignore
+  return sum + (item.variant.weight || 0)
+}, 0)
 
-enum Templates {
-  ORDER_PLACED = "order-placed",
-}
-
-const templates: {[key in Templates]?: (props: unknown) => React.ReactNode} = {
-  // TODO add templates
-}
-
-class ResendNotificationProviderService extends AbstractNotificationProviderService {
-  // ...
-  getTemplate(template: Templates) {
-    if (this.options.html_templates?.[template]) {
-      return this.options.html_templates[template].content
-    }
-    const allowedTemplates = Object.keys(templates)
-
-    if (!allowedTemplates.includes(template)) {
-      return null
-    }
-
-    return templates[template]
-  }
-
-  getTemplateSubject(template: Templates) {
-    if (this.options.html_templates?.[template]?.subject) {
-      return this.options.html_templates[template].subject
-    }
-    switch(template) {
-      case Templates.ORDER_PLACED:
-        return "Order Confirmation"
-      default:
-        return "New Email"
-    }
-  }
-}
+return await this.client.getShippingRates({
+  shipment: {
+    carrier_id: carrier_id,
+    service_code: carrier_service_code,
+    ship_to,
+    ship_from,
+    validate_address: "no_validation",
+    items: items?.map((item) => ({
+      name: item.title,
+      quantity: item.quantity,
+      sku: item.variant_sku || "",
+    })),
+    packages: [{
+      weight: {
+        value: packageWeight,
+        unit: "kilogram",
+      },
+    }],
+    customs: {
+      contents: "merchandise",
+      non_delivery: "return_to_sender",
+    },
+  },
+  rate_options: {
+    carrier_ids: [carrier_id],
+    service_codes: [carrier_service_code],
+    preferred_currency: currency_code as string,
+  },
+})
 ```
 
-You first define a `Templates` enum, which holds the names of supported template types. You can add more template types to this enum later. You also define a `templates` variable that specifies the React template for each template type. You'll add templates to this variable later.
+You create a shipment and get its rates using the `getShippingRates` method you added to the client. You pass the method the expected request body parameters by [ShipStation's get shipping rates endpoint](https://docs.shipstation.com/openapi/rates/calculate_rates), including the carrier ID, the items to be shipped, and more.
 
-In the `ResendNotificationProviderService` you add two methods:
+The above snippet assumes all items are sent in a single package. You can instead pass a package for each item, specifying its weight and optionally its height, width, and length.
 
-- `getTemplate`: Retrieve the template of a template type. If the `html_templates` option is set for the specified template type, you return its `content`'s value. Otherwise, you retrieve the template from the `templates` variable.
-- `getTemplateSubject`: Retrieve the subject of a template type. If a `subject` is passed for the template type in the `html_templates`, you return its value. Otherwise, you return a subject based on the template type.
+Finally, add the `calculatePrice` method to `ShipStationProviderService`:
 
-You'll use these methods in the `send` method next.
-
-#### Implement Send Method
-
-In this section, you'll implement the `send` method of `ResendNotificationProviderService`. When you send a notification through the email channel later using the Notification Module, the Notification Module's service will use this `send` method under the hood to send the email with Resend.
-
-In the `send` method, you'll retrieve the template and subject of the email template, then send the email using the Resend client.
-
-Add the `send` method to the `ResendNotificationProviderService` class:
-
-```ts title="src/modules/resend/service.ts" highlights={serviceHighlights3}
+```ts title="src/modules/shipstation/service.ts" highlights={serviceHighlights5}
 // other imports...
 import { 
   // ...
-  ProviderSendNotificationDTO, 
-  ProviderSendNotificationResultsDTO,
+  CalculatedShippingOptionPrice,
 } from "@medusajs/framework/types"
-import { 
+
+class ShipStationProviderService extends AbstractFulfillmentProviderService {
   // ...
-  CreateEmailOptions, 
-} from "resend"
-
-class ResendNotificationProviderService extends AbstractNotificationProviderService {
-  // ...
-  async send(
-    notification: ProviderSendNotificationDTO
-  ): Promise<ProviderSendNotificationResultsDTO> {
-    const template = this.getTemplate(notification.template as Templates)
-
-    if (!template) {
-      this.logger.error(`Couldn't find an email template for ${notification.template}. The valid options are ${Object.values(Templates)}`)
-      return {}
+  async calculatePrice(
+    optionData: CalculateShippingOptionPriceDTO["optionData"], 
+    data: CalculateShippingOptionPriceDTO["data"], 
+    context: CalculateShippingOptionPriceDTO["context"]
+  ): Promise<CalculatedShippingOptionPrice> {
+    const { shipment_id } = data as {
+      shipment_id?: string
+    } || {}
+    const { carrier_id, carrier_service_code } = optionData as {
+      carrier_id: string
+      carrier_service_code: string
     }
+    let rate: Rate | undefined
 
-    const emailOptions: CreateEmailOptions = {
-      from: this.options.from,
-      to: [notification.to],
-      subject: this.getTemplateSubject(notification.template as Templates),
-      html: "",
-    }
-
-    if (typeof template === "string") {
-      emailOptions.html = template
+    if (!shipment_id) {
+      const shipment = await this.createShipment({
+        carrier_id,
+        carrier_service_code,
+        from_address: {
+          name: context.from_location?.name,
+          address: context.from_location?.address,
+        },
+        to_address: context.shipping_address,
+        items: context.items || [],
+        currency_code: context.currency_code as string,
+      })
+      rate = shipment.rate_response.rates[0]
     } else {
-      emailOptions.react = template(notification.data)
-      delete emailOptions.html
+      const rateResponse = await this.client.getShipmentRates(shipment_id)
+      rate = rateResponse[0].rates[0]
     }
 
-    const { data, error } = await this.resendClient.emails.send(emailOptions)
+    const calculatedPrice = !rate ? 0 : rate.shipping_amount.amount + rate.insurance_amount.amount + 
+      rate.confirmation_amount.amount + rate.other_amount.amount + 
+      (rate.tax_amount?.amount || 0)
 
-    if (error) {
-      this.logger.error(`Failed to send email`, error)
-      return {}
+    return {
+      calculated_amount: calculatedPrice,
+      is_calculated_price_tax_inclusive: !!rate?.tax_amount,
     }
-
-    return { id: data.id }
   }
 }
 ```
 
-The `send` method receives the notification details object as a parameter. Some of its properties include:
+The `calculatePrice` method accepts the following parameters:
 
-- `to`: The address to send the notification to.
-- `template`: The template type of the notification.
-- `data`: The data useful for the email type. For example, when sending an order-confirmation email, `data` would hold the order's details.
+1. The `data` property of the chosen shipping option during checkout.
+2. The `data` property of the shipping method, which will hold the ID of the shipment in ShipStation.
+3. An object of the checkout's context, including the cart's items, the location associated with the shipping option, and more.
 
-In the method, you retrieve the template and subject of the email using the methods you defined earlier. Then, you put together the data to pass to Resend, such as the email address to send the notification to and the email address to send from. Also, if the email's template is a string, it's passed as an HTML template. Otherwise, it's passed as a React template.
+In the method, you first check if a `shipment_id` is already stored in the shipping method's `data` property. If so, you retrieve the shipment's rates using the client's `getShipmentRates` method. Otherwise, you use the `createShipment` method to create the shipment and get its rates.
 
-Finally, you use the `emails.send` method of the Resend client to send the email. If an error occurs you log it in the terminal. Otherwise, you return the ID of the send email as received from Resend. Medusa uses this ID when creating the notification in its database.
+A rate returned by ShipStation has four properties that, when added up, make up the full price: `shipping_amount`, `insurance_amount`, `confirmation_amount`, and `other_amount`. It may have a `tax_amount` property, which is the amount for applied taxes.
+
+Learn more about these fields in [ShipStation's documentation](https://docs.shipstation.com/rate-shopping#about-the-response).
+
+The method returns an object having the following properties:
+
+- `calculated_amount`: The shipping method's price calculated by adding the four rate properties with the tax property, if available.
+- `is_calculated_price_tax_inclusive`: Whether the price includes taxes, which is inferred from whether the `tax_amount` property is set in the rate.
+
+Customers will now see the calculated price of a ShipStation shipping option during checkout.
+
+#### validateFulfillmentData
+
+When a customer chooses a shipping option during checkout, Medusa creates a shipping method from that option. A shipping method has a `data` property to store data relevant for later processing of the method and its fulfillments.
+
+So, in the `validateFulfillmentData` method of your provider, you'll create a shipment in ShipStation if it wasn't already created using their [get shipping rates endpoint](https://docs.shipstation.com/openapi/rates/calculate_rates), and store the ID of that shipment in the created shipping method's `data` property.
+
+Add the `validateFulfillmentData` method to `ShipStationProviderService`:
+
+```ts title="src/modules/shipstation/service.ts" highlights={serviceHighlights4}
+class ShipStationProviderService extends AbstractFulfillmentProviderService {
+  // ...
+  async validateFulfillmentData(
+    optionData: Record<string, unknown>, 
+    data: Record<string, unknown>, 
+    context: Record<string, unknown>
+  ): Promise<any> {
+    let { shipment_id } = data as {
+      shipment_id?: string
+    }
+
+    if (!shipment_id) {
+      const { carrier_id, carrier_service_code } = optionData as {
+        carrier_id: string
+        carrier_service_code: string
+      }
+      const shipment = await this.createShipment({
+        carrier_id,
+        carrier_service_code,
+        from_address: {
+          // @ts-ignore
+          name: context.from_location?.name,
+          // @ts-ignore
+          address: context.from_location?.address,
+        },
+        // @ts-ignore
+        to_address: context.shipping_address,
+        // @ts-ignore
+        items: context.items || [],
+        // @ts-ignore
+        currency_code: context.currency_code,
+      })
+      shipment_id = shipment.shipment_id
+    }
+
+    return {
+      ...data,
+      shipment_id,
+    }
+  }
+}
+```
+
+The `validateFulfillmentData` method accepts the following parameters:
+
+1. The `data` property of the chosen shipping option during checkout. It will hold the carrier ID and its service code.
+2. The `data` property of the shipping method to be created. This can hold custom data sent in the [Add Shipping Method API route](https://docs.medusajs.com/api/store#carts_postcartsidshippingmethods).
+3. An object of the checkout's context, including the cart's items, the location associated with the shipping option, and more.
+
+In the method, you try to retrieve the shipment ID from the shipping method's `data` parameter if it was already created. If not, you create the shipment in ShipStation using the `createShipment` method.
+
+Finally, you return the object to be stored in the shipping method's `data` property. You include in it the ID of the shipment in ShipStation.
+
+#### createFulfillment
+
+After the customer places the order, the admin user can manage its fulfillments. When the admin user creates a fulfillment for the order, Medusa uses the `createFulfillment` method of the associated provider to handle any processing in the third-party provider.
+
+This method supports creating split fulfillments, meaning you can partially fulfill and order's items. So, you'll create a new shipment, then purchase a label for that shipment. You'll use the existing shipment to retrieve details like the address to ship from and to.
+
+First, add a new type to `src/modules/shipstation/types.ts`:
+
+```ts title="src/modules/shipstation/types.ts"
+export type Label = {
+  label_id: string
+  status: "processing" | "completed" | "error" | "voided"
+  shipment_id: string
+  ship_date: Date
+  shipment_cost: {
+    currency: string
+    amount: number
+  }
+  insurance_cost: {
+    currency: string
+    amount: number
+  }
+  confirmation_amount: {
+    currency: string
+    amount: number
+  }
+  tracking_number: string
+  is_return_label: boolean
+  carrier_id: string
+  service_code: string
+  trackable: string
+  tracking_status: "unknown" | "in_transit" | "error" | "delivered"
+  label_download: {
+    href: string
+    pdf: string
+    png: string
+    zpl: string
+  }
+}
+```
+
+You add the `Label` type for the details in a label object. You can find more properties in [ShipStation's documentation](https://docs.shipstation.com/openapi/labels/create_label#labels/create_label/response\&c=200/body).
+
+Then, add the following methods to the `ShipStationClient`:
+
+```ts title="src/modules/shipstation/client.ts"
+// other imports...
+import { 
+  // ...
+  Label,
+  Shipment,
+} from "./types"
+
+export class ShipStationClient {
+  // ...
+
+  async getShipment(id: string): Promise<Shipment> {
+    return await this.sendRequest(`/shipments/${id}`)
+  }
+
+  async purchaseLabelForShipment(id: string): Promise<Label> {
+    return await this.sendRequest(`/labels/shipment/${id}`, {
+      method: "POST",
+      body: JSON.stringify({}),
+    })
+  }
+}
+```
+
+You add the `getShipment` method to retrieve a shipment's details, and the `purchaseLabelForShipment` method to purchase a label in ShipStation for a shipment by its ID.
+
+Finally, add the `createFulfillment` method in `ShipStationProviderService`:
+
+```ts title="src/modules/shipstation/service.ts" highlights={serviceHighlights6}
+class ShipStationProviderService extends AbstractFulfillmentProviderService {
+  // ...
+  async createFulfillment(
+    data: object, 
+    items: object[], 
+    order: object | undefined, 
+    fulfillment: Record<string, unknown>
+  ): Promise<any> {
+    const { shipment_id } = data as {
+      shipment_id: string
+    }
+
+    const originalShipment = await this.client.getShipment(shipment_id)
+
+    const orderItemsToFulfill = []
+
+    items.map((item) => {
+      // @ts-ignore
+      const orderItem = order.items.find((i) => i.id === item.line_item_id)
+
+      if (!orderItem) {
+        return
+      }
+
+      // @ts-ignore
+      orderItemsToFulfill.push({
+        ...orderItem,
+        // @ts-ignore
+        quantity: item.quantity,
+      })
+    })
+
+    const newShipment = await this.createShipment({
+      carrier_id: originalShipment.carrier_id,
+      carrier_service_code: originalShipment.service_code,
+      from_address: {
+        name: originalShipment.ship_from.name,
+        address: {
+          ...originalShipment.ship_from,
+          address_1: originalShipment.ship_from.address_line1,
+          city: originalShipment.ship_from.city_locality,
+          province: originalShipment.ship_from.state_province,
+        },
+      },
+      to_address: {
+        ...originalShipment.ship_to,
+        address_1: originalShipment.ship_to.address_line1,
+        city: originalShipment.ship_to.city_locality,
+        province: originalShipment.ship_to.state_province,
+      },
+      items: orderItemsToFulfill as OrderLineItemDTO[],
+      // @ts-ignore
+      currency_code: order.currency_code,
+    })
+
+    const label = await this.client.purchaseLabelForShipment(newShipment.shipment_id)
+
+    return {
+      data: {
+        ...(fulfillment.data as object || {}),
+        label_id: label.label_id,
+        shipment_id: label.shipment_id,
+      },
+    }
+  }
+}
+```
+
+This method accepts the following parameters:
+
+- `data`: The `data` property of the associated shipping method, which holds the ID of the shipment.
+- `items`: The items to fulfill.
+- `order`: The order's details.
+- `fulfillment`: The details of the fulfillment to be created.
+
+In the method, you:
+
+- Retrieve the details of the shipment originally associated with the fulfillment's shipping method.
+- Filter out the order items to retrieve the items to fulfill.
+- Create a new shipment for the items to fulfill. You use the original shipment for details like the carrier ID or the addresses to ship from and to.
+- Purchase a label for the new shipment.
+
+You return an object whose `data` property will be stored in the created fulfillment's `data` property. You store in it the ID of the purchased label and the ID of its associated shipment.
+
+#### cancelFulfillment
+
+The last method you'll implement is the `cancelFulfillment` method. When an admin user cancels a fulfillment, Medusa uses the associated provider's `cancelFulfillment` method to perform any necessary actions in the third-party provider.
+
+You'll use this method to void the label in ShipStation that was purchased in the `createFulfillment` method and cancel its associated shipment.
+
+Start by adding the following type to `src/modules/shipstation/types.ts`:
+
+```ts title="src/modules/shipstation/types.ts"
+export type VoidLabelResponse = {
+  approved: boolean
+  message: string
+  reason_code?: string
+}
+```
+
+`VoidLabelResponse` is the response type of [ShipStation's void label endpoint](https://docs.shipstation.com/openapi/labels/void_label).
+
+Next, add two methods to `ShipStationClient`:
+
+```ts title="src/modules/shipstation/client.ts" highlights={clientHighlights4}
+// other imports...
+import { 
+  // ...
+  VoidLabelResponse,
+} from "./types"
+
+export class ShipStationClient {
+  // ...
+  async voidLabel(id: string): Promise<VoidLabelResponse> {
+    return await this.sendRequest(`/labels/${id}/void`, {
+      method: "PUT",
+    })
+  }
+
+  async cancelShipment(id: string): Promise<void> {
+    return await this.sendRequest(`/shipments/${id}/cancel`, {
+      method: "PUT",
+    })
+  }
+}
+```
+
+You added two methods:
+
+- `voidLabel` that accepts the ID of a label to void using [ShipStation's endpoint](https://docs.shipstation.com/openapi/labels/void_label).
+- `cancelShipment` that accepts the ID of a shipment to cancel using [ShipStation's endpoint](https://docs.shipstation.com/openapi/shipments/cancel_shipments).
+
+Finally, in `ShipStationProviderService`, add the `cancelFulfillment` method:
+
+```ts title="src/modules/shipstation/service.ts"
+class ShipStationProviderService extends AbstractFulfillmentProviderService {
+  // ...
+  async cancelFulfillment(data: Record<string, unknown>): Promise<any> {
+    const { label_id, shipment_id } = data as {
+      label_id: string
+      shipment_id: string
+    }
+
+    await this.client.voidLabel(label_id)
+    await this.client.cancelShipment(shipment_id)
+  }
+}
+```
+
+This method accepts the fulfillment's `data` property as a parameter. You get the ID of the label and shipment from the `data` parameter.
+
+Then, you use the client's `voidLabel` method to void the label, and `cancelShipment` to cancel the shipment.
+
+Refer to [this guide](https://docs.medusajs.com/references/fulfillment/provider/index.html.md) for a full reference of all methods, their parameters and return types.
 
 ### Export Module Definition
 
-The `ResendNotificationProviderService` class now has the methods necessary to start sending emails.
+The `ShipStationProviderService` class now has the methods necessary to handle fulfillments.
 
 Next, you must export the module provider's definition, which lets Medusa know what module this provider belongs to and its service.
 
-Create the file `src/modules/resend/index.ts` with the following content:
+Create the file `src/modules/shipstation/index.ts` with the following content:
 
-```ts title="src/modules/resend/index.ts"
+![The directory structure of the Medusa application after adding the index file](https://res.cloudinary.com/dza7lstvk/image/upload/v1734350125/Medusa%20Resources/shipstation-dir-overview-5_zs6beg.jpg)
+
+```ts title="src/modules/shipstation/index.ts"
+import ShipStationProviderService from "./service"
 import { 
   ModuleProvider, 
   Modules,
 } from "@medusajs/framework/utils"
-import ResendNotificationProviderService from "./service"
 
-export default ModuleProvider(Modules.NOTIFICATION, {
-  services: [ResendNotificationProviderService],
+export default ModuleProvider(Modules.FULFILLMENT, {
+  services: [ShipStationProviderService],
 })
 ```
 
-You export the module provider's definition using `ModuleProvider` from the Modules SDK. It accepts as a first parameter the name of the module that this provider belongs to, which is the Notification Module. It also accepts as a second parameter an object having a `service` property indicating the provider's service.
+You export the module provider's definition using `ModuleProvider` from the Modules SDK. It accepts as a first parameter the name of the module that this provider belongs to, which is the Fulfillment Module. It also accepts as a second parameter an object having a `service` property indicating the provider's service.
 
 ### Add Module to Configurations
 
@@ -49375,16 +50619,19 @@ module.exports = defineConfig({
   // ...
   modules: [
     {
-      resolve: "@medusajs/medusa/notification",
+      resolve: "@medusajs/medusa/fulfillment",
       options: {
         providers: [
+          // default provider
           {
-            resolve: "./src/modules/resend",
-            id: "resend",
+            resolve: "@medusajs/medusa/fulfillment-manual",
+            id: "manual",
+          },
+          {
+            resolve: "./src/modules/shipstation",
+            id: "shipstation",
             options: {
-              channels: ["email"],
-              api_key: process.env.RESEND_API_KEY,
-              from: process.env.RESEND_FROM_EMAIL,
+              api_key: process.env.SHIPSTATION_API_KEY,
             },
           },
         ],
@@ -49396,1398 +50643,155 @@ module.exports = defineConfig({
 
 In the `modules` array, you pass a module object having the following properties:
 
-- `resolve`: The NPM package of the Notification Module. Since the Resend Module is a Notification Module Provider, it'll be passed in the options of the Notification Module.
+- `resolve`: The NPM package of the Fulfillment Module. Since the ShipStation Module is a Fulfillment Module Provider, it'll be passed in the options of the Fulfillment Module.
 - `options`: An object of options to pass to the module. It has a `providers` property which is an array of module providers to register. Each module provider object has the following properties:
   - `resolve`: The path to the module provider to register in the application. It can also be the name of an NPM package.
   - `id`: A unique ID, which Medusa will use along with the `identifier` static property that you set earlier in the class to identify this module provider.
-  - `options`: An object of options to pass to the module provider. These are the options you expect and use in the module provider's service. You must also specify the `channels` option, which indicates the channels that this provider sends notifications through.
+  - `options`: An object of options to pass to the module provider. These are the options you expect and use in the module provider's service.
 
-Some of the module's options, such as the Resend API key, are set in environment variables. So, add the following environment variables to `.env`:
+The values of the ShipStation Module's options are set in environment variables. So, add the following environment variables to `.env`:
 
 ```shell
-RESEND_FROM_EMAIL=onboarding@resend.dev
-RESEND_API_KEY=
+SHIPSTATION_API_KEY=123...
 ```
 
-Where:
+Where `SHIPSTATION_API_KEY` is the ShipStation API key, which you can retrieve on the ShipStation dashboard:
 
-- `RESEND_FROM_EMAIL`: The email to send emails from. If you've configured the custom domain as explained in [Step 2](#step-2-prepare-resend-account), change this email to an email from your custom domain. Otherwise, you can use `onboarding@resend.dev` for development purposes.
-- `RESEND_API_KEY` is the API key of your Resend account. To retrieve it:
-  - Go to API Keys in the sidebar.
-  - Click on the Create API Key button.
+- Click on the cog icon in the navigation bar to go to Settings.
 
-![Click on the API keys in the sidebar, then click on the Create API Key button at the top right](https://res.cloudinary.com/dza7lstvk/image/upload/v1732535399/Medusa%20Resources/Screenshot_2024-11-25_at_10.22.25_AM_v4d09s.png)
+![The cog icon is at the top right of the navigation bar. It's the third icon from the right.](https://res.cloudinary.com/dza7lstvk/image/upload/v1734352047/Medusa%20Resources/Screenshot_2024-12-16_at_2.27.02_PM_nnmwzo.png)
 
-- In the form that opens, enter a name for the API key (for example, Medusa). You can keep its permissions to Full Access or change it to Sending Access. Once you're done, click Add.
+- In the sidebar, expand Account and click on API Settings
 
-![The form to create an API key with fields for the API key's name, permissions, and domain](https://res.cloudinary.com/dza7lstvk/image/upload/v1732535464/Medusa%20Resources/Screenshot_2024-11-25_at_10.23.26_AM_g7gcuc.png)
+![The sidebar has an Account expandable. When you click on it, more items will show. Click on the API Settings](https://res.cloudinary.com/dza7lstvk/image/upload/v1734352145/Medusa%20Resources/Screenshot_2024-12-16_at_2.28.32_PM_wwfc1s.png).
 
-- A new pop-up will show with your API key hidden. Copy it before closing the pop-up, since you can't access the key again afterwards. Use its value for the `RESEND_API_KEY` environment variable.
+- On the API Settings page, make sure V2 API is selected for "Select API Verion" field, then click the "Generate API Key" button.
 
-![Click the copy icon to copy the API key](https://res.cloudinary.com/dza7lstvk/image/upload/v1732535791/Medusa%20Resources/Screenshot_2024-11-25_at_10.23.43_AM_divins.png)
+![Make sure V2 API is selected in the Select API Version dropdown, then click on the "Generate API Key" button.](https://res.cloudinary.com/dza7lstvk/image/upload/v1734352261/Medusa%20Resources/Screenshot_2024-12-16_at_2.30.31_PM_vbkz4i.png)
 
-Your Resend Module Provider is all set up. You'll test it out in a later section.
+- Copy the generated API key and use it as the value of the `SHIPSTATION_API_KEY` environment variable.
 
 ***
 
-## Step 5: Add Order Confirmation Template
+## Step 4: Add Shipping Options for ShipStation
 
-In this step, you'll add a React template for order confirmation emails. You'll create it using the [react-email](https://github.com/resend/react-email) package you installed earlier. You can follow the same steps for other email templates, such as for customer confirmation.
+Now that you've integrated ShipStation, you need to create its shipping options so that customers can choose from them during checkout.
 
-Create the directory `src/modules/resend/emails` that will hold the email templates. Then, to add the template for order confirmation, create the file `src/modules/resend/emails/order-placed.tsx` with the following content:
-
-```tsx title="src/modules/resend/emails/order-placed.tsx" highlights={templateHighlights}
-import { Text, Column, Container, Heading, Html, Img, Row, Section } from "@react-email/components"
-import { BigNumberValue, OrderDTO } from "@medusajs/framework/types"
-
-type OrderPlacedEmailProps = {
-  order: OrderDTO
-}
-
-function OrderPlacedEmailComponent({ order }: OrderPlacedEmailProps) {
-  const formatter = new Intl.NumberFormat([], {
-    style: "currency",
-    currencyDisplay: "narrowSymbol",
-    currency: order.currency_code,
-  })
-
-  const formatPrice = (price: BigNumberValue) => {
-    if (typeof price === "number") {
-      return formatter.format(price)
-    }
-
-    if (typeof price === "string") {
-      return formatter.format(parseFloat(price))
-    }
-
-    return price?.toString() || ""
-  }
-
-  return (
-    <Html>
-      <Heading>Thank you for your order</Heading>
-      {order.email}'s Items
-      <Container>
-        {order.items.map((item) => {
-          return (
-            <Section
-              key={item.id}
-              style={{ paddingTop: "40px", paddingBottom: "40px" }}
-            >
-              <Row>
-                <Column>
-                  <Img
-                    src={item.thumbnail}
-                    alt={item.product_title}
-                    style={{ float: "left" }}
-                    width="260px"
-                  />
-                </Column>
-                <Column style={{ verticalAlign: "top", paddingLeft: "12px" }}>
-                  <Text style={{ fontWeight: "500" }}>
-                    {item.product_title}
-                  </Text>
-                  <Text>{item.variant_title}</Text>
-                  <Text>{formatPrice(item.total)}</Text>
-                </Column>
-              </Row>
-            </Section>
-          )
-        })}
-      </Container>
-    </Html>
-  )
-}
-
-export const orderPlacedEmail = (props: OrderPlacedEmailProps) => (
-  <OrderPlacedEmailComponent {...props} />
-)
-```
-
-You define the `OrderPlacedEmailComponent` which is a React email template that shows the order's details, such as items and their totals. The component accepts an `order` object as a prop.
-
-You also export an `orderPlacedEmail` function, which accepts props as an input and returns the `OrderPlacedEmailComponent` passing it the props. Because you can't use JSX syntax in `src/modules/resend/service.ts`, you'll import this function instead.
-
-Next, update the `templates` variable in `src/modules/resend/service.ts` to assign this template to the `order-placed` template type:
-
-```ts title="src/modules/resend/service.ts"
-// other imports...
-import { orderPlacedEmail } from "./emails/order-placed"
-
-const templates: {[key in Templates]?: (props: unknown) => React.ReactNode} = {
-  [Templates.ORDER_PLACED]: orderPlacedEmail,
-}
-```
-
-The `ResendNotificationProviderService` will now use the `OrderPlacedEmailComponent` as the template of order confirmation emails.
-
-***
-
-## Step 6: Send Email when Order is Placed
-
-Medusa has an event system that emits an event when a commerce operation is performed. You can then listen and handle that event in an asynchronous function called a subscriber.
-
-So, to send a confirmation email when a customer places an order, which is a commerce operation that Medusa already implements, you don't need to extend or hack your way into Medusa's implementation as you would do with other commerce platforms.
-
-Instead, you'll create a subscriber that listens to the `order.placed` event and sends an email when the event is emitted.
-
-Learn more about Medusa's event system in [this documentation](https://docs.medusajs.com/docs/learn/fundamentals/events-and-subscribers/index.html.md).
-
-### Send Order Confirmation Email Workflow
-
-To send the order confirmation email, you need to retrieve the order's details first, then use the Notification Module's service to send the email. To implement this flow, you'll create a workflow.
-
-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 a subscriber.
-
-Learn more about workflows in [this documentation](https://docs.medusajs.com/docs/learn/fundamentals/workflows/index.html.md)
-
-#### Send Notification Step
-
-You'll start by implementing the step of the workflow that sends the notification. To do that, create the file `src/workflows/steps/send-notification.ts` with the following content:
-
-```ts title="src/workflows/steps/send-notification.ts"
-import { Modules } from "@medusajs/framework/utils"
-import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk"
-import { CreateNotificationDTO } from "@medusajs/framework/types"
-
-export const sendNotificationStep = createStep(
-  "send-notification",
-  async (data: CreateNotificationDTO[], { container }) => {
-    const notificationModuleService = container.resolve(
-      Modules.NOTIFICATION
-    )
-    const notification = await notificationModuleService.createNotifications(data)
-    return new StepResponse(notification)
-  }
-)
-```
-
-You define the `sendNotificationStep` using the `createStep` function that accepts two parameters:
-
-- A string indicating the step's unique name.
-- The step's function definition as a second parameter. It accepts the step's input as a first parameter, and an object of options as a second.
-
-The `container` property in the second parameter is an instance of the [Medusa container](https://docs.medusajs.com/docs/learn/fundamentals/medusa-container/index.html.md), which is a registry of Framework and commerce tools, such as a module's service, that you can resolve to utilize their functionalities.
-
-The Medusa container is accessible by all customizations, such as workflows and subscribers, except for modules. Each module has its own container with Framework tools like the Logger utility.
-
-In the step function, you resolve the Notification Module's service, and use its `createNotifications` method, passing it the notification's data that the step receives as an input.
-
-The step returns an instance of `StepResponse`, which must be returned by any step. It accepts as a parameter the data to return to the workflow that executed this step.
-
-#### Workflow Implementation
-
-You'll now create the workflow that uses the `sendNotificationStep` to send the order confirmation email.
-
-Create the file `src/workflows/send-order-confirmation.ts` with the following content:
-
-```ts title="src/workflows/send-order-confirmation.ts" highlights={workflowHighlights}
-import { 
-  createWorkflow, 
-  WorkflowResponse,
-} from "@medusajs/framework/workflows-sdk"
-import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
-import { sendNotificationStep } from "./steps/send-notification"
-
-type WorkflowInput = {
-  id: string
-}
-
-export const sendOrderConfirmationWorkflow = createWorkflow(
-  "send-order-confirmation",
-  ({ id }: WorkflowInput) => {
-    // @ts-ignore
-    const { data: orders } = useQueryGraphStep({
-      entity: "order",
-      fields: [
-        "id",
-        "email",
-        "currency_code",
-        "total",
-        "items.*",
-      ],
-      filters: {
-        id,
-      },
-    })
-    
-    const notification = sendNotificationStep([{
-      to: orders[0].email,
-      channel: "email",
-      template: "order-placed",
-      data: {
-        order: orders[0],
-      },
-    }])
-
-    return new WorkflowResponse(notification)
-  }
-)
-```
-
-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 workflow has the following steps:
-
-1. `useQueryGraphStep`, which is a step implemented by Medusa that uses [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), a tool that allows you to retrieve data across modules. You use it to retrieve the order's details.
-2. `sendNotificationStep` which is the step you implemented. You pass it an array with one object, which is the notification's details having following properties:
-   - `to`: The address to send the email to. You pass the customer's email that is stored in the order.
-   - `channel`: The channel to send the notification through, which is `email`. Since you specified `email` in the Resend Module Provider's `channel` option, the Notification Module will delegate the sending to the Resend Module Provider's service.
-   - `template`: The email's template type. You retrieve the template content in the `ResendNotificationProviderService`'s `send` method based on the template specified here.
-   - `data`: The data to pass to the email template, which is the order's details.
-
-A workflow's constructor function has some constraints in implementation. Learn more about them in [this documentation](https://docs.medusajs.com/docs/learn/fundamentals/workflows/constructor-constraints/index.html.md).
-
-You'll execute the workflow when you create the subscriber next.
-
-#### Add the Order Placed Subscriber
-
-Now that you have the workflow to send an order-confirmation email, you'll execute it in a subscriber that's executed whenever an order is placed.
-
-You create a subscriber in a TypeScript or JavaScript file under the `src/subscribers` directory. So, create the file `src/subscribers/order-placed.ts` with the following content:
-
-```ts title="src/subscribers/order-placed.ts" highlights={subscriberHighlights}
-import type {
-  SubscriberArgs,
-  SubscriberConfig,
-} from "@medusajs/framework"
-import { sendOrderConfirmationWorkflow } from "../workflows/send-order-confirmation"
-
-export default async function orderPlacedHandler({
-  event: { data },
-  container,
-}: SubscriberArgs<{ id: string }>) {
-  await sendOrderConfirmationWorkflow(container)
-    .run({
-      input: {
-        id: data.id,
-      },
-    })
-}
-
-export const config: SubscriberConfig = {
-  event: "order.placed",
-}
-```
-
-A subscriber file exports:
-
-- An asynchronous function that's executed whenever the associated event is emitted, which is the `order.placed` event.
-- A configuration object with an `event` property indicating the event the subscriber is listening to.
-
-The subscriber function accepts the event's details as a first paramter which has a `data` property that holds the data payload of the event. For example, Medusa emits the `order.placed` event with the order's ID in the data payload. The function also accepts as a second parameter the [Medusa container](https://docs.medusajs.com/docs/learn/fundamentals/medusa-container/index.html.md).
-
-In the function, you execute the `sendOrderConfirmationWorkflow` by invoking it, passing it the `container`, then using its `run` method. The `run` method accepts an object having an `input` property, which is the input to pass to the workflow. You pass the ID of the placed order as received in the event's data payload.
-
-This subscriber now runs whenever an order is placed. You'll see this in action in the next section.
-
-***
-
-## Test it Out: Place an Order
-
-To test out the Resend integration, you'll place an order using the [Next.js storefront](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/nextjs-starter/index.html.md) that you installed as part of installing Medusa.
-
-Start your Medusa application first:
+First, start the Medusa application:
 
 ```bash npm2yarn
 npm run dev
 ```
 
-Then, in the Next.js storefront's directory (which was installed in a directory outside of the Medusa application's directory with the name `{project-name}-storefront`, where `{project-name}` is the name of the Medusa application's directory), run the following command to start the storefront:
+Then:
+
+1. Open the Medusa Admin at `http://localhost:9000/app` and log in.
+2. Go to Settings -> Locations & Shipping
+
+![After clicking on settings in the main dashboard, a new sidebar will be shown where you can click on Location & Shipping](https://res.cloudinary.com/dza7lstvk/image/upload/v1733923761/Medusa%20Resources/Screenshot_2024-12-11_at_2.41.25_PM_wjbq5f.png)
+
+3. Each location has shipping options. So, either create a new location, or click on the "View details" link at the top-right of a location.
+
+![A location's card has the "View details" link at the top-right.](https://res.cloudinary.com/dza7lstvk/image/upload/v1733923793/Medusa%20Resources/Screenshot_2024-12-11_at_2.41.50_PM_idglsu.png)
+
+4. On the location's page and under the Fulfillment Providers section, click on the three-dots icon and choose Edit from the dropdown.
+
+![The location's page has as a "Fulfillment Providers" section in the side column at the right. Click on the three-dots icon in that section and choose Edit from the dropdown](https://res.cloudinary.com/dza7lstvk/image/upload/v1733923832/Medusa%20Resources/Screenshot_2024-12-11_at_2.42.47_PM_rzbjbf.png)
+
+5. A pop up will open with the list of all integrated fulfillment providers. Click the checkbox at the left of the "Shipstation" provider, then click Save.
+
+![Choose the fulfillment provider from the list and click on the Save button](https://res.cloudinary.com/dza7lstvk/image/upload/v1734517015/Medusa%20Resources/Screenshot_2024-12-18_at_12.06.05_PM_nkmljy.png)
+
+6. Under the Shipping section, click on the "Create option" link.
+
+![The Create Option link is in the Shipping section next to shipping options](https://res.cloudinary.com/dza7lstvk/image/upload/v1734517185/Medusa%20Resources/Screenshot_2024-12-18_at_12.19.26_PM_o3yz4n.png)
+
+7. In the form that opens:
+   - Select Calculated for the price type.
+   - Enter a name for the shipping option. This is the name that customers see in the storefront.
+   - Choose a Shipping Profile.
+   - Choose ShipStation for Fulfillment Provider
+   - This will load in the "Fulfillment option" field the ShipStation provider's options, which are retrieved on the server from the provider's `getFulfillmentOptions` method. Once they're loaded, choose one of the options retrieved from ShipStation.
+   - Click the Save button.
+
+![Select Calculated for price type, and select the correct fulfillment provider and option](https://res.cloudinary.com/dza7lstvk/image/upload/v1734517536/Medusa%20Resources/Screenshot_2024-12-18_at_12.24.44_PM_yk7s3z.png)
+
+You can create a shipping option for each fulfillment option.
+
+Customers can now select this shipping option during checkout, and the fulfillment for their order will be processed by ShipStation.
+
+***
+
+## Test it Out: Place an Order and Fulfill It
+
+To test out the integration, you'll place an order using the Next.js Starter Storefront you installed with the Medusa application. You'll then create a fulfillment for the order's items from the Medusa Admin dashboard.
+
+### Place Order in Storefront
+
+Open the terminal in the Next.js Starter Storefront's directory. It's a sibling directory of the Medusa application with the name `{project-name}-storefront`, where `{project-name}` is the name of the Medusa application's project.
+
+Then, while the Medusa application is running, run the following command in the storefront's directory:
 
 ```bash npm2yarn
 npm run dev
 ```
 
-Then, open the storefront in your browser at `http://localhost:8000` and:
+This will run the storefront at `http://localhost:8000`. Open it in your browser, then:
 
-1. Go to Menu -> Store.
+1. Click on Menu at the top left of the navigation bar, then choose Store.
 
-![Choose Store from Menu](https://res.cloudinary.com/dza7lstvk/image/upload/v1732539139/Medusa%20Resources/Screenshot_2024-11-25_at_2.51.59_PM_fubiwj.png)
+![After you click on Menu, choose Store from the side menu.](https://res.cloudinary.com/dza7lstvk/image/upload/v1734518126/Medusa%20Resources/Screenshot_2024-12-18_at_12.35.10_PM_knk46m.png)
 
-2\. Click on a product, select its options, and add it to the cart.
+2. Click on a product and add it to the cart.
 
-![Choose an option, such as size, then click on the Add to cart button](https://res.cloudinary.com/dza7lstvk/image/upload/v1732539227/Medusa%20Resources/Screenshot_2024-11-25_at_2.53.11_PM_iswcjy.png)
+![On a product's page, choose and option then click "add to cart"](https://res.cloudinary.com/dza7lstvk/image/upload/v1734518298/Medusa%20Resources/Screenshot_2024-12-18_at_12.36.18_PM_lrqnsj.png)
 
-3\. Click on Cart at the top right, then click Go to Cart.
+3. Click on "Cart" at the top right to go to the cart's page.
 
-![Cart is at the top right. It opens a dropdown with a Go to Cart button](https://res.cloudinary.com/dza7lstvk/image/upload/v1732539354/Medusa%20Resources/Screenshot_2024-11-25_at_2.54.44_PM_b1pnlu.png)
+![Click on Cart at the top right of the navigation bar.](https://res.cloudinary.com/dza7lstvk/image/upload/v1734518298/Medusa%20Resources/Screenshot_2024-12-18_at_12.36.59_PM_hmvpgb.png)
 
-4\. On the cart's page, click on the "Go to checkout" button.
+4. From the cart's page, click on "Go to checkout".
 
-![The Go to checkout button is at the right side of the page](https://res.cloudinary.com/dza7lstvk/image/upload/v1732539443/Medusa%20Resources/Screenshot_2024-11-25_at_2.56.27_PM_cvqshj.png)
+![The "Go to checkout" button is at the bottom right of the page.](https://res.cloudinary.com/dza7lstvk/image/upload/v1734518298/Medusa%20Resources/Screenshot_2024-12-18_at_12.37.52_PM_ma4dij.png)
 
-5\. On the checkout page, when entering the shipping address, make sure to set the email to your Resend account's email if you didn't set up a custom domain.
+5. Enter the customer address as a first step of the Checkout. Make sure that the country you choose is the same as the location that the fulfillment provider's options are available in.
 
-![Enter your Resend account email if you didn't set up a custom domain](https://res.cloudinary.com/dza7lstvk/image/upload/v1732539536/Medusa%20Resources/Screenshot_2024-11-25_at_2.58.31_PM_wmlh60.png)
+If you're entering US-based address, make sure to enter the two-letter code for your state, as that's required by ShipStation.
 
-6\. After entering the shipping address, choose a delivery and payment methods, then click the Place Order button.
+6. In the Delivery step, you'll find the option you added for ShipStation. There will be a loading indicator while its price is fetched, and the price will be shown afterwards.
 
-Once the order is placed, you'll find the following message logged in the Medusa application's terminal:
+![Price is shown next to the ShipStation shipping option](https://res.cloudinary.com/dza7lstvk/image/upload/v1734528106/Medusa%20Resources/Screenshot_2024-12-18_at_3.19.14_PM_smrzae.png)
 
-```bash
-info:    Processing order.placed which has 1 subscribers
-```
+7. Click on the ShipStation option, then click Continue to Payment.
+8. Finish the payment step, then click Place order in the Review section
 
-This indicates that the `order.placed` event was emitted and its subscriber, which you added in the previous step, is executed.
+You've now created an order that uses a shipping option from ShipStation.
 
-If you check the inbox of the email address you specified in the shipping address, you'll find a new email with the order's details.
+### Fulfill Order in Admin
 
-![Example of order-confirmation email](https://res.cloudinary.com/dza7lstvk/image/upload/v1732551372/Medusa%20Resources/Screenshot_2024-11-25_at_6.15.59_PM_efyuoj.png)
+You'll now manage the order you've created in the admin to fulfill it:
+
+1. Open the admin at `http://localhost:9000/app` and login.
+2. You'll find on the Orders page the order you've created. Click on it to view its details.
+3. On the order's details page, scroll down to the Unfulfilled Items section. Then, click on the three-dots icon at the top right of the section and choose "Fulfill items" from the dropdown.
+
+![In the Unfulfilled Items section, click on the three dots, then Fulfill items from the dropdown](https://res.cloudinary.com/dza7lstvk/image/upload/v1734530779/Medusa%20Resources/Screenshot_2024-12-18_at_4.05.29_PM_z9lwsk.png)
+
+4. In the form that opens, choose the Location to fulfill the item(s) from, then click Create Fulfillment.
+
+![Choose from the dropdown the location to fulfill the items from, then click Create Fulfillment at the bottom right.](https://res.cloudinary.com/dza7lstvk/image/upload/v1734530888/Medusa%20Resources/Screenshot_2024-12-18_at_4.07.35_PM_f4h5o1.png)
+
+5. The created fulfillment will be showing on the order's details page now.
+
+![Created fulfillment with details](https://res.cloudinary.com/dza7lstvk/image/upload/v1734535715/Medusa%20Resources/Screenshot_2024-12-18_at_5.28.06_PM_tsuk4a.png)
+
+You can also cancel the fulfillment by clicking on the three-dots icon, then choosing Cancel from the dropdown. This will void the label in ShipStation and cancel its shipment.
 
 ***
 
 ## Next Steps
 
-You've now integrated Medusa with Resend. You can add more templates for other emails, such as customer registration confirmation, user invites, and more. Check out the [Events Reference](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/events-reference/index.html.md) for a list of all events that the Medusa application emits.
-
-If you're new to Medusa, check out the [main documentation](https://docs.medusajs.com/docs/learn/index.html.md), where you'll get a more in-depth learning of all the concepts you've used in this guide and more.
-
-To learn more about the commerce features that Medusa provides, check out Medusa's [Commerce Modules](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/index.html.md).
-
-
-# How to Build Magento Data Migration Plugin
-
-In this tutorial, you'll learn how to build a [plugin](https://docs.medusajs.com/docs/learn/fundamentals/plugins/index.html.md) that migrates data, such as products, from Magento to Medusa.
-
-Magento is known for its customization capabilities. However, its monolithic architecture imposes limitations on business requirements, often forcing development teams to implement hacky workarounds. Over time, these customizations become challenging to maintain, especially as the business scales, leading to increased technical debt and slower feature delivery.
-
-Medusa's modular architecture allows you to build a custom digital commerce platform that meets your business requirements without the limitations of a monolithic system. By migrating from Magento to Medusa, you can take advantage of Medusa's modern technology stack to build a scalable and flexible commerce platform that grows with your business.
-
-By following this tutorial, you'll create a Medusa plugin that migrates data from a Magento server to a Medusa application in minimal time. You can re-use this plugin across multiple Medusa applications, allowing you to adopt Medusa across your projects.
-
-## Summary
-
-### Prerequisites
-
-
-
-This tutorial will teach you how to:
-
-- Install and set up a Medusa application project.
-- Install and set up a Medusa plugin.
-- Implement a Magento Module in the plugin to connect to Magento's APIs and retrieve products.
-  - This guide will only focus on migrating product data from Magento to Medusa. You can extend the implementation to migrate other data, such as customers, orders, and more.
-- Trigger data migration from Magento to Medusa in a scheduled job.
-
-You can follow this tutorial whether you're new to Medusa or an advanced Medusa developer.
-
-![Diagram showcasing the flow of migrating data from Magento to Medusa](https://res.cloudinary.com/dza7lstvk/image/upload/v1739360550/Medusa%20Resources/magento-summary_hsewci.jpg)
-
-[Example Repository](https://github.com/medusajs/examples/tree/main/migrate-from-magento): Find the full code of the guide in this repository. The repository also includes additional features, such as triggering migrations from the Medusa Admin dashboard.
-
-***
-
-## Step 1: Install a Medusa Application
-
-You'll first install a Medusa application that exposes core commerce features through REST APIs. You'll later install the Magento plugin in this application to test it out.
-
-### 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 be asked for the project's name. You can also optionally choose to install the [Next.js starter storefront](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/nextjs-starter/index.html.md).
-
-Afterward, the installation process will start, which will install the Medusa application in a directory with your project's name. If you chose to install the Next.js starter, it'll be installed 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). Refer to the [Medusa Architecture](https://docs.medusajs.com/docs/learn/introduction/architecture/index.html.md) documentation to learn more.
-
-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. Afterward, 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: Install a Medusa Plugin Project
-
-A plugin is a package of reusable Medusa customizations that you can install in any Medusa application. You can add in the plugin [API Routes](https://docs.medusajs.com/docs/learn/fundamentals/api-routes/index.html.md), [Workflows](https://docs.medusajs.com/docs/learn/fundamentals/workflows/index.html.md), and other customizations, as you'll see in this guide. Afterward, you can test it out locally in a Medusa application, then publish it to npm to install and use it in any Medusa application.
-
-Refer to the [Plugins](https://docs.medusajs.com/docs/learn/fundamentals/plugins/index.html.md) documentation to learn more about plugins.
-
-A Medusa plugin is set up in a different project, giving you the flexibility in building and publishing it, while providing you with the tools to test it out locally in a Medusa application.
-
-To create a new Medusa plugin project, run the following command in a directory different than that of the Medusa application:
-
-```bash npm2yarn
-npx create-medusa-app@latest medusa-plugin-magento --plugin
-```
-
-Where `medusa-plugin-magento` is the name of the plugin's directory and the name set in the plugin's `package.json`. So, if you wish to publish it to NPM later under a different name, you can change it here in the command or later in `package.json`.
-
-Once the installation process is done, a new directory named `medusa-plugin-magento` will be created with the plugin project files.
-
-![Directory structure of a plugin project](https://res.cloudinary.com/dza7lstvk/image/upload/v1737019441/Medusa%20Book/project-dir_q4xtri.jpg)
-
-***
-
-## Step 3: Set up Plugin in Medusa Application
-
-Before you start your development, you'll set up the plugin in the Medusa application you installed in the first step. This will allow you to test the plugin during your development process.
-
-In the plugin's directory, run the following command to publish the plugin to the local package registry:
-
-```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, you'll install the plugin in the Medusa application from the local registry.
-
-If you've installed your Medusa project before v2.3.1, you must install [yalc](https://github.com/wclr/yalc) as a development dependency first.
-
-Run the following command in the Medusa application's directory to install the plugin:
-
-```bash title="Medusa application"
-npx medusa plugin:add medusa-plugin-magento
-```
-
-This command installs the plugin in the Medusa application from the local package registry.
-
-Next, register the plugin in the `medusa-config.ts` file of the Medusa application:
-
-```ts title="medusa-config.ts"
-module.exports = defineConfig({
-  // ...
-  plugins: [
-    {
-      resolve: "medusa-plugin-magento",
-      options: {
-        // TODO add options
-      },
-    },
-  ],
-})
-```
-
-You add the plugin to the array of plugins. Later, you'll pass options useful to retrieve data from Magento.
-
-Finally, to ensure your plugin's changes are constantly published to the local registry, simplifying your testing process, keep the following command running in the plugin project during development:
-
-```bash title="Plugin project"
-npx medusa plugin:develop
-```
-
-***
-
-## Step 4: Implement Magento Module
-
-To connect to external applications in Medusa, you create a custom module. 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 this step, you'll create a Magento Module in the Magento plugin that connects to a Magento server's REST APIs and retrieves data, such as products.
-
-Refer to the [Modules](https://docs.medusajs.com/docs/learn/fundamentals/modules/index.html.md) documentation to learn more about modules.
-
-### Create Module Directory
-
-A module is created under the `src/modules` directory of your plugin. So, create the directory `src/modules/magento`.
-
-![Diagram showcasing the module directory to create](https://res.cloudinary.com/dza7lstvk/image/upload/v1739272368/magento-1_ikev4x.jpg)
-
-### Create Module's Service
-
-You define a module's functionalities in a service. A service is a TypeScript or JavaScript class that the module exports. In the service's methods, you can connect to external systems or the database, which is useful if your module defines tables in the database.
-
-In this section, you'll create the Magento Module's service that connects to Magento's REST APIs and retrieves data.
-
-Start by creating the file `src/modules/magento/service.ts` in the plugin with the following content:
-
-![Diagram showcasing the service file to create](https://res.cloudinary.com/dza7lstvk/image/upload/v1739272483/magento-2_ajetpr.jpg)
-
-```ts title="src/modules/magento/service.ts"
-type Options = {
-  baseUrl: string
-  storeCode?: string
-  username: string
-  password: string
-  migrationOptions?: {
-    imageBaseUrl?: string
-  }
-}
-
-export default class MagentoModuleService {
-  private options: Options
-
-  constructor({}, options: Options) {
-    this.options = {
-      ...options,
-      storeCode: options.storeCode || "default",
-    }
-  }
-}
-```
-
-You create a `MagentoModuleService` that has an `options` property to store the module's options. These options include:
-
-- `baseUrl`: The base URL of the Magento server.
-- `storeCode`: The store code of the Magento store, which is `default` by default.
-- `username`: The username of a Magento admin user to authenticate with the Magento server.
-- `password`: The password of the Magento admin user.
-- `migrationOptions`: Additional options useful for migrating data, such as the base URL to use for product images.
-
-The service's constructor accepts as a first parameter the [Module Container](https://docs.medusajs.com/docs/learn/fundamentals/modules/container/index.html.md), which allows you to access resources available for the module. As a second parameter, it accepts the module's options.
-
-### Add Authentication Logic
-
-To authenticate with the Magento server, you'll add a method to the service that retrieves an access token from Magento using the username and password in the options. This access token is used in subsequent requests to the Magento server.
-
-First, add the following property to the `MagentoModuleService` class:
-
-```ts title="src/modules/magento/service.ts"
-export default class MagentoModuleService {
-  private accessToken: {
-    token: string
-    expiresAt: Date
-  }
-  // ...
-}
-```
-
-You add an `accessToken` property to store the access token and its expiration date. The access token Magento returns expires after four hours, so you store the expiration date to know when to refresh the token.
-
-Next, add the following `authenticate` method to the `MagentoModuleService` class:
-
-```ts title="src/modules/magento/service.ts"
-import { MedusaError } from "@medusajs/framework/utils"
-
-export default class MagentoModuleService {
-  // ...
-  async authenticate() {
-    const response = await fetch(`${this.options.baseUrl}/rest/${this.options.storeCode}/V1/integration/admin/token`, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-      },
-      body: JSON.stringify({ username: this.options.username, password: this.options.password }),
-    })
-
-    const token = await response.text()
-
-    if (!response.ok) {
-      throw new MedusaError(MedusaError.Types.UNAUTHORIZED, `Failed to authenticate with Magento: ${token}`)
-    }
-
-    this.accessToken = {
-      token: token.replaceAll("\"", ""),
-      expiresAt: new Date(Date.now() + 4 * 60 * 60 * 1000), // 4 hours in milliseconds
-    }
-  }
-}
-```
-
-You create an `authenticate` method that sends a POST request to the Magento server's `/rest/{storeCode}/V1/integration/admin/token` endpoint, passing the username and password in the request body.
-
-If the request is successful, you store the access token and its expiration date in the `accessToken` property. If the request fails, you throw a `MedusaError` with the error message returned by Magento.
-
-Lastly, add an `isAccessTokenExpired` method that checks if the access token has expired:
-
-```ts title="src/modules/magento/service.ts"
-export default class MagentoModuleService {
-  // ...
-  async isAccessTokenExpired(): Promise<boolean> {
-    return !this.accessToken || this.accessToken.expiresAt < new Date()
-  }
-}
-```
-
-In the `isAccessTokenExpired` method, you return a boolean indicating whether the access token has expired. You'll use this in later methods to check if you need to refresh the access token.
-
-### Retrieve Products from Magento
-
-Next, you'll add a method that retrieves products from Magento. Due to limitations in Magento's API that makes it difficult to differentiate between simple products that don't belong to a configurable product and those that do, you'll only retrieve configurable products and their children. You'll also retrieve the configurable attributes of the product, such as color and size.
-
-First, you'll add some types to represent a Magento product and its attributes. Create the file `src/modules/magento/types.ts` in the plugin with the following content:
-
-![Diagram showcasing the types file to create](https://res.cloudinary.com/dza7lstvk/image/upload/v1739346287/Medusa%20Resources/magento-3_fpghog.jpg)
-
-```ts title="src/modules/magento/types.ts"
-export type MagentoProduct = {
-  id: number
-  sku: string
-  name: string
-  price: number
-  status: number
-  // not handling other types
-  type_id: "simple" | "configurable"
-  created_at: string
-  updated_at: string
-  extension_attributes: {
-    category_links: {
-      category_id: string
-    }[]
-    configurable_product_links?: number[] 
-    configurable_product_options?: {
-      id: number
-      attribute_id: string
-      label: string
-      position: number
-      values: {
-        value_index: number
-      }[]
-    }[]
-  }
-  media_gallery_entries: {
-    id: number
-    media_type: string
-    label: string
-    position: number
-    disabled: boolean
-    types: string[]
-    file: string
-  }[]
-  custom_attributes: {
-    attribute_code: string
-    value: string
-  }[]
-  // added by module
-  children?: MagentoProduct[]
-}
-
-export type MagentoAttribute = {
-  attribute_code: string
-  attribute_id: number
-  default_frontend_label: string
-  options: {
-    label: string
-    value: string
-  }[]
-}
-
-export type MagentoPagination = {
-  search_criteria: {
-    filter_groups: [],
-    page_size: number
-    current_page: number
-  }
-  total_count: number
-}
-
-export type MagentoPaginatedResponse<TData> = {
-  items: TData[]
-} & MagentoPagination
-```
-
-You define the following types:
-
-- `MagentoProduct`: Represents a product in Magento.
-- `MagentoAttribute`: Represents an attribute in Magento.
-- `MagentoPagination`: Represents the pagination information returned by Magento's API.
-- `MagentoPaginatedResponse`: Represents a paginated response from Magento's API for a specific item type, such as products.
-
-Next, add the `getProducts` method to the `MagentoModuleService` class:
-
-```ts title="src/modules/magento/service.ts"
-export default class MagentoModuleService {
-  // ...
-  async getProducts(options?: {
-    currentPage?: number
-    pageSize?: number
-  }): Promise<{
-    products: MagentoProduct[]
-    attributes: MagentoAttribute[]
-    pagination: MagentoPagination
-  }> {
-    const { currentPage = 1, pageSize = 100 } = options || {}
-    const getAccessToken = await this.isAccessTokenExpired()
-    if (getAccessToken) {
-      await this.authenticate()
-    }
-
-    // TODO prepare query params
-  }
-}
-```
-
-The `getProducts` method receives an optional `options` object with the `currentPage` and `pageSize` properties. So far, you check if the access token has expired and, if so, retrieve a new one using the `authenticate` method.
-
-Next, you'll prepare the query parameters to pass in the request that retrieves products. Replace the `TODO` with the following:
-
-```ts title="src/modules/magento/service.ts"
-const searchQuery = new URLSearchParams()
-// pass pagination parameters
-searchQuery.append(
-  "searchCriteria[currentPage]", 
-  currentPage?.toString() || "1"
-)
-searchQuery.append(
-  "searchCriteria[pageSize]", 
-  pageSize?.toString() || "100"
-)
-
-// retrieve only configurable products
-searchQuery.append(
-  "searchCriteria[filter_groups][1][filters][0][field]", 
-  "type_id"
-)
-searchQuery.append(
-  "searchCriteria[filter_groups][1][filters][0][value]", 
-  "configurable"
-)
-searchQuery.append(
-  "searchCriteria[filter_groups][1][filters][0][condition_type]", 
-  "in"
-)
-
-// TODO send request to retrieve products
-```
-
-You create a `searchQuery` object to store the query parameters to pass in the request. Then, you add the pagination parameters and the filter to retrieve only configurable products.
-
-Next, you'll send the request to retrieve products from Magento. Replace the `TODO` with the following:
-
-```ts title="src/modules/magento/service.ts"
-const { items: products, ...pagination }: MagentoPaginatedResponse<MagentoProduct> = await fetch(
-  `${this.options.baseUrl}/rest/${this.options.storeCode}/V1/products?${searchQuery}`, 
-  {
-    headers: {
-      "Authorization": `Bearer ${this.accessToken.token}`,
-    },
-  }
-).then((res) => res.json())
-.catch((err) => {
-  console.log(err)
-  throw new MedusaError(
-    MedusaError.Types.INVALID_DATA, 
-    `Failed to get products from Magento: ${err.message}`
-  )
-})
-
-// TODO prepare products
-```
-
-You send a `GET` request to the Magento server's `/rest/{storeCode}/V1/products` endpoint, passing the query parameters in the URL. You also pass the access token in the `Authorization` header.
-
-Next, you'll prepare the retrieved products by retrieving their children, configurable attributes, and modifying their image URLs. Replace the `TODO` with the following:
-
-```ts title="src/modules/magento/service.ts"
-const attributeIds: string[] = []
-
-await promiseAll(
-  products.map(async (product) => {
-    // retrieve its children
-    product.children = await fetch(
-      `${this.options.baseUrl}/rest/${this.options.storeCode}/V1/configurable-products/${product.sku}/children`,
-      {
-        headers: {
-          "Authorization": `Bearer ${this.accessToken.token}`,
-        },
-      }
-    ).then((res) => res.json())
-    .catch((err) => {
-      throw new MedusaError(
-        MedusaError.Types.INVALID_DATA, 
-        `Failed to get product children from Magento: ${err.message}`
-      )
-    })
-
-    product.media_gallery_entries = product.media_gallery_entries.map(
-      (entry) => ({
-        ...entry,
-        file: `${this.options.migrationOptions?.imageBaseUrl}${entry.file}`,
-      }
-    ))
-
-    attributeIds.push(...(
-      product.extension_attributes.configurable_product_options?.map(
-        (option) => option.attribute_id) || []
-      )
-    )
-  })
-)
-
-// TODO retrieve attributes
-```
-
-You loop over the retrieved products and retrieve their children using the `/rest/{storeCode}/V1/configurable-products/{sku}/children` endpoint. You also modify the image URLs to use the base URL in the migration options, if provided.
-
-In addition, you store the IDs of the configurable products' attributes in the `attributeIds` array. You'll add a method that retrieves these attributes.
-
-Add the new method `getAttributes` to the `MagentoModuleService` class:
-
-```ts title="src/modules/magento/service.ts"
-export default class MagentoModuleService {
-  // ...
-  async getAttributes({
-    ids,
-  }: {
-    ids: string[]
-  }): Promise<MagentoAttribute[]> {
-    const getAccessToken = await this.isAccessTokenExpired()
-    if (getAccessToken) {
-      await this.authenticate()
-    }
-
-    // filter by attribute IDs
-    const searchQuery = new URLSearchParams()
-    searchQuery.append(
-      "searchCriteria[filter_groups][0][filters][0][field]", 
-      "attribute_id"
-    )
-    searchQuery.append(
-      "searchCriteria[filter_groups][0][filters][0][value]", 
-      ids.join(",")
-    )
-    searchQuery.append(
-      "searchCriteria[filter_groups][0][filters][0][condition_type]", 
-      "in"
-    )
-
-    const { 
-      items: attributes,
-    }: MagentoPaginatedResponse<MagentoAttribute> = await fetch(
-      `${this.options.baseUrl}/rest/${this.options.storeCode}/V1/products/attributes?${searchQuery}`, 
-      {
-        headers: {
-          "Authorization": `Bearer ${this.accessToken.token}`,
-        },
-      }
-    ).then((res) => res.json())
-    .catch((err) => {
-      throw new MedusaError(
-        MedusaError.Types.INVALID_DATA, 
-        `Failed to get attributes from Magento: ${err.message}`
-      )
-    })
-
-    return attributes
-  }
-}
-```
-
-The `getAttributes` method receives an object with the `ids` property, which is an array of attribute IDs. You check if the access token has expired and, if so, retrieve a new one using the `authenticate` method.
-
-Next, you prepare the query parameters to pass in the request to retrieve attributes. You send a `GET` request to the Magento server's `/rest/{storeCode}/V1/products/attributes` endpoint, passing the query parameters in the URL. You also pass the access token in the `Authorization` header.
-
-Finally, you return the retrieved attributes.
-
-Now, go back to the `getProducts` method and replace the `TODO` with the following:
-
-```ts title="src/modules/magento/service.ts"
-const attributes = await this.getAttributes({ ids: attributeIds })
-    
-return { products, attributes, pagination }
-```
-
-You retrieve the configurable products' attributes using the `getAttributes` method and return the products, attributes, and pagination information.
-
-You'll use this method in a later step to retrieve products from Magento.
-
-### 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/magento/index.ts` with the following content:
-
-![Diagram showcasing the module definition file to create](https://res.cloudinary.com/dza7lstvk/image/upload/v1739348316/Medusa%20Resources/magento-4_bmepvh.jpg)
-
-```ts title="src/modules/magento/index.ts"
-import { Module } from "@medusajs/framework/utils"
-import MagentoModuleService from "./service"
-
-export const MAGENTO_MODULE = "magento"
-
-export default Module(MAGENTO_MODULE, {
-  service: MagentoModuleService,
-})
-```
-
-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 `magento`.
-2. An object with a required property `service` indicating the module's service.
-
-You'll later use the module's service to retrieve products from Magento.
-
-### Pass Options to Plugin
-
-As mentioned earlier when you registered the plugin in the Medusa Application's `medusa-config.ts` file, you can pass options to the plugin. These options are then passed to the modules in the plugin.
-
-So, add the following options to the plugin's registration in the `medusa-config.ts` file of the Medusa application:
-
-```ts title="medusa-config.ts"
-module.exports = defineConfig({
-  // ...
-  plugins: [
-    {
-      resolve: "medusa-plugin-magento",
-      options: {
-        baseUrl: process.env.MAGENTO_BASE_URL,
-        username: process.env.MAGENTO_USERNAME,
-        password: process.env.MAGENTO_PASSWORD,
-        migrationOptions: {
-          imageBaseUrl: process.env.MAGENTO_IMAGE_BASE_URL,
-        },
-      },
-    },
-  ],
-})
-```
-
-You pass the options that you defined in the `MagentoModuleService`. Make sure to also set their environment variables in the `.env` file:
-
-```bash
-MAGENTO_BASE_URL=https://magento.example.com
-MAGENTO_USERNAME=admin
-MAGENTO_PASSWORD=password
-MAGENTO_IMAGE_BASE_URL=https://magento.example.com/pub/media/catalog/product
-```
-
-Where:
-
-- `MAGENTO_BASE_URL`: The base URL of the Magento server. It can also be a local URL, such as `http://localhost:8080`.
-- `MAGENTO_USERNAME`: The username of a Magento admin user to authenticate with the Magento server.
-- `MAGENTO_PASSWORD`: The password of the Magento admin user.
-- `MAGENTO_IMAGE_BASE_URL`: The base URL to use for product images. Magento stores product images in the `pub/media/catalog/product` directory, so you can reference them directly or use a CDN URL. If the URLs of product images in the Medusa server already have a different base URL, you can omit this option.
-
-Medusa supports integrating third-party services, such as [S3](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/infrastructure-modules/file/s3/index.html.md), in a File Module Provider. Refer to the [File Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/infrastructure-modules/file/index.html.md) documentation to find other module providers and how to create a custom provider.
-
-You can now use the Magento Module to migrate data, which you'll do in the next steps.
-
-***
-
-## Step 5: Build Product Migration Workflow
-
-In this section, you'll add the feature to migrate products from Magento to Medusa. To implement this feature, you'll use a workflow.
-
-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 API route or a scheduled job.
-
-By implementing the migration feature in a workflow, you ensure that the data remains consistent and that the migration process can be rolled back if an error occurs.
-
-Refer to the [Workflows](https://docs.medusajs.com/docs/learn/fundamentals/workflows/index.html.md) documentation to learn more about workflows.
-
-### Workflow Steps
-
-The workflow you'll create will have the following steps:
-
-- [getMagentoProductsStep](#getMagentoProductsStep): Retrieve products from Magento using the Magento Module.
-- [useQueryGraphStep](https://docs.medusajs.com/references/helper-steps/useQueryGraphStep/index.html.md): Retrieve Medusa store details, which you'll need when creating the products.
-- [useQueryGraphStep](https://docs.medusajs.com/references/helper-steps/useQueryGraphStep/index.html.md): Retrieve a shipping profile, which you'll associate the created products with.
-- [useQueryGraphStep](https://docs.medusajs.com/references/helper-steps/useQueryGraphStep/index.html.md): Retrieve Magento products that are already in Medusa to update them, instead of creating them.
-- [createProductsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createProductsWorkflow/index.html.md): Create products in the Medusa application.
-- [updateProductsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateProductsWorkflow/index.html.md): Update existing products in the Medusa application.
-
-You only need to implement the `getMagentoProductsStep` step, which retrieves the products from Magento. The other steps and workflows are provided by Medusa's `@medusajs/medusa/core-flows` package.
-
-### getMagentoProductsStep
-
-The first step of the workflow retrieves and returns the products from Magento.
-
-In your plugin, create the file `src/workflows/steps/get-magento-products.ts` with the following content:
-
-![Diagram showcasing the get-magento-products file to create](https://res.cloudinary.com/dza7lstvk/image/upload/v1739349590/Medusa%20Resources/magento-5_ueb4wn.jpg)
-
-```ts title="src/workflows/steps/get-magento-products.ts"
-import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk"
-import { MAGENTO_MODULE } from "../../modules/magento"
-import MagentoModuleService from "../../modules/magento/service"
-
-type GetMagentoProductsInput = {
-  currentPage: number
-  pageSize: number
-}
-
-export const getMagentoProductsStep = createStep(
-  "get-magento-products",
-  async ({ currentPage, pageSize }: GetMagentoProductsInput, { container }) => {
-    const magentoModuleService: MagentoModuleService = 
-      container.resolve(MAGENTO_MODULE)
-
-    const response = await magentoModuleService.getProducts({
-      currentPage,
-      pageSize,
-    })
-
-    return new StepResponse(response)
-  }
-)
-```
-
-You create a step using `createStep` from the Workflows SDK. It accepts two parameters:
-
-1. The step's name, which is `get-magento-products`.
-2. An async function that executes the step's logic. The function receives two parameters:
-   - The input data for the step, which in this case is the pagination parameters.
-   - An object holding the workflow's context, including the [Medusa Container](https://docs.medusajs.com/docslearn/fundamentals/medusa-container/index.html.md) that allows you to resolve Framework and commerce tools.
-
-In the step function, you resolve the Magento Module's service from the container, then use its `getProducts` method to retrieve the products from Magento.
-
-Steps that return data must return them in a `StepResponse` instance. The `StepResponse` constructor accepts as a parameter the data to return.
-
-### Create migrateProductsFromMagentoWorkflow
-
-You'll now create the workflow that migrates products from Magento using the step you created and steps from Medusa's `@medusajs/medusa/core-flows` package.
-
-In your plugin, create the file `src/workflows/migrate-products-from-magento.ts` with the following content:
-
-![Diagram showcasing the migrate-products-from-magento file to create](https://res.cloudinary.com/dza7lstvk/image/upload/v1739349820/Medusa%20Resources/magento-6_jjdaxj.jpg)
-
-```ts title="src/workflows/migrate-products-from-magento.ts"
-import { 
-  createWorkflow, transform, WorkflowResponse,
-} from "@medusajs/framework/workflows-sdk"
-import { 
-  CreateProductWorkflowInputDTO, UpsertProductDTO,
-} from "@medusajs/framework/types"
-import { 
-  createProductsWorkflow, 
-  updateProductsWorkflow, 
-  useQueryGraphStep,
-} from "@medusajs/medusa/core-flows"
-import { getMagentoProductsStep } from "./steps/get-magento-products"
-
-type MigrateProductsFromMagentoWorkflowInput = {
-  currentPage: number
-  pageSize: number
-}
-
-export const migrateProductsFromMagentoWorkflowId = 
-  "migrate-products-from-magento"
-
-export const migrateProductsFromMagentoWorkflow = createWorkflow(
-  {
-    name: migrateProductsFromMagentoWorkflowId,
-    retentionTime: 10000,
-    store: true,
-  },
-  (input: MigrateProductsFromMagentoWorkflowInput) => {
-    const { pagination, products, attributes } = getMagentoProductsStep(
-      input
-    )
-    // TODO prepare data to create and update products
-  }
-)
-```
-
-You create a workflow using `createWorkflow` from the Workflows SDK. It accepts two parameters:
-
-1. An object with the workflow's configuration, including the name and whether to store the workflow's executions. You enable storing the workflow execution so that you can view it later in the Medusa Admin dashboard.
-2. A worflow constructor function, which holds the workflow's implementation. The function receives the input data for the workflow, which is the pagination parameters.
-
-In the workflow constructor function, you use the `getMagentoProductsStep` step to retrieve the products from Magento, passing it the pagination parameters from the workflow's input.
-
-Next, you'll retrieve the Medusa store details and shipping profiles. These are necessary to prepare the data of the products to create or update.
-
-Replace the `TODO` in the workflow function with the following:
-
-```ts title="src/workflows/migrate-products-from-magento.ts"
-const { data: stores } = useQueryGraphStep({
-  entity: "store",
-  fields: ["supported_currencies.*", "default_sales_channel_id"],
-  pagination: {
-    take: 1,
-    skip: 0,
-  },
-})
-
-const { data: shippingProfiles } = useQueryGraphStep({
-  entity: "shipping_profile",
-  fields: ["id"],
-  pagination: {
-    take: 1,
-    skip: 0,
-  },
-}).config({ name: "get-shipping-profiles" })
-
-// TODO retrieve existing products
-```
-
-You use the `useQueryGraphStep` step to retrieve the store details and shipping profiles. `useQueryGraphStep` is a Medusa step that wraps [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), allowing you to use it in a workflow. Query is a tool that retrieves data across modules.
-
-Whe retrieving the store details, you specifically retrieve its supported currencies and default sales channel ID. You'll associate the products with the store's default sales channel, and set their variant prices in the supported currencies. You'll also associate the products with a shipping profile.
-
-Next, you'll retrieve products that were previously migrated from Magento to determine which products to create or update. Replace the `TODO` with the following:
-
-```ts title="src/workflows/migrate-products-from-magento.ts"
-const externalIdFilters = transform({
-  products,
-}, (data) => {
-  return data.products.map((product) => product.id.toString())
-})
-
-const { data: existingProducts } = useQueryGraphStep({
-  entity: "product",
-  fields: ["id", "external_id", "variants.id", "variants.metadata"],
-  filters: {
-    external_id: externalIdFilters,
-  },
-}).config({ name: "get-existing-products" })
-
-// TODO prepare products to create or update
-```
-
-Since the Medusa application creates an internal representation of the workflow's constructor function, you can't manipulate data directly, as variables have no value while creating the internal representation.
-
-Refer to the [Workflows](https://docs.medusajs.com/docs/learn/fundamentals/workflows/constructor-constraints/index.html.md) documentation to learn more about the workflow constructor function's constraints.
-
-Instead, you can manipulate data in a workflow's constructor function using `transform` from the Workflows SDK. `transform` is a function that accepts two parameters:
-
-- The data to transform, which in this case is the Magento products.
-- A function that transforms the data. The function receives the data passed in the first parameter and returns the transformed data.
-
-In the transformation function, you return the IDs of the Magento products. Then, you use the `useQueryGraphStep` to retrieve products in the Medusa application that have an `external_id` property matching the IDs of the Magento products. You'll use this property to store the IDs of the products in Magento.
-
-Next, you'll prepare the data to create and update the products. Replace the `TODO` in the workflow function with the following:
-
-```ts title="src/workflows/migrate-products-from-magento.ts" highlights={prepareHighlights}
-const { 
-  productsToCreate,
-  productsToUpdate,
-} = transform({
-  products,
-  attributes,
-  stores,
-  shippingProfiles,
-  existingProducts,
-}, (data) => {
-  const productsToCreate = new Map<string, CreateProductWorkflowInputDTO>()
-  const productsToUpdate = new Map<string, UpsertProductDTO>()
-
-  data.products.forEach((magentoProduct) => {
-    const productData: CreateProductWorkflowInputDTO | UpsertProductDTO = {
-      title: magentoProduct.name,
-      description: magentoProduct.custom_attributes.find(
-        (attr) => attr.attribute_code === "description"
-      )?.value,
-      status: magentoProduct.status === 1 ? "published" : "draft",
-      handle: magentoProduct.custom_attributes.find(
-        (attr) => attr.attribute_code === "url_key"
-      )?.value,
-      external_id: magentoProduct.id.toString(),
-      thumbnail: magentoProduct.media_gallery_entries.find(
-        (entry) => entry.types.includes("thumbnail")
-      )?.file,
-      sales_channels: [{
-        id: data.stores[0].default_sales_channel_id,
-      }],
-      shipping_profile_id: data.shippingProfiles[0].id,
-    }
-    const existingProduct = data.existingProducts.find((p) => p.external_id === productData.external_id)
-
-    if (existingProduct) {
-      productData.id = existingProduct.id
-    }
-
-    productData.options = magentoProduct.extension_attributes.configurable_product_options?.map((option) => {
-      const attribute = data.attributes.find((attr) => attr.attribute_id === parseInt(option.attribute_id))
-      return {
-        title: option.label,
-        values: attribute?.options.filter((opt) => {
-          return option.values.find((v) => v.value_index === parseInt(opt.value))
-        }).map((opt) => opt.label) || [],
-      }
-    }) || []
-
-    productData.variants = magentoProduct.children?.map((child) => {
-      const childOptions: Record<string, string> = {}
-
-      child.custom_attributes.forEach((attr) => {
-        const attrData = data.attributes.find((a) => a.attribute_code === attr.attribute_code)
-        if (!attrData) {
-          return
-        }
-
-        childOptions[attrData.default_frontend_label] = attrData.options.find((opt) => opt.value === attr.value)?.label || ""
-      })
-
-      const variantExternalId = child.id.toString()
-      const existingVariant = existingProduct.variants.find((v) => v.metadata.external_id === variantExternalId)
-
-      return {
-        title: child.name,
-        sku: child.sku,
-        options: childOptions,
-        prices: data.stores[0].supported_currencies.map(({ currency_code }) => {
-          return {
-            amount: child.price,
-            currency_code,
-          }
-        }),
-        metadata: {
-          external_id: variantExternalId,
-        },
-        id: existingVariant?.id,
-      }
-    })
-
-    productData.images = magentoProduct.media_gallery_entries.filter((entry) => !entry.types.includes("thumbnail")).map((entry) => {
-      return {
-        url: entry.file,
-        metadata: {
-          external_id: entry.id.toString(),
-        },
-      }
-    })
-
-    if (productData.id) {
-      productsToUpdate.set(existingProduct.id, productData)
-    } else {
-      productsToCreate.set(productData.external_id!, productData)
-    }
-  })
-
-  return {
-    productsToCreate: Array.from(productsToCreate.values()),
-    productsToUpdate: Array.from(productsToUpdate.values()),
-  }
-})
-
-// TODO create and update products
-```
-
-You use `transform` again to prepare the data to create and update the products in the Medusa application. For each Magento product, you map its equivalent Medusa product's data:
-
-- You set the product's general details, such as the title, description, status, handle, external ID, and thumbnail using the Magento product's data and custom attributes.
-- You associate the product with the default sales channel and shipping profile retrieved previously.
-- You map the Magento product's configurable product options to Medusa product options. In Medusa, a product's option has a label, such as "Color", and values, such as "Red". To map the option values, you use the attributes retrieved from Magento.
-- You map the Magento product's children to Medusa product variants. For the variant options, you pass an object whose keys is the option's label, such as "Color", and values is the option's value, such as "Red". For the prices, you set the variant's price based on the Magento child's price for every supported currency in the Medusa store. Also, you set the Magento child product's ID in the Medusa variant's `metadata.external_id` property.
-- You map the Magento product's media gallery entries to Medusa product images. You filter out the thumbnail image and set the URL and the Magento image's ID in the Medusa image's `metadata.external_id` property.
-
-In addition, you use the existing products retrieved in the previous step to determine whether a product should be created or updated. If there's an existing product whose `external_id` matches the ID of the magento product, you set the existing product's ID in the `id` property of the product to be updated. You also do the same for its variants.
-
-Finally, you return the products to create and update.
-
-The last steps of the workflow is to create and update the products. Replace the `TODO` in the workflow function with the following:
-
-```ts title="src/workflows/migrate-products-from-magento.ts"
-createProductsWorkflow.runAsStep({
-  input: {
-    products: productsToCreate,
-  },
-})
-
-updateProductsWorkflow.runAsStep({
-  input: {
-    products: productsToUpdate,
-  },
-})
-
-return new WorkflowResponse(pagination)
-```
-
-You use the `createProductsWorkflow` and `updateProductsWorkflow` workflows from Medusa's `@medusajs/medusa/core-flows` package to create and update the products in the Medusa application.
-
-Workflows must return an instance of `WorkflowResponse`, passing as a parameter the data to return to the workflow's executor. This workflow returns the pagination parameters, allowing you to paginate the product migration process.
-
-You can now use this workflow to migrate products from Magento to Medusa. You'll learn how to use it in the next steps.
-
-***
-
-## Step 6: Schedule Product Migration
-
-There are many ways to execute tasks asynchronously in Medusa, such as [scheduling a job](https://docs.medusajs.com/docs/learn/fundamentals/scheduled-jobs/index.html.md) or [handling emitted events](https://docs.medusajs.com/docs/learn/fundamentals/events-and-subscribers/index.html.md).
-
-In this guide, you'll learn how to schedule the product migration at a specified interval using a scheduled job. A scheduled job is an asynchronous function that the Medusa application runs at the interval you specify during the Medusa application's runtime.
-
-Refer to the [Scheduled Jobs](https://docs.medusajs.com/docs/learn/fundamentals/scheduled-jobs/index.html.md) documentation to learn more about scheduled jobs.
-
-To create a scheduled job, in your plugin, create the file `src/jobs/migrate-magento.ts` with the following content:
-
-![Diagram showcasing the migrate-magento file to create](https://res.cloudinary.com/dza7lstvk/image/upload/v1739358924/Medusa%20Resources/magento-7_rqoodo.jpg)
-
-```ts title="src/jobs/migrate-magento.ts"
-import { MedusaContainer } from "@medusajs/framework/types"
-import { migrateProductsFromMagentoWorkflow } from "../workflows"
-
-export default async function migrateMagentoJob(
-  container: MedusaContainer
-) {
-  const logger = container.resolve("logger")
-    logger.info("Migrating products from Magento...")
-    
-    let currentPage = 0
-    const pageSize = 100
-    let totalCount = 0
-  
-    do {
-      currentPage++
-  
-      const { 
-        result: pagination,
-      } = await migrateProductsFromMagentoWorkflow(container).run({
-        input: {
-          currentPage,
-          pageSize,
-        },
-      })
-  
-      totalCount = pagination.total_count
-    } while (currentPage * pageSize < totalCount)
-  
-    logger.info("Finished migrating products from Magento")
-}
-
-export const config = {
-  name: "migrate-magento-job",
-  schedule: "0 0 * * *",
-}
-```
-
-A scheduled job file must export:
-
-- An asynchronous function that executes the job's logic. The function receives the [Medusa container](https://docs.medusajs.com/docs/learn/fundamentals/medusa-container/index.html.md) as a parameter.
-- An object with the job's configuration, including the name and the schedule. The schedule is a cron job pattern as a string.
-
-In the job function, you resolve the [logger](https://docs.medusajs.com/docs/learn/debugging-and-testing/logging/index.html.md) from the container to log messages. Then, you paginate the product migration process by running the `migrateProductsFromMagentoWorkflow` workflow at each page until you've migrated all products. You use the pagination result returned by the workflow to determine whether there are more products to migrate.
-
-Based on the job's configurations, the Medusa application will run the job at midnight every day.
-
-### Test it Out
-
-To test out this scheduled job, first, change the configuration to run the job every minute:
-
-```ts title="src/jobs/migrate-magento.ts"
-export const config = {
-  // ...
-  schedule: "* * * * *",
-}
-```
-
-Then, make sure to run the `plugin:develop` command in the plugin if you haven't already:
-
-```bash
-npx medusa plugin:develop
-```
-
-This ensures that the plugin's latest changes are reflected in the Medusa application.
-
-Finally, start the Medusa application that the plugin is installed in:
-
-```bash npm2yarn
-npm run dev
-```
-
-After a minute, you'll see a message in the terminal indicating that the migration started:
-
-```plain title="Terminal"
-info: Migrating products from Magento...
-```
-
-Once the migration is done, you'll see the following message:
-
-```plain title="Terminal"
-info: Finished migrating products from Magento
-```
-
-To confirm that the products were migrated, open the Medusa Admin dashboard at `http://localhost:9000/app` and log in. Then, click on Products in the sidebar. You'll see your magento products in the list of products.
-
-![Click on products at the sidebar on the right, then view the products in the table in the middle.](https://res.cloudinary.com/dza7lstvk/image/upload/v1739359394/Medusa%20Resources/Screenshot_2025-02-12_at_1.22.44_PM_uva98i.png)
-
-***
-
-## Next Steps
-
-You've now implemented the logic to migrate products from Magento to Medusa. You can re-use the plugin across Medusa applications. You can also expand on the plugin to:
-
-- Migrate other entities, such as orders, customers, and categories. Migrating other entities follows the same pattern as migrating products, using workflows and scheduled jobs. You only need to format the data to be migrated as needed.
-- Allow triggering migrations from the Medusa Admin dashboard using [Admin Customizations](https://docs.medusajs.com/docs/learn/fundamentals/admin/index.html.md). This feature is available in the [Example Repository](https://github.com/medusajs/example-repository/tree/main/src/admin).
+You've now integrated Medusa with ShipStation. You can fulfill orders with many carriers and providers, all from a single integration and platform.
 
 If you're new to Medusa, check out the [main documentation](https://docs.medusajs.com/docs/learn/index.html.md), where you'll get a more in-depth learning of all the concepts you've used in this guide and more.
 
@@ -52634,347 +52638,347 @@ To learn more about the commerce features that Medusa provides, check out Medusa
 - [addInboundItems](https://docs.medusajs.com/references/js_sdk/admin/Claim/methods/js_sdk.admin.Claim.addInboundItems/index.html.md)
 - [addItems](https://docs.medusajs.com/references/js_sdk/admin/Claim/methods/js_sdk.admin.Claim.addItems/index.html.md)
 - [addInboundShipping](https://docs.medusajs.com/references/js_sdk/admin/Claim/methods/js_sdk.admin.Claim.addInboundShipping/index.html.md)
-- [addOutboundShipping](https://docs.medusajs.com/references/js_sdk/admin/Claim/methods/js_sdk.admin.Claim.addOutboundShipping/index.html.md)
-- [cancel](https://docs.medusajs.com/references/js_sdk/admin/Claim/methods/js_sdk.admin.Claim.cancel/index.html.md)
 - [addOutboundItems](https://docs.medusajs.com/references/js_sdk/admin/Claim/methods/js_sdk.admin.Claim.addOutboundItems/index.html.md)
+- [cancel](https://docs.medusajs.com/references/js_sdk/admin/Claim/methods/js_sdk.admin.Claim.cancel/index.html.md)
+- [addOutboundShipping](https://docs.medusajs.com/references/js_sdk/admin/Claim/methods/js_sdk.admin.Claim.addOutboundShipping/index.html.md)
 - [cancelRequest](https://docs.medusajs.com/references/js_sdk/admin/Claim/methods/js_sdk.admin.Claim.cancelRequest/index.html.md)
-- [deleteInboundShipping](https://docs.medusajs.com/references/js_sdk/admin/Claim/methods/js_sdk.admin.Claim.deleteInboundShipping/index.html.md)
 - [create](https://docs.medusajs.com/references/js_sdk/admin/Claim/methods/js_sdk.admin.Claim.create/index.html.md)
+- [deleteInboundShipping](https://docs.medusajs.com/references/js_sdk/admin/Claim/methods/js_sdk.admin.Claim.deleteInboundShipping/index.html.md)
+- [deleteOutboundShipping](https://docs.medusajs.com/references/js_sdk/admin/Claim/methods/js_sdk.admin.Claim.deleteOutboundShipping/index.html.md)
 - [removeInboundItem](https://docs.medusajs.com/references/js_sdk/admin/Claim/methods/js_sdk.admin.Claim.removeInboundItem/index.html.md)
 - [list](https://docs.medusajs.com/references/js_sdk/admin/Claim/methods/js_sdk.admin.Claim.list/index.html.md)
-- [deleteOutboundShipping](https://docs.medusajs.com/references/js_sdk/admin/Claim/methods/js_sdk.admin.Claim.deleteOutboundShipping/index.html.md)
-- [removeOutboundItem](https://docs.medusajs.com/references/js_sdk/admin/Claim/methods/js_sdk.admin.Claim.removeOutboundItem/index.html.md)
-- [request](https://docs.medusajs.com/references/js_sdk/admin/Claim/methods/js_sdk.admin.Claim.request/index.html.md)
-- [updateInboundItem](https://docs.medusajs.com/references/js_sdk/admin/Claim/methods/js_sdk.admin.Claim.updateInboundItem/index.html.md)
 - [removeItem](https://docs.medusajs.com/references/js_sdk/admin/Claim/methods/js_sdk.admin.Claim.removeItem/index.html.md)
 - [retrieve](https://docs.medusajs.com/references/js_sdk/admin/Claim/methods/js_sdk.admin.Claim.retrieve/index.html.md)
+- [request](https://docs.medusajs.com/references/js_sdk/admin/Claim/methods/js_sdk.admin.Claim.request/index.html.md)
+- [removeOutboundItem](https://docs.medusajs.com/references/js_sdk/admin/Claim/methods/js_sdk.admin.Claim.removeOutboundItem/index.html.md)
+- [updateInboundItem](https://docs.medusajs.com/references/js_sdk/admin/Claim/methods/js_sdk.admin.Claim.updateInboundItem/index.html.md)
 - [updateItem](https://docs.medusajs.com/references/js_sdk/admin/Claim/methods/js_sdk.admin.Claim.updateItem/index.html.md)
+- [updateInboundShipping](https://docs.medusajs.com/references/js_sdk/admin/Claim/methods/js_sdk.admin.Claim.updateInboundShipping/index.html.md)
 - [updateOutboundItem](https://docs.medusajs.com/references/js_sdk/admin/Claim/methods/js_sdk.admin.Claim.updateOutboundItem/index.html.md)
 - [updateOutboundShipping](https://docs.medusajs.com/references/js_sdk/admin/Claim/methods/js_sdk.admin.Claim.updateOutboundShipping/index.html.md)
-- [updateInboundShipping](https://docs.medusajs.com/references/js_sdk/admin/Claim/methods/js_sdk.admin.Claim.updateInboundShipping/index.html.md)
+- [create](https://docs.medusajs.com/references/js_sdk/admin/Campaign/methods/js_sdk.admin.Campaign.create/index.html.md)
+- [batchPromotions](https://docs.medusajs.com/references/js_sdk/admin/Campaign/methods/js_sdk.admin.Campaign.batchPromotions/index.html.md)
+- [list](https://docs.medusajs.com/references/js_sdk/admin/Campaign/methods/js_sdk.admin.Campaign.list/index.html.md)
+- [retrieve](https://docs.medusajs.com/references/js_sdk/admin/Campaign/methods/js_sdk.admin.Campaign.retrieve/index.html.md)
+- [delete](https://docs.medusajs.com/references/js_sdk/admin/Campaign/methods/js_sdk.admin.Campaign.delete/index.html.md)
+- [update](https://docs.medusajs.com/references/js_sdk/admin/Campaign/methods/js_sdk.admin.Campaign.update/index.html.md)
+- [getItem](https://docs.medusajs.com/references/js_sdk/admin/CustomStorage/methods/js_sdk.admin.CustomStorage.getItem/index.html.md)
+- [setItem](https://docs.medusajs.com/references/js_sdk/admin/CustomStorage/methods/js_sdk.admin.CustomStorage.setItem/index.html.md)
+- [removeItem](https://docs.medusajs.com/references/js_sdk/admin/CustomStorage/methods/js_sdk.admin.CustomStorage.removeItem/index.html.md)
+- [batchSalesChannels](https://docs.medusajs.com/references/js_sdk/admin/ApiKey/methods/js_sdk.admin.ApiKey.batchSalesChannels/index.html.md)
 - [create](https://docs.medusajs.com/references/js_sdk/admin/ApiKey/methods/js_sdk.admin.ApiKey.create/index.html.md)
 - [delete](https://docs.medusajs.com/references/js_sdk/admin/ApiKey/methods/js_sdk.admin.ApiKey.delete/index.html.md)
-- [batchSalesChannels](https://docs.medusajs.com/references/js_sdk/admin/ApiKey/methods/js_sdk.admin.ApiKey.batchSalesChannels/index.html.md)
 - [list](https://docs.medusajs.com/references/js_sdk/admin/ApiKey/methods/js_sdk.admin.ApiKey.list/index.html.md)
 - [retrieve](https://docs.medusajs.com/references/js_sdk/admin/ApiKey/methods/js_sdk.admin.ApiKey.retrieve/index.html.md)
 - [revoke](https://docs.medusajs.com/references/js_sdk/admin/ApiKey/methods/js_sdk.admin.ApiKey.revoke/index.html.md)
 - [update](https://docs.medusajs.com/references/js_sdk/admin/ApiKey/methods/js_sdk.admin.ApiKey.update/index.html.md)
-- [create](https://docs.medusajs.com/references/js_sdk/admin/Campaign/methods/js_sdk.admin.Campaign.create/index.html.md)
-- [batchPromotions](https://docs.medusajs.com/references/js_sdk/admin/Campaign/methods/js_sdk.admin.Campaign.batchPromotions/index.html.md)
-- [delete](https://docs.medusajs.com/references/js_sdk/admin/Campaign/methods/js_sdk.admin.Campaign.delete/index.html.md)
-- [list](https://docs.medusajs.com/references/js_sdk/admin/Campaign/methods/js_sdk.admin.Campaign.list/index.html.md)
-- [update](https://docs.medusajs.com/references/js_sdk/admin/Campaign/methods/js_sdk.admin.Campaign.update/index.html.md)
-- [retrieve](https://docs.medusajs.com/references/js_sdk/admin/Campaign/methods/js_sdk.admin.Campaign.retrieve/index.html.md)
 - [clearToken\_](https://docs.medusajs.com/references/js_sdk/admin/Client/methods/js_sdk.admin.Client.clearToken_/index.html.md)
 - [clearToken](https://docs.medusajs.com/references/js_sdk/admin/Client/methods/js_sdk.admin.Client.clearToken/index.html.md)
-- [fetchStream](https://docs.medusajs.com/references/js_sdk/admin/Client/methods/js_sdk.admin.Client.fetchStream/index.html.md)
 - [fetch](https://docs.medusajs.com/references/js_sdk/admin/Client/methods/js_sdk.admin.Client.fetch/index.html.md)
+- [fetchStream](https://docs.medusajs.com/references/js_sdk/admin/Client/methods/js_sdk.admin.Client.fetchStream/index.html.md)
 - [getApiKeyHeader\_](https://docs.medusajs.com/references/js_sdk/admin/Client/methods/js_sdk.admin.Client.getApiKeyHeader_/index.html.md)
-- [getPublishableKeyHeader\_](https://docs.medusajs.com/references/js_sdk/admin/Client/methods/js_sdk.admin.Client.getPublishableKeyHeader_/index.html.md)
 - [getJwtHeader\_](https://docs.medusajs.com/references/js_sdk/admin/Client/methods/js_sdk.admin.Client.getJwtHeader_/index.html.md)
-- [getTokenStorageInfo\_](https://docs.medusajs.com/references/js_sdk/admin/Client/methods/js_sdk.admin.Client.getTokenStorageInfo_/index.html.md)
-- [getToken\_](https://docs.medusajs.com/references/js_sdk/admin/Client/methods/js_sdk.admin.Client.getToken_/index.html.md)
-- [setToken\_](https://docs.medusajs.com/references/js_sdk/admin/Client/methods/js_sdk.admin.Client.setToken_/index.html.md)
-- [setToken](https://docs.medusajs.com/references/js_sdk/admin/Client/methods/js_sdk.admin.Client.setToken/index.html.md)
+- [getPublishableKeyHeader\_](https://docs.medusajs.com/references/js_sdk/admin/Client/methods/js_sdk.admin.Client.getPublishableKeyHeader_/index.html.md)
 - [initClient](https://docs.medusajs.com/references/js_sdk/admin/Client/methods/js_sdk.admin.Client.initClient/index.html.md)
-- [throwError\_](https://docs.medusajs.com/references/js_sdk/admin/Client/methods/js_sdk.admin.Client.throwError_/index.html.md)
+- [setToken](https://docs.medusajs.com/references/js_sdk/admin/Client/methods/js_sdk.admin.Client.setToken/index.html.md)
+- [getToken\_](https://docs.medusajs.com/references/js_sdk/admin/Client/methods/js_sdk.admin.Client.getToken_/index.html.md)
+- [getTokenStorageInfo\_](https://docs.medusajs.com/references/js_sdk/admin/Client/methods/js_sdk.admin.Client.getTokenStorageInfo_/index.html.md)
+- [setToken\_](https://docs.medusajs.com/references/js_sdk/admin/Client/methods/js_sdk.admin.Client.setToken_/index.html.md)
 - [list](https://docs.medusajs.com/references/js_sdk/admin/Currency/methods/js_sdk.admin.Currency.list/index.html.md)
 - [retrieve](https://docs.medusajs.com/references/js_sdk/admin/Currency/methods/js_sdk.admin.Currency.retrieve/index.html.md)
-- [setItem](https://docs.medusajs.com/references/js_sdk/admin/CustomStorage/methods/js_sdk.admin.CustomStorage.setItem/index.html.md)
-- [removeItem](https://docs.medusajs.com/references/js_sdk/admin/CustomStorage/methods/js_sdk.admin.CustomStorage.removeItem/index.html.md)
-- [getItem](https://docs.medusajs.com/references/js_sdk/admin/CustomStorage/methods/js_sdk.admin.CustomStorage.getItem/index.html.md)
-- [delete](https://docs.medusajs.com/references/js_sdk/admin/CustomerGroup/methods/js_sdk.admin.CustomerGroup.delete/index.html.md)
-- [create](https://docs.medusajs.com/references/js_sdk/admin/CustomerGroup/methods/js_sdk.admin.CustomerGroup.create/index.html.md)
-- [batchCustomers](https://docs.medusajs.com/references/js_sdk/admin/CustomerGroup/methods/js_sdk.admin.CustomerGroup.batchCustomers/index.html.md)
-- [list](https://docs.medusajs.com/references/js_sdk/admin/CustomerGroup/methods/js_sdk.admin.CustomerGroup.list/index.html.md)
-- [retrieve](https://docs.medusajs.com/references/js_sdk/admin/CustomerGroup/methods/js_sdk.admin.CustomerGroup.retrieve/index.html.md)
-- [update](https://docs.medusajs.com/references/js_sdk/admin/CustomerGroup/methods/js_sdk.admin.CustomerGroup.update/index.html.md)
+- [throwError\_](https://docs.medusajs.com/references/js_sdk/admin/Client/methods/js_sdk.admin.Client.throwError_/index.html.md)
 - [batchCustomerGroups](https://docs.medusajs.com/references/js_sdk/admin/Customer/methods/js_sdk.admin.Customer.batchCustomerGroups/index.html.md)
-- [create](https://docs.medusajs.com/references/js_sdk/admin/Customer/methods/js_sdk.admin.Customer.create/index.html.md)
 - [createAddress](https://docs.medusajs.com/references/js_sdk/admin/Customer/methods/js_sdk.admin.Customer.createAddress/index.html.md)
-- [list](https://docs.medusajs.com/references/js_sdk/admin/Customer/methods/js_sdk.admin.Customer.list/index.html.md)
+- [create](https://docs.medusajs.com/references/js_sdk/admin/Customer/methods/js_sdk.admin.Customer.create/index.html.md)
 - [deleteAddress](https://docs.medusajs.com/references/js_sdk/admin/Customer/methods/js_sdk.admin.Customer.deleteAddress/index.html.md)
 - [delete](https://docs.medusajs.com/references/js_sdk/admin/Customer/methods/js_sdk.admin.Customer.delete/index.html.md)
+- [list](https://docs.medusajs.com/references/js_sdk/admin/Customer/methods/js_sdk.admin.Customer.list/index.html.md)
 - [listAddresses](https://docs.medusajs.com/references/js_sdk/admin/Customer/methods/js_sdk.admin.Customer.listAddresses/index.html.md)
 - [retrieve](https://docs.medusajs.com/references/js_sdk/admin/Customer/methods/js_sdk.admin.Customer.retrieve/index.html.md)
 - [retrieveAddress](https://docs.medusajs.com/references/js_sdk/admin/Customer/methods/js_sdk.admin.Customer.retrieveAddress/index.html.md)
 - [update](https://docs.medusajs.com/references/js_sdk/admin/Customer/methods/js_sdk.admin.Customer.update/index.html.md)
 - [updateAddress](https://docs.medusajs.com/references/js_sdk/admin/Customer/methods/js_sdk.admin.Customer.updateAddress/index.html.md)
-- [listFulfillmentOptions](https://docs.medusajs.com/references/js_sdk/admin/FulfillmentProvider/methods/js_sdk.admin.FulfillmentProvider.listFulfillmentOptions/index.html.md)
-- [list](https://docs.medusajs.com/references/js_sdk/admin/FulfillmentProvider/methods/js_sdk.admin.FulfillmentProvider.list/index.html.md)
-- [addInboundShipping](https://docs.medusajs.com/references/js_sdk/admin/Exchange/methods/js_sdk.admin.Exchange.addInboundShipping/index.html.md)
-- [addOutboundItems](https://docs.medusajs.com/references/js_sdk/admin/Exchange/methods/js_sdk.admin.Exchange.addOutboundItems/index.html.md)
+- [batchCustomers](https://docs.medusajs.com/references/js_sdk/admin/CustomerGroup/methods/js_sdk.admin.CustomerGroup.batchCustomers/index.html.md)
+- [create](https://docs.medusajs.com/references/js_sdk/admin/CustomerGroup/methods/js_sdk.admin.CustomerGroup.create/index.html.md)
+- [delete](https://docs.medusajs.com/references/js_sdk/admin/CustomerGroup/methods/js_sdk.admin.CustomerGroup.delete/index.html.md)
+- [retrieve](https://docs.medusajs.com/references/js_sdk/admin/CustomerGroup/methods/js_sdk.admin.CustomerGroup.retrieve/index.html.md)
+- [list](https://docs.medusajs.com/references/js_sdk/admin/CustomerGroup/methods/js_sdk.admin.CustomerGroup.list/index.html.md)
+- [addItems](https://docs.medusajs.com/references/js_sdk/admin/DraftOrder/methods/js_sdk.admin.DraftOrder.addItems/index.html.md)
+- [update](https://docs.medusajs.com/references/js_sdk/admin/CustomerGroup/methods/js_sdk.admin.CustomerGroup.update/index.html.md)
+- [addPromotions](https://docs.medusajs.com/references/js_sdk/admin/DraftOrder/methods/js_sdk.admin.DraftOrder.addPromotions/index.html.md)
+- [beginEdit](https://docs.medusajs.com/references/js_sdk/admin/DraftOrder/methods/js_sdk.admin.DraftOrder.beginEdit/index.html.md)
+- [addShippingMethod](https://docs.medusajs.com/references/js_sdk/admin/DraftOrder/methods/js_sdk.admin.DraftOrder.addShippingMethod/index.html.md)
+- [cancelEdit](https://docs.medusajs.com/references/js_sdk/admin/DraftOrder/methods/js_sdk.admin.DraftOrder.cancelEdit/index.html.md)
+- [confirmEdit](https://docs.medusajs.com/references/js_sdk/admin/DraftOrder/methods/js_sdk.admin.DraftOrder.confirmEdit/index.html.md)
+- [convertToOrder](https://docs.medusajs.com/references/js_sdk/admin/DraftOrder/methods/js_sdk.admin.DraftOrder.convertToOrder/index.html.md)
+- [create](https://docs.medusajs.com/references/js_sdk/admin/DraftOrder/methods/js_sdk.admin.DraftOrder.create/index.html.md)
+- [list](https://docs.medusajs.com/references/js_sdk/admin/DraftOrder/methods/js_sdk.admin.DraftOrder.list/index.html.md)
+- [removeActionItem](https://docs.medusajs.com/references/js_sdk/admin/DraftOrder/methods/js_sdk.admin.DraftOrder.removeActionItem/index.html.md)
+- [removeShippingMethod](https://docs.medusajs.com/references/js_sdk/admin/DraftOrder/methods/js_sdk.admin.DraftOrder.removeShippingMethod/index.html.md)
+- [removeActionShippingMethod](https://docs.medusajs.com/references/js_sdk/admin/DraftOrder/methods/js_sdk.admin.DraftOrder.removeActionShippingMethod/index.html.md)
+- [requestEdit](https://docs.medusajs.com/references/js_sdk/admin/DraftOrder/methods/js_sdk.admin.DraftOrder.requestEdit/index.html.md)
+- [removePromotions](https://docs.medusajs.com/references/js_sdk/admin/DraftOrder/methods/js_sdk.admin.DraftOrder.removePromotions/index.html.md)
+- [update](https://docs.medusajs.com/references/js_sdk/admin/DraftOrder/methods/js_sdk.admin.DraftOrder.update/index.html.md)
+- [retrieve](https://docs.medusajs.com/references/js_sdk/admin/DraftOrder/methods/js_sdk.admin.DraftOrder.retrieve/index.html.md)
+- [updateItem](https://docs.medusajs.com/references/js_sdk/admin/DraftOrder/methods/js_sdk.admin.DraftOrder.updateItem/index.html.md)
+- [updateActionItem](https://docs.medusajs.com/references/js_sdk/admin/DraftOrder/methods/js_sdk.admin.DraftOrder.updateActionItem/index.html.md)
+- [updateActionShippingMethod](https://docs.medusajs.com/references/js_sdk/admin/DraftOrder/methods/js_sdk.admin.DraftOrder.updateActionShippingMethod/index.html.md)
+- [updateShippingMethod](https://docs.medusajs.com/references/js_sdk/admin/DraftOrder/methods/js_sdk.admin.DraftOrder.updateShippingMethod/index.html.md)
+- [cancel](https://docs.medusajs.com/references/js_sdk/admin/Fulfillment/methods/js_sdk.admin.Fulfillment.cancel/index.html.md)
+- [createShipment](https://docs.medusajs.com/references/js_sdk/admin/Fulfillment/methods/js_sdk.admin.Fulfillment.createShipment/index.html.md)
+- [create](https://docs.medusajs.com/references/js_sdk/admin/Fulfillment/methods/js_sdk.admin.Fulfillment.create/index.html.md)
 - [addInboundItems](https://docs.medusajs.com/references/js_sdk/admin/Exchange/methods/js_sdk.admin.Exchange.addInboundItems/index.html.md)
-- [addOutboundShipping](https://docs.medusajs.com/references/js_sdk/admin/Exchange/methods/js_sdk.admin.Exchange.addOutboundShipping/index.html.md)
+- [addInboundShipping](https://docs.medusajs.com/references/js_sdk/admin/Exchange/methods/js_sdk.admin.Exchange.addInboundShipping/index.html.md)
 - [cancel](https://docs.medusajs.com/references/js_sdk/admin/Exchange/methods/js_sdk.admin.Exchange.cancel/index.html.md)
+- [addOutboundItems](https://docs.medusajs.com/references/js_sdk/admin/Exchange/methods/js_sdk.admin.Exchange.addOutboundItems/index.html.md)
+- [addOutboundShipping](https://docs.medusajs.com/references/js_sdk/admin/Exchange/methods/js_sdk.admin.Exchange.addOutboundShipping/index.html.md)
 - [cancelRequest](https://docs.medusajs.com/references/js_sdk/admin/Exchange/methods/js_sdk.admin.Exchange.cancelRequest/index.html.md)
-- [deleteInboundShipping](https://docs.medusajs.com/references/js_sdk/admin/Exchange/methods/js_sdk.admin.Exchange.deleteInboundShipping/index.html.md)
 - [create](https://docs.medusajs.com/references/js_sdk/admin/Exchange/methods/js_sdk.admin.Exchange.create/index.html.md)
 - [deleteOutboundShipping](https://docs.medusajs.com/references/js_sdk/admin/Exchange/methods/js_sdk.admin.Exchange.deleteOutboundShipping/index.html.md)
+- [deleteInboundShipping](https://docs.medusajs.com/references/js_sdk/admin/Exchange/methods/js_sdk.admin.Exchange.deleteInboundShipping/index.html.md)
 - [list](https://docs.medusajs.com/references/js_sdk/admin/Exchange/methods/js_sdk.admin.Exchange.list/index.html.md)
 - [removeInboundItem](https://docs.medusajs.com/references/js_sdk/admin/Exchange/methods/js_sdk.admin.Exchange.removeInboundItem/index.html.md)
 - [removeOutboundItem](https://docs.medusajs.com/references/js_sdk/admin/Exchange/methods/js_sdk.admin.Exchange.removeOutboundItem/index.html.md)
 - [retrieve](https://docs.medusajs.com/references/js_sdk/admin/Exchange/methods/js_sdk.admin.Exchange.retrieve/index.html.md)
-- [updateInboundItem](https://docs.medusajs.com/references/js_sdk/admin/Exchange/methods/js_sdk.admin.Exchange.updateInboundItem/index.html.md)
 - [request](https://docs.medusajs.com/references/js_sdk/admin/Exchange/methods/js_sdk.admin.Exchange.request/index.html.md)
 - [updateInboundShipping](https://docs.medusajs.com/references/js_sdk/admin/Exchange/methods/js_sdk.admin.Exchange.updateInboundShipping/index.html.md)
-- [updateOutboundShipping](https://docs.medusajs.com/references/js_sdk/admin/Exchange/methods/js_sdk.admin.Exchange.updateOutboundShipping/index.html.md)
-- [addPromotions](https://docs.medusajs.com/references/js_sdk/admin/DraftOrder/methods/js_sdk.admin.DraftOrder.addPromotions/index.html.md)
+- [updateInboundItem](https://docs.medusajs.com/references/js_sdk/admin/Exchange/methods/js_sdk.admin.Exchange.updateInboundItem/index.html.md)
 - [updateOutboundItem](https://docs.medusajs.com/references/js_sdk/admin/Exchange/methods/js_sdk.admin.Exchange.updateOutboundItem/index.html.md)
-- [addItems](https://docs.medusajs.com/references/js_sdk/admin/DraftOrder/methods/js_sdk.admin.DraftOrder.addItems/index.html.md)
-- [addShippingMethod](https://docs.medusajs.com/references/js_sdk/admin/DraftOrder/methods/js_sdk.admin.DraftOrder.addShippingMethod/index.html.md)
-- [beginEdit](https://docs.medusajs.com/references/js_sdk/admin/DraftOrder/methods/js_sdk.admin.DraftOrder.beginEdit/index.html.md)
-- [confirmEdit](https://docs.medusajs.com/references/js_sdk/admin/DraftOrder/methods/js_sdk.admin.DraftOrder.confirmEdit/index.html.md)
-- [cancelEdit](https://docs.medusajs.com/references/js_sdk/admin/DraftOrder/methods/js_sdk.admin.DraftOrder.cancelEdit/index.html.md)
-- [convertToOrder](https://docs.medusajs.com/references/js_sdk/admin/DraftOrder/methods/js_sdk.admin.DraftOrder.convertToOrder/index.html.md)
-- [list](https://docs.medusajs.com/references/js_sdk/admin/DraftOrder/methods/js_sdk.admin.DraftOrder.list/index.html.md)
-- [create](https://docs.medusajs.com/references/js_sdk/admin/DraftOrder/methods/js_sdk.admin.DraftOrder.create/index.html.md)
-- [removeActionShippingMethod](https://docs.medusajs.com/references/js_sdk/admin/DraftOrder/methods/js_sdk.admin.DraftOrder.removeActionShippingMethod/index.html.md)
-- [removeShippingMethod](https://docs.medusajs.com/references/js_sdk/admin/DraftOrder/methods/js_sdk.admin.DraftOrder.removeShippingMethod/index.html.md)
-- [removePromotions](https://docs.medusajs.com/references/js_sdk/admin/DraftOrder/methods/js_sdk.admin.DraftOrder.removePromotions/index.html.md)
-- [removeActionItem](https://docs.medusajs.com/references/js_sdk/admin/DraftOrder/methods/js_sdk.admin.DraftOrder.removeActionItem/index.html.md)
-- [requestEdit](https://docs.medusajs.com/references/js_sdk/admin/DraftOrder/methods/js_sdk.admin.DraftOrder.requestEdit/index.html.md)
-- [retrieve](https://docs.medusajs.com/references/js_sdk/admin/DraftOrder/methods/js_sdk.admin.DraftOrder.retrieve/index.html.md)
-- [updateActionItem](https://docs.medusajs.com/references/js_sdk/admin/DraftOrder/methods/js_sdk.admin.DraftOrder.updateActionItem/index.html.md)
-- [update](https://docs.medusajs.com/references/js_sdk/admin/DraftOrder/methods/js_sdk.admin.DraftOrder.update/index.html.md)
-- [updateActionShippingMethod](https://docs.medusajs.com/references/js_sdk/admin/DraftOrder/methods/js_sdk.admin.DraftOrder.updateActionShippingMethod/index.html.md)
-- [updateItem](https://docs.medusajs.com/references/js_sdk/admin/DraftOrder/methods/js_sdk.admin.DraftOrder.updateItem/index.html.md)
-- [createServiceZone](https://docs.medusajs.com/references/js_sdk/admin/FulfillmentSet/methods/js_sdk.admin.FulfillmentSet.createServiceZone/index.html.md)
-- [delete](https://docs.medusajs.com/references/js_sdk/admin/FulfillmentSet/methods/js_sdk.admin.FulfillmentSet.delete/index.html.md)
-- [updateShippingMethod](https://docs.medusajs.com/references/js_sdk/admin/DraftOrder/methods/js_sdk.admin.DraftOrder.updateShippingMethod/index.html.md)
-- [deleteServiceZone](https://docs.medusajs.com/references/js_sdk/admin/FulfillmentSet/methods/js_sdk.admin.FulfillmentSet.deleteServiceZone/index.html.md)
-- [updateServiceZone](https://docs.medusajs.com/references/js_sdk/admin/FulfillmentSet/methods/js_sdk.admin.FulfillmentSet.updateServiceZone/index.html.md)
-- [cancel](https://docs.medusajs.com/references/js_sdk/admin/Fulfillment/methods/js_sdk.admin.Fulfillment.cancel/index.html.md)
-- [create](https://docs.medusajs.com/references/js_sdk/admin/Fulfillment/methods/js_sdk.admin.Fulfillment.create/index.html.md)
-- [createShipment](https://docs.medusajs.com/references/js_sdk/admin/Fulfillment/methods/js_sdk.admin.Fulfillment.createShipment/index.html.md)
-- [retrieveServiceZone](https://docs.medusajs.com/references/js_sdk/admin/FulfillmentSet/methods/js_sdk.admin.FulfillmentSet.retrieveServiceZone/index.html.md)
-- [list](https://docs.medusajs.com/references/js_sdk/admin/Notification/methods/js_sdk.admin.Notification.list/index.html.md)
+- [updateOutboundShipping](https://docs.medusajs.com/references/js_sdk/admin/Exchange/methods/js_sdk.admin.Exchange.updateOutboundShipping/index.html.md)
+- [list](https://docs.medusajs.com/references/js_sdk/admin/FulfillmentProvider/methods/js_sdk.admin.FulfillmentProvider.list/index.html.md)
+- [listFulfillmentOptions](https://docs.medusajs.com/references/js_sdk/admin/FulfillmentProvider/methods/js_sdk.admin.FulfillmentProvider.listFulfillmentOptions/index.html.md)
 - [retrieve](https://docs.medusajs.com/references/js_sdk/admin/Notification/methods/js_sdk.admin.Notification.retrieve/index.html.md)
+- [list](https://docs.medusajs.com/references/js_sdk/admin/Notification/methods/js_sdk.admin.Notification.list/index.html.md)
 - [batchInventoryItemLocationLevels](https://docs.medusajs.com/references/js_sdk/admin/InventoryItem/methods/js_sdk.admin.InventoryItem.batchInventoryItemLocationLevels/index.html.md)
-- [batchUpdateLevels](https://docs.medusajs.com/references/js_sdk/admin/InventoryItem/methods/js_sdk.admin.InventoryItem.batchUpdateLevels/index.html.md)
 - [batchInventoryItemsLocationLevels](https://docs.medusajs.com/references/js_sdk/admin/InventoryItem/methods/js_sdk.admin.InventoryItem.batchInventoryItemsLocationLevels/index.html.md)
 - [create](https://docs.medusajs.com/references/js_sdk/admin/InventoryItem/methods/js_sdk.admin.InventoryItem.create/index.html.md)
-- [delete](https://docs.medusajs.com/references/js_sdk/admin/InventoryItem/methods/js_sdk.admin.InventoryItem.delete/index.html.md)
+- [batchUpdateLevels](https://docs.medusajs.com/references/js_sdk/admin/InventoryItem/methods/js_sdk.admin.InventoryItem.batchUpdateLevels/index.html.md)
 - [deleteLevel](https://docs.medusajs.com/references/js_sdk/admin/InventoryItem/methods/js_sdk.admin.InventoryItem.deleteLevel/index.html.md)
+- [delete](https://docs.medusajs.com/references/js_sdk/admin/InventoryItem/methods/js_sdk.admin.InventoryItem.delete/index.html.md)
 - [list](https://docs.medusajs.com/references/js_sdk/admin/InventoryItem/methods/js_sdk.admin.InventoryItem.list/index.html.md)
 - [update](https://docs.medusajs.com/references/js_sdk/admin/InventoryItem/methods/js_sdk.admin.InventoryItem.update/index.html.md)
-- [retrieve](https://docs.medusajs.com/references/js_sdk/admin/InventoryItem/methods/js_sdk.admin.InventoryItem.retrieve/index.html.md)
 - [listLevels](https://docs.medusajs.com/references/js_sdk/admin/InventoryItem/methods/js_sdk.admin.InventoryItem.listLevels/index.html.md)
+- [retrieve](https://docs.medusajs.com/references/js_sdk/admin/InventoryItem/methods/js_sdk.admin.InventoryItem.retrieve/index.html.md)
 - [updateLevel](https://docs.medusajs.com/references/js_sdk/admin/InventoryItem/methods/js_sdk.admin.InventoryItem.updateLevel/index.html.md)
-- [addItems](https://docs.medusajs.com/references/js_sdk/admin/OrderEdit/methods/js_sdk.admin.OrderEdit.addItems/index.html.md)
+- [createServiceZone](https://docs.medusajs.com/references/js_sdk/admin/FulfillmentSet/methods/js_sdk.admin.FulfillmentSet.createServiceZone/index.html.md)
+- [delete](https://docs.medusajs.com/references/js_sdk/admin/FulfillmentSet/methods/js_sdk.admin.FulfillmentSet.delete/index.html.md)
+- [deleteServiceZone](https://docs.medusajs.com/references/js_sdk/admin/FulfillmentSet/methods/js_sdk.admin.FulfillmentSet.deleteServiceZone/index.html.md)
+- [retrieveServiceZone](https://docs.medusajs.com/references/js_sdk/admin/FulfillmentSet/methods/js_sdk.admin.FulfillmentSet.retrieveServiceZone/index.html.md)
+- [updateServiceZone](https://docs.medusajs.com/references/js_sdk/admin/FulfillmentSet/methods/js_sdk.admin.FulfillmentSet.updateServiceZone/index.html.md)
+- [accept](https://docs.medusajs.com/references/js_sdk/admin/Invite/methods/js_sdk.admin.Invite.accept/index.html.md)
+- [create](https://docs.medusajs.com/references/js_sdk/admin/Invite/methods/js_sdk.admin.Invite.create/index.html.md)
+- [list](https://docs.medusajs.com/references/js_sdk/admin/Invite/methods/js_sdk.admin.Invite.list/index.html.md)
+- [delete](https://docs.medusajs.com/references/js_sdk/admin/Invite/methods/js_sdk.admin.Invite.delete/index.html.md)
+- [resend](https://docs.medusajs.com/references/js_sdk/admin/Invite/methods/js_sdk.admin.Invite.resend/index.html.md)
+- [retrieve](https://docs.medusajs.com/references/js_sdk/admin/Invite/methods/js_sdk.admin.Invite.retrieve/index.html.md)
 - [cancelRequest](https://docs.medusajs.com/references/js_sdk/admin/OrderEdit/methods/js_sdk.admin.OrderEdit.cancelRequest/index.html.md)
-- [removeAddedItem](https://docs.medusajs.com/references/js_sdk/admin/OrderEdit/methods/js_sdk.admin.OrderEdit.removeAddedItem/index.html.md)
-- [initiateRequest](https://docs.medusajs.com/references/js_sdk/admin/OrderEdit/methods/js_sdk.admin.OrderEdit.initiateRequest/index.html.md)
 - [confirm](https://docs.medusajs.com/references/js_sdk/admin/OrderEdit/methods/js_sdk.admin.OrderEdit.confirm/index.html.md)
+- [addItems](https://docs.medusajs.com/references/js_sdk/admin/OrderEdit/methods/js_sdk.admin.OrderEdit.addItems/index.html.md)
+- [initiateRequest](https://docs.medusajs.com/references/js_sdk/admin/OrderEdit/methods/js_sdk.admin.OrderEdit.initiateRequest/index.html.md)
+- [removeAddedItem](https://docs.medusajs.com/references/js_sdk/admin/OrderEdit/methods/js_sdk.admin.OrderEdit.removeAddedItem/index.html.md)
 - [request](https://docs.medusajs.com/references/js_sdk/admin/OrderEdit/methods/js_sdk.admin.OrderEdit.request/index.html.md)
-- [updateOriginalItem](https://docs.medusajs.com/references/js_sdk/admin/OrderEdit/methods/js_sdk.admin.OrderEdit.updateOriginalItem/index.html.md)
 - [updateAddedItem](https://docs.medusajs.com/references/js_sdk/admin/OrderEdit/methods/js_sdk.admin.OrderEdit.updateAddedItem/index.html.md)
+- [updateOriginalItem](https://docs.medusajs.com/references/js_sdk/admin/OrderEdit/methods/js_sdk.admin.OrderEdit.updateOriginalItem/index.html.md)
+- [create](https://docs.medusajs.com/references/js_sdk/admin/PaymentCollection/methods/js_sdk.admin.PaymentCollection.create/index.html.md)
+- [delete](https://docs.medusajs.com/references/js_sdk/admin/PaymentCollection/methods/js_sdk.admin.PaymentCollection.delete/index.html.md)
+- [markAsPaid](https://docs.medusajs.com/references/js_sdk/admin/PaymentCollection/methods/js_sdk.admin.PaymentCollection.markAsPaid/index.html.md)
+- [list](https://docs.medusajs.com/references/js_sdk/admin/Plugin/methods/js_sdk.admin.Plugin.list/index.html.md)
 - [cancel](https://docs.medusajs.com/references/js_sdk/admin/Order/methods/js_sdk.admin.Order.cancel/index.html.md)
 - [cancelFulfillment](https://docs.medusajs.com/references/js_sdk/admin/Order/methods/js_sdk.admin.Order.cancelFulfillment/index.html.md)
 - [cancelTransfer](https://docs.medusajs.com/references/js_sdk/admin/Order/methods/js_sdk.admin.Order.cancelTransfer/index.html.md)
 - [createFulfillment](https://docs.medusajs.com/references/js_sdk/admin/Order/methods/js_sdk.admin.Order.createFulfillment/index.html.md)
-- [createCreditLine](https://docs.medusajs.com/references/js_sdk/admin/Order/methods/js_sdk.admin.Order.createCreditLine/index.html.md)
 - [createShipment](https://docs.medusajs.com/references/js_sdk/admin/Order/methods/js_sdk.admin.Order.createShipment/index.html.md)
-- [listChanges](https://docs.medusajs.com/references/js_sdk/admin/Order/methods/js_sdk.admin.Order.listChanges/index.html.md)
 - [list](https://docs.medusajs.com/references/js_sdk/admin/Order/methods/js_sdk.admin.Order.list/index.html.md)
-- [listLineItems](https://docs.medusajs.com/references/js_sdk/admin/Order/methods/js_sdk.admin.Order.listLineItems/index.html.md)
+- [createCreditLine](https://docs.medusajs.com/references/js_sdk/admin/Order/methods/js_sdk.admin.Order.createCreditLine/index.html.md)
+- [listChanges](https://docs.medusajs.com/references/js_sdk/admin/Order/methods/js_sdk.admin.Order.listChanges/index.html.md)
 - [markAsDelivered](https://docs.medusajs.com/references/js_sdk/admin/Order/methods/js_sdk.admin.Order.markAsDelivered/index.html.md)
+- [listLineItems](https://docs.medusajs.com/references/js_sdk/admin/Order/methods/js_sdk.admin.Order.listLineItems/index.html.md)
 - [requestTransfer](https://docs.medusajs.com/references/js_sdk/admin/Order/methods/js_sdk.admin.Order.requestTransfer/index.html.md)
 - [retrieve](https://docs.medusajs.com/references/js_sdk/admin/Order/methods/js_sdk.admin.Order.retrieve/index.html.md)
-- [retrievePreview](https://docs.medusajs.com/references/js_sdk/admin/Order/methods/js_sdk.admin.Order.retrievePreview/index.html.md)
 - [update](https://docs.medusajs.com/references/js_sdk/admin/Order/methods/js_sdk.admin.Order.update/index.html.md)
-- [accept](https://docs.medusajs.com/references/js_sdk/admin/Invite/methods/js_sdk.admin.Invite.accept/index.html.md)
-- [delete](https://docs.medusajs.com/references/js_sdk/admin/Invite/methods/js_sdk.admin.Invite.delete/index.html.md)
-- [create](https://docs.medusajs.com/references/js_sdk/admin/Invite/methods/js_sdk.admin.Invite.create/index.html.md)
-- [list](https://docs.medusajs.com/references/js_sdk/admin/Invite/methods/js_sdk.admin.Invite.list/index.html.md)
-- [resend](https://docs.medusajs.com/references/js_sdk/admin/Invite/methods/js_sdk.admin.Invite.resend/index.html.md)
-- [retrieve](https://docs.medusajs.com/references/js_sdk/admin/Invite/methods/js_sdk.admin.Invite.retrieve/index.html.md)
+- [retrievePreview](https://docs.medusajs.com/references/js_sdk/admin/Order/methods/js_sdk.admin.Order.retrievePreview/index.html.md)
+- [batchPrices](https://docs.medusajs.com/references/js_sdk/admin/PriceList/methods/js_sdk.admin.PriceList.batchPrices/index.html.md)
+- [create](https://docs.medusajs.com/references/js_sdk/admin/PriceList/methods/js_sdk.admin.PriceList.create/index.html.md)
+- [list](https://docs.medusajs.com/references/js_sdk/admin/PriceList/methods/js_sdk.admin.PriceList.list/index.html.md)
+- [linkProducts](https://docs.medusajs.com/references/js_sdk/admin/PriceList/methods/js_sdk.admin.PriceList.linkProducts/index.html.md)
+- [delete](https://docs.medusajs.com/references/js_sdk/admin/PriceList/methods/js_sdk.admin.PriceList.delete/index.html.md)
+- [retrieve](https://docs.medusajs.com/references/js_sdk/admin/PriceList/methods/js_sdk.admin.PriceList.retrieve/index.html.md)
+- [create](https://docs.medusajs.com/references/js_sdk/admin/ProductCategory/methods/js_sdk.admin.ProductCategory.create/index.html.md)
+- [update](https://docs.medusajs.com/references/js_sdk/admin/PriceList/methods/js_sdk.admin.PriceList.update/index.html.md)
+- [list](https://docs.medusajs.com/references/js_sdk/admin/ProductCategory/methods/js_sdk.admin.ProductCategory.list/index.html.md)
+- [delete](https://docs.medusajs.com/references/js_sdk/admin/ProductCategory/methods/js_sdk.admin.ProductCategory.delete/index.html.md)
+- [retrieve](https://docs.medusajs.com/references/js_sdk/admin/ProductCategory/methods/js_sdk.admin.ProductCategory.retrieve/index.html.md)
+- [update](https://docs.medusajs.com/references/js_sdk/admin/ProductCategory/methods/js_sdk.admin.ProductCategory.update/index.html.md)
+- [updateProducts](https://docs.medusajs.com/references/js_sdk/admin/ProductCategory/methods/js_sdk.admin.ProductCategory.updateProducts/index.html.md)
+- [create](https://docs.medusajs.com/references/js_sdk/admin/PricePreference/methods/js_sdk.admin.PricePreference.create/index.html.md)
+- [retrieve](https://docs.medusajs.com/references/js_sdk/admin/PricePreference/methods/js_sdk.admin.PricePreference.retrieve/index.html.md)
+- [update](https://docs.medusajs.com/references/js_sdk/admin/PricePreference/methods/js_sdk.admin.PricePreference.update/index.html.md)
+- [list](https://docs.medusajs.com/references/js_sdk/admin/PricePreference/methods/js_sdk.admin.PricePreference.list/index.html.md)
+- [delete](https://docs.medusajs.com/references/js_sdk/admin/ProductCollection/methods/js_sdk.admin.ProductCollection.delete/index.html.md)
+- [create](https://docs.medusajs.com/references/js_sdk/admin/ProductCollection/methods/js_sdk.admin.ProductCollection.create/index.html.md)
+- [list](https://docs.medusajs.com/references/js_sdk/admin/ProductCollection/methods/js_sdk.admin.ProductCollection.list/index.html.md)
+- [retrieve](https://docs.medusajs.com/references/js_sdk/admin/ProductCollection/methods/js_sdk.admin.ProductCollection.retrieve/index.html.md)
+- [update](https://docs.medusajs.com/references/js_sdk/admin/ProductCollection/methods/js_sdk.admin.ProductCollection.update/index.html.md)
+- [updateProducts](https://docs.medusajs.com/references/js_sdk/admin/ProductCollection/methods/js_sdk.admin.ProductCollection.updateProducts/index.html.md)
+- [batch](https://docs.medusajs.com/references/js_sdk/admin/Product/methods/js_sdk.admin.Product.batch/index.html.md)
+- [batchVariantInventoryItems](https://docs.medusajs.com/references/js_sdk/admin/Product/methods/js_sdk.admin.Product.batchVariantInventoryItems/index.html.md)
+- [delete](https://docs.medusajs.com/references/js_sdk/admin/PricePreference/methods/js_sdk.admin.PricePreference.delete/index.html.md)
+- [create](https://docs.medusajs.com/references/js_sdk/admin/Product/methods/js_sdk.admin.Product.create/index.html.md)
+- [confirmImport](https://docs.medusajs.com/references/js_sdk/admin/Product/methods/js_sdk.admin.Product.confirmImport/index.html.md)
+- [batchVariants](https://docs.medusajs.com/references/js_sdk/admin/Product/methods/js_sdk.admin.Product.batchVariants/index.html.md)
+- [createVariant](https://docs.medusajs.com/references/js_sdk/admin/Product/methods/js_sdk.admin.Product.createVariant/index.html.md)
+- [deleteOption](https://docs.medusajs.com/references/js_sdk/admin/Product/methods/js_sdk.admin.Product.deleteOption/index.html.md)
+- [delete](https://docs.medusajs.com/references/js_sdk/admin/Product/methods/js_sdk.admin.Product.delete/index.html.md)
+- [createOption](https://docs.medusajs.com/references/js_sdk/admin/Product/methods/js_sdk.admin.Product.createOption/index.html.md)
+- [deleteVariant](https://docs.medusajs.com/references/js_sdk/admin/Product/methods/js_sdk.admin.Product.deleteVariant/index.html.md)
+- [import](https://docs.medusajs.com/references/js_sdk/admin/Product/methods/js_sdk.admin.Product.import/index.html.md)
+- [listOptions](https://docs.medusajs.com/references/js_sdk/admin/Product/methods/js_sdk.admin.Product.listOptions/index.html.md)
+- [list](https://docs.medusajs.com/references/js_sdk/admin/Product/methods/js_sdk.admin.Product.list/index.html.md)
+- [export](https://docs.medusajs.com/references/js_sdk/admin/Product/methods/js_sdk.admin.Product.export/index.html.md)
+- [listVariants](https://docs.medusajs.com/references/js_sdk/admin/Product/methods/js_sdk.admin.Product.listVariants/index.html.md)
+- [retrieveOption](https://docs.medusajs.com/references/js_sdk/admin/Product/methods/js_sdk.admin.Product.retrieveOption/index.html.md)
+- [retrieve](https://docs.medusajs.com/references/js_sdk/admin/Product/methods/js_sdk.admin.Product.retrieve/index.html.md)
+- [retrieveVariant](https://docs.medusajs.com/references/js_sdk/admin/Product/methods/js_sdk.admin.Product.retrieveVariant/index.html.md)
+- [updateOption](https://docs.medusajs.com/references/js_sdk/admin/Product/methods/js_sdk.admin.Product.updateOption/index.html.md)
+- [update](https://docs.medusajs.com/references/js_sdk/admin/Product/methods/js_sdk.admin.Product.update/index.html.md)
+- [updateVariant](https://docs.medusajs.com/references/js_sdk/admin/Product/methods/js_sdk.admin.Product.updateVariant/index.html.md)
 - [capture](https://docs.medusajs.com/references/js_sdk/admin/Payment/methods/js_sdk.admin.Payment.capture/index.html.md)
 - [list](https://docs.medusajs.com/references/js_sdk/admin/Payment/methods/js_sdk.admin.Payment.list/index.html.md)
 - [listPaymentProviders](https://docs.medusajs.com/references/js_sdk/admin/Payment/methods/js_sdk.admin.Payment.listPaymentProviders/index.html.md)
-- [refund](https://docs.medusajs.com/references/js_sdk/admin/Payment/methods/js_sdk.admin.Payment.refund/index.html.md)
 - [retrieve](https://docs.medusajs.com/references/js_sdk/admin/Payment/methods/js_sdk.admin.Payment.retrieve/index.html.md)
-- [delete](https://docs.medusajs.com/references/js_sdk/admin/PaymentCollection/methods/js_sdk.admin.PaymentCollection.delete/index.html.md)
-- [markAsPaid](https://docs.medusajs.com/references/js_sdk/admin/PaymentCollection/methods/js_sdk.admin.PaymentCollection.markAsPaid/index.html.md)
-- [create](https://docs.medusajs.com/references/js_sdk/admin/PaymentCollection/methods/js_sdk.admin.PaymentCollection.create/index.html.md)
-- [list](https://docs.medusajs.com/references/js_sdk/admin/Plugin/methods/js_sdk.admin.Plugin.list/index.html.md)
-- [batchPrices](https://docs.medusajs.com/references/js_sdk/admin/PriceList/methods/js_sdk.admin.PriceList.batchPrices/index.html.md)
-- [create](https://docs.medusajs.com/references/js_sdk/admin/PriceList/methods/js_sdk.admin.PriceList.create/index.html.md)
-- [delete](https://docs.medusajs.com/references/js_sdk/admin/PriceList/methods/js_sdk.admin.PriceList.delete/index.html.md)
-- [linkProducts](https://docs.medusajs.com/references/js_sdk/admin/PriceList/methods/js_sdk.admin.PriceList.linkProducts/index.html.md)
-- [list](https://docs.medusajs.com/references/js_sdk/admin/PriceList/methods/js_sdk.admin.PriceList.list/index.html.md)
-- [update](https://docs.medusajs.com/references/js_sdk/admin/PriceList/methods/js_sdk.admin.PriceList.update/index.html.md)
-- [retrieve](https://docs.medusajs.com/references/js_sdk/admin/PriceList/methods/js_sdk.admin.PriceList.retrieve/index.html.md)
-- [list](https://docs.medusajs.com/references/js_sdk/admin/PricePreference/methods/js_sdk.admin.PricePreference.list/index.html.md)
-- [delete](https://docs.medusajs.com/references/js_sdk/admin/PricePreference/methods/js_sdk.admin.PricePreference.delete/index.html.md)
-- [create](https://docs.medusajs.com/references/js_sdk/admin/PricePreference/methods/js_sdk.admin.PricePreference.create/index.html.md)
-- [retrieve](https://docs.medusajs.com/references/js_sdk/admin/PricePreference/methods/js_sdk.admin.PricePreference.retrieve/index.html.md)
-- [create](https://docs.medusajs.com/references/js_sdk/admin/ProductCategory/methods/js_sdk.admin.ProductCategory.create/index.html.md)
-- [update](https://docs.medusajs.com/references/js_sdk/admin/PricePreference/methods/js_sdk.admin.PricePreference.update/index.html.md)
-- [delete](https://docs.medusajs.com/references/js_sdk/admin/ProductCategory/methods/js_sdk.admin.ProductCategory.delete/index.html.md)
-- [list](https://docs.medusajs.com/references/js_sdk/admin/ProductCategory/methods/js_sdk.admin.ProductCategory.list/index.html.md)
-- [retrieve](https://docs.medusajs.com/references/js_sdk/admin/ProductCategory/methods/js_sdk.admin.ProductCategory.retrieve/index.html.md)
-- [updateProducts](https://docs.medusajs.com/references/js_sdk/admin/ProductCategory/methods/js_sdk.admin.ProductCategory.updateProducts/index.html.md)
-- [update](https://docs.medusajs.com/references/js_sdk/admin/ProductCategory/methods/js_sdk.admin.ProductCategory.update/index.html.md)
-- [batch](https://docs.medusajs.com/references/js_sdk/admin/Product/methods/js_sdk.admin.Product.batch/index.html.md)
-- [batchVariantInventoryItems](https://docs.medusajs.com/references/js_sdk/admin/Product/methods/js_sdk.admin.Product.batchVariantInventoryItems/index.html.md)
-- [confirmImport](https://docs.medusajs.com/references/js_sdk/admin/Product/methods/js_sdk.admin.Product.confirmImport/index.html.md)
-- [batchVariants](https://docs.medusajs.com/references/js_sdk/admin/Product/methods/js_sdk.admin.Product.batchVariants/index.html.md)
-- [create](https://docs.medusajs.com/references/js_sdk/admin/Product/methods/js_sdk.admin.Product.create/index.html.md)
-- [createOption](https://docs.medusajs.com/references/js_sdk/admin/Product/methods/js_sdk.admin.Product.createOption/index.html.md)
-- [createVariant](https://docs.medusajs.com/references/js_sdk/admin/Product/methods/js_sdk.admin.Product.createVariant/index.html.md)
-- [deleteVariant](https://docs.medusajs.com/references/js_sdk/admin/Product/methods/js_sdk.admin.Product.deleteVariant/index.html.md)
-- [deleteOption](https://docs.medusajs.com/references/js_sdk/admin/Product/methods/js_sdk.admin.Product.deleteOption/index.html.md)
-- [delete](https://docs.medusajs.com/references/js_sdk/admin/Product/methods/js_sdk.admin.Product.delete/index.html.md)
-- [export](https://docs.medusajs.com/references/js_sdk/admin/Product/methods/js_sdk.admin.Product.export/index.html.md)
-- [import](https://docs.medusajs.com/references/js_sdk/admin/Product/methods/js_sdk.admin.Product.import/index.html.md)
-- [list](https://docs.medusajs.com/references/js_sdk/admin/Product/methods/js_sdk.admin.Product.list/index.html.md)
-- [listOptions](https://docs.medusajs.com/references/js_sdk/admin/Product/methods/js_sdk.admin.Product.listOptions/index.html.md)
-- [listVariants](https://docs.medusajs.com/references/js_sdk/admin/Product/methods/js_sdk.admin.Product.listVariants/index.html.md)
-- [retrieve](https://docs.medusajs.com/references/js_sdk/admin/Product/methods/js_sdk.admin.Product.retrieve/index.html.md)
-- [retrieveVariant](https://docs.medusajs.com/references/js_sdk/admin/Product/methods/js_sdk.admin.Product.retrieveVariant/index.html.md)
-- [update](https://docs.medusajs.com/references/js_sdk/admin/Product/methods/js_sdk.admin.Product.update/index.html.md)
-- [updateOption](https://docs.medusajs.com/references/js_sdk/admin/Product/methods/js_sdk.admin.Product.updateOption/index.html.md)
-- [retrieveOption](https://docs.medusajs.com/references/js_sdk/admin/Product/methods/js_sdk.admin.Product.retrieveOption/index.html.md)
-- [updateVariant](https://docs.medusajs.com/references/js_sdk/admin/Product/methods/js_sdk.admin.Product.updateVariant/index.html.md)
-- [delete](https://docs.medusajs.com/references/js_sdk/admin/ProductCollection/methods/js_sdk.admin.ProductCollection.delete/index.html.md)
-- [create](https://docs.medusajs.com/references/js_sdk/admin/ProductCollection/methods/js_sdk.admin.ProductCollection.create/index.html.md)
-- [retrieve](https://docs.medusajs.com/references/js_sdk/admin/ProductCollection/methods/js_sdk.admin.ProductCollection.retrieve/index.html.md)
-- [list](https://docs.medusajs.com/references/js_sdk/admin/ProductCollection/methods/js_sdk.admin.ProductCollection.list/index.html.md)
-- [update](https://docs.medusajs.com/references/js_sdk/admin/ProductCollection/methods/js_sdk.admin.ProductCollection.update/index.html.md)
-- [delete](https://docs.medusajs.com/references/js_sdk/admin/ProductTag/methods/js_sdk.admin.ProductTag.delete/index.html.md)
+- [refund](https://docs.medusajs.com/references/js_sdk/admin/Payment/methods/js_sdk.admin.Payment.refund/index.html.md)
 - [create](https://docs.medusajs.com/references/js_sdk/admin/ProductTag/methods/js_sdk.admin.ProductTag.create/index.html.md)
-- [updateProducts](https://docs.medusajs.com/references/js_sdk/admin/ProductCollection/methods/js_sdk.admin.ProductCollection.updateProducts/index.html.md)
 - [list](https://docs.medusajs.com/references/js_sdk/admin/ProductTag/methods/js_sdk.admin.ProductTag.list/index.html.md)
-- [retrieve](https://docs.medusajs.com/references/js_sdk/admin/ProductTag/methods/js_sdk.admin.ProductTag.retrieve/index.html.md)
 - [update](https://docs.medusajs.com/references/js_sdk/admin/ProductTag/methods/js_sdk.admin.ProductTag.update/index.html.md)
+- [delete](https://docs.medusajs.com/references/js_sdk/admin/ProductTag/methods/js_sdk.admin.ProductTag.delete/index.html.md)
+- [retrieve](https://docs.medusajs.com/references/js_sdk/admin/ProductTag/methods/js_sdk.admin.ProductTag.retrieve/index.html.md)
 - [list](https://docs.medusajs.com/references/js_sdk/admin/ProductVariant/methods/js_sdk.admin.ProductVariant.list/index.html.md)
+- [create](https://docs.medusajs.com/references/js_sdk/admin/Reservation/methods/js_sdk.admin.Reservation.create/index.html.md)
+- [delete](https://docs.medusajs.com/references/js_sdk/admin/Reservation/methods/js_sdk.admin.Reservation.delete/index.html.md)
+- [update](https://docs.medusajs.com/references/js_sdk/admin/Reservation/methods/js_sdk.admin.Reservation.update/index.html.md)
+- [list](https://docs.medusajs.com/references/js_sdk/admin/Reservation/methods/js_sdk.admin.Reservation.list/index.html.md)
+- [retrieve](https://docs.medusajs.com/references/js_sdk/admin/Reservation/methods/js_sdk.admin.Reservation.retrieve/index.html.md)
 - [create](https://docs.medusajs.com/references/js_sdk/admin/ProductType/methods/js_sdk.admin.ProductType.create/index.html.md)
 - [delete](https://docs.medusajs.com/references/js_sdk/admin/ProductType/methods/js_sdk.admin.ProductType.delete/index.html.md)
 - [list](https://docs.medusajs.com/references/js_sdk/admin/ProductType/methods/js_sdk.admin.ProductType.list/index.html.md)
-- [retrieve](https://docs.medusajs.com/references/js_sdk/admin/ProductType/methods/js_sdk.admin.ProductType.retrieve/index.html.md)
 - [update](https://docs.medusajs.com/references/js_sdk/admin/ProductType/methods/js_sdk.admin.ProductType.update/index.html.md)
-- [addRules](https://docs.medusajs.com/references/js_sdk/admin/Promotion/methods/js_sdk.admin.Promotion.addRules/index.html.md)
-- [create](https://docs.medusajs.com/references/js_sdk/admin/Promotion/methods/js_sdk.admin.Promotion.create/index.html.md)
-- [delete](https://docs.medusajs.com/references/js_sdk/admin/Promotion/methods/js_sdk.admin.Promotion.delete/index.html.md)
-- [listRuleAttributes](https://docs.medusajs.com/references/js_sdk/admin/Promotion/methods/js_sdk.admin.Promotion.listRuleAttributes/index.html.md)
-- [list](https://docs.medusajs.com/references/js_sdk/admin/Promotion/methods/js_sdk.admin.Promotion.list/index.html.md)
-- [listRuleValues](https://docs.medusajs.com/references/js_sdk/admin/Promotion/methods/js_sdk.admin.Promotion.listRuleValues/index.html.md)
-- [retrieve](https://docs.medusajs.com/references/js_sdk/admin/Promotion/methods/js_sdk.admin.Promotion.retrieve/index.html.md)
-- [update](https://docs.medusajs.com/references/js_sdk/admin/Promotion/methods/js_sdk.admin.Promotion.update/index.html.md)
-- [listRules](https://docs.medusajs.com/references/js_sdk/admin/Promotion/methods/js_sdk.admin.Promotion.listRules/index.html.md)
-- [removeRules](https://docs.medusajs.com/references/js_sdk/admin/Promotion/methods/js_sdk.admin.Promotion.removeRules/index.html.md)
-- [updateRules](https://docs.medusajs.com/references/js_sdk/admin/Promotion/methods/js_sdk.admin.Promotion.updateRules/index.html.md)
-- [list](https://docs.medusajs.com/references/js_sdk/admin/Reservation/methods/js_sdk.admin.Reservation.list/index.html.md)
-- [delete](https://docs.medusajs.com/references/js_sdk/admin/Reservation/methods/js_sdk.admin.Reservation.delete/index.html.md)
-- [create](https://docs.medusajs.com/references/js_sdk/admin/Reservation/methods/js_sdk.admin.Reservation.create/index.html.md)
-- [update](https://docs.medusajs.com/references/js_sdk/admin/Reservation/methods/js_sdk.admin.Reservation.update/index.html.md)
-- [retrieve](https://docs.medusajs.com/references/js_sdk/admin/Reservation/methods/js_sdk.admin.Reservation.retrieve/index.html.md)
+- [retrieve](https://docs.medusajs.com/references/js_sdk/admin/ProductType/methods/js_sdk.admin.ProductType.retrieve/index.html.md)
 - [list](https://docs.medusajs.com/references/js_sdk/admin/RefundReason/methods/js_sdk.admin.RefundReason.list/index.html.md)
-- [create](https://docs.medusajs.com/references/js_sdk/admin/Region/methods/js_sdk.admin.Region.create/index.html.md)
 - [delete](https://docs.medusajs.com/references/js_sdk/admin/Region/methods/js_sdk.admin.Region.delete/index.html.md)
-- [list](https://docs.medusajs.com/references/js_sdk/admin/Region/methods/js_sdk.admin.Region.list/index.html.md)
 - [retrieve](https://docs.medusajs.com/references/js_sdk/admin/Region/methods/js_sdk.admin.Region.retrieve/index.html.md)
 - [update](https://docs.medusajs.com/references/js_sdk/admin/Region/methods/js_sdk.admin.Region.update/index.html.md)
-- [list](https://docs.medusajs.com/references/js_sdk/admin/ReturnReason/methods/js_sdk.admin.ReturnReason.list/index.html.md)
-- [retrieve](https://docs.medusajs.com/references/js_sdk/admin/ReturnReason/methods/js_sdk.admin.ReturnReason.retrieve/index.html.md)
+- [create](https://docs.medusajs.com/references/js_sdk/admin/Region/methods/js_sdk.admin.Region.create/index.html.md)
+- [list](https://docs.medusajs.com/references/js_sdk/admin/Region/methods/js_sdk.admin.Region.list/index.html.md)
+- [addRules](https://docs.medusajs.com/references/js_sdk/admin/Promotion/methods/js_sdk.admin.Promotion.addRules/index.html.md)
+- [create](https://docs.medusajs.com/references/js_sdk/admin/Promotion/methods/js_sdk.admin.Promotion.create/index.html.md)
+- [listRuleAttributes](https://docs.medusajs.com/references/js_sdk/admin/Promotion/methods/js_sdk.admin.Promotion.listRuleAttributes/index.html.md)
+- [list](https://docs.medusajs.com/references/js_sdk/admin/Promotion/methods/js_sdk.admin.Promotion.list/index.html.md)
+- [delete](https://docs.medusajs.com/references/js_sdk/admin/Promotion/methods/js_sdk.admin.Promotion.delete/index.html.md)
+- [listRuleValues](https://docs.medusajs.com/references/js_sdk/admin/Promotion/methods/js_sdk.admin.Promotion.listRuleValues/index.html.md)
+- [listRules](https://docs.medusajs.com/references/js_sdk/admin/Promotion/methods/js_sdk.admin.Promotion.listRules/index.html.md)
+- [retrieve](https://docs.medusajs.com/references/js_sdk/admin/Promotion/methods/js_sdk.admin.Promotion.retrieve/index.html.md)
+- [removeRules](https://docs.medusajs.com/references/js_sdk/admin/Promotion/methods/js_sdk.admin.Promotion.removeRules/index.html.md)
+- [update](https://docs.medusajs.com/references/js_sdk/admin/Promotion/methods/js_sdk.admin.Promotion.update/index.html.md)
+- [updateRules](https://docs.medusajs.com/references/js_sdk/admin/Promotion/methods/js_sdk.admin.Promotion.updateRules/index.html.md)
 - [create](https://docs.medusajs.com/references/js_sdk/admin/ReturnReason/methods/js_sdk.admin.ReturnReason.create/index.html.md)
+- [retrieve](https://docs.medusajs.com/references/js_sdk/admin/ReturnReason/methods/js_sdk.admin.ReturnReason.retrieve/index.html.md)
+- [list](https://docs.medusajs.com/references/js_sdk/admin/ReturnReason/methods/js_sdk.admin.ReturnReason.list/index.html.md)
 - [delete](https://docs.medusajs.com/references/js_sdk/admin/ReturnReason/methods/js_sdk.admin.ReturnReason.delete/index.html.md)
-- [update](https://docs.medusajs.com/references/js_sdk/admin/ReturnReason/methods/js_sdk.admin.ReturnReason.update/index.html.md)
 - [batchProducts](https://docs.medusajs.com/references/js_sdk/admin/SalesChannel/methods/js_sdk.admin.SalesChannel.batchProducts/index.html.md)
+- [update](https://docs.medusajs.com/references/js_sdk/admin/ReturnReason/methods/js_sdk.admin.ReturnReason.update/index.html.md)
 - [create](https://docs.medusajs.com/references/js_sdk/admin/SalesChannel/methods/js_sdk.admin.SalesChannel.create/index.html.md)
+- [delete](https://docs.medusajs.com/references/js_sdk/admin/SalesChannel/methods/js_sdk.admin.SalesChannel.delete/index.html.md)
 - [list](https://docs.medusajs.com/references/js_sdk/admin/SalesChannel/methods/js_sdk.admin.SalesChannel.list/index.html.md)
 - [retrieve](https://docs.medusajs.com/references/js_sdk/admin/SalesChannel/methods/js_sdk.admin.SalesChannel.retrieve/index.html.md)
-- [update](https://docs.medusajs.com/references/js_sdk/admin/SalesChannel/methods/js_sdk.admin.SalesChannel.update/index.html.md)
-- [delete](https://docs.medusajs.com/references/js_sdk/admin/SalesChannel/methods/js_sdk.admin.SalesChannel.delete/index.html.md)
 - [updateProducts](https://docs.medusajs.com/references/js_sdk/admin/SalesChannel/methods/js_sdk.admin.SalesChannel.updateProducts/index.html.md)
+- [update](https://docs.medusajs.com/references/js_sdk/admin/SalesChannel/methods/js_sdk.admin.SalesChannel.update/index.html.md)
 - [addReturnItem](https://docs.medusajs.com/references/js_sdk/admin/Return/methods/js_sdk.admin.Return.addReturnItem/index.html.md)
-- [cancel](https://docs.medusajs.com/references/js_sdk/admin/Return/methods/js_sdk.admin.Return.cancel/index.html.md)
-- [cancelReceive](https://docs.medusajs.com/references/js_sdk/admin/Return/methods/js_sdk.admin.Return.cancelReceive/index.html.md)
 - [addReturnShipping](https://docs.medusajs.com/references/js_sdk/admin/Return/methods/js_sdk.admin.Return.addReturnShipping/index.html.md)
+- [cancelReceive](https://docs.medusajs.com/references/js_sdk/admin/Return/methods/js_sdk.admin.Return.cancelReceive/index.html.md)
+- [cancel](https://docs.medusajs.com/references/js_sdk/admin/Return/methods/js_sdk.admin.Return.cancel/index.html.md)
 - [cancelRequest](https://docs.medusajs.com/references/js_sdk/admin/Return/methods/js_sdk.admin.Return.cancelRequest/index.html.md)
 - [confirmReceive](https://docs.medusajs.com/references/js_sdk/admin/Return/methods/js_sdk.admin.Return.confirmReceive/index.html.md)
 - [confirmRequest](https://docs.medusajs.com/references/js_sdk/admin/Return/methods/js_sdk.admin.Return.confirmRequest/index.html.md)
 - [deleteReturnShipping](https://docs.medusajs.com/references/js_sdk/admin/Return/methods/js_sdk.admin.Return.deleteReturnShipping/index.html.md)
-- [dismissItems](https://docs.medusajs.com/references/js_sdk/admin/Return/methods/js_sdk.admin.Return.dismissItems/index.html.md)
 - [initiateReceive](https://docs.medusajs.com/references/js_sdk/admin/Return/methods/js_sdk.admin.Return.initiateReceive/index.html.md)
-- [initiateRequest](https://docs.medusajs.com/references/js_sdk/admin/Return/methods/js_sdk.admin.Return.initiateRequest/index.html.md)
+- [dismissItems](https://docs.medusajs.com/references/js_sdk/admin/Return/methods/js_sdk.admin.Return.dismissItems/index.html.md)
 - [list](https://docs.medusajs.com/references/js_sdk/admin/Return/methods/js_sdk.admin.Return.list/index.html.md)
-- [receiveItems](https://docs.medusajs.com/references/js_sdk/admin/Return/methods/js_sdk.admin.Return.receiveItems/index.html.md)
 - [removeDismissItem](https://docs.medusajs.com/references/js_sdk/admin/Return/methods/js_sdk.admin.Return.removeDismissItem/index.html.md)
-- [removeReceiveItem](https://docs.medusajs.com/references/js_sdk/admin/Return/methods/js_sdk.admin.Return.removeReceiveItem/index.html.md)
+- [receiveItems](https://docs.medusajs.com/references/js_sdk/admin/Return/methods/js_sdk.admin.Return.receiveItems/index.html.md)
 - [removeReturnItem](https://docs.medusajs.com/references/js_sdk/admin/Return/methods/js_sdk.admin.Return.removeReturnItem/index.html.md)
+- [removeReceiveItem](https://docs.medusajs.com/references/js_sdk/admin/Return/methods/js_sdk.admin.Return.removeReceiveItem/index.html.md)
 - [updateDismissItem](https://docs.medusajs.com/references/js_sdk/admin/Return/methods/js_sdk.admin.Return.updateDismissItem/index.html.md)
-- [retrieve](https://docs.medusajs.com/references/js_sdk/admin/Return/methods/js_sdk.admin.Return.retrieve/index.html.md)
+- [initiateRequest](https://docs.medusajs.com/references/js_sdk/admin/Return/methods/js_sdk.admin.Return.initiateRequest/index.html.md)
 - [updateRequest](https://docs.medusajs.com/references/js_sdk/admin/Return/methods/js_sdk.admin.Return.updateRequest/index.html.md)
+- [updateReceiveItem](https://docs.medusajs.com/references/js_sdk/admin/Return/methods/js_sdk.admin.Return.updateReceiveItem/index.html.md)
 - [updateReturnItem](https://docs.medusajs.com/references/js_sdk/admin/Return/methods/js_sdk.admin.Return.updateReturnItem/index.html.md)
 - [updateReturnShipping](https://docs.medusajs.com/references/js_sdk/admin/Return/methods/js_sdk.admin.Return.updateReturnShipping/index.html.md)
-- [updateReceiveItem](https://docs.medusajs.com/references/js_sdk/admin/Return/methods/js_sdk.admin.Return.updateReceiveItem/index.html.md)
-- [create](https://docs.medusajs.com/references/js_sdk/admin/ShippingOption/methods/js_sdk.admin.ShippingOption.create/index.html.md)
-- [delete](https://docs.medusajs.com/references/js_sdk/admin/ShippingOption/methods/js_sdk.admin.ShippingOption.delete/index.html.md)
-- [retrieve](https://docs.medusajs.com/references/js_sdk/admin/ShippingOption/methods/js_sdk.admin.ShippingOption.retrieve/index.html.md)
-- [list](https://docs.medusajs.com/references/js_sdk/admin/ShippingOption/methods/js_sdk.admin.ShippingOption.list/index.html.md)
-- [updateRules](https://docs.medusajs.com/references/js_sdk/admin/ShippingOption/methods/js_sdk.admin.ShippingOption.updateRules/index.html.md)
+- [retrieve](https://docs.medusajs.com/references/js_sdk/admin/Return/methods/js_sdk.admin.Return.retrieve/index.html.md)
 - [create](https://docs.medusajs.com/references/js_sdk/admin/ShippingProfile/methods/js_sdk.admin.ShippingProfile.create/index.html.md)
-- [update](https://docs.medusajs.com/references/js_sdk/admin/ShippingOption/methods/js_sdk.admin.ShippingOption.update/index.html.md)
 - [delete](https://docs.medusajs.com/references/js_sdk/admin/ShippingProfile/methods/js_sdk.admin.ShippingProfile.delete/index.html.md)
+- [retrieve](https://docs.medusajs.com/references/js_sdk/admin/ShippingProfile/methods/js_sdk.admin.ShippingProfile.retrieve/index.html.md)
+- [update](https://docs.medusajs.com/references/js_sdk/admin/ShippingProfile/methods/js_sdk.admin.ShippingProfile.update/index.html.md)
+- [create](https://docs.medusajs.com/references/js_sdk/admin/StockLocation/methods/js_sdk.admin.StockLocation.create/index.html.md)
+- [createFulfillmentSet](https://docs.medusajs.com/references/js_sdk/admin/StockLocation/methods/js_sdk.admin.StockLocation.createFulfillmentSet/index.html.md)
 - [list](https://docs.medusajs.com/references/js_sdk/admin/ShippingProfile/methods/js_sdk.admin.ShippingProfile.list/index.html.md)
+- [list](https://docs.medusajs.com/references/js_sdk/admin/StockLocation/methods/js_sdk.admin.StockLocation.list/index.html.md)
+- [delete](https://docs.medusajs.com/references/js_sdk/admin/StockLocation/methods/js_sdk.admin.StockLocation.delete/index.html.md)
+- [updateFulfillmentProviders](https://docs.medusajs.com/references/js_sdk/admin/StockLocation/methods/js_sdk.admin.StockLocation.updateFulfillmentProviders/index.html.md)
+- [update](https://docs.medusajs.com/references/js_sdk/admin/StockLocation/methods/js_sdk.admin.StockLocation.update/index.html.md)
+- [retrieve](https://docs.medusajs.com/references/js_sdk/admin/StockLocation/methods/js_sdk.admin.StockLocation.retrieve/index.html.md)
 - [create](https://docs.medusajs.com/references/js_sdk/admin/TaxRate/methods/js_sdk.admin.TaxRate.create/index.html.md)
 - [delete](https://docs.medusajs.com/references/js_sdk/admin/TaxRate/methods/js_sdk.admin.TaxRate.delete/index.html.md)
-- [retrieve](https://docs.medusajs.com/references/js_sdk/admin/ShippingProfile/methods/js_sdk.admin.ShippingProfile.retrieve/index.html.md)
 - [list](https://docs.medusajs.com/references/js_sdk/admin/TaxRate/methods/js_sdk.admin.TaxRate.list/index.html.md)
-- [update](https://docs.medusajs.com/references/js_sdk/admin/ShippingProfile/methods/js_sdk.admin.ShippingProfile.update/index.html.md)
+- [updateSalesChannels](https://docs.medusajs.com/references/js_sdk/admin/StockLocation/methods/js_sdk.admin.StockLocation.updateSalesChannels/index.html.md)
 - [update](https://docs.medusajs.com/references/js_sdk/admin/TaxRate/methods/js_sdk.admin.TaxRate.update/index.html.md)
+- [create](https://docs.medusajs.com/references/js_sdk/admin/ShippingOption/methods/js_sdk.admin.ShippingOption.create/index.html.md)
 - [retrieve](https://docs.medusajs.com/references/js_sdk/admin/TaxRate/methods/js_sdk.admin.TaxRate.retrieve/index.html.md)
-- [create](https://docs.medusajs.com/references/js_sdk/admin/TaxRegion/methods/js_sdk.admin.TaxRegion.create/index.html.md)
-- [retrieve](https://docs.medusajs.com/references/js_sdk/admin/TaxRegion/methods/js_sdk.admin.TaxRegion.retrieve/index.html.md)
-- [delete](https://docs.medusajs.com/references/js_sdk/admin/TaxRegion/methods/js_sdk.admin.TaxRegion.delete/index.html.md)
+- [list](https://docs.medusajs.com/references/js_sdk/admin/ShippingOption/methods/js_sdk.admin.ShippingOption.list/index.html.md)
+- [delete](https://docs.medusajs.com/references/js_sdk/admin/ShippingOption/methods/js_sdk.admin.ShippingOption.delete/index.html.md)
+- [retrieve](https://docs.medusajs.com/references/js_sdk/admin/ShippingOption/methods/js_sdk.admin.ShippingOption.retrieve/index.html.md)
+- [updateRules](https://docs.medusajs.com/references/js_sdk/admin/ShippingOption/methods/js_sdk.admin.ShippingOption.updateRules/index.html.md)
+- [update](https://docs.medusajs.com/references/js_sdk/admin/ShippingOption/methods/js_sdk.admin.ShippingOption.update/index.html.md)
 - [list](https://docs.medusajs.com/references/js_sdk/admin/TaxRegion/methods/js_sdk.admin.TaxRegion.list/index.html.md)
+- [create](https://docs.medusajs.com/references/js_sdk/admin/TaxRegion/methods/js_sdk.admin.TaxRegion.create/index.html.md)
+- [delete](https://docs.medusajs.com/references/js_sdk/admin/TaxRegion/methods/js_sdk.admin.TaxRegion.delete/index.html.md)
+- [retrieve](https://docs.medusajs.com/references/js_sdk/admin/TaxRegion/methods/js_sdk.admin.TaxRegion.retrieve/index.html.md)
 - [list](https://docs.medusajs.com/references/js_sdk/admin/Store/methods/js_sdk.admin.Store.list/index.html.md)
 - [update](https://docs.medusajs.com/references/js_sdk/admin/Store/methods/js_sdk.admin.Store.update/index.html.md)
 - [retrieve](https://docs.medusajs.com/references/js_sdk/admin/Store/methods/js_sdk.admin.Store.retrieve/index.html.md)
-- [create](https://docs.medusajs.com/references/js_sdk/admin/StockLocation/methods/js_sdk.admin.StockLocation.create/index.html.md)
-- [createFulfillmentSet](https://docs.medusajs.com/references/js_sdk/admin/StockLocation/methods/js_sdk.admin.StockLocation.createFulfillmentSet/index.html.md)
-- [list](https://docs.medusajs.com/references/js_sdk/admin/StockLocation/methods/js_sdk.admin.StockLocation.list/index.html.md)
-- [retrieve](https://docs.medusajs.com/references/js_sdk/admin/StockLocation/methods/js_sdk.admin.StockLocation.retrieve/index.html.md)
-- [update](https://docs.medusajs.com/references/js_sdk/admin/StockLocation/methods/js_sdk.admin.StockLocation.update/index.html.md)
-- [updateFulfillmentProviders](https://docs.medusajs.com/references/js_sdk/admin/StockLocation/methods/js_sdk.admin.StockLocation.updateFulfillmentProviders/index.html.md)
-- [delete](https://docs.medusajs.com/references/js_sdk/admin/StockLocation/methods/js_sdk.admin.StockLocation.delete/index.html.md)
-- [updateSalesChannels](https://docs.medusajs.com/references/js_sdk/admin/StockLocation/methods/js_sdk.admin.StockLocation.updateSalesChannels/index.html.md)
-- [delete](https://docs.medusajs.com/references/js_sdk/admin/User/methods/js_sdk.admin.User.delete/index.html.md)
-- [list](https://docs.medusajs.com/references/js_sdk/admin/User/methods/js_sdk.admin.User.list/index.html.md)
-- [me](https://docs.medusajs.com/references/js_sdk/admin/User/methods/js_sdk.admin.User.me/index.html.md)
-- [update](https://docs.medusajs.com/references/js_sdk/admin/User/methods/js_sdk.admin.User.update/index.html.md)
-- [retrieve](https://docs.medusajs.com/references/js_sdk/admin/User/methods/js_sdk.admin.User.retrieve/index.html.md)
-- [list](https://docs.medusajs.com/references/js_sdk/admin/WorkflowExecution/methods/js_sdk.admin.WorkflowExecution.list/index.html.md)
-- [retrieve](https://docs.medusajs.com/references/js_sdk/admin/WorkflowExecution/methods/js_sdk.admin.WorkflowExecution.retrieve/index.html.md)
-- [retrieve](https://docs.medusajs.com/references/js_sdk/admin/Upload/methods/js_sdk.admin.Upload.retrieve/index.html.md)
 - [create](https://docs.medusajs.com/references/js_sdk/admin/Upload/methods/js_sdk.admin.Upload.create/index.html.md)
 - [delete](https://docs.medusajs.com/references/js_sdk/admin/Upload/methods/js_sdk.admin.Upload.delete/index.html.md)
+- [list](https://docs.medusajs.com/references/js_sdk/admin/User/methods/js_sdk.admin.User.list/index.html.md)
+- [me](https://docs.medusajs.com/references/js_sdk/admin/User/methods/js_sdk.admin.User.me/index.html.md)
+- [retrieve](https://docs.medusajs.com/references/js_sdk/admin/Upload/methods/js_sdk.admin.Upload.retrieve/index.html.md)
+- [retrieve](https://docs.medusajs.com/references/js_sdk/admin/User/methods/js_sdk.admin.User.retrieve/index.html.md)
+- [update](https://docs.medusajs.com/references/js_sdk/admin/User/methods/js_sdk.admin.User.update/index.html.md)
+- [delete](https://docs.medusajs.com/references/js_sdk/admin/User/methods/js_sdk.admin.User.delete/index.html.md)
+- [retrieve](https://docs.medusajs.com/references/js_sdk/admin/WorkflowExecution/methods/js_sdk.admin.WorkflowExecution.retrieve/index.html.md)
+- [list](https://docs.medusajs.com/references/js_sdk/admin/WorkflowExecution/methods/js_sdk.admin.WorkflowExecution.list/index.html.md)
 
 
 ## JS SDK Auth
 
 - [callback](https://docs.medusajs.com/references/js-sdk/auth/callback/index.html.md)
-- [register](https://docs.medusajs.com/references/js-sdk/auth/register/index.html.md)
-- [resetPassword](https://docs.medusajs.com/references/js-sdk/auth/resetPassword/index.html.md)
 - [login](https://docs.medusajs.com/references/js-sdk/auth/login/index.html.md)
-- [updateProvider](https://docs.medusajs.com/references/js-sdk/auth/updateProvider/index.html.md)
-- [refresh](https://docs.medusajs.com/references/js-sdk/auth/refresh/index.html.md)
 - [logout](https://docs.medusajs.com/references/js-sdk/auth/logout/index.html.md)
+- [refresh](https://docs.medusajs.com/references/js-sdk/auth/refresh/index.html.md)
+- [resetPassword](https://docs.medusajs.com/references/js-sdk/auth/resetPassword/index.html.md)
+- [register](https://docs.medusajs.com/references/js-sdk/auth/register/index.html.md)
+- [updateProvider](https://docs.medusajs.com/references/js-sdk/auth/updateProvider/index.html.md)
 
 
 ## JS SDK Store
 
 - [cart](https://docs.medusajs.com/references/js-sdk/store/cart/index.html.md)
+- [category](https://docs.medusajs.com/references/js-sdk/store/category/index.html.md)
 - [customer](https://docs.medusajs.com/references/js-sdk/store/customer/index.html.md)
 - [fulfillment](https://docs.medusajs.com/references/js-sdk/store/fulfillment/index.html.md)
-- [payment](https://docs.medusajs.com/references/js-sdk/store/payment/index.html.md)
-- [order](https://docs.medusajs.com/references/js-sdk/store/order/index.html.md)
 - [collection](https://docs.medusajs.com/references/js-sdk/store/collection/index.html.md)
-- [product](https://docs.medusajs.com/references/js-sdk/store/product/index.html.md)
+- [order](https://docs.medusajs.com/references/js-sdk/store/order/index.html.md)
+- [payment](https://docs.medusajs.com/references/js-sdk/store/payment/index.html.md)
 - [region](https://docs.medusajs.com/references/js-sdk/store/region/index.html.md)
-- [category](https://docs.medusajs.com/references/js-sdk/store/category/index.html.md)
+- [product](https://docs.medusajs.com/references/js-sdk/store/product/index.html.md)
 
 
 # Configure Medusa Backend
@@ -53911,6 +53915,579 @@ export default ProductWidget
 This widget also uses a [Header](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/admin-components/components/header/index.html.md) custom component.
 
 
+# Forms - Admin Components
+
+The Medusa Admin has two types of forms:
+
+1. Create forms, created using the [FocusModal UI component](https://docs.medusajs.com/ui/components/focus-modal/index.html.md).
+2. Edit or update forms, created using the [Drawer UI component](https://docs.medusajs.com/ui/components/drawer/index.html.md).
+
+This guide explains how to create these two form types following the Medusa Admin's conventions.
+
+## Form Tooling
+
+The Medusa Admin uses the following tools to build the forms:
+
+1. [react-hook-form](https://react-hook-form.com/) to easily build forms and manage their states.
+2. [Zod](https://zod.dev/) to validate the form's fields.
+
+Both of these libraries are available in your project, so you don't have to install them to use them.
+
+***
+
+## Create Form
+
+In this section, you'll build a form component to create an item of a resource.
+
+### Full Component
+
+```tsx title="src/admin/components/create-form.tsx"
+import { 
+  FocusModal,
+  Heading,
+  Label,
+  Input,
+  Button,
+} from "@medusajs/ui"
+import { 
+  useForm, 
+  FormProvider,
+  Controller,
+} from "react-hook-form"
+import * as zod from "zod"
+
+const schema = zod.object({
+  name: zod.string(),
+})
+
+export const CreateForm = () => {
+  const form = useForm<zod.infer<typeof schema>>({
+    defaultValues: {
+      name: "",
+    },
+  })
+
+  const handleSubmit = form.handleSubmit(({ name }) => {
+    // TODO submit to backend
+    console.log(name)
+  })
+
+  return (
+    <FocusModal>
+      <FocusModal.Trigger asChild>
+        <Button>Create</Button>
+      </FocusModal.Trigger>
+      <FocusModal.Content>
+        <FormProvider {...form}>
+          <form
+            onSubmit={handleSubmit}
+            className="flex h-full flex-col overflow-hidden"
+          >
+            <FocusModal.Header>
+              <div className="flex items-center justify-end gap-x-2">
+                  <FocusModal.Close asChild>
+                    <Button size="small" variant="secondary">
+                      Cancel
+                    </Button>
+                  </FocusModal.Close>
+                  <Button type="submit" size="small">
+                    Save
+                  </Button>
+                </div>
+            </FocusModal.Header>
+            <FocusModal.Body>
+                <div className="flex flex-1 flex-col items-center overflow-y-auto">
+                  <div className="mx-auto flex w-full max-w-[720px] flex-col gap-y-8 px-2 py-16">
+                    <div>
+                      <Heading className="capitalize">
+                        Create Item
+                      </Heading>
+                    </div>
+                    <div className="grid grid-cols-2 gap-4">
+                      <Controller
+                        control={form.control}
+                        name="name"
+                        render={({ field }) => {
+                          return (
+                            <div className="flex flex-col space-y-2">
+                              <div className="flex items-center gap-x-1">
+                                <Label size="small" weight="plus">
+                                  Name
+                                </Label>
+                              </div>
+                              <Input {...field} />
+                            </div>
+                          )
+                        }}
+                      />
+                    </div>
+                  </div>
+                </div>
+            </FocusModal.Body>
+          </form>
+        </FormProvider>
+      </FocusModal.Content>
+    </FocusModal>
+  )
+}
+```
+
+Unlike other components in this documentation, this form component isn't reusable. You have to create one for every resource that has a create form in the admin.
+
+Start by creating the file `src/admin/components/create-form.tsx` that you'll create the form in.
+
+### Create Validation Schema
+
+In `src/admin/components/create-form.tsx`, create a validation schema with Zod for the form's fields:
+
+```tsx title="src/admin/components/create-form.tsx"
+import * as zod from "zod"
+
+const schema = zod.object({
+  name: zod.string(),
+})
+```
+
+The form in this guide is simple, it only has a required `name` field, which is a string.
+
+### Initialize Form
+
+Next, you'll initialize the form using `react-hook-form`.
+
+Add to `src/admin/components/create-form.tsx` the following:
+
+```tsx title="src/admin/components/create-form.tsx"
+// other imports...
+import { useForm } from "react-hook-form"
+
+// validation schema...
+
+export const CreateForm = () => {
+  const form = useForm<zod.infer<typeof schema>>({
+    defaultValues: {
+      name: "",
+    },
+  })
+
+  const handleSubmit = form.handleSubmit(({ name }) => {
+    // TODO submit to backend
+    console.log(name)
+  })
+
+  // TODO render form
+}
+```
+
+You create the `CreateForm` component. For now, it uses `useForm` from `react-hook-form` to initialize a form.
+
+You also define a `handleSubmit` function to perform an action when the form is submitted.
+
+You can replace the content of the function with sending a request to Medusa's routes. Refer to [this guide](https://docs.medusajs.com/docs/learn/fundamentals/admin/tips#send-requests-to-api-routes/index.html.md) for more details on how to do that.
+
+### Render Components
+
+You'll now add a `return` statement that renders the focus modal where the form is shown.
+
+Replace `// TODO render form` with the following:
+
+```tsx title="src/admin/components/create-form.tsx"
+// other imports...
+import { 
+  FocusModal,
+  Heading,
+  Label,
+  Input,
+  Button,
+} from "@medusajs/ui"
+import { 
+  FormProvider,
+  Controller,
+} from "react-hook-form"
+
+export const CreateForm = () => {
+  // ...
+
+  return (
+    <FocusModal>
+      <FocusModal.Trigger asChild>
+        <Button>Create</Button>
+      </FocusModal.Trigger>
+      <FocusModal.Content>
+        <FormProvider {...form}>
+          <form
+            onSubmit={handleSubmit}
+            className="flex h-full flex-col overflow-hidden"
+          >
+            <FocusModal.Header>
+              <div className="flex items-center justify-end gap-x-2">
+                  <FocusModal.Close asChild>
+                    <Button size="small" variant="secondary">
+                      Cancel
+                    </Button>
+                  </FocusModal.Close>
+                  <Button type="submit" size="small">
+                    Save
+                  </Button>
+                </div>
+            </FocusModal.Header>
+            <FocusModal.Body>
+                <div className="flex flex-1 flex-col items-center overflow-y-auto">
+                  <div className="mx-auto flex w-full max-w-[720px] flex-col gap-y-8 px-2 py-16">
+                    <div>
+                      <Heading className="capitalize">
+                        Create Item
+                      </Heading>
+                    </div>
+                    <div className="grid grid-cols-2 gap-4">
+                      <Controller
+                        control={form.control}
+                        name="name"
+                        render={({ field }) => {
+                          return (
+                            <div className="flex flex-col space-y-2">
+                              <div className="flex items-center gap-x-1">
+                                <Label size="small" weight="plus">
+                                  Name
+                                </Label>
+                              </div>
+                              <Input {...field} />
+                            </div>
+                          )
+                        }}
+                      />
+                    </div>
+                  </div>
+                </div>
+            </FocusModal.Body>
+          </form>
+        </FormProvider>
+      </FocusModal.Content>
+    </FocusModal>
+  )
+}
+```
+
+You render a focus modal, with a trigger button to open it.
+
+In the `FocusModal.Content` component, you wrap the content with the `FormProvider` component from `react-hook-form`, passing it the details of the form you initialized earlier as props.
+
+In the `FormProvider`, you add a `form` component passing it the `handleSubmit` function you created earlier as the handler of the `onSubmit` event.
+
+In the `FocusModal.Header` component, you add buttons to save or cancel the form submission.
+
+Finally, you render the form's components inside the `FocusModal.Body`. To render inputs, you use the `Controller` component imported from `react-hook-form`.
+
+### Use Create Form Component
+
+You can use the `CreateForm` component in your widget or UI route.
+
+For example, create the widget `src/admin/widgets/product-widget.tsx` with the following content:
+
+```tsx title="src/admin/widgets/product-widget.tsx"
+import { defineWidgetConfig } from "@medusajs/admin-sdk"
+import { CreateForm } from "../components/create-form"
+import { Container } from "../components/container"
+import { Header } from "../components/header"
+
+const ProductWidget = () => {
+  return (
+    <Container>
+      <Header
+        title="Items"
+        actions={[
+          {
+            type: "custom",
+            children: <CreateForm />,
+          },
+        ]}
+      />
+    </Container>
+  )
+}
+
+export const config = defineWidgetConfig({
+  zone: "product.details.before",
+})
+
+export default ProductWidget
+```
+
+This component uses the [Container](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/admin-components/components/container/index.html.md) and [Header](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/admin-components/components/header/index.html.md) custom components.
+
+It will add at the top of a product's details page a new section, and in its header you'll find a Create button. If you click on it, it will open the focus modal with your form.
+
+***
+
+## Edit Form
+
+In this section, you'll build a form component to edit an item of a resource.
+
+### Full Component
+
+```tsx title="src/admin/components/edit-form.tsx"
+import { 
+  Drawer,
+  Heading,
+  Label,
+  Input,
+  Button,
+} from "@medusajs/ui"
+import { 
+  useForm, 
+  FormProvider,
+  Controller,
+} from "react-hook-form"
+import * as zod from "zod"
+
+const schema = zod.object({
+  name: zod.string(),
+})
+
+export const EditForm = () => {
+  const form = useForm<zod.infer<typeof schema>>({
+    defaultValues: {
+      name: "",
+    },
+  })
+
+  const handleSubmit = form.handleSubmit(({ name }) => {
+    // TODO submit to backend
+    console.log(name)
+  })
+
+  return (
+    <Drawer>
+      <Drawer.Trigger asChild>
+        <Button>Edit Item</Button>
+      </Drawer.Trigger>
+      <Drawer.Content>
+        <FormProvider {...form}>
+          <form
+            onSubmit={handleSubmit}
+            className="flex flex-1 flex-col overflow-hidden"
+          >
+          <Drawer.Header>
+            <Heading className="capitalize">
+              Edit Item
+            </Heading>
+          </Drawer.Header>
+          <Drawer.Body className="flex max-w-full flex-1 flex-col gap-y-8 overflow-y-auto">
+            <Controller
+              control={form.control}
+              name="name"
+              render={({ field }) => {
+                return (
+                  <div className="flex flex-col space-y-2">
+                    <div className="flex items-center gap-x-1">
+                      <Label size="small" weight="plus">
+                        Name
+                      </Label>
+                    </div>
+                    <Input {...field} />
+                  </div>
+                )
+              }}
+            />
+          </Drawer.Body>
+          <Drawer.Footer>
+            <div className="flex items-center justify-end gap-x-2">
+              <Drawer.Close asChild>
+                <Button size="small" variant="secondary">
+                  Cancel
+                </Button>
+              </Drawer.Close>
+              <Button size="small" type="submit">
+                Save
+              </Button>
+            </div>
+          </Drawer.Footer>
+          </form>
+        </FormProvider>
+      </Drawer.Content>
+    </Drawer>
+  )
+}
+```
+
+Unlike other components in this documentation, this form component isn't reusable. You have to create one for every resource that has an edit form in the admin.
+
+Start by creating the file `src/admin/components/edit-form.tsx` that you'll create the form in.
+
+### Create Validation Schema
+
+In `src/admin/components/edit-form.tsx`, create a validation schema with Zod for the form's fields:
+
+```tsx title="src/admin/components/edit-form.tsx"
+import * as zod from "zod"
+
+const schema = zod.object({
+  name: zod.string(),
+})
+```
+
+The form in this guide is simple, it only has a required `name` field, which is a string.
+
+### Initialize Form
+
+Next, you'll initialize the form using `react-hook-form`.
+
+Add to `src/admin/components/edit-form.tsx` the following:
+
+```tsx title="src/admin/components/edit-form.tsx"
+// other imports...
+import { useForm } from "react-hook-form"
+
+// validation schema...
+
+export const EditForm = () => {
+  const form = useForm<zod.infer<typeof schema>>({
+    defaultValues: {
+      name: "",
+    },
+  })
+
+  const handleSubmit = form.handleSubmit(({ name }) => {
+    // TODO submit to backend
+    console.log(name)
+  })
+
+  // TODO render form
+}
+```
+
+You create the `EditForm` component. For now, it uses `useForm` from `react-hook-form` to initialize a form.
+
+You also define a `handleSubmit` function to perform an action when the form is submitted.
+
+You can replace the content of the function with sending a request to Medusa's routes. Refer to [this guide](https://docs.medusajs.com/docs/learn/fundamentals/admin/tips#send-requests-to-api-routes/index.html.md) for more details on how to do that.
+
+### Render Components
+
+You'll now add a `return` statement that renders the drawer where the form is shown.
+
+Replace `// TODO render form` with the following:
+
+```tsx title="src/admin/components/edit-form.tsx"
+// other imports...
+import { 
+  Drawer,
+  Heading,
+  Label,
+  Input,
+  Button,
+} from "@medusajs/ui"
+import { 
+  FormProvider,
+  Controller,
+} from "react-hook-form"
+
+export const EditForm = () => {
+  // ...
+
+  return (
+    <Drawer>
+      <Drawer.Trigger asChild>
+        <Button>Edit Item</Button>
+      </Drawer.Trigger>
+      <Drawer.Content>
+        <FormProvider {...form}>
+          <form
+            onSubmit={handleSubmit}
+            className="flex flex-1 flex-col overflow-hidden"
+          >
+          <Drawer.Header>
+            <Heading className="capitalize">
+              Edit Item
+            </Heading>
+          </Drawer.Header>
+          <Drawer.Body className="flex max-w-full flex-1 flex-col gap-y-8 overflow-y-auto">
+            <Controller
+              control={form.control}
+              name="name"
+              render={({ field }) => {
+                return (
+                  <div className="flex flex-col space-y-2">
+                    <div className="flex items-center gap-x-1">
+                      <Label size="small" weight="plus">
+                        Name
+                      </Label>
+                    </div>
+                    <Input {...field} />
+                  </div>
+                )
+              }}
+            />
+          </Drawer.Body>
+          <Drawer.Footer>
+            <div className="flex items-center justify-end gap-x-2">
+              <Drawer.Close asChild>
+                <Button size="small" variant="secondary">
+                  Cancel
+                </Button>
+              </Drawer.Close>
+              <Button size="small" type="submit">
+                Save
+              </Button>
+            </div>
+          </Drawer.Footer>
+          </form>
+        </FormProvider>
+      </Drawer.Content>
+    </Drawer>
+  )
+}
+```
+
+You render a drawer, with a trigger button to open it.
+
+In the `Drawer.Content` component, you wrap the content with the `FormProvider` component from `react-hook-form`, passing it the details of the form you initialized earlier as props.
+
+In the `FormProvider`, you add a `form` component passing it the `handleSubmit` function you created earlier as the handler of the `onSubmit` event.
+
+You render the form's components inside the `Drawer.Body`. To render inputs, you use the `Controller` component imported from `react-hook-form`.
+
+Finally, in the `Drawer.Footer` component, you add buttons to save or cancel the form submission.
+
+### Use Edit Form Component
+
+You can use the `EditForm` component in your widget or UI route.
+
+For example, create the widget `src/admin/widgets/product-widget.tsx` with the following content:
+
+```tsx title="src/admin/widgets/product-widget.tsx"
+import { defineWidgetConfig } from "@medusajs/admin-sdk"
+import { Container } from "../components/container"
+import { Header } from "../components/header"
+import { EditForm } from "../components/edit-form"
+
+const ProductWidget = () => {
+  return (
+    <Container>
+      <Header
+        title="Items"
+        actions={[
+          {
+            type: "custom",
+            children: <EditForm />,
+          },
+        ]}
+      />
+    </Container>
+  )
+}
+
+export const config = defineWidgetConfig({
+  zone: "product.details.before",
+})
+
+export default ProductWidget
+```
+
+This component uses the [Container](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/admin-components/components/container/index.html.md) and [Header](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/admin-components/components/header/index.html.md) custom components.
+
+It will add at the top of a product's details page a new section, and in its header you'll find an "Edit Item" button. If you click on it, it will open the drawer with your form.
+
+
 # Header - Admin Components
 
 Each section in the Medusa Admin has a header with a title, and optionally a subtitle with buttons to perform an action.
@@ -54864,577 +55441,143 @@ export default ProductWidget
 This widget also uses the [Container](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/admin-components/components/container/index.html.md) and [Header](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/admin-components/components/header/index.html.md) custom component.
 
 
-# Forms - Admin Components
+# Single Column Layout - Admin Components
 
-The Medusa Admin has two types of forms:
+The Medusa Admin has pages with a single column of content.
 
-1. Create forms, created using the [FocusModal UI component](https://docs.medusajs.com/ui/components/focus-modal/index.html.md).
-2. Edit or update forms, created using the [Drawer UI component](https://docs.medusajs.com/ui/components/drawer/index.html.md).
+This doesn't include the sidebar, only the main content.
 
-This guide explains how to create these two form types following the Medusa Admin's conventions.
+![An example of an admin page with a single column](https://res.cloudinary.com/dza7lstvk/image/upload/v1728286605/Medusa%20Resources/single-column.png)
 
-## Form Tooling
+To create a layout that you can use in UI routes to support one column of content, create the component `src/admin/layouts/single-column.tsx` with the following content:
 
-The Medusa Admin uses the following tools to build the forms:
+```tsx title="src/admin/layouts/single-column.tsx"
+export type SingleColumnLayoutProps = {
+  children: React.ReactNode
+}
 
-1. [react-hook-form](https://react-hook-form.com/) to easily build forms and manage their states.
-2. [Zod](https://zod.dev/) to validate the form's fields.
+export const SingleColumnLayout = ({ children }: SingleColumnLayoutProps) => {
+  return (
+    <div className="flex flex-col gap-y-3">
+      {children}
+    </div>
+  )
+}
+```
 
-Both of these libraries are available in your project, so you don't have to install them to use them.
+The `SingleColumnLayout` accepts the content in the `children` props.
 
 ***
 
-## Create Form
+## Example
 
-In this section, you'll build a form component to create an item of a resource.
+Use the `SingleColumnLayout` component in your UI routes that have a single column. For example:
 
-### Full Component
+```tsx title="src/admin/routes/custom/page.tsx" highlights={[["9"]]}
+import { defineRouteConfig } from "@medusajs/admin-sdk"
+import { ChatBubbleLeftRight } from "@medusajs/icons"
+import { Container } from "../../components/container"
+import { SingleColumnLayout } from "../../layouts/single-column"
+import { Header } from "../../components/header"
 
-```tsx title="src/admin/components/create-form.tsx"
-import { 
-  FocusModal,
-  Heading,
-  Label,
-  Input,
-  Button,
-} from "@medusajs/ui"
-import { 
-  useForm, 
-  FormProvider,
-  Controller,
-} from "react-hook-form"
-import * as zod from "zod"
+const CustomPage = () => {
+  return (
+    <SingleColumnLayout>
+      <Container>
+        <Header title="Custom Page" />
+      </Container>
+    </SingleColumnLayout>
+  )
+}
 
-const schema = zod.object({
-  name: zod.string(),
+export const config = defineRouteConfig({
+  label: "Custom",
+  icon: ChatBubbleLeftRight,
 })
 
-export const CreateForm = () => {
-  const form = useForm<zod.infer<typeof schema>>({
-    defaultValues: {
-      name: "",
-    },
-  })
+export default CustomPage
+```
 
-  const handleSubmit = form.handleSubmit(({ name }) => {
-    // TODO submit to backend
-    console.log(name)
-  })
+This UI route also uses a [Container](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/admin-components/components/container/index.html.md) and a [Header]() custom components.
 
+
+# Two Column Layout - Admin Components
+
+The Medusa Admin has pages with two columns of content.
+
+This doesn't include the sidebar, only the main content.
+
+![An example of an admin page with two columns](https://res.cloudinary.com/dza7lstvk/image/upload/v1728286690/Medusa%20Resources/two-column_sdnkg0.png)
+
+To create a layout that you can use in UI routes to support two columns of content, create the component `src/admin/layouts/two-column.tsx` with the following content:
+
+```tsx title="src/admin/layouts/two-column.tsx"
+export type TwoColumnLayoutProps = {
+  firstCol: React.ReactNode
+  secondCol: React.ReactNode
+}
+
+export const TwoColumnLayout = ({ 
+  firstCol,
+  secondCol,
+}: TwoColumnLayoutProps) => {
   return (
-    <FocusModal>
-      <FocusModal.Trigger asChild>
-        <Button>Create</Button>
-      </FocusModal.Trigger>
-      <FocusModal.Content>
-        <FormProvider {...form}>
-          <form
-            onSubmit={handleSubmit}
-            className="flex h-full flex-col overflow-hidden"
-          >
-            <FocusModal.Header>
-              <div className="flex items-center justify-end gap-x-2">
-                  <FocusModal.Close asChild>
-                    <Button size="small" variant="secondary">
-                      Cancel
-                    </Button>
-                  </FocusModal.Close>
-                  <Button type="submit" size="small">
-                    Save
-                  </Button>
-                </div>
-            </FocusModal.Header>
-            <FocusModal.Body>
-                <div className="flex flex-1 flex-col items-center overflow-y-auto">
-                  <div className="mx-auto flex w-full max-w-[720px] flex-col gap-y-8 px-2 py-16">
-                    <div>
-                      <Heading className="capitalize">
-                        Create Item
-                      </Heading>
-                    </div>
-                    <div className="grid grid-cols-2 gap-4">
-                      <Controller
-                        control={form.control}
-                        name="name"
-                        render={({ field }) => {
-                          return (
-                            <div className="flex flex-col space-y-2">
-                              <div className="flex items-center gap-x-1">
-                                <Label size="small" weight="plus">
-                                  Name
-                                </Label>
-                              </div>
-                              <Input {...field} />
-                            </div>
-                          )
-                        }}
-                      />
-                    </div>
-                  </div>
-                </div>
-            </FocusModal.Body>
-          </form>
-        </FormProvider>
-      </FocusModal.Content>
-    </FocusModal>
+    <div className="flex flex-col gap-x-4 gap-y-3 xl:flex-row xl:items-start">
+      <div className="flex w-full flex-col gap-y-3">
+          {firstCol}
+        </div>
+        <div className="flex w-full max-w-[100%] flex-col gap-y-3 xl:mt-0 xl:max-w-[440px]">
+          {secondCol}
+        </div>
+    </div>
   )
 }
 ```
 
-Unlike other components in this documentation, this form component isn't reusable. You have to create one for every resource that has a create form in the admin.
+The `TwoColumnLayout` accepts two props:
 
-Start by creating the file `src/admin/components/create-form.tsx` that you'll create the form in.
-
-### Create Validation Schema
-
-In `src/admin/components/create-form.tsx`, create a validation schema with Zod for the form's fields:
-
-```tsx title="src/admin/components/create-form.tsx"
-import * as zod from "zod"
-
-const schema = zod.object({
-  name: zod.string(),
-})
-```
-
-The form in this guide is simple, it only has a required `name` field, which is a string.
-
-### Initialize Form
-
-Next, you'll initialize the form using `react-hook-form`.
-
-Add to `src/admin/components/create-form.tsx` the following:
-
-```tsx title="src/admin/components/create-form.tsx"
-// other imports...
-import { useForm } from "react-hook-form"
-
-// validation schema...
-
-export const CreateForm = () => {
-  const form = useForm<zod.infer<typeof schema>>({
-    defaultValues: {
-      name: "",
-    },
-  })
-
-  const handleSubmit = form.handleSubmit(({ name }) => {
-    // TODO submit to backend
-    console.log(name)
-  })
-
-  // TODO render form
-}
-```
-
-You create the `CreateForm` component. For now, it uses `useForm` from `react-hook-form` to initialize a form.
-
-You also define a `handleSubmit` function to perform an action when the form is submitted.
-
-You can replace the content of the function with sending a request to Medusa's routes. Refer to [this guide](https://docs.medusajs.com/docs/learn/fundamentals/admin/tips#send-requests-to-api-routes/index.html.md) for more details on how to do that.
-
-### Render Components
-
-You'll now add a `return` statement that renders the focus modal where the form is shown.
-
-Replace `// TODO render form` with the following:
-
-```tsx title="src/admin/components/create-form.tsx"
-// other imports...
-import { 
-  FocusModal,
-  Heading,
-  Label,
-  Input,
-  Button,
-} from "@medusajs/ui"
-import { 
-  FormProvider,
-  Controller,
-} from "react-hook-form"
-
-export const CreateForm = () => {
-  // ...
-
-  return (
-    <FocusModal>
-      <FocusModal.Trigger asChild>
-        <Button>Create</Button>
-      </FocusModal.Trigger>
-      <FocusModal.Content>
-        <FormProvider {...form}>
-          <form
-            onSubmit={handleSubmit}
-            className="flex h-full flex-col overflow-hidden"
-          >
-            <FocusModal.Header>
-              <div className="flex items-center justify-end gap-x-2">
-                  <FocusModal.Close asChild>
-                    <Button size="small" variant="secondary">
-                      Cancel
-                    </Button>
-                  </FocusModal.Close>
-                  <Button type="submit" size="small">
-                    Save
-                  </Button>
-                </div>
-            </FocusModal.Header>
-            <FocusModal.Body>
-                <div className="flex flex-1 flex-col items-center overflow-y-auto">
-                  <div className="mx-auto flex w-full max-w-[720px] flex-col gap-y-8 px-2 py-16">
-                    <div>
-                      <Heading className="capitalize">
-                        Create Item
-                      </Heading>
-                    </div>
-                    <div className="grid grid-cols-2 gap-4">
-                      <Controller
-                        control={form.control}
-                        name="name"
-                        render={({ field }) => {
-                          return (
-                            <div className="flex flex-col space-y-2">
-                              <div className="flex items-center gap-x-1">
-                                <Label size="small" weight="plus">
-                                  Name
-                                </Label>
-                              </div>
-                              <Input {...field} />
-                            </div>
-                          )
-                        }}
-                      />
-                    </div>
-                  </div>
-                </div>
-            </FocusModal.Body>
-          </form>
-        </FormProvider>
-      </FocusModal.Content>
-    </FocusModal>
-  )
-}
-```
-
-You render a focus modal, with a trigger button to open it.
-
-In the `FocusModal.Content` component, you wrap the content with the `FormProvider` component from `react-hook-form`, passing it the details of the form you initialized earlier as props.
-
-In the `FormProvider`, you add a `form` component passing it the `handleSubmit` function you created earlier as the handler of the `onSubmit` event.
-
-In the `FocusModal.Header` component, you add buttons to save or cancel the form submission.
-
-Finally, you render the form's components inside the `FocusModal.Body`. To render inputs, you use the `Controller` component imported from `react-hook-form`.
-
-### Use Create Form Component
-
-You can use the `CreateForm` component in your widget or UI route.
-
-For example, create the widget `src/admin/widgets/product-widget.tsx` with the following content:
-
-```tsx title="src/admin/widgets/product-widget.tsx"
-import { defineWidgetConfig } from "@medusajs/admin-sdk"
-import { CreateForm } from "../components/create-form"
-import { Container } from "../components/container"
-import { Header } from "../components/header"
-
-const ProductWidget = () => {
-  return (
-    <Container>
-      <Header
-        title="Items"
-        actions={[
-          {
-            type: "custom",
-            children: <CreateForm />,
-          },
-        ]}
-      />
-    </Container>
-  )
-}
-
-export const config = defineWidgetConfig({
-  zone: "product.details.before",
-})
-
-export default ProductWidget
-```
-
-This component uses the [Container](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/admin-components/components/container/index.html.md) and [Header](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/admin-components/components/header/index.html.md) custom components.
-
-It will add at the top of a product's details page a new section, and in its header you'll find a Create button. If you click on it, it will open the focus modal with your form.
+- `firstCol` indicating the content of the first column.
+- `secondCol` indicating the content of the second column.
 
 ***
 
-## Edit Form
+## Example
 
-In this section, you'll build a form component to edit an item of a resource.
+Use the `TwoColumnLayout` component in your UI routes that have a single column. For example:
 
-### Full Component
-
-```tsx title="src/admin/components/edit-form.tsx"
-import { 
-  Drawer,
-  Heading,
-  Label,
-  Input,
-  Button,
-} from "@medusajs/ui"
-import { 
-  useForm, 
-  FormProvider,
-  Controller,
-} from "react-hook-form"
-import * as zod from "zod"
-
-const schema = zod.object({
-  name: zod.string(),
-})
-
-export const EditForm = () => {
-  const form = useForm<zod.infer<typeof schema>>({
-    defaultValues: {
-      name: "",
-    },
-  })
-
-  const handleSubmit = form.handleSubmit(({ name }) => {
-    // TODO submit to backend
-    console.log(name)
-  })
+```tsx title="src/admin/routes/custom/page.tsx" highlights={[["9"]]}
+import { defineRouteConfig } from "@medusajs/admin-sdk"
+import { ChatBubbleLeftRight } from "@medusajs/icons"
+import { Container } from "../../components/container"
+import { Header } from "../../components/header"
+import { TwoColumnLayout } from "../../layouts/two-column"
 
+const CustomPage = () => {
   return (
-    <Drawer>
-      <Drawer.Trigger asChild>
-        <Button>Edit Item</Button>
-      </Drawer.Trigger>
-      <Drawer.Content>
-        <FormProvider {...form}>
-          <form
-            onSubmit={handleSubmit}
-            className="flex flex-1 flex-col overflow-hidden"
-          >
-          <Drawer.Header>
-            <Heading className="capitalize">
-              Edit Item
-            </Heading>
-          </Drawer.Header>
-          <Drawer.Body className="flex max-w-full flex-1 flex-col gap-y-8 overflow-y-auto">
-            <Controller
-              control={form.control}
-              name="name"
-              render={({ field }) => {
-                return (
-                  <div className="flex flex-col space-y-2">
-                    <div className="flex items-center gap-x-1">
-                      <Label size="small" weight="plus">
-                        Name
-                      </Label>
-                    </div>
-                    <Input {...field} />
-                  </div>
-                )
-              }}
-            />
-          </Drawer.Body>
-          <Drawer.Footer>
-            <div className="flex items-center justify-end gap-x-2">
-              <Drawer.Close asChild>
-                <Button size="small" variant="secondary">
-                  Cancel
-                </Button>
-              </Drawer.Close>
-              <Button size="small" type="submit">
-                Save
-              </Button>
-            </div>
-          </Drawer.Footer>
-          </form>
-        </FormProvider>
-      </Drawer.Content>
-    </Drawer>
-  )
-}
-```
-
-Unlike other components in this documentation, this form component isn't reusable. You have to create one for every resource that has an edit form in the admin.
-
-Start by creating the file `src/admin/components/edit-form.tsx` that you'll create the form in.
-
-### Create Validation Schema
-
-In `src/admin/components/edit-form.tsx`, create a validation schema with Zod for the form's fields:
-
-```tsx title="src/admin/components/edit-form.tsx"
-import * as zod from "zod"
-
-const schema = zod.object({
-  name: zod.string(),
-})
-```
-
-The form in this guide is simple, it only has a required `name` field, which is a string.
-
-### Initialize Form
-
-Next, you'll initialize the form using `react-hook-form`.
-
-Add to `src/admin/components/edit-form.tsx` the following:
-
-```tsx title="src/admin/components/edit-form.tsx"
-// other imports...
-import { useForm } from "react-hook-form"
-
-// validation schema...
-
-export const EditForm = () => {
-  const form = useForm<zod.infer<typeof schema>>({
-    defaultValues: {
-      name: "",
-    },
-  })
-
-  const handleSubmit = form.handleSubmit(({ name }) => {
-    // TODO submit to backend
-    console.log(name)
-  })
-
-  // TODO render form
-}
-```
-
-You create the `EditForm` component. For now, it uses `useForm` from `react-hook-form` to initialize a form.
-
-You also define a `handleSubmit` function to perform an action when the form is submitted.
-
-You can replace the content of the function with sending a request to Medusa's routes. Refer to [this guide](https://docs.medusajs.com/docs/learn/fundamentals/admin/tips#send-requests-to-api-routes/index.html.md) for more details on how to do that.
-
-### Render Components
-
-You'll now add a `return` statement that renders the drawer where the form is shown.
-
-Replace `// TODO render form` with the following:
-
-```tsx title="src/admin/components/edit-form.tsx"
-// other imports...
-import { 
-  Drawer,
-  Heading,
-  Label,
-  Input,
-  Button,
-} from "@medusajs/ui"
-import { 
-  FormProvider,
-  Controller,
-} from "react-hook-form"
-
-export const EditForm = () => {
-  // ...
-
-  return (
-    <Drawer>
-      <Drawer.Trigger asChild>
-        <Button>Edit Item</Button>
-      </Drawer.Trigger>
-      <Drawer.Content>
-        <FormProvider {...form}>
-          <form
-            onSubmit={handleSubmit}
-            className="flex flex-1 flex-col overflow-hidden"
-          >
-          <Drawer.Header>
-            <Heading className="capitalize">
-              Edit Item
-            </Heading>
-          </Drawer.Header>
-          <Drawer.Body className="flex max-w-full flex-1 flex-col gap-y-8 overflow-y-auto">
-            <Controller
-              control={form.control}
-              name="name"
-              render={({ field }) => {
-                return (
-                  <div className="flex flex-col space-y-2">
-                    <div className="flex items-center gap-x-1">
-                      <Label size="small" weight="plus">
-                        Name
-                      </Label>
-                    </div>
-                    <Input {...field} />
-                  </div>
-                )
-              }}
-            />
-          </Drawer.Body>
-          <Drawer.Footer>
-            <div className="flex items-center justify-end gap-x-2">
-              <Drawer.Close asChild>
-                <Button size="small" variant="secondary">
-                  Cancel
-                </Button>
-              </Drawer.Close>
-              <Button size="small" type="submit">
-                Save
-              </Button>
-            </div>
-          </Drawer.Footer>
-          </form>
-        </FormProvider>
-      </Drawer.Content>
-    </Drawer>
-  )
-}
-```
-
-You render a drawer, with a trigger button to open it.
-
-In the `Drawer.Content` component, you wrap the content with the `FormProvider` component from `react-hook-form`, passing it the details of the form you initialized earlier as props.
-
-In the `FormProvider`, you add a `form` component passing it the `handleSubmit` function you created earlier as the handler of the `onSubmit` event.
-
-You render the form's components inside the `Drawer.Body`. To render inputs, you use the `Controller` component imported from `react-hook-form`.
-
-Finally, in the `Drawer.Footer` component, you add buttons to save or cancel the form submission.
-
-### Use Edit Form Component
-
-You can use the `EditForm` component in your widget or UI route.
-
-For example, create the widget `src/admin/widgets/product-widget.tsx` with the following content:
-
-```tsx title="src/admin/widgets/product-widget.tsx"
-import { defineWidgetConfig } from "@medusajs/admin-sdk"
-import { Container } from "../components/container"
-import { Header } from "../components/header"
-import { EditForm } from "../components/edit-form"
-
-const ProductWidget = () => {
-  return (
-    <Container>
-      <Header
-        title="Items"
-        actions={[
-          {
-            type: "custom",
-            children: <EditForm />,
-          },
-        ]}
-      />
-    </Container>
+    <TwoColumnLayout
+      firstCol={
+        <Container>
+          <Header title="First Column" />
+        </Container>
+      }
+      secondCol={
+        <Container>
+          <Header title="Second Column" />
+        </Container>
+      }
+    />
   )
 }
 
-export const config = defineWidgetConfig({
-  zone: "product.details.before",
+export const config = defineRouteConfig({
+  label: "Custom",
+  icon: ChatBubbleLeftRight,
 })
 
-export default ProductWidget
+export default CustomPage
 ```
 
-This component uses the [Container](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/admin-components/components/container/index.html.md) and [Header](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/admin-components/components/header/index.html.md) custom components.
-
-It will add at the top of a product's details page a new section, and in its header you'll find an "Edit Item" button. If you click on it, it will open the drawer with your form.
+This UI route also uses [Container](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/admin-components/components/container/index.html.md) and [Header]() custom components.
 
 
 # Table - Admin Components
@@ -55727,145 +55870,6 @@ If `data` isn't `undefined`, you display the `Table` component passing it the fo
 To test it out, log into the Medusa Admin and open `http://localhost:9000/app/custom`. You'll find a table of products with pagination.
 
 
-# Two Column Layout - Admin Components
-
-The Medusa Admin has pages with two columns of content.
-
-This doesn't include the sidebar, only the main content.
-
-![An example of an admin page with two columns](https://res.cloudinary.com/dza7lstvk/image/upload/v1728286690/Medusa%20Resources/two-column_sdnkg0.png)
-
-To create a layout that you can use in UI routes to support two columns of content, create the component `src/admin/layouts/two-column.tsx` with the following content:
-
-```tsx title="src/admin/layouts/two-column.tsx"
-export type TwoColumnLayoutProps = {
-  firstCol: React.ReactNode
-  secondCol: React.ReactNode
-}
-
-export const TwoColumnLayout = ({ 
-  firstCol,
-  secondCol,
-}: TwoColumnLayoutProps) => {
-  return (
-    <div className="flex flex-col gap-x-4 gap-y-3 xl:flex-row xl:items-start">
-      <div className="flex w-full flex-col gap-y-3">
-          {firstCol}
-        </div>
-        <div className="flex w-full max-w-[100%] flex-col gap-y-3 xl:mt-0 xl:max-w-[440px]">
-          {secondCol}
-        </div>
-    </div>
-  )
-}
-```
-
-The `TwoColumnLayout` accepts two props:
-
-- `firstCol` indicating the content of the first column.
-- `secondCol` indicating the content of the second column.
-
-***
-
-## Example
-
-Use the `TwoColumnLayout` component in your UI routes that have a single column. For example:
-
-```tsx title="src/admin/routes/custom/page.tsx" highlights={[["9"]]}
-import { defineRouteConfig } from "@medusajs/admin-sdk"
-import { ChatBubbleLeftRight } from "@medusajs/icons"
-import { Container } from "../../components/container"
-import { Header } from "../../components/header"
-import { TwoColumnLayout } from "../../layouts/two-column"
-
-const CustomPage = () => {
-  return (
-    <TwoColumnLayout
-      firstCol={
-        <Container>
-          <Header title="First Column" />
-        </Container>
-      }
-      secondCol={
-        <Container>
-          <Header title="Second Column" />
-        </Container>
-      }
-    />
-  )
-}
-
-export const config = defineRouteConfig({
-  label: "Custom",
-  icon: ChatBubbleLeftRight,
-})
-
-export default CustomPage
-```
-
-This UI route also uses [Container](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/admin-components/components/container/index.html.md) and [Header]() custom components.
-
-
-# Single Column Layout - Admin Components
-
-The Medusa Admin has pages with a single column of content.
-
-This doesn't include the sidebar, only the main content.
-
-![An example of an admin page with a single column](https://res.cloudinary.com/dza7lstvk/image/upload/v1728286605/Medusa%20Resources/single-column.png)
-
-To create a layout that you can use in UI routes to support one column of content, create the component `src/admin/layouts/single-column.tsx` with the following content:
-
-```tsx title="src/admin/layouts/single-column.tsx"
-export type SingleColumnLayoutProps = {
-  children: React.ReactNode
-}
-
-export const SingleColumnLayout = ({ children }: SingleColumnLayoutProps) => {
-  return (
-    <div className="flex flex-col gap-y-3">
-      {children}
-    </div>
-  )
-}
-```
-
-The `SingleColumnLayout` accepts the content in the `children` props.
-
-***
-
-## Example
-
-Use the `SingleColumnLayout` component in your UI routes that have a single column. For example:
-
-```tsx title="src/admin/routes/custom/page.tsx" highlights={[["9"]]}
-import { defineRouteConfig } from "@medusajs/admin-sdk"
-import { ChatBubbleLeftRight } from "@medusajs/icons"
-import { Container } from "../../components/container"
-import { SingleColumnLayout } from "../../layouts/single-column"
-import { Header } from "../../components/header"
-
-const CustomPage = () => {
-  return (
-    <SingleColumnLayout>
-      <Container>
-        <Header title="Custom Page" />
-      </Container>
-    </SingleColumnLayout>
-  )
-}
-
-export const config = defineRouteConfig({
-  label: "Custom",
-  icon: ChatBubbleLeftRight,
-})
-
-export default CustomPage
-```
-
-This UI route also uses a [Container](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/admin-components/components/container/index.html.md) and a [Header]() custom components.
-
-
 # Service Factory Reference
 
 This section of the documentation provides a reference of the methods generated for services extending the service factory (`MedusaService`), and how to use them.
@@ -55893,6 +55897,692 @@ Some examples of method names:
 The reference uses only the operation name to refer to the method.
 
 
+# create Method - Service Factory Reference
+
+This method creates one or more records of the data model.
+
+## Create One Record
+
+```ts
+const post = await postModuleService.createPosts({
+  name: "My Post",
+  published_at: new Date(),
+  metadata: {
+     external_id: "1234",
+  },
+})
+```
+
+If an object is passed of the method, an object of the created record is also returned.
+
+***
+
+## Create Multiple Records
+
+```ts
+const posts = await postModuleService.createPosts([
+  {
+    name: "My Post",
+    published_at: new Date(),
+  },
+  {
+    name: "My Other Post",
+    published_at: new Date(),
+  },
+])
+```
+
+If an array is passed of the method, an array of the created records is also returned.
+
+
+# list Method - Service Factory Reference
+
+This method retrieves a list of records.
+
+## Retrieve List of Records
+
+```ts
+const posts = await postModuleService.listPosts()
+```
+
+If no parameters are passed, the method returns an array of the first `15` records.
+
+***
+
+## Filter Records
+
+```ts
+const posts = await postModuleService.listPosts({
+  id: ["123", "321"],
+})
+```
+
+### Parameters
+
+To retrieve records matching a set of filters, pass an object of the filters as a first parameter.
+
+Learn more about accepted filters in [this documentation](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/service-factory-reference/tips/filtering/index.html.md).
+
+### Returns
+
+The method returns an array of the first `15` records matching the filters.
+
+***
+
+## Retrieve Relations
+
+This applies to relations between data models of the same module. To retrieve linked records of different modules, use [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md).
+
+```ts
+const posts = await postModuleService.listPosts({}, {
+  relations: ["author"],
+})
+```
+
+### Parameters
+
+To retrieve records with their relations, pass as a second parameter an object having a `relations` property. `relations`'s value is an array of relation names.
+
+### Returns
+
+The method returns an array of the first `15` records matching the filters.
+
+***
+
+## Select Properties
+
+```ts
+const posts = await postModuleService.listPosts({}, {
+  select: ["id", "name"],
+})
+```
+
+### Parameters
+
+By default, retrieved records have all their properties. To select specific properties to retrieve, pass in the second object parameter a `select` property.
+
+`select`'s value is an array of property names to retrieve.
+
+### Returns
+
+The method returns an array of the first `15` records matching the filters.
+
+***
+
+## Paginate Relations
+
+```ts
+const posts = await postModuleService.listPosts({}, {
+  take: 20,
+  skip: 10,
+})
+```
+
+### Parameters
+
+To paginate the returned records, the second object parameter accepts the following properties:
+
+- `take`: a number indicating how many records to retrieve. By default, it's `15`.
+- `skip`: a number indicating how many records to skip before the retrieved records. By default, it's `0`.
+
+### Returns
+
+The method returns an array of records. The number of records is less than or equal to `take`'s value.
+
+***
+
+## Sort Records
+
+```ts
+const posts = await postModuleService.listPosts({}, {
+  order: {
+    name: "ASC",
+  },
+})
+```
+
+### Parameters
+
+To sort records by one or more properties, pass to the second object parameter the `order` property. Its value is an object whose keys are the property names, and values can either be:
+
+- `ASC` to sort by this property in the ascending order.
+- `DESC` to sort by this property in the descending order.
+
+### Returns
+
+The method returns an array of the first `15` records matching the filters.
+
+
+# listAndCount Method - Service Factory Reference
+
+This method retrieves a list of records with the total count.
+
+## Retrieve List of Records
+
+```ts
+const [posts, count] = await postModuleService.listAndCountPosts()
+```
+
+If no parameters are passed, the method returns an array with two items:
+
+1. The first is an array of the first `15` records retrieved.
+2. The second is the total count of records.
+
+***
+
+## Filter Records
+
+```ts
+const [posts, count] = await postModuleService.listAndCountPosts({
+  id: ["123", "321"],
+})
+```
+
+### Parameters
+
+To retrieve records matching a set of filters, pass an object of the filters as a first parameter.
+
+Learn more about accepted filters in [this documentation](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/service-factory-reference/tips/filtering/index.html.md).
+
+### Returns
+
+The method returns an array with two items:
+
+1. The first is an array of the first `15` records retrieved matching the specified filters.
+2. The second is the total count of records matching the specified filters.
+
+***
+
+## Retrieve Relations
+
+This applies to relations between data models of the same module. To retrieve linked records of different modules, use [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md).
+
+```ts
+const [posts, count] = await postModuleService.listAndCountPosts({}, {
+  relations: ["author"],
+})
+```
+
+### Parameters
+
+To retrieve records with their relations, pass as a second parameter an object having a `relations` property. Its value is an array of relation names.
+
+### Returns
+
+The method returns an array with two items:
+
+1. The first is an array of the first `15` records retrieved.
+2. The second is the total count of records.
+
+***
+
+## Select Properties
+
+```ts
+const [posts, count] = await postModuleService.listAndCountPosts({}, {
+  select: ["id", "name"],
+})
+```
+
+### Parameters
+
+By default, retrieved records have all their properties. To select specific properties to retrieve, pass in the second object parameter a `select` property.
+
+`select`'s value is an array of property names to retrieve.
+
+### Returns
+
+The method returns an array with two items:
+
+1. The first is an array of the first `15` records retrieved.
+2. The second is the total count of records.
+
+***
+
+## Paginate Relations
+
+```ts
+const [posts, count] = await postModuleService.listAndCountPosts({}, {
+  take: 20,
+  skip: 10,
+})
+```
+
+### Parameters
+
+To paginate the returned records, the second object parameter accepts the following properties:
+
+- `take`: a number indicating how many records to retrieve. By default, it's `15`.
+- `skip`: a number indicating how many records to skip before the retrieved records. By default, it's `0`.
+
+### Returns
+
+The method returns an array with two items:
+
+1. The first is an array of the records retrieved. The number of records is less than or equal to `take`'s value.
+2. The second is the total count of records.
+
+***
+
+## Sort Records
+
+```ts
+const [posts, count] = await postModuleService.listAndCountPosts({}, {
+  order: {
+    name: "ASC",
+  },
+})
+```
+
+### Parameters
+
+To sort records by one or more properties, pass to the second object parameter the `order` property. Its value is an object whose keys are the property names, and values can either be:
+
+- `ASC` to sort by this property in the ascending order.
+- `DESC` to sort by this property in the descending order.
+
+### Returns
+
+The method returns an array with two items:
+
+1. The first is an array of the first `15` records retrieved.
+2. The second is the total count of records.
+
+
+# delete Method - Service Factory Reference
+
+This method deletes one or more records.
+
+## Delete One Record
+
+```ts
+await postModuleService.deletePosts("123")
+```
+
+To delete one record, pass its ID as a parameter of the method.
+
+***
+
+## Delete Multiple Records
+
+```ts
+await postModuleService.deletePosts([
+  "123",
+  "321",
+])
+```
+
+To delete multiple records, pass an array of IDs as a parameter of the method.
+
+***
+
+## Delete Records Matching Filters
+
+```ts
+await postModuleService.deletePosts({
+  name: "My Post",
+})
+```
+
+To delete records matching a set of filters, pass an object of filters as a parameter.
+
+Learn more about accepted filters in [this documentation](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/service-factory-reference/tips/filtering/index.html.md).
+
+
+# restore Method - Service Factory Reference
+
+This method restores one or more records of the data model that were [soft-deleted](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/service-factory-reference/methods/soft-delete/index.html.md).
+
+## Restore One Record
+
+```ts
+const restoredPosts = await postModuleService.restorePosts("123")
+```
+
+### Parameters
+
+To restore one record, pass its ID as a parameter of the method.
+
+### Returns
+
+The method returns an object, whose keys are of the format `{camel_case_data_model_name}_id`, and their values are arrays of restored records' IDs.
+
+For example, the returned object of the above example is:
+
+```ts
+restoredPosts = {
+  post_id: ["123"],
+}
+```
+
+***
+
+## Restore Multiple Records
+
+```ts
+const restoredPosts = await postModuleService.restorePosts([
+  "123",
+  "321",
+])
+```
+
+### Parameters
+
+To restore multiple records, pass an array of IDs as a parameter of the method.
+
+### Returns
+
+The method returns an object, whose keys are of the format `{camel_case_data_model_name}_id`, and their values are arrays of restored records' IDs.
+
+For example, the returned object of the above example is:
+
+```ts
+restoredPosts = {
+  post_id: [
+    "123",
+    "321",
+  ],
+}
+```
+
+***
+
+## Restore Records Matching Filters
+
+```ts
+const restoredPosts = await postModuleService.restorePosts({
+  name: "My Post",
+})
+```
+
+### Parameters
+
+To restore records matching a set of filters, pass an object of fitlers as a parameter of the method.
+
+Learn more about accepted filters in [this documentation](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/service-factory-reference/tips/filtering/index.html.md).
+
+### Returns
+
+The method returns an object, whose keys are of the format `{camel_case_data_model_name}_id`, and their values are arrays of restored records' IDs.
+
+For example, the returned object of the above example is:
+
+```ts
+restoredPosts = {
+  post_id: [
+    "123",
+  ],
+}
+```
+
+
+# retrieve Method - Service Factory Reference
+
+This method retrieves one record of the data model by its ID.
+
+## Retrieve a Record
+
+```ts
+const post = await postModuleService.retrievePost("123")
+```
+
+### Parameters
+
+Pass the ID of the record to retrieve.
+
+### Returns
+
+The method returns the record as an object.
+
+***
+
+## Retrieve a Record's Relations
+
+This applies to relations between data models of the same module. To retrieve linked records of different modules, use [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md).
+
+```ts
+const post = await postModuleService.retrievePost("123", {
+  relations: ["author"],
+})
+```
+
+### Parameters
+
+To retrieve the data model with relations, pass as a second parameter of the method an object with the property `relations`. `relations`'s value is an array of relation names.
+
+### Returns
+
+The method returns the record as an object.
+
+***
+
+## Select Properties to Retrieve
+
+```ts
+const post = await postModuleService.retrievePost("123", {
+  select: ["id", "name"],
+})
+```
+
+### Parameters
+
+By default, all of the record's properties are retrieved. To select specific ones, pass in the second object parameter a `select` property. Its value is an array of property names.
+
+### Returns
+
+The method returns the record as an object.
+
+
+# softDelete Method - Service Factory Reference
+
+This method soft deletes one or more records of the data model.
+
+## Soft Delete One Record
+
+```ts
+const deletedPosts = await postModuleService.softDeletePosts(
+  "123"
+)
+```
+
+### Parameters
+
+To soft delete a record, pass its ID as a parameter of the method.
+
+### Returns
+
+The method returns an object, whose keys are of the format `{camel_case_data_model_name}_id`, and their values are arrays of soft-deleted records' IDs.
+
+For example, the returned object of the above example is:
+
+```ts
+deletedPosts = {
+  post_id: ["123"],
+}
+```
+
+***
+
+## Soft Delete Multiple Records
+
+```ts
+const deletedPosts = await postModuleService.softDeletePosts([
+  "123",
+  "321",
+])
+```
+
+### Parameters
+
+To soft delete multiple records, pass an array of IDs as a parameter of the method.
+
+### Returns
+
+The method returns an object, whose keys are of the format `{camel_case_data_model_name}_id`, and their values are arrays of soft-deleted records' IDs.
+
+For example, the returned object of the above example is:
+
+```ts
+deletedPosts = {
+  post_id: [
+    "123",
+    "321",
+  ],
+}
+```
+
+***
+
+## Soft Delete Records Matching Filters
+
+```ts
+const deletedPosts = await postModuleService.softDeletePosts({
+  name: "My Post",
+})
+```
+
+### Parameters
+
+To soft delete records matching a set of filters, pass an object of filters as a parameter.
+
+Learn more about accepted filters in [this documentation](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/service-factory-reference/tips/filtering/index.html.md).
+
+### Returns
+
+The method returns an object, whose keys are of the format `{camel_case_data_model_name}_id`, and their values are arrays of soft-deleted records' IDs.
+
+For example, the returned object of the above example is:
+
+```ts
+deletedPosts = {
+  post_id: ["123"],
+}
+```
+
+
+# update Method - Service Factory Reference
+
+This method updates one or more records of the data model.
+
+## Update One Record
+
+```ts
+const post = await postModuleService.updatePosts({
+  id: "123",
+  name: "My Post",
+})
+```
+
+### Parameters
+
+To update one record, pass an object that at least has an `id` property, identifying the ID of the record to update.
+
+You can pass in the same object any other properties to update.
+
+### Returns
+
+The method returns the updated record as an object.
+
+***
+
+## Update Multiple Records
+
+```ts
+const posts = await postModuleService.updatePosts([
+  {
+    id: "123",
+    name: "My Post",
+  },
+  {
+    id: "321",
+    published_at: new Date(),
+  },
+])
+```
+
+### Parameters
+
+To update multiple records, pass an array of objects. Each object has at least an `id` property, identifying the ID of the record to update.
+
+You can pass in each object any other properties to update.
+
+### Returns
+
+The method returns an array of objects of updated records.
+
+***
+
+## Update Records Matching a Filter
+
+```ts
+const posts = await postModuleService.updatePosts({
+  selector: {
+    name: "My Post",
+  },
+  data: {
+    published_at: new Date(),
+  },
+})
+```
+
+### Parameters
+
+To update records that match specified filters, pass as a parameter an object having two properties:
+
+- `selector`: An object of filters that a record must match to be updated.
+- `data`: An object of the properties to update in every record that match the filters in `selector`.
+
+In the example above, you update the `published_at` property of every post record whose name is `My Post`.
+
+Learn more about accepted filters in [this documentation](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/service-factory-reference/tips/filtering/index.html.md).
+
+### Returns
+
+The method returns an array of objects of updated records.
+
+***
+
+## Multiple Record Updates with Filters
+
+```ts
+const posts = await postModuleService.updatePosts([
+  {
+    selector: {
+      name: "My Post",
+    },
+    data: {
+      published_at: new Date(),
+    },
+  },
+  {
+    selector: {
+      name: "Another Post",
+    },
+    data: {
+      metadata: {
+        external_id: "123",
+      },
+    },
+  },
+])
+```
+
+### Parameters
+
+To update records matching different sets of filters, pass an array of objects, each having two properties:
+
+- `selector`: An object of filters that a record must match to be updated.
+- `data`: An object of the properties to update in every record that match the filters in `selector`.
+
+In the example above, you update the `published_at` property of post records whose name is `My Post`, and update the `metadata` property of post records whose name is `Another Post`.
+
+Learn more about accepted filters in [this documentation](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/service-factory-reference/tips/filtering/index.html.md).
+
+### Returns
+
+The method returns an array of objects of updated records.
+
+
 # Filter Records - Service Factory Reference
 
 Many of the service factory's generated methods allow passing filters to perform an operation, such as to update or delete records matching the filters.
@@ -56180,692 +56870,6 @@ The following operators are supported by the service factory filtering mechanism
 |\`$not\`|Inverts the logic of a condition. For example, |
 
 
-# delete Method - Service Factory Reference
-
-This method deletes one or more records.
-
-## Delete One Record
-
-```ts
-await postModuleService.deletePosts("123")
-```
-
-To delete one record, pass its ID as a parameter of the method.
-
-***
-
-## Delete Multiple Records
-
-```ts
-await postModuleService.deletePosts([
-  "123",
-  "321",
-])
-```
-
-To delete multiple records, pass an array of IDs as a parameter of the method.
-
-***
-
-## Delete Records Matching Filters
-
-```ts
-await postModuleService.deletePosts({
-  name: "My Post",
-})
-```
-
-To delete records matching a set of filters, pass an object of filters as a parameter.
-
-Learn more about accepted filters in [this documentation](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/service-factory-reference/tips/filtering/index.html.md).
-
-
-# create Method - Service Factory Reference
-
-This method creates one or more records of the data model.
-
-## Create One Record
-
-```ts
-const post = await postModuleService.createPosts({
-  name: "My Post",
-  published_at: new Date(),
-  metadata: {
-     external_id: "1234",
-  },
-})
-```
-
-If an object is passed of the method, an object of the created record is also returned.
-
-***
-
-## Create Multiple Records
-
-```ts
-const posts = await postModuleService.createPosts([
-  {
-    name: "My Post",
-    published_at: new Date(),
-  },
-  {
-    name: "My Other Post",
-    published_at: new Date(),
-  },
-])
-```
-
-If an array is passed of the method, an array of the created records is also returned.
-
-
-# restore Method - Service Factory Reference
-
-This method restores one or more records of the data model that were [soft-deleted](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/service-factory-reference/methods/soft-delete/index.html.md).
-
-## Restore One Record
-
-```ts
-const restoredPosts = await postModuleService.restorePosts("123")
-```
-
-### Parameters
-
-To restore one record, pass its ID as a parameter of the method.
-
-### Returns
-
-The method returns an object, whose keys are of the format `{camel_case_data_model_name}_id`, and their values are arrays of restored records' IDs.
-
-For example, the returned object of the above example is:
-
-```ts
-restoredPosts = {
-  post_id: ["123"],
-}
-```
-
-***
-
-## Restore Multiple Records
-
-```ts
-const restoredPosts = await postModuleService.restorePosts([
-  "123",
-  "321",
-])
-```
-
-### Parameters
-
-To restore multiple records, pass an array of IDs as a parameter of the method.
-
-### Returns
-
-The method returns an object, whose keys are of the format `{camel_case_data_model_name}_id`, and their values are arrays of restored records' IDs.
-
-For example, the returned object of the above example is:
-
-```ts
-restoredPosts = {
-  post_id: [
-    "123",
-    "321",
-  ],
-}
-```
-
-***
-
-## Restore Records Matching Filters
-
-```ts
-const restoredPosts = await postModuleService.restorePosts({
-  name: "My Post",
-})
-```
-
-### Parameters
-
-To restore records matching a set of filters, pass an object of fitlers as a parameter of the method.
-
-Learn more about accepted filters in [this documentation](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/service-factory-reference/tips/filtering/index.html.md).
-
-### Returns
-
-The method returns an object, whose keys are of the format `{camel_case_data_model_name}_id`, and their values are arrays of restored records' IDs.
-
-For example, the returned object of the above example is:
-
-```ts
-restoredPosts = {
-  post_id: [
-    "123",
-  ],
-}
-```
-
-
-# list Method - Service Factory Reference
-
-This method retrieves a list of records.
-
-## Retrieve List of Records
-
-```ts
-const posts = await postModuleService.listPosts()
-```
-
-If no parameters are passed, the method returns an array of the first `15` records.
-
-***
-
-## Filter Records
-
-```ts
-const posts = await postModuleService.listPosts({
-  id: ["123", "321"],
-})
-```
-
-### Parameters
-
-To retrieve records matching a set of filters, pass an object of the filters as a first parameter.
-
-Learn more about accepted filters in [this documentation](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/service-factory-reference/tips/filtering/index.html.md).
-
-### Returns
-
-The method returns an array of the first `15` records matching the filters.
-
-***
-
-## Retrieve Relations
-
-This applies to relations between data models of the same module. To retrieve linked records of different modules, use [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md).
-
-```ts
-const posts = await postModuleService.listPosts({}, {
-  relations: ["author"],
-})
-```
-
-### Parameters
-
-To retrieve records with their relations, pass as a second parameter an object having a `relations` property. `relations`'s value is an array of relation names.
-
-### Returns
-
-The method returns an array of the first `15` records matching the filters.
-
-***
-
-## Select Properties
-
-```ts
-const posts = await postModuleService.listPosts({}, {
-  select: ["id", "name"],
-})
-```
-
-### Parameters
-
-By default, retrieved records have all their properties. To select specific properties to retrieve, pass in the second object parameter a `select` property.
-
-`select`'s value is an array of property names to retrieve.
-
-### Returns
-
-The method returns an array of the first `15` records matching the filters.
-
-***
-
-## Paginate Relations
-
-```ts
-const posts = await postModuleService.listPosts({}, {
-  take: 20,
-  skip: 10,
-})
-```
-
-### Parameters
-
-To paginate the returned records, the second object parameter accepts the following properties:
-
-- `take`: a number indicating how many records to retrieve. By default, it's `15`.
-- `skip`: a number indicating how many records to skip before the retrieved records. By default, it's `0`.
-
-### Returns
-
-The method returns an array of records. The number of records is less than or equal to `take`'s value.
-
-***
-
-## Sort Records
-
-```ts
-const posts = await postModuleService.listPosts({}, {
-  order: {
-    name: "ASC",
-  },
-})
-```
-
-### Parameters
-
-To sort records by one or more properties, pass to the second object parameter the `order` property. Its value is an object whose keys are the property names, and values can either be:
-
-- `ASC` to sort by this property in the ascending order.
-- `DESC` to sort by this property in the descending order.
-
-### Returns
-
-The method returns an array of the first `15` records matching the filters.
-
-
-# retrieve Method - Service Factory Reference
-
-This method retrieves one record of the data model by its ID.
-
-## Retrieve a Record
-
-```ts
-const post = await postModuleService.retrievePost("123")
-```
-
-### Parameters
-
-Pass the ID of the record to retrieve.
-
-### Returns
-
-The method returns the record as an object.
-
-***
-
-## Retrieve a Record's Relations
-
-This applies to relations between data models of the same module. To retrieve linked records of different modules, use [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md).
-
-```ts
-const post = await postModuleService.retrievePost("123", {
-  relations: ["author"],
-})
-```
-
-### Parameters
-
-To retrieve the data model with relations, pass as a second parameter of the method an object with the property `relations`. `relations`'s value is an array of relation names.
-
-### Returns
-
-The method returns the record as an object.
-
-***
-
-## Select Properties to Retrieve
-
-```ts
-const post = await postModuleService.retrievePost("123", {
-  select: ["id", "name"],
-})
-```
-
-### Parameters
-
-By default, all of the record's properties are retrieved. To select specific ones, pass in the second object parameter a `select` property. Its value is an array of property names.
-
-### Returns
-
-The method returns the record as an object.
-
-
-# listAndCount Method - Service Factory Reference
-
-This method retrieves a list of records with the total count.
-
-## Retrieve List of Records
-
-```ts
-const [posts, count] = await postModuleService.listAndCountPosts()
-```
-
-If no parameters are passed, the method returns an array with two items:
-
-1. The first is an array of the first `15` records retrieved.
-2. The second is the total count of records.
-
-***
-
-## Filter Records
-
-```ts
-const [posts, count] = await postModuleService.listAndCountPosts({
-  id: ["123", "321"],
-})
-```
-
-### Parameters
-
-To retrieve records matching a set of filters, pass an object of the filters as a first parameter.
-
-Learn more about accepted filters in [this documentation](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/service-factory-reference/tips/filtering/index.html.md).
-
-### Returns
-
-The method returns an array with two items:
-
-1. The first is an array of the first `15` records retrieved matching the specified filters.
-2. The second is the total count of records matching the specified filters.
-
-***
-
-## Retrieve Relations
-
-This applies to relations between data models of the same module. To retrieve linked records of different modules, use [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md).
-
-```ts
-const [posts, count] = await postModuleService.listAndCountPosts({}, {
-  relations: ["author"],
-})
-```
-
-### Parameters
-
-To retrieve records with their relations, pass as a second parameter an object having a `relations` property. Its value is an array of relation names.
-
-### Returns
-
-The method returns an array with two items:
-
-1. The first is an array of the first `15` records retrieved.
-2. The second is the total count of records.
-
-***
-
-## Select Properties
-
-```ts
-const [posts, count] = await postModuleService.listAndCountPosts({}, {
-  select: ["id", "name"],
-})
-```
-
-### Parameters
-
-By default, retrieved records have all their properties. To select specific properties to retrieve, pass in the second object parameter a `select` property.
-
-`select`'s value is an array of property names to retrieve.
-
-### Returns
-
-The method returns an array with two items:
-
-1. The first is an array of the first `15` records retrieved.
-2. The second is the total count of records.
-
-***
-
-## Paginate Relations
-
-```ts
-const [posts, count] = await postModuleService.listAndCountPosts({}, {
-  take: 20,
-  skip: 10,
-})
-```
-
-### Parameters
-
-To paginate the returned records, the second object parameter accepts the following properties:
-
-- `take`: a number indicating how many records to retrieve. By default, it's `15`.
-- `skip`: a number indicating how many records to skip before the retrieved records. By default, it's `0`.
-
-### Returns
-
-The method returns an array with two items:
-
-1. The first is an array of the records retrieved. The number of records is less than or equal to `take`'s value.
-2. The second is the total count of records.
-
-***
-
-## Sort Records
-
-```ts
-const [posts, count] = await postModuleService.listAndCountPosts({}, {
-  order: {
-    name: "ASC",
-  },
-})
-```
-
-### Parameters
-
-To sort records by one or more properties, pass to the second object parameter the `order` property. Its value is an object whose keys are the property names, and values can either be:
-
-- `ASC` to sort by this property in the ascending order.
-- `DESC` to sort by this property in the descending order.
-
-### Returns
-
-The method returns an array with two items:
-
-1. The first is an array of the first `15` records retrieved.
-2. The second is the total count of records.
-
-
-# softDelete Method - Service Factory Reference
-
-This method soft deletes one or more records of the data model.
-
-## Soft Delete One Record
-
-```ts
-const deletedPosts = await postModuleService.softDeletePosts(
-  "123"
-)
-```
-
-### Parameters
-
-To soft delete a record, pass its ID as a parameter of the method.
-
-### Returns
-
-The method returns an object, whose keys are of the format `{camel_case_data_model_name}_id`, and their values are arrays of soft-deleted records' IDs.
-
-For example, the returned object of the above example is:
-
-```ts
-deletedPosts = {
-  post_id: ["123"],
-}
-```
-
-***
-
-## Soft Delete Multiple Records
-
-```ts
-const deletedPosts = await postModuleService.softDeletePosts([
-  "123",
-  "321",
-])
-```
-
-### Parameters
-
-To soft delete multiple records, pass an array of IDs as a parameter of the method.
-
-### Returns
-
-The method returns an object, whose keys are of the format `{camel_case_data_model_name}_id`, and their values are arrays of soft-deleted records' IDs.
-
-For example, the returned object of the above example is:
-
-```ts
-deletedPosts = {
-  post_id: [
-    "123",
-    "321",
-  ],
-}
-```
-
-***
-
-## Soft Delete Records Matching Filters
-
-```ts
-const deletedPosts = await postModuleService.softDeletePosts({
-  name: "My Post",
-})
-```
-
-### Parameters
-
-To soft delete records matching a set of filters, pass an object of filters as a parameter.
-
-Learn more about accepted filters in [this documentation](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/service-factory-reference/tips/filtering/index.html.md).
-
-### Returns
-
-The method returns an object, whose keys are of the format `{camel_case_data_model_name}_id`, and their values are arrays of soft-deleted records' IDs.
-
-For example, the returned object of the above example is:
-
-```ts
-deletedPosts = {
-  post_id: ["123"],
-}
-```
-
-
-# update Method - Service Factory Reference
-
-This method updates one or more records of the data model.
-
-## Update One Record
-
-```ts
-const post = await postModuleService.updatePosts({
-  id: "123",
-  name: "My Post",
-})
-```
-
-### Parameters
-
-To update one record, pass an object that at least has an `id` property, identifying the ID of the record to update.
-
-You can pass in the same object any other properties to update.
-
-### Returns
-
-The method returns the updated record as an object.
-
-***
-
-## Update Multiple Records
-
-```ts
-const posts = await postModuleService.updatePosts([
-  {
-    id: "123",
-    name: "My Post",
-  },
-  {
-    id: "321",
-    published_at: new Date(),
-  },
-])
-```
-
-### Parameters
-
-To update multiple records, pass an array of objects. Each object has at least an `id` property, identifying the ID of the record to update.
-
-You can pass in each object any other properties to update.
-
-### Returns
-
-The method returns an array of objects of updated records.
-
-***
-
-## Update Records Matching a Filter
-
-```ts
-const posts = await postModuleService.updatePosts({
-  selector: {
-    name: "My Post",
-  },
-  data: {
-    published_at: new Date(),
-  },
-})
-```
-
-### Parameters
-
-To update records that match specified filters, pass as a parameter an object having two properties:
-
-- `selector`: An object of filters that a record must match to be updated.
-- `data`: An object of the properties to update in every record that match the filters in `selector`.
-
-In the example above, you update the `published_at` property of every post record whose name is `My Post`.
-
-Learn more about accepted filters in [this documentation](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/service-factory-reference/tips/filtering/index.html.md).
-
-### Returns
-
-The method returns an array of objects of updated records.
-
-***
-
-## Multiple Record Updates with Filters
-
-```ts
-const posts = await postModuleService.updatePosts([
-  {
-    selector: {
-      name: "My Post",
-    },
-    data: {
-      published_at: new Date(),
-    },
-  },
-  {
-    selector: {
-      name: "Another Post",
-    },
-    data: {
-      metadata: {
-        external_id: "123",
-      },
-    },
-  },
-])
-```
-
-### Parameters
-
-To update records matching different sets of filters, pass an array of objects, each having two properties:
-
-- `selector`: An object of filters that a record must match to be updated.
-- `data`: An object of the properties to update in every record that match the filters in `selector`.
-
-In the example above, you update the `published_at` property of post records whose name is `My Post`, and update the `metadata` property of post records whose name is `Another Post`.
-
-Learn more about accepted filters in [this documentation](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/service-factory-reference/tips/filtering/index.html.md).
-
-### Returns
-
-The method returns an array of objects of updated records.
-
-
 
 
 <H3 className="!mt-0">Just Getting Started?</H3>
diff --git a/www/apps/resources/app/commerce-modules/fulfillment/concepts/page.mdx b/www/apps/resources/app/commerce-modules/fulfillment/concepts/page.mdx
index 2b5d15c6a3..1721028476 100644
--- a/www/apps/resources/app/commerce-modules/fulfillment/concepts/page.mdx
+++ b/www/apps/resources/app/commerce-modules/fulfillment/concepts/page.mdx
@@ -39,6 +39,12 @@ A service zone is represented by the [ServiceZone data model](/references/fulfil
 
 A service zone can have multiple geographical zones, each represented by the [GeoZone data model](/references/fulfillment/models/GeoZone). It holds location-related details to narrow down supported areas, such as country, city, or province code.
 
+<Note title="Tip">
+
+The province code is always in lower-case and in [ISO 3166-2 format](https://en.wikipedia.org/wiki/ISO_3166-2).
+
+</Note>
+
 ---
 
 ## Shipping Profile
diff --git a/www/apps/resources/app/commerce-modules/fulfillment/shipping-option/page.mdx b/www/apps/resources/app/commerce-modules/fulfillment/shipping-option/page.mdx
index 08b45db2fc..8670524472 100644
--- a/www/apps/resources/app/commerce-modules/fulfillment/shipping-option/page.mdx
+++ b/www/apps/resources/app/commerce-modules/fulfillment/shipping-option/page.mdx
@@ -26,6 +26,12 @@ For example, a fulfillment provider may have a shipping option that can be used
 
 Service zones can be more restrictive, such as restricting to certain cities or province codes.
 
+<Note title="Tip">
+
+The province code is always in lower-case and in [ISO 3166-2 format](https://en.wikipedia.org/wiki/ISO_3166-2).
+
+</Note>
+
 ![A diagram showcasing the relation between shipping options, service zones, and geo zones](https://res.cloudinary.com/dza7lstvk/image/upload/v1712331186/Medusa%20Resources/shipping-option-service-zone-city_m5sxod.jpg)
 
 ---
diff --git a/www/apps/resources/app/storefront-development/products/price/page.mdx b/www/apps/resources/app/storefront-development/products/price/page.mdx
index 60bfc1dc3e..06da618eac 100644
--- a/www/apps/resources/app/storefront-development/products/price/page.mdx
+++ b/www/apps/resources/app/storefront-development/products/price/page.mdx
@@ -56,7 +56,7 @@ You also must pass at least one of the following query parameters to retrieve an
         `province`
       </Table.Cell>
       <Table.Cell>
-        The province, which can be taken from a customer's address. This parameter helps further narrowing down the taxes applied on a the product variant's prices.
+        The lower-case [ISO 3166-2 province code](https://en.wikipedia.org/wiki/ISO_3166-2), which can be taken from a customer's address. This parameter helps further narrowing down the taxes applied on a the product variant's prices.
       </Table.Cell>
     </Table.Row>
     <Table.Row>
diff --git a/www/apps/resources/generated/edit-dates.mjs b/www/apps/resources/generated/edit-dates.mjs
index 7436d3b114..2869644e21 100644
--- a/www/apps/resources/generated/edit-dates.mjs
+++ b/www/apps/resources/generated/edit-dates.mjs
@@ -20,11 +20,11 @@ export const generatedEditDates = {
   "app/commerce-modules/customer/page.mdx": "2025-04-17T08:48:31.918Z",
   "app/commerce-modules/fulfillment/_events/_events-table/page.mdx": "2024-07-03T19:27:13+03:00",
   "app/commerce-modules/fulfillment/_events/page.mdx": "2024-07-03T19:27:13+03:00",
-  "app/commerce-modules/fulfillment/concepts/page.mdx": "2024-06-19T13:02:16+00:00",
+  "app/commerce-modules/fulfillment/concepts/page.mdx": "2025-04-24T09:21:37.616Z",
   "app/commerce-modules/fulfillment/fulfillment-provider/page.mdx": "2025-02-26T11:21:56.242Z",
   "app/commerce-modules/fulfillment/item-fulfillment/page.mdx": "2024-10-08T14:38:15.496Z",
   "app/commerce-modules/fulfillment/module-options/page.mdx": "2024-10-15T12:51:56.118Z",
-  "app/commerce-modules/fulfillment/shipping-option/page.mdx": "2025-04-17T13:51:40.980Z",
+  "app/commerce-modules/fulfillment/shipping-option/page.mdx": "2025-04-24T09:21:52.540Z",
   "app/commerce-modules/fulfillment/page.mdx": "2025-04-17T08:48:19.367Z",
   "app/commerce-modules/inventory/_events/_events-table/page.mdx": "2024-07-03T19:27:13+03:00",
   "app/commerce-modules/inventory/_events/page.mdx": "2024-07-03T19:27:13+03:00",
@@ -168,7 +168,7 @@ export const generatedEditDates = {
   "app/storefront-development/products/price/examples/sale-price/page.mdx": "2025-03-27T14:47:14.308Z",
   "app/storefront-development/products/price/examples/show-price/page.mdx": "2025-03-27T14:47:14.292Z",
   "app/storefront-development/products/price/examples/tax-price/page.mdx": "2025-03-27T14:47:14.292Z",
-  "app/storefront-development/products/price/page.mdx": "2025-03-26T12:08:16.029Z",
+  "app/storefront-development/products/price/page.mdx": "2025-04-24T09:25:43.094Z",
   "app/storefront-development/products/retrieve/page.mdx": "2025-03-27T14:46:51.433Z",
   "app/storefront-development/products/variants/page.mdx": "2025-03-27T14:46:51.576Z",
   "app/storefront-development/products/page.mdx": "2024-06-11T19:55:56+02:00",
diff --git a/www/apps/user-guide/app/settings/tax-regions/page.mdx b/www/apps/user-guide/app/settings/tax-regions/page.mdx
index 9d4a61c1bb..153b3534cd 100644
--- a/www/apps/user-guide/app/settings/tax-regions/page.mdx
+++ b/www/apps/user-guide/app/settings/tax-regions/page.mdx
@@ -150,7 +150,7 @@ To create a sublevel tax region in a tax region:
 2. In the "Sublevels" section or its equivalent (such as States, Province, or Cantons), click the "Create" button.
 3. In the form that opens:
     - If the country supports a sublevel by default, you'll find an input to select a state, province, or canton.
-    - If the country doesn't support a sublevel by default, you'll find an input to enter the ISO 3166-2 code of the sublevel.
+    - If the country doesn't support a sublevel by default, you'll find an input to enter the lower-case [ISO 3166-2 code](https://en.wikipedia.org/wiki/ISO_3166-2) of the sublevel.
     - Under the "Default tax rate" section, you can optionally enter a name, tax rate, and tax code in their respective fields.
     - If the tax region's rates should be combined with the parent's rates, enable the "Combinable" toggle.
 4. Once you're done, click the Save button.
diff --git a/www/utils/generated/oas-output/operations/admin/get_admin_customers_[id]_addresses.ts b/www/utils/generated/oas-output/operations/admin/get_admin_customers_[id]_addresses.ts
index 95c7fc29b9..98b5a46517 100644
--- a/www/utils/generated/oas-output/operations/admin/get_admin_customers_[id]_addresses.ts
+++ b/www/utils/generated/oas-output/operations/admin/get_admin_customers_[id]_addresses.ts
@@ -110,13 +110,21 @@
  *       oneOf:
  *         - type: string
  *           title: province
- *           description: Filter by a province.
+ *           description: Filter by an ISO 3166-2 province code. Must be lower-case.
+ *           example: "us-ca"
+ *           externalDocs:
+ *             url: https://en.wikipedia.org/wiki/ISO_3166-2
+ *             description: Learn more about ISO 3166-2
  *         - type: array
- *           description: Filter by provinces.
+ *           description: Filter by ISO 3166-2 provinces.
  *           items:
  *             type: string
  *             title: province
- *             description: A province code.
+ *             description: A ISO 3166-2 province code. Must be lower-case.
+ *             example: "us-ca"
+ *             externalDocs:
+ *               url: https://en.wikipedia.org/wiki/ISO_3166-2
+ *               description: Learn more about ISO 3166-2
  *   - name: postal_code
  *     in: query
  *     required: false
diff --git a/www/utils/generated/oas-output/operations/admin/get_admin_tax-regions.ts b/www/utils/generated/oas-output/operations/admin/get_admin_tax-regions.ts
index ba6a442904..67dfc83033 100644
--- a/www/utils/generated/oas-output/operations/admin/get_admin_tax-regions.ts
+++ b/www/utils/generated/oas-output/operations/admin/get_admin_tax-regions.ts
@@ -133,13 +133,21 @@
  *       oneOf:
  *         - type: string
  *           title: province_code
- *           description: Filter by a province code.
+ *           description: Filter by a ISO 3166-2 province code. Must be lower-case.
+ *           example: "us-ca"
+ *           externalDocs:
+ *             url: https://en.wikipedia.org/wiki/ISO_3166-2
+ *             description: Learn more about ISO 3166-2
  *         - type: array
- *           description: Filter by province codes.
+ *           description: Filter by ISO 3166-2 province codes.
  *           items:
  *             type: string
  *             title: province_code
- *             description: A province code.
+ *             description: A ISO 3166-2 province code.
+ *             example: "us-ca"
+ *             externalDocs:
+ *               url: https://en.wikipedia.org/wiki/ISO_3166-2
+ *               description: Learn more about ISO 3166-2
  *         - type: object
  *           description: Apply filters on the province code.
  *           properties:
diff --git a/www/utils/generated/oas-output/operations/admin/post_admin_customers_[id]_addresses.ts b/www/utils/generated/oas-output/operations/admin/post_admin_customers_[id]_addresses.ts
index 4d9efa2f6a..af25f9f126 100644
--- a/www/utils/generated/oas-output/operations/admin/post_admin_customers_[id]_addresses.ts
+++ b/www/utils/generated/oas-output/operations/admin/post_admin_customers_[id]_addresses.ts
@@ -94,7 +94,11 @@
  *               province:
  *                 type: string
  *                 title: province
- *                 description: The address's province.
+ *                 description: The address's ISO 3166-2 province code. Must be lower-case.
+ *                 example: "us-ca"
+ *                 externalDocs:
+ *                   url: https://en.wikipedia.org/wiki/ISO_3166-2
+ *                   description: Learn more about ISO 3166-2
  *               postal_code:
  *                 type: string
  *                 title: postal_code
@@ -151,7 +155,7 @@
  *         "address_2": "{value}",
  *         "city": "{value}",
  *         "country_code": "{value}",
- *         "province": "{value}",
+ *         "province": "us-ca",
  *         "postal_code": "{value}",
  *         "phone": "{value}",
  *         "metadata": {}
diff --git a/www/utils/generated/oas-output/operations/admin/post_admin_customers_[id]_addresses_[address_id].ts b/www/utils/generated/oas-output/operations/admin/post_admin_customers_[id]_addresses_[address_id].ts
index 0d6cd20376..2e5f168a7a 100644
--- a/www/utils/generated/oas-output/operations/admin/post_admin_customers_[id]_addresses_[address_id].ts
+++ b/www/utils/generated/oas-output/operations/admin/post_admin_customers_[id]_addresses_[address_id].ts
@@ -100,7 +100,11 @@
  *               province:
  *                 type: string
  *                 title: province
- *                 description: The address's province.
+ *                 description: The address's ISO 3166-2 province code. Must be lower-case.
+ *                 example: "us-ca"
+ *                 externalDocs:
+ *                   url: https://en.wikipedia.org/wiki/ISO_3166-2
+ *                   description: Learn more about ISO 3166-2
  *               postal_code:
  *                 type: string
  *                 title: postal_code
diff --git a/www/utils/generated/oas-output/operations/admin/post_admin_draft-orders.ts b/www/utils/generated/oas-output/operations/admin/post_admin_draft-orders.ts
index f1ed63c595..00c386aab3 100644
--- a/www/utils/generated/oas-output/operations/admin/post_admin_draft-orders.ts
+++ b/www/utils/generated/oas-output/operations/admin/post_admin_draft-orders.ts
@@ -107,7 +107,11 @@
  *                   province:
  *                     type: string
  *                     title: province
- *                     description: The billing address's province.
+ *                     description: The billing address's ISO 3166-2 province code. Must be lower-case.
+ *                     example: "us-ca"
+ *                     externalDocs:
+ *                       url: https://en.wikipedia.org/wiki/ISO_3166-2
+ *                       description: Learn more about ISO 3166-2
  *                   postal_code:
  *                     type: string
  *                     title: postal_code
@@ -166,7 +170,11 @@
  *                   province:
  *                     type: string
  *                     title: province
- *                     description: The shipping address's province.
+ *                     description: The shipping address's ISO 3166-2 province code. Must be lower-case.
+ *                     example: "us-ca"
+ *                     externalDocs:
+ *                       url: https://en.wikipedia.org/wiki/ISO_3166-2
+ *                       description: Learn more about ISO 3166-2
  *                   postal_code:
  *                     type: string
  *                     title: postal_code
diff --git a/www/utils/generated/oas-output/operations/admin/post_admin_fulfillment-sets_[id]_service-zones.ts b/www/utils/generated/oas-output/operations/admin/post_admin_fulfillment-sets_[id]_service-zones.ts
index a09b11cd1c..a8b4fec005 100644
--- a/www/utils/generated/oas-output/operations/admin/post_admin_fulfillment-sets_[id]_service-zones.ts
+++ b/www/utils/generated/oas-output/operations/admin/post_admin_fulfillment-sets_[id]_service-zones.ts
@@ -88,7 +88,11 @@
  *                     province_code:
  *                       type: string
  *                       title: province_code
- *                       description: The geo zone's province code.
+ *                       description: The geo zone's ISO 3166-2 province code. Must be lower-case.
+ *                       example: "us-ca"
+ *                       externalDocs:
+ *                         url: https://en.wikipedia.org/wiki/ISO_3166-2
+ *                         description: Learn more about ISO 3166-2
  *                 - type: object
  *                   description: A city geo zone
  *                   required:
@@ -113,7 +117,11 @@
  *                     province_code:
  *                       type: string
  *                       title: province_code
- *                       description: The geo zone's province code.
+ *                       description: The geo zone's ISO 3166-2 province code. Must be lower-case.
+ *                       example: "us-ca"
+ *                       externalDocs:
+ *                         url: https://en.wikipedia.org/wiki/ISO_3166-2
+ *                         description: Learn more about ISO 3166-2
  *                     city:
  *                       type: string
  *                       title: city
@@ -143,7 +151,11 @@
  *                     province_code:
  *                       type: string
  *                       title: province_code
- *                       description: The geo zone's province code.
+ *                       description: The geo zone's ISO 3166-2 province code. Must be lower-case.
+ *                       example: "us-ca"
+ *                       externalDocs:
+ *                         url: https://en.wikipedia.org/wiki/ISO_3166-2
+ *                         description: Learn more about ISO 3166-2
  *                     city:
  *                       type: string
  *                       title: city
diff --git a/www/utils/generated/oas-output/operations/admin/post_admin_fulfillment-sets_[id]_service-zones_[zone_id].ts b/www/utils/generated/oas-output/operations/admin/post_admin_fulfillment-sets_[id]_service-zones_[zone_id].ts
index 331af09f79..144756db6f 100644
--- a/www/utils/generated/oas-output/operations/admin/post_admin_fulfillment-sets_[id]_service-zones_[zone_id].ts
+++ b/www/utils/generated/oas-output/operations/admin/post_admin_fulfillment-sets_[id]_service-zones_[zone_id].ts
@@ -96,7 +96,11 @@
  *                     province_code:
  *                       type: string
  *                       title: province_code
- *                       description: The geo zone's province code.
+ *                       description: The geo zone's ISO 3166-2 province code. Must be lower-case.
+ *                       example: "us-ca"
+ *                       externalDocs:
+ *                         url: https://en.wikipedia.org/wiki/ISO_3166-2
+ *                         description: Learn more about ISO 3166-2
  *                     id:
  *                       type: string
  *                       title: id
@@ -129,7 +133,11 @@
  *                     province_code:
  *                       type: string
  *                       title: province_code
- *                       description: The geo zone's province code.
+ *                       description: The geo zone's ISO 3166-2 province code. Must be lower-case.
+ *                       example: "us-ca"
+ *                       externalDocs:
+ *                         url: https://en.wikipedia.org/wiki/ISO_3166-2
+ *                         description: Learn more about ISO 3166-2
  *                     id:
  *                       type: string
  *                       title: id
@@ -163,7 +171,11 @@
  *                     province_code:
  *                       type: string
  *                       title: province_code
- *                       description: The geo zone's province code.
+ *                       description: The geo zone's ISO 3166-2 province code. Must be lower-case.
+ *                       example: "us-ca"
+ *                       externalDocs:
+ *                         url: https://en.wikipedia.org/wiki/ISO_3166-2
+ *                         description: Learn more about ISO 3166-2
  *                     postal_expression:
  *                       type: object
  *                       description: The geo zone's postal expression or ZIP code.
diff --git a/www/utils/generated/oas-output/operations/admin/post_admin_fulfillments.ts b/www/utils/generated/oas-output/operations/admin/post_admin_fulfillments.ts
index 67c84c69fc..d898f73ae9 100644
--- a/www/utils/generated/oas-output/operations/admin/post_admin_fulfillments.ts
+++ b/www/utils/generated/oas-output/operations/admin/post_admin_fulfillments.ts
@@ -79,7 +79,7 @@
  *           "address_2": "{value}",
  *           "city": "{value}",
  *           "country_code": "{value}",
- *           "province": "{value}",
+ *           "province": "us-ca",
  *           "postal_code": "{value}",
  *           "metadata": {}
  *         },
diff --git a/www/utils/generated/oas-output/operations/admin/post_admin_tax-regions.ts b/www/utils/generated/oas-output/operations/admin/post_admin_tax-regions.ts
index fbae3caf57..faea50b653 100644
--- a/www/utils/generated/oas-output/operations/admin/post_admin_tax-regions.ts
+++ b/www/utils/generated/oas-output/operations/admin/post_admin_tax-regions.ts
@@ -42,7 +42,7 @@
  * 
  *       sdk.admin.taxRegion.create({
  *         country_code: "us",
- *         province_code: "ca",
+ *         province_code: "us-ca",
  *         default_tax_rate: {
  *           code: "VAT",
  *           name: "VAT",
@@ -61,7 +61,7 @@
  *       -H 'Content-Type: application/json' \
  *       --data-raw '{
  *         "country_code": "{value}",
- *         "province_code": "{value}",
+ *         "province_code": "us-ca",
  *         "parent_id": "{value}",
  *         "metadata": {}
  *       }'
diff --git a/www/utils/generated/oas-output/operations/store/get_store_products.ts b/www/utils/generated/oas-output/operations/store/get_store_products.ts
index 7a5f6ea2ef..d687731019 100644
--- a/www/utils/generated/oas-output/operations/store/get_store_products.ts
+++ b/www/utils/generated/oas-output/operations/store/get_store_products.ts
@@ -654,12 +654,16 @@
  *         description: "Storefront guide: How to show product variants' prices with taxes."
  *   - name: province
  *     in: query
- *     description: The province the products are being viewed from. This is useful to narrow down the tax context when calculating product variant prices with taxes.
+ *     description: The lower-case ISO 3166-2 province code the products are being viewed from. This is useful to narrow down the tax context when calculating product variant prices with taxes.
  *     required: false
  *     schema:
  *       type: string
  *       title: province
- *       description: The province the products are being viewed from. This is useful to narrow down the tax context when calculating product variant prices with taxes.
+ *       description: The lower-case ISO 3166-2 province code the products are being viewed from. This is useful to narrow down the tax context when calculating product variant prices with taxes.
+ *       example: "us-ca"
+ *       externalDocs:
+ *         url: https://en.wikipedia.org/wiki/ISO_3166-2
+ *         description: Learn more about ISO 3166-2
  *   - name: sales_channel_id
  *     in: query
  *     required: false
diff --git a/www/utils/generated/oas-output/operations/store/get_store_products_[id].ts b/www/utils/generated/oas-output/operations/store/get_store_products_[id].ts
index d40ed906cb..b3d5e52dba 100644
--- a/www/utils/generated/oas-output/operations/store/get_store_products_[id].ts
+++ b/www/utils/generated/oas-output/operations/store/get_store_products_[id].ts
@@ -55,12 +55,16 @@
  *       description: The country code the product is being viewed from. This is required if you're retrieving product variant prices with taxes.
  *   - name: province
  *     in: query
- *     description: The province the product is being viewed from. This is useful to narrow down the tax context when calculating product variant prices with taxes.
+ *     description: The lower-case ISO 3166-2 province code the product is being viewed from. This is useful to narrow down the tax context when calculating product variant prices with taxes.
  *     required: false
  *     schema:
  *       type: string
  *       title: province
- *       description: The province the product is being viewed from. This is useful to narrow down the tax context when calculating product variant prices with taxes.
+ *       description: The lower-case ISO 3166-2 province code the product is being viewed from. This is useful to narrow down the tax context when calculating product variant prices with taxes.
+ *       example: "us-ca"
+ *       externalDocs:
+ *         url: https://en.wikipedia.org/wiki/ISO_3166-2
+ *         description: Learn more about ISO 3166-2
  *   - name: cart_id
  *     in: query
  *     description: The ID of the customer's cart. If set, the cart's region and shipping address's country code and province are used instead of the `region_id`, `country_code`, and `province` properties.
diff --git a/www/utils/generated/oas-output/operations/store/post_store_customers_me_addresses.ts b/www/utils/generated/oas-output/operations/store/post_store_customers_me_addresses.ts
index af5ae1e3f3..adf56a1fcb 100644
--- a/www/utils/generated/oas-output/operations/store/post_store_customers_me_addresses.ts
+++ b/www/utils/generated/oas-output/operations/store/post_store_customers_me_addresses.ts
@@ -76,7 +76,11 @@
  *           province:
  *             type: string
  *             title: province
- *             description: The address's province.
+ *             description: The address's ISO 3166-2 province code. Must be lower-case.
+ *             example: "us-ca"
+ *             externalDocs:
+ *               url: https://en.wikipedia.org/wiki/ISO_3166-2
+ *               description: Learn more about ISO 3166-2
  *           postal_code:
  *             type: string
  *             title: postal_code
@@ -137,7 +141,7 @@
  *         "address_2": "{value}",
  *         "city": "{value}",
  *         "country_code": "{value}",
- *         "province": "{value}",
+ *         "province": "us-ca",
  *         "postal_code": "{value}",
  *         "address_name": "{value}"
  *       }'
diff --git a/www/utils/generated/oas-output/operations/store/post_store_customers_me_addresses_[address_id].ts b/www/utils/generated/oas-output/operations/store/post_store_customers_me_addresses_[address_id].ts
index 9d1e780431..1db9459fef 100644
--- a/www/utils/generated/oas-output/operations/store/post_store_customers_me_addresses_[address_id].ts
+++ b/www/utils/generated/oas-output/operations/store/post_store_customers_me_addresses_[address_id].ts
@@ -82,7 +82,11 @@
  *           province:
  *             type: string
  *             title: province
- *             description: The address's province.
+ *             description: The address's ISO 3166-2 province code. Must be lower-case.
+ *             example: "us-ca"
+ *             externalDocs:
+ *               url: https://en.wikipedia.org/wiki/ISO_3166-2
+ *               description: Learn more about ISO 3166-2
  *           postal_code:
  *             type: string
  *             title: postal_code
diff --git a/www/utils/generated/oas-output/schemas/AdminCreateFulfillment.ts b/www/utils/generated/oas-output/schemas/AdminCreateFulfillment.ts
index 7f7cb831e1..ab7876e7e5 100644
--- a/www/utils/generated/oas-output/schemas/AdminCreateFulfillment.ts
+++ b/www/utils/generated/oas-output/schemas/AdminCreateFulfillment.ts
@@ -60,7 +60,11 @@
  *       province:
  *         type: string
  *         title: province
- *         description: The delivery address's province.
+ *         description: The delivery address's ISO 3166-2 province code. Must be lower-case.
+ *         example: "us-ca"
+ *         externalDocs:
+ *           url: https://en.wikipedia.org/wiki/ISO_3166-2
+ *           description: Learn more about ISO 3166-2
  *       postal_code:
  *         type: string
  *         title: postal_code
diff --git a/www/utils/generated/oas-output/schemas/AdminCreateTaxRegion.ts b/www/utils/generated/oas-output/schemas/AdminCreateTaxRegion.ts
index 33caed8c48..4e71514c31 100644
--- a/www/utils/generated/oas-output/schemas/AdminCreateTaxRegion.ts
+++ b/www/utils/generated/oas-output/schemas/AdminCreateTaxRegion.ts
@@ -14,7 +14,11 @@
  *   province_code:
  *     type: string
  *     title: province_code
- *     description: The tax region's province code.
+ *     description: The tax region's ISO 3166-2 province code. Must be lower-case.
+ *     example: "us-ca"
+ *     externalDocs:
+ *       url: https://en.wikipedia.org/wiki/ISO_3166-2
+ *       description: Learn more about ISO 3166-2
  *   parent_id:
  *     type: string
  *     title: parent_id
diff --git a/www/utils/generated/oas-output/schemas/AdminCustomerAddress.ts b/www/utils/generated/oas-output/schemas/AdminCustomerAddress.ts
index 4ef272f38a..576584c04a 100644
--- a/www/utils/generated/oas-output/schemas/AdminCustomerAddress.ts
+++ b/www/utils/generated/oas-output/schemas/AdminCustomerAddress.ts
@@ -75,7 +75,11 @@
  *   province:
  *     type: string
  *     title: province
- *     description: The address's province.
+ *     description: The address's lower-case ISO 3166-2 province code.
+ *     example: "us-ca"
+ *     externalDocs:
+ *       url: https://en.wikipedia.org/wiki/ISO_3166-2
+ *       description: Learn more about ISO 3166-2
  *   postal_code:
  *     type: string
  *     title: postal_code
diff --git a/www/utils/generated/oas-output/schemas/AdminFulfillmentAddress.ts b/www/utils/generated/oas-output/schemas/AdminFulfillmentAddress.ts
index ead5df0e92..f542d27224 100644
--- a/www/utils/generated/oas-output/schemas/AdminFulfillmentAddress.ts
+++ b/www/utils/generated/oas-output/schemas/AdminFulfillmentAddress.ts
@@ -60,7 +60,11 @@
  *   province:
  *     type: string
  *     title: province
- *     description: The address's province.
+ *     description: The address's lower-case ISO 3166-2 province code.
+ *     example: "us-ca"
+ *     externalDocs:
+ *       url: https://en.wikipedia.org/wiki/ISO_3166-2
+ *       description: Learn more about ISO 3166-2
  *   postal_code:
  *     type: string
  *     title: postal_code
diff --git a/www/utils/generated/oas-output/schemas/AdminGeoZone.ts b/www/utils/generated/oas-output/schemas/AdminGeoZone.ts
index 3e9b55aa98..9ba0067f31 100644
--- a/www/utils/generated/oas-output/schemas/AdminGeoZone.ts
+++ b/www/utils/generated/oas-output/schemas/AdminGeoZone.ts
@@ -33,7 +33,11 @@
  *   province_code:
  *     type: string
  *     title: province_code
- *     description: The geo zone's province code.
+ *     description: The geo zone's lower-case ISO 3166-2 province code.
+ *     example: "us-ca"
+ *     externalDocs:
+ *       url: https://en.wikipedia.org/wiki/ISO_3166-2
+ *       description: Learn more about ISO 3166-2
  *   city:
  *     type: string
  *     title: city
diff --git a/www/utils/generated/oas-output/schemas/AdminOrderAddress.ts b/www/utils/generated/oas-output/schemas/AdminOrderAddress.ts
index 2582c46e43..c254cd2954 100644
--- a/www/utils/generated/oas-output/schemas/AdminOrderAddress.ts
+++ b/www/utils/generated/oas-output/schemas/AdminOrderAddress.ts
@@ -55,7 +55,11 @@
  *   province:
  *     type: string
  *     title: province
- *     description: The address's province.
+ *     description: The address's lower-case ISO 3166-2 province code.
+ *     example: "us-ca"
+ *     externalDocs:
+ *       url: https://en.wikipedia.org/wiki/ISO_3166-2
+ *       description: Learn more about ISO 3166-2
  *   postal_code:
  *     type: string
  *     title: postal_code
diff --git a/www/utils/generated/oas-output/schemas/AdminStockLocationAddress.ts b/www/utils/generated/oas-output/schemas/AdminStockLocationAddress.ts
index 4917c534eb..c47ce9e6bf 100644
--- a/www/utils/generated/oas-output/schemas/AdminStockLocationAddress.ts
+++ b/www/utils/generated/oas-output/schemas/AdminStockLocationAddress.ts
@@ -40,7 +40,11 @@
  *   province:
  *     type: string
  *     title: province
- *     description: The address's province.
+ *     description: The address's lower-case ISO 3166-2 province code.
+ *     example: "us-ca"
+ *     externalDocs:
+ *       url: https://en.wikipedia.org/wiki/ISO_3166-2
+ *       description: Learn more about ISO 3166-2
  * required:
  *   - id
  *   - address_1
diff --git a/www/utils/generated/oas-output/schemas/AdminTaxRegion.ts b/www/utils/generated/oas-output/schemas/AdminTaxRegion.ts
index 18976c9491..12bd569868 100644
--- a/www/utils/generated/oas-output/schemas/AdminTaxRegion.ts
+++ b/www/utils/generated/oas-output/schemas/AdminTaxRegion.ts
@@ -29,7 +29,11 @@
  *   province_code:
  *     type: string
  *     title: province_code
- *     description: The tax region's province code.
+ *     description: The tax region's lower-case ISO 3166-2 province code.
+ *     example: "us-ca"
+ *     externalDocs:
+ *       url: https://en.wikipedia.org/wiki/ISO_3166-2
+ *       description: Learn more about ISO 3166-2
  *   metadata:
  *     type: object
  *     description: The tax region's metadata, can hold custom key-value pairs.
diff --git a/www/utils/generated/oas-output/schemas/AdminUpdateDraftOrder.ts b/www/utils/generated/oas-output/schemas/AdminUpdateDraftOrder.ts
index 34057ddd0a..c304160318 100644
--- a/www/utils/generated/oas-output/schemas/AdminUpdateDraftOrder.ts
+++ b/www/utils/generated/oas-output/schemas/AdminUpdateDraftOrder.ts
@@ -49,7 +49,11 @@
  *       province:
  *         type: string
  *         title: province
- *         description: The shipping address's province.
+ *         description: The shipping address's ISO 3166-2 province code. Must be lower-case.
+ *         example: "us-ca"
+ *         externalDocs:
+ *           url: https://en.wikipedia.org/wiki/ISO_3166-2
+ *           description: Learn more about ISO 3166-2
  *       postal_code:
  *         type: string
  *         title: postal_code
@@ -97,7 +101,11 @@
  *       province:
  *         type: string
  *         title: province
- *         description: The billing address's province.
+ *         description: The billing address's ISO 3166-2 province code. Must be lower-case.
+ *         example: "us-ca"
+ *         externalDocs:
+ *           url: https://en.wikipedia.org/wiki/ISO_3166-2
+ *           description: Learn more about ISO 3166-2
  *       postal_code:
  *         type: string
  *         title: postal_code
diff --git a/www/utils/generated/oas-output/schemas/AdminUpdateOrder.ts b/www/utils/generated/oas-output/schemas/AdminUpdateOrder.ts
index fc2eb6ab4c..e5c41b9c77 100644
--- a/www/utils/generated/oas-output/schemas/AdminUpdateOrder.ts
+++ b/www/utils/generated/oas-output/schemas/AdminUpdateOrder.ts
@@ -49,7 +49,11 @@
  *       province:
  *         type: string
  *         title: province
- *         description: The address's province.
+ *         description: The address's ISO 3166-2 province code. Must be lower-case.
+ *         example: "us-ca"
+ *         externalDocs:
+ *           url: https://en.wikipedia.org/wiki/ISO_3166-2
+ *           description: Learn more about ISO 3166-2
  *       postal_code:
  *         type: string
  *         title: postal_code
@@ -97,7 +101,11 @@
  *       province:
  *         type: string
  *         title: province
- *         description: The address's province.
+ *         description: The address's ISO 3166-2 province code. Must be lower-case.
+ *         example: "us-ca"
+ *         externalDocs:
+ *           url: https://en.wikipedia.org/wiki/ISO_3166-2
+ *           description: Learn more about ISO 3166-2
  *       postal_code:
  *         type: string
  *         title: postal_code
diff --git a/www/utils/generated/oas-output/schemas/AdminUpdateStockLocation.ts b/www/utils/generated/oas-output/schemas/AdminUpdateStockLocation.ts
index 7b5850c6c0..9a58b5e005 100644
--- a/www/utils/generated/oas-output/schemas/AdminUpdateStockLocation.ts
+++ b/www/utils/generated/oas-output/schemas/AdminUpdateStockLocation.ts
@@ -47,7 +47,11 @@
  *       province:
  *         type: string
  *         title: province
- *         description: The address's province.
+ *         description: The address's ISO 3166-2 province code. Must be lower-case.
+ *         example: "us-ca"
+ *         externalDocs:
+ *           url: https://en.wikipedia.org/wiki/ISO_3166-2
+ *           description: Learn more about ISO 3166-2
  *   address_id:
  *     type: string
  *     title: address_id
diff --git a/www/utils/generated/oas-output/schemas/AdminUpdateTaxRegion.ts b/www/utils/generated/oas-output/schemas/AdminUpdateTaxRegion.ts
index e400ee58b9..1960232917 100644
--- a/www/utils/generated/oas-output/schemas/AdminUpdateTaxRegion.ts
+++ b/www/utils/generated/oas-output/schemas/AdminUpdateTaxRegion.ts
@@ -7,7 +7,11 @@
  *   province_code:
  *     type: string
  *     title: province_code
- *     description: The tax region's province code.
+ *     description: The tax region's ISO 3166-2 province code. Must be lower-case.
+ *     example: "us-ca"
+ *     externalDocs:
+ *       url: https://en.wikipedia.org/wiki/ISO_3166-2
+ *       description: Learn more about ISO 3166-2
  *   metadata:
  *     type: object
  *     description: The tax region's metadata, can hold custom key-value pairs.
diff --git a/www/utils/generated/oas-output/schemas/AdminUpsertStockLocationAddress.ts b/www/utils/generated/oas-output/schemas/AdminUpsertStockLocationAddress.ts
index 152b141952..e094d06267 100644
--- a/www/utils/generated/oas-output/schemas/AdminUpsertStockLocationAddress.ts
+++ b/www/utils/generated/oas-output/schemas/AdminUpsertStockLocationAddress.ts
@@ -39,7 +39,11 @@
  *   province:
  *     type: string
  *     title: province
- *     description: The address's province.
+ *     description: The address's ISO 3166-2 province code. Must be lower-case.
+ *     example: "us-ca"
+ *     externalDocs:
+ *       url: https://en.wikipedia.org/wiki/ISO_3166-2
+ *       description: Learn more about ISO 3166-2
  * 
 */
 
diff --git a/www/utils/generated/oas-output/schemas/BaseOrderAddress.ts b/www/utils/generated/oas-output/schemas/BaseOrderAddress.ts
index b1b136f743..69dfe6f1a7 100644
--- a/www/utils/generated/oas-output/schemas/BaseOrderAddress.ts
+++ b/www/utils/generated/oas-output/schemas/BaseOrderAddress.ts
@@ -53,7 +53,11 @@
  *   province:
  *     type: string
  *     title: province
- *     description: The address's province.
+ *     description: The address's lower-case ISO 3166-2 province code.
+ *     example: "US-CA"
+ *     externalDocs:
+ *       url: https://en.wikipedia.org/wiki/ISO_3166-2
+ *       description: Learn more about ISO 3166-2
  *   postal_code:
  *     type: string
  *     title: postal_code
diff --git a/www/utils/generated/oas-output/schemas/CreateAddress.ts b/www/utils/generated/oas-output/schemas/CreateAddress.ts
index 988ac9cc66..c893b059e0 100644
--- a/www/utils/generated/oas-output/schemas/CreateAddress.ts
+++ b/www/utils/generated/oas-output/schemas/CreateAddress.ts
@@ -40,7 +40,11 @@
  *   province:
  *     type: string
  *     title: province
- *     description: The address's province.
+ *     description: The address's ISO 3166-2 province code. Must be lower-case.
+ *     example: "us-ca"
+ *     externalDocs:
+ *       url: https://en.wikipedia.org/wiki/ISO_3166-2
+ *       description: Learn more about ISO 3166-2
  *   postal_code:
  *     type: string
  *     title: postal_code
diff --git a/www/utils/generated/oas-output/schemas/OrderAddress.ts b/www/utils/generated/oas-output/schemas/OrderAddress.ts
index 5f063aaf7b..ac66527a55 100644
--- a/www/utils/generated/oas-output/schemas/OrderAddress.ts
+++ b/www/utils/generated/oas-output/schemas/OrderAddress.ts
@@ -52,7 +52,11 @@
  *   province:
  *     type: string
  *     title: province
- *     description: The address's province.
+ *     description: The address's lower-case ISO 3166-2 province code.
+ *     example: "us-ca"
+ *     externalDocs:
+ *       url: https://en.wikipedia.org/wiki/ISO_3166-2
+ *       description: Learn more about ISO 3166-2
  *   postal_code:
  *     type: string
  *     title: postal_code
diff --git a/www/utils/generated/oas-output/schemas/StoreCartAddress.ts b/www/utils/generated/oas-output/schemas/StoreCartAddress.ts
index 30315c091f..b6ed549187 100644
--- a/www/utils/generated/oas-output/schemas/StoreCartAddress.ts
+++ b/www/utils/generated/oas-output/schemas/StoreCartAddress.ts
@@ -52,7 +52,11 @@
  *   province:
  *     type: string
  *     title: province
- *     description: The address's province.
+ *     description: The address's lower-case ISO 3166-2 province code.
+ *     example: "us-ca"
+ *     externalDocs:
+ *       url: https://en.wikipedia.org/wiki/ISO_3166-2
+ *       description: Learn more about ISO 3166-2
  *   postal_code:
  *     type: string
  *     title: postal_code
diff --git a/www/utils/generated/oas-output/schemas/StoreCustomerAddress.ts b/www/utils/generated/oas-output/schemas/StoreCustomerAddress.ts
index efdf6120d7..70236c0311 100644
--- a/www/utils/generated/oas-output/schemas/StoreCustomerAddress.ts
+++ b/www/utils/generated/oas-output/schemas/StoreCustomerAddress.ts
@@ -75,7 +75,11 @@
  *   province:
  *     type: string
  *     title: province
- *     description: The address's province.
+ *     description: The address's lower-case ISO 3166-2 province code.
+ *     example: "us-ca"
+ *     externalDocs:
+ *       url: https://en.wikipedia.org/wiki/ISO_3166-2
+ *       description: Learn more about ISO 3166-2
  *   postal_code:
  *     type: string
  *     title: postal_code
diff --git a/www/utils/generated/oas-output/schemas/StoreOrderAddress.ts b/www/utils/generated/oas-output/schemas/StoreOrderAddress.ts
index 077d8756c7..b45a54054a 100644
--- a/www/utils/generated/oas-output/schemas/StoreOrderAddress.ts
+++ b/www/utils/generated/oas-output/schemas/StoreOrderAddress.ts
@@ -55,7 +55,11 @@
  *   province:
  *     type: string
  *     title: province
- *     description: The address's province.
+ *     description: The address's lower-case ISO 3166-2 province code.
+ *     example: "us-ca"
+ *     externalDocs:
+ *       url: https://en.wikipedia.org/wiki/ISO_3166-2
+ *       description: Learn more about ISO 3166-2
  *   postal_code:
  *     type: string
  *     title: postal_code
diff --git a/www/utils/generated/oas-output/schemas/UpdateAddress.ts b/www/utils/generated/oas-output/schemas/UpdateAddress.ts
index 61fbf9f35c..55b16a1eb5 100644
--- a/www/utils/generated/oas-output/schemas/UpdateAddress.ts
+++ b/www/utils/generated/oas-output/schemas/UpdateAddress.ts
@@ -46,7 +46,11 @@
  *   province:
  *     type: string
  *     title: province
- *     description: The address's province.
+ *     description: The address's ISO 3166-2 province code. Must be lower-case.
+ *     example: "us-ca"
+ *     externalDocs:
+ *       url: https://en.wikipedia.org/wiki/ISO_3166-2
+ *       description: Learn more about ISO 3166-2
  *   postal_code:
  *     type: string
  *     title: postal_code