diff --git a/www/apps/book/public/llms-full.txt b/www/apps/book/public/llms-full.txt
index 34aa3befa6..ea98ea67c2 100644
--- a/www/apps/book/public/llms-full.txt
+++ b/www/apps/book/public/llms-full.txt
@@ -473,6 +473,135 @@ npm  install
 ```
 
 
+# Build Custom Features
+
+In the upcoming chapters, you'll follow step-by-step guides to build custom features in Medusa. These guides gradually introduce Medusa's concepts to help you understand what they are and how to use them.
+
+By following these guides, you'll add brands to the Medusa application that you can associate with products.
+
+To build a custom feature in Medusa, you need three main tools:
+
+- [Module](https://docs.medusajs.com/learn/fundamentals/modules/index.html.md): a package with commerce logic for a single domain. It defines new tables to add to the database, and a class of methods to manage these tables.
+- [Workflow](https://docs.medusajs.com/learn/fundamentals/workflows/index.html.md): a tool to perform an operation comprising multiple steps with built-in rollback and retry mechanisms.
+- [API route](https://docs.medusajs.com/learn/fundamentals/api-routes/index.html.md): a REST endpoint that exposes commerce features to clients, such as the admin dashboard or a storefront. The API route executes a workflow that implements the commerce feature using modules.
+
+![Diagram showcasing the flow of a custom developed feature](https://res.cloudinary.com/dza7lstvk/image/upload/v1725867628/Medusa%20Book/custom-development_nofvp6.jpg)
+
+***
+
+## Next Chapters: Brand Module Example
+
+The next chapters will guide you to:
+
+1. Build a Brand Module that creates a `Brand` data model and provides data-management features.
+2. Add a workflow to create a brand.
+3. Expose an API route that allows admin users to create a brand using the workflow.
+
+
+# Customize Medusa Admin Dashboard
+
+In the previous chapters, you've customized your Medusa application to [add brands](https://docs.medusajs.com/learn/customization/custom-features/module/index.html.md), [expose an API route to create brands](https://docs.medusajs.com/learn/customization/custom-features/api-route/index.html.md), and [linked brands to products](https://docs.medusajs.com/learn/customization/extend-features/define-link/index.html.md).
+
+After customizing and extending your application with new features, you may need to provide an interface for admin users to utilize these features. The Medusa Admin dashboard is extendable, allowing you to:
+
+- Insert components, called [widgets](https://docs.medusajs.com/learn/fundamentals/admin/widgets/index.html.md), on existing pages.
+- Add new pages, called [UI Routes](https://docs.medusajs.com/learn/fundamentals/admin/ui-routes/index.html.md).
+
+From these customizations, you can send requests to custom API routes, allowing admin users to manage custom resources on the dashboard
+
+***
+
+## Next Chapters: View Brands in Dashboard
+
+In the next chapters, you'll continue with the brands example to:
+
+- Add a new section to the product details page that shows the product's brand.
+- Add a new page in the dashboard that shows all brands in the store.
+
+
+# Integrate Third-Party Systems
+
+Commerce applications often connect to third-party systems that provide additional or specialized features. For example, you may integrate a Content-Management System (CMS) for rich content features, a payment provider to process credit-card payments, and a notification service to send emails.
+
+The Medusa Framework facilitates integrating these systems and orchestrating operations across them, saving you the effort of managing them yourself. You won't find those capabilities in other commerce platforms that in these scenarios become a bottleneck to building customizations and iterating quickly.
+
+In Medusa, you integrate a third-party system by:
+
+1. Creating a module whose service provides the methods to connect to and perform operations in the third-party system.
+2. Building workflows that complete tasks spanning across systems. You use the module that integrates a third-party system in the workflow's steps.
+3. Executing the workflows you built in an [API route](https://docs.medusajs.com/learn/fundamentals/api-routes/index.html.md), at a scheduled time, or when an event is emitted.
+
+***
+
+## Next Chapters: Sync Brands Example
+
+In the previous chapters, you've [added brands](https://docs.medusajs.com/learn/customization/custom-features/module/index.html.md) to your Medusa application. In the next chapters, you will:
+
+1. Integrate a dummy third-party CMS in the Brand Module.
+2. Sync brands to the CMS when a brand is created.
+3. Sync brands from the CMS at a daily schedule.
+
+
+# Extend Core Commerce Features
+
+In the upcoming chapters, you'll learn about the concepts and tools to extend Medusa's core commerce features.
+
+In other commerce platforms, you extend core features and models through hacky workarounds that can introduce unexpected issues and side effects across the platform. It also makes your application difficult to maintain and upgrade in the long run.
+
+The Medusa Framework and orchestration tools mitigate these issues while supporting all your customization needs:
+
+- [Module Links](https://docs.medusajs.com/learn/fundamentals/module-links/index.html.md): Link data models of different modules without building direct dependencies, ensuring that the Medusa application integrates your modules without side effects.
+- [Workflow Hooks](https://docs.medusajs.com/learn/fundamentals/workflows/workflow-hooks/index.html.md): inject custom functionalities into a workflow at predefined points, called hooks. This allows you to perform custom actions as a part of a core workflow without hacky workarounds.
+- [Additional Data in API Routes](https://docs.medusajs.com/learn/fundamentals/api-routes/additional-data/index.html.md): Configure core API routes to accept request parameters relevant to your customizations. These parameters are passed to the underlying workflow's hooks, where you can manage your custom data as part of an existing flow.
+
+***
+
+## Next Chapters: Link Brands to Products Example
+
+The next chapters explain how to use the tools mentioned above with step-by-step guides. You'll continue with the [brands example from the previous chapters](https://docs.medusajs.com/learn/customization/custom-features/index.html.md) to:
+
+- Link brands from the custom [Brand Module](https://docs.medusajs.com/learn/customization/custom-features/module/index.html.md) to products from Medusa's [Product Module](https://docs.medusajs.com/resources/commerce-modules/product/index.html.md).
+- Extend the core product-creation workflow and the API route that uses it to allow setting the brand of a newly created product.
+- Retrieve a product's associated brand's details.
+
+
+# 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.
+
+
+# Re-Use Customizations with Plugins
+
+In the previous chapters, you've learned important concepts related to creating modules, implementing commerce features in workflows, exposing those features in API routes, customizing the Medusa Admin dashboard with Admin Extensions, and integrating third-party systems.
+
+You've implemented the brands example within a single Medusa application. However, this approach is not scalable when you want to reuse your customizations across multiple projects.
+
+To reuse your customizations across multiple Medusa applications, such as implementing brands in different projects, you can create a plugin. A plugin is an NPM package that encapsulates your customizations and can be installed in any Medusa application. Plugins can include modules, workflows, API routes, Admin Extensions, and more.
+
+![Diagram showcasing how the Brand Plugin would add its resources to any application it's installed in](https://res.cloudinary.com/dza7lstvk/image/upload/v1737540091/Medusa%20Book/brand-plugin_bk9zi9.jpg)
+
+Medusa provides the tooling to create a plugin package, test it in a local Medusa application, and publish it to NPM.
+
+To learn more about plugins and how to create them, refer to [this chapter](https://docs.medusajs.com/learn/fundamentals/plugins/index.html.md).
+
+
 # Using TypeScript Aliases
 
 By default, Medusa doesn't support TypeScript aliases in production.
@@ -627,6 +756,242 @@ Trace span names start with the following keywords based on what it's reporting:
 - `pg.query:` when reporting database queries and operations.
 
 
+# Logging
+
+In this chapter, you’ll learn how to use Medusa’s logging utility.
+
+## Logger Class
+
+Medusa provides a `Logger` class with advanced logging functionalities. This includes configuring logging levels or saving logs to a file.
+
+The Medusa application registers the `Logger` class in the Medusa container and each module's container as `logger`.
+
+***
+
+## How to Log a Message
+
+Resolve the `logger` using the Medusa container to log a message in your resource.
+
+For example, create the file `src/jobs/log-message.ts` with the following content:
+
+```ts title="src/jobs/log-message.ts" highlights={highlights}
+import { MedusaContainer } from "@medusajs/framework/types"
+import { ContainerRegistrationKeys } from "@medusajs/framework/utils"
+
+export default async function myCustomJob(
+  container: MedusaContainer
+) {
+  const logger = container.resolve(ContainerRegistrationKeys.LOGGER)
+
+  logger.info("I'm using the logger!")
+}
+
+export const config = {
+  name: "test-logger",
+  // execute every minute
+  schedule: "* * * * *",
+}
+```
+
+This creates a scheduled job that resolves the `logger` from the Medusa container and uses it to log a message.
+
+### Test the Scheduled Job
+
+To test out the above scheduled job, start the Medusa application:
+
+```bash npm2yarn
+npm run dev
+```
+
+After a minute, you'll see the following message as part of the logged messages:
+
+```text
+info:    I'm using the logger!
+```
+
+***
+
+## Log Levels
+
+The `Logger` class has the following methods:
+
+- `info`: The message is logged with level `info`.
+- `warn`: The message is logged with level `warn`.
+- `error`: The message is logged with level `error`.
+- `debug`: The message is logged with level `debug`.
+
+Each of these methods accepts a string parameter to log in the terminal with the associated level.
+
+***
+
+## Logging Configurations
+
+### Log Level
+
+The available log levels, from lowest to highest levels, are:
+
+1. `silly` (default, meaning messages of all levels are logged)
+2. `debug`
+3. `info`
+4. `warn`
+5. `error`
+
+You can change that by setting the `LOG_LEVEL` environment variable to the minimum level you want to be logged.
+
+For example:
+
+```bash
+LOG_LEVEL=error
+```
+
+This logs `error` messages only.
+
+The environment variable must be set as a system environment variable and not in `.env`.
+
+### Save Logs in a File
+
+Aside from showing the logs in the terminal, you can save the logs in a file by setting the `LOG_FILE` environment variable to the path of the file relative to the Medusa server’s root directory.
+
+For example:
+
+```bash
+LOG_FILE=all.log
+```
+
+Your logs are now saved in the `all.log` file at the root of your Medusa application.
+
+The environment variable must be set as a system environment variable and not in `.env`.
+
+***
+
+## Show Log with Progress
+
+The `Logger` class has an `activity` method used to log a message of level `info`. If the Medusa application is running in a development environment, a spinner starts to show the activity's progress.
+
+For example:
+
+```ts title="src/jobs/log-message.ts"
+import { MedusaContainer } from "@medusajs/framework/types"
+import { ContainerRegistrationKeys } from "@medusajs/framework/utils"
+
+export default async function myCustomJob(
+  container: MedusaContainer
+) {
+  const logger = container.resolve(ContainerRegistrationKeys.LOGGER)
+
+  const activityId = logger.activity("First log message")
+
+  logger.progress(activityId, `Second log message`)
+
+  logger.success(activityId, "Last log message")
+}
+```
+
+The `activity` method returns the ID of the started activity. This ID can then be passed to one of the following methods of the `Logger` class:
+
+- `progress`: Log a message of level `info` that indicates progress within that same activity.
+- `success`: Log a message of level `info` that indicates that the activity has succeeded. This also ends the associated activity.
+- `failure`: Log a message of level `error` that indicates that the activity has failed. This also ends the associated activity.
+
+If you configured the `LOG_LEVEL` environment variable to a level higher than those associated with the above methods, their messages won’t be logged.
+
+
+# Medusa Testing Tools
+
+In this chapter, you'll learn about Medusa's testing tools and how to install and configure them.
+
+## @medusajs/test-utils Package
+
+Medusa provides a Testing Framework to create integration tests for your custom API routes, modules, or other Medusa customizations.
+
+To use the Testing Framework, install `@medusajs/test-utils` as a `devDependency`:
+
+```bash npm2yarn
+npm install --save-dev @medusajs/test-utils@latest
+```
+
+***
+
+## Install and Configure Jest
+
+Writing tests with `@medusajs/test-utils`'s tools requires installing and configuring Jest in your project.
+
+Run the following command to install the required Jest dependencies:
+
+```bash npm2yarn
+npm install --save-dev jest @types/jest @swc/jest
+```
+
+Then, create the file `jest.config.js` with the following content:
+
+```js title="jest.config.js"
+const { loadEnv } = require("@medusajs/framework/utils")
+loadEnv("test", process.cwd())
+
+module.exports = {
+  transform: {
+    "^.+\\.[jt]s$": [
+      "@swc/jest",
+      {
+        jsc: {
+          parser: { syntax: "typescript", decorators: true },
+        },
+      },
+    ],
+  },
+  testEnvironment: "node",
+  moduleFileExtensions: ["js", "ts", "json"],
+  modulePathIgnorePatterns: ["dist/"],
+  setupFiles: ["./integration-tests/setup.js"],
+}
+
+if (process.env.TEST_TYPE === "integration:http") {
+  module.exports.testMatch = ["**/integration-tests/http/*.spec.[jt]s"]
+} else if (process.env.TEST_TYPE === "integration:modules") {
+  module.exports.testMatch = ["**/src/modules/*/__tests__/**/*.[jt]s"]
+} else if (process.env.TEST_TYPE === "unit") {
+  module.exports.testMatch = ["**/src/**/__tests__/**/*.unit.spec.[jt]s"]
+}
+```
+
+Next, create the `integration-tests/setup.js` file with the following content:
+
+```js title="integration-tests/setup.js"
+const { MetadataStorage } = require("@mikro-orm/core")
+
+MetadataStorage.clear()
+```
+
+***
+
+## Add Test Commands
+
+Finally, add the following scripts to `package.json`:
+
+```json title="package.json"
+"scripts": {
+  // ...
+  "test:integration:http": "TEST_TYPE=integration:http NODE_OPTIONS=--experimental-vm-modules jest --silent=false --runInBand --forceExit",
+  "test:integration:modules": "TEST_TYPE=integration:modules NODE_OPTIONS=--experimental-vm-modules jest --silent --runInBand --forceExit",
+  "test:unit": "TEST_TYPE=unit NODE_OPTIONS=--experimental-vm-modules jest --silent --runInBand --forceExit"
+},
+```
+
+You now have two commands:
+
+- `test:integration:http` to run integration tests (for example, for API routes and workflows) available under the `integration-tests/http` directory.
+- `test:integration:modules` to run integration tests for modules available in any `__tests__` directory under `src/modules`.
+- `test:unit` to run unit tests in any `__tests__` directory under the `src` directory.
+
+Medusa's Testing Framework works for integration tests only. You can write unit tests using Jest.
+
+***
+
+## Test Tools and Writing Tests
+
+The next chapters explain how to use the testing tools provided by `@medusajs/test-utils` to write tests.
+
+
 # Medusa Application Configuration
 
 In this chapter, you'll learn available configurations in the Medusa application. You can change the application's configurations to customize the behavior of the application, its integrated modules and plugins, and more.
@@ -1530,356 +1895,6 @@ npx medusa db:migrate
 ```
 
 
-# Logging
-
-In this chapter, you’ll learn how to use Medusa’s logging utility.
-
-## Logger Class
-
-Medusa provides a `Logger` class with advanced logging functionalities. This includes configuring logging levels or saving logs to a file.
-
-The Medusa application registers the `Logger` class in the Medusa container and each module's container as `logger`.
-
-***
-
-## How to Log a Message
-
-Resolve the `logger` using the Medusa container to log a message in your resource.
-
-For example, create the file `src/jobs/log-message.ts` with the following content:
-
-```ts title="src/jobs/log-message.ts" highlights={highlights}
-import { MedusaContainer } from "@medusajs/framework/types"
-import { ContainerRegistrationKeys } from "@medusajs/framework/utils"
-
-export default async function myCustomJob(
-  container: MedusaContainer
-) {
-  const logger = container.resolve(ContainerRegistrationKeys.LOGGER)
-
-  logger.info("I'm using the logger!")
-}
-
-export const config = {
-  name: "test-logger",
-  // execute every minute
-  schedule: "* * * * *",
-}
-```
-
-This creates a scheduled job that resolves the `logger` from the Medusa container and uses it to log a message.
-
-### Test the Scheduled Job
-
-To test out the above scheduled job, start the Medusa application:
-
-```bash npm2yarn
-npm run dev
-```
-
-After a minute, you'll see the following message as part of the logged messages:
-
-```text
-info:    I'm using the logger!
-```
-
-***
-
-## Log Levels
-
-The `Logger` class has the following methods:
-
-- `info`: The message is logged with level `info`.
-- `warn`: The message is logged with level `warn`.
-- `error`: The message is logged with level `error`.
-- `debug`: The message is logged with level `debug`.
-
-Each of these methods accepts a string parameter to log in the terminal with the associated level.
-
-***
-
-## Logging Configurations
-
-### Log Level
-
-The available log levels, from lowest to highest levels, are:
-
-1. `silly` (default, meaning messages of all levels are logged)
-2. `debug`
-3. `info`
-4. `warn`
-5. `error`
-
-You can change that by setting the `LOG_LEVEL` environment variable to the minimum level you want to be logged.
-
-For example:
-
-```bash
-LOG_LEVEL=error
-```
-
-This logs `error` messages only.
-
-The environment variable must be set as a system environment variable and not in `.env`.
-
-### Save Logs in a File
-
-Aside from showing the logs in the terminal, you can save the logs in a file by setting the `LOG_FILE` environment variable to the path of the file relative to the Medusa server’s root directory.
-
-For example:
-
-```bash
-LOG_FILE=all.log
-```
-
-Your logs are now saved in the `all.log` file at the root of your Medusa application.
-
-The environment variable must be set as a system environment variable and not in `.env`.
-
-***
-
-## Show Log with Progress
-
-The `Logger` class has an `activity` method used to log a message of level `info`. If the Medusa application is running in a development environment, a spinner starts to show the activity's progress.
-
-For example:
-
-```ts title="src/jobs/log-message.ts"
-import { MedusaContainer } from "@medusajs/framework/types"
-import { ContainerRegistrationKeys } from "@medusajs/framework/utils"
-
-export default async function myCustomJob(
-  container: MedusaContainer
-) {
-  const logger = container.resolve(ContainerRegistrationKeys.LOGGER)
-
-  const activityId = logger.activity("First log message")
-
-  logger.progress(activityId, `Second log message`)
-
-  logger.success(activityId, "Last log message")
-}
-```
-
-The `activity` method returns the ID of the started activity. This ID can then be passed to one of the following methods of the `Logger` class:
-
-- `progress`: Log a message of level `info` that indicates progress within that same activity.
-- `success`: Log a message of level `info` that indicates that the activity has succeeded. This also ends the associated activity.
-- `failure`: Log a message of level `error` that indicates that the activity has failed. This also ends the associated activity.
-
-If you configured the `LOG_LEVEL` environment variable to a level higher than those associated with the above methods, their messages won’t be logged.
-
-
-# Medusa Testing Tools
-
-In this chapter, you'll learn about Medusa's testing tools and how to install and configure them.
-
-## @medusajs/test-utils Package
-
-Medusa provides a Testing Framework to create integration tests for your custom API routes, modules, or other Medusa customizations.
-
-To use the Testing Framework, install `@medusajs/test-utils` as a `devDependency`:
-
-```bash npm2yarn
-npm install --save-dev @medusajs/test-utils@latest
-```
-
-***
-
-## Install and Configure Jest
-
-Writing tests with `@medusajs/test-utils`'s tools requires installing and configuring Jest in your project.
-
-Run the following command to install the required Jest dependencies:
-
-```bash npm2yarn
-npm install --save-dev jest @types/jest @swc/jest
-```
-
-Then, create the file `jest.config.js` with the following content:
-
-```js title="jest.config.js"
-const { loadEnv } = require("@medusajs/framework/utils")
-loadEnv("test", process.cwd())
-
-module.exports = {
-  transform: {
-    "^.+\\.[jt]s$": [
-      "@swc/jest",
-      {
-        jsc: {
-          parser: { syntax: "typescript", decorators: true },
-        },
-      },
-    ],
-  },
-  testEnvironment: "node",
-  moduleFileExtensions: ["js", "ts", "json"],
-  modulePathIgnorePatterns: ["dist/"],
-  setupFiles: ["./integration-tests/setup.js"],
-}
-
-if (process.env.TEST_TYPE === "integration:http") {
-  module.exports.testMatch = ["**/integration-tests/http/*.spec.[jt]s"]
-} else if (process.env.TEST_TYPE === "integration:modules") {
-  module.exports.testMatch = ["**/src/modules/*/__tests__/**/*.[jt]s"]
-} else if (process.env.TEST_TYPE === "unit") {
-  module.exports.testMatch = ["**/src/**/__tests__/**/*.unit.spec.[jt]s"]
-}
-```
-
-Next, create the `integration-tests/setup.js` file with the following content:
-
-```js title="integration-tests/setup.js"
-const { MetadataStorage } = require("@mikro-orm/core")
-
-MetadataStorage.clear()
-```
-
-***
-
-## Add Test Commands
-
-Finally, add the following scripts to `package.json`:
-
-```json title="package.json"
-"scripts": {
-  // ...
-  "test:integration:http": "TEST_TYPE=integration:http NODE_OPTIONS=--experimental-vm-modules jest --silent=false --runInBand --forceExit",
-  "test:integration:modules": "TEST_TYPE=integration:modules NODE_OPTIONS=--experimental-vm-modules jest --silent --runInBand --forceExit",
-  "test:unit": "TEST_TYPE=unit NODE_OPTIONS=--experimental-vm-modules jest --silent --runInBand --forceExit"
-},
-```
-
-You now have two commands:
-
-- `test:integration:http` to run integration tests (for example, for API routes and workflows) available under the `integration-tests/http` directory.
-- `test:integration:modules` to run integration tests for modules available in any `__tests__` directory under `src/modules`.
-- `test:unit` to run unit tests in any `__tests__` directory under the `src` directory.
-
-Medusa's Testing Framework works for integration tests only. You can write unit tests using Jest.
-
-***
-
-## Test Tools and Writing Tests
-
-The next chapters explain how to use the testing tools provided by `@medusajs/test-utils` to write tests.
-
-
-# Build Custom Features
-
-In the upcoming chapters, you'll follow step-by-step guides to build custom features in Medusa. These guides gradually introduce Medusa's concepts to help you understand what they are and how to use them.
-
-By following these guides, you'll add brands to the Medusa application that you can associate with products.
-
-To build a custom feature in Medusa, you need three main tools:
-
-- [Module](https://docs.medusajs.com/learn/fundamentals/modules/index.html.md): a package with commerce logic for a single domain. It defines new tables to add to the database, and a class of methods to manage these tables.
-- [Workflow](https://docs.medusajs.com/learn/fundamentals/workflows/index.html.md): a tool to perform an operation comprising multiple steps with built-in rollback and retry mechanisms.
-- [API route](https://docs.medusajs.com/learn/fundamentals/api-routes/index.html.md): a REST endpoint that exposes commerce features to clients, such as the admin dashboard or a storefront. The API route executes a workflow that implements the commerce feature using modules.
-
-![Diagram showcasing the flow of a custom developed feature](https://res.cloudinary.com/dza7lstvk/image/upload/v1725867628/Medusa%20Book/custom-development_nofvp6.jpg)
-
-***
-
-## Next Chapters: Brand Module Example
-
-The next chapters will guide you to:
-
-1. Build a Brand Module that creates a `Brand` data model and provides data-management features.
-2. Add a workflow to create a brand.
-3. Expose an API route that allows admin users to create a brand using the workflow.
-
-
-# Customize Medusa Admin Dashboard
-
-In the previous chapters, you've customized your Medusa application to [add brands](https://docs.medusajs.com/learn/customization/custom-features/module/index.html.md), [expose an API route to create brands](https://docs.medusajs.com/learn/customization/custom-features/api-route/index.html.md), and [linked brands to products](https://docs.medusajs.com/learn/customization/extend-features/define-link/index.html.md).
-
-After customizing and extending your application with new features, you may need to provide an interface for admin users to utilize these features. The Medusa Admin dashboard is extendable, allowing you to:
-
-- Insert components, called [widgets](https://docs.medusajs.com/learn/fundamentals/admin/widgets/index.html.md), on existing pages.
-- Add new pages, called [UI Routes](https://docs.medusajs.com/learn/fundamentals/admin/ui-routes/index.html.md).
-
-From these customizations, you can send requests to custom API routes, allowing admin users to manage custom resources on the dashboard
-
-***
-
-## Next Chapters: View Brands in Dashboard
-
-In the next chapters, you'll continue with the brands example to:
-
-- Add a new section to the product details page that shows the product's brand.
-- Add a new page in the dashboard that shows all brands in the store.
-
-
-# Integrate Third-Party Systems
-
-Commerce applications often connect to third-party systems that provide additional or specialized features. For example, you may integrate a Content-Management System (CMS) for rich content features, a payment provider to process credit-card payments, and a notification service to send emails.
-
-The Medusa Framework facilitates integrating these systems and orchestrating operations across them, saving you the effort of managing them yourself. You won't find those capabilities in other commerce platforms that in these scenarios become a bottleneck to building customizations and iterating quickly.
-
-In Medusa, you integrate a third-party system by:
-
-1. Creating a module whose service provides the methods to connect to and perform operations in the third-party system.
-2. Building workflows that complete tasks spanning across systems. You use the module that integrates a third-party system in the workflow's steps.
-3. Executing the workflows you built in an [API route](https://docs.medusajs.com/learn/fundamentals/api-routes/index.html.md), at a scheduled time, or when an event is emitted.
-
-***
-
-## Next Chapters: Sync Brands Example
-
-In the previous chapters, you've [added brands](https://docs.medusajs.com/learn/customization/custom-features/module/index.html.md) to your Medusa application. In the next chapters, you will:
-
-1. Integrate a dummy third-party CMS in the Brand Module.
-2. Sync brands to the CMS when a brand is created.
-3. Sync brands from the CMS at a daily schedule.
-
-
-# Extend Core Commerce Features
-
-In the upcoming chapters, you'll learn about the concepts and tools to extend Medusa's core commerce features.
-
-In other commerce platforms, you extend core features and models through hacky workarounds that can introduce unexpected issues and side effects across the platform. It also makes your application difficult to maintain and upgrade in the long run.
-
-The Medusa Framework and orchestration tools mitigate these issues while supporting all your customization needs:
-
-- [Module Links](https://docs.medusajs.com/learn/fundamentals/module-links/index.html.md): Link data models of different modules without building direct dependencies, ensuring that the Medusa application integrates your modules without side effects.
-- [Workflow Hooks](https://docs.medusajs.com/learn/fundamentals/workflows/workflow-hooks/index.html.md): inject custom functionalities into a workflow at predefined points, called hooks. This allows you to perform custom actions as a part of a core workflow without hacky workarounds.
-- [Additional Data in API Routes](https://docs.medusajs.com/learn/fundamentals/api-routes/additional-data/index.html.md): Configure core API routes to accept request parameters relevant to your customizations. These parameters are passed to the underlying workflow's hooks, where you can manage your custom data as part of an existing flow.
-
-***
-
-## Next Chapters: Link Brands to Products Example
-
-The next chapters explain how to use the tools mentioned above with step-by-step guides. You'll continue with the [brands example from the previous chapters](https://docs.medusajs.com/learn/customization/custom-features/index.html.md) to:
-
-- Link brands from the custom [Brand Module](https://docs.medusajs.com/learn/customization/custom-features/module/index.html.md) to products from Medusa's [Product Module](https://docs.medusajs.com/resources/commerce-modules/product/index.html.md).
-- Extend the core product-creation workflow and the API route that uses it to allow setting the brand of a newly created product.
-- Retrieve a product's associated brand's details.
-
-
-# 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.
-
-
 # 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.
@@ -2188,94 +2203,6 @@ 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.
 
 
-# Re-Use Customizations with Plugins
-
-In the previous chapters, you've learned important concepts related to creating modules, implementing commerce features in workflows, exposing those features in API routes, customizing the Medusa Admin dashboard with Admin Extensions, and integrating third-party systems.
-
-You've implemented the brands example within a single Medusa application. However, this approach is not scalable when you want to reuse your customizations across multiple projects.
-
-To reuse your customizations across multiple Medusa applications, such as implementing brands in different projects, you can create a plugin. A plugin is an NPM package that encapsulates your customizations and can be installed in any Medusa application. Plugins can include modules, workflows, API routes, Admin Extensions, and more.
-
-![Diagram showcasing how the Brand Plugin would add its resources to any application it's installed in](https://res.cloudinary.com/dza7lstvk/image/upload/v1737540091/Medusa%20Book/brand-plugin_bk9zi9.jpg)
-
-Medusa provides the tooling to create a plugin package, test it in a local Medusa application, and publish it to NPM.
-
-To learn more about plugins and how to create them, refer to [this chapter](https://docs.medusajs.com/learn/fundamentals/plugins/index.html.md).
-
-
-# Medusa's Architecture
-
-In this chapter, you'll learn about the architectural layers in Medusa.
-
-Find the full architectural diagram at the [end of this chapter](#full-diagram-of-medusas-architecture).
-
-## HTTP, Workflow, and Module Layers
-
-Medusa is a headless commerce platform. So, storefronts, admin dashboards, and other clients consume Medusa's functionalities through its API routes.
-
-In a common Medusa application, requests go through four layers in the stack. In order of entry, those are:
-
-1. API Routes (HTTP): Our API Routes are the typical entry point. The Medusa server is based on Express.js, which handles incoming requests. It can also connect to a Redis database that stores the server session data.
-2. Workflows: API Routes consume workflows that hold the opinionated business logic of your application.
-3. Modules: Workflows use domain-specific modules for resource management.
-4. Data store: Modules query the underlying datastore, which is a PostgreSQL database in common cases.
-
-These layers of stack can be implemented within [plugins](https://docs.medusajs.com/learn/fundamentals/plugins/index.html.md).
-
-![This diagram illustrates the entry point of requests into the Medusa application through API routes. It shows a storefront and an admin that can send a request to the HTTP layer. The HTTP layer then uses workflows to handle the business logic. Finally, the workflows use modules to query and manipulate data in the data stores.](https://res.cloudinary.com/dza7lstvk/image/upload/v1727175296/Medusa%20Book/http-layer_sroafr.jpg)
-
-***
-
-## Database Layer
-
-The Medusa application injects into each module, including your [custom modules](https://docs.medusajs.com/learn/fundamentals/modules/index.html.md), a connection to the configured PostgreSQL database. Modules use that connection to read and write data to the database.
-
-Modules can be implemented within [plugins](https://docs.medusajs.com/learn/fundamentals/plugins/index.html.md).
-
-![This diagram illustrates how modules connect to the database.](https://res.cloudinary.com/dza7lstvk/image/upload/v1727175379/Medusa%20Book/db-layer_pi7tix.jpg)
-
-***
-
-## Third-Party Integrations Layer
-
-Third-party services and systems are integrated through Medusa's Commerce and Infrastructure Modules. You also create custom third-party integrations through a [custom module](https://docs.medusajs.com/learn/fundamentals/modules/index.html.md).
-
-Modules can be implemented within [plugins](https://docs.medusajs.com/learn/fundamentals/plugins/index.html.md).
-
-### Commerce Modules
-
-[Commerce Modules](https://docs.medusajs.com/resources/commerce-modules/index.html.md) integrate third-party services relevant for commerce or user-facing features. For example, you can integrate [Stripe](https://docs.medusajs.com/resources/commerce-modules/payment/payment-provider/stripe/index.html.md) through a Payment Module Provider, or [ShipStation](https://docs.medusajs.com/resources/integrations/guides/shipstation/index.html.md) through a Fulfillment Module Provider.
-
-You can also integrate third-party services for custom functionalities. For example, you can integrate [Sanity](https://docs.medusajs.com/resources/integrations/guides/sanity/index.html.md) for rich CMS capabilities, or [Odoo](https://docs.medusajs.com/resources/recipes/erp/odoo/index.html.md) to sync your Medusa application with your ERP system.
-
-You can replace any of the third-party services mentioned above to build your preferred commerce ecosystem.
-
-![Diagram illustrating the Commerce Modules integration to third-party services](https://res.cloudinary.com/dza7lstvk/image/upload/v1727175357/Medusa%20Book/service-commerce_qcbdsl.jpg)
-
-### Infrastructure Modules
-
-[Infrastructure Modules](https://docs.medusajs.com/resources/infrastructure-modules/index.html.md) integrate third-party services and systems that customize Medusa's infrastructure. Medusa has the following Infrastructure Modules:
-
-- [Cache Module](https://docs.medusajs.com/resources/infrastructure-modules/cache/index.html.md): Caches data that require heavy computation. You can integrate a custom module to handle the caching with services like Memcached, or use the existing [Redis Cache Module](https://docs.medusajs.com/resources/infrastructure-modules/cache/redis/index.html.md).
-- [Event Module](https://docs.medusajs.com/resources/infrastructure-modules/event/index.html.md): A pub/sub system that allows you to subscribe to events and trigger them. You can integrate [Redis](https://docs.medusajs.com/resources/infrastructure-modules/event/redis/index.html.md) as the pub/sub system.
-- [File Module](https://docs.medusajs.com/resources/infrastructure-modules/file/index.html.md): Manages file uploads and storage, such as upload of product images. You can integrate [AWS S3](https://docs.medusajs.com/resources/infrastructure-modules/file/s3/index.html.md) for file storage.
-- [Locking Module](https://docs.medusajs.com/resources/infrastructure-modules/locking/index.html.md): Manages access to shared resources by multiple processes or threads, preventing conflict between processes and ensuring data consistency. You can integrate [Redis](https://docs.medusajs.com/resources/infrastructure-modules/locking/redis/index.html.md) for locking.
-- [Notification Module](https://docs.medusajs.com/resources/infrastructure-modules/notification/index.html.md): Sends notifications to customers and users, such as for order updates or newsletters. You can integrate [SendGrid](https://docs.medusajs.com/resources/infrastructure-modules/notification/sendgrid/index.html.md) for sending emails.
-- [Workflow Engine Module](https://docs.medusajs.com/resources/infrastructure-modules/workflow-engine/index.html.md): Orchestrates workflows that hold the business logic of your application. You can integrate [Redis](https://docs.medusajs.com/resources/infrastructure-modules/workflow-engine/redis/index.html.md) to orchestrate workflows.
-
-All of the third-party services mentioned above can be replaced to help you build your preferred architecture and ecosystem.
-
-![Diagram illustrating the Infrastructure Modules integration to third-party services and systems](https://res.cloudinary.com/dza7lstvk/image/upload/v1727175342/Medusa%20Book/service-arch_ozvryw.jpg)
-
-***
-
-## Full Diagram of Medusa's Architecture
-
-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)
-
-
 # Admin Development
 
 In this chapter, you'll learn about the Medusa Admin dashboard and the possible ways to customize it.
@@ -2322,65 +2249,6 @@ Refer to the [Medusa UI documentation](https://docs.medusajs.com/ui/index.html.m
 To build admin customizations that match the Medusa Admin's designs and layouts, refer to [this guide](https://docs.medusajs.com/resources/admin-components/index.html.md) to find common components.
 
 
-# API Routes
-
-In this chapter, you’ll learn what API Routes are and how to create them.
-
-## What is an API Route?
-
-An API Route is an endpoint. It exposes commerce features to external applications, such as storefronts, the admin dashboard, or third-party systems.
-
-The Medusa core application provides a set of admin and store API routes out-of-the-box. You can also create custom API routes to expose your custom functionalities.
-
-***
-
-## How to Create an API Route?
-
-An API Route is created in a TypeScript or JavaScript file under the `src/api` directory of your Medusa application. The file’s name must be `route.ts` or `route.js`.
-
-![Example of API route in the application's directory structure](https://res.cloudinary.com/dza7lstvk/image/upload/v1732808645/Medusa%20Book/route-dir-overview_dqgzmk.jpg)
-
-Each file exports API Route handler functions for at least one HTTP method (`GET`, `POST`, `DELETE`, etc…).
-
-For example, to create a `GET` API Route at `/hello-world`, create the file `src/api/hello-world/route.ts` with the following content:
-
-```ts title="src/api/hello-world/route.ts"
-import type {
-  MedusaRequest,
-  MedusaResponse,
-} from "@medusajs/framework/http"
-
-export const GET = (
-  req: MedusaRequest,
-  res: MedusaResponse
-) => {
-  res.json({
-    message: "[GET] Hello world!",
-  })
-}
-```
-
-### Test API Route
-
-To test the API route above, start the Medusa application:
-
-```bash npm2yarn
-npm run dev
-```
-
-Then, send a `GET` request to the `/hello-world` API Route:
-
-```bash
-curl http://localhost:9000/hello-world
-```
-
-***
-
-## When to Use API Routes
-
-You're exposing custom functionality to be used by a storefront, admin dashboard, or any external application.
-
-
 # Custom CLI Scripts
 
 In this chapter, you'll learn how to create and execute custom scripts from Medusa's CLI tool.
@@ -2451,6 +2319,65 @@ npx medusa exec ./src/scripts/my-script.ts arg1 arg2
 ```
 
 
+# API Routes
+
+In this chapter, you’ll learn what API Routes are and how to create them.
+
+## What is an API Route?
+
+An API Route is an endpoint. It exposes commerce features to external applications, such as storefronts, the admin dashboard, or third-party systems.
+
+The Medusa core application provides a set of admin and store API routes out-of-the-box. You can also create custom API routes to expose your custom functionalities.
+
+***
+
+## How to Create an API Route?
+
+An API Route is created in a TypeScript or JavaScript file under the `src/api` directory of your Medusa application. The file’s name must be `route.ts` or `route.js`.
+
+![Example of API route in the application's directory structure](https://res.cloudinary.com/dza7lstvk/image/upload/v1732808645/Medusa%20Book/route-dir-overview_dqgzmk.jpg)
+
+Each file exports API Route handler functions for at least one HTTP method (`GET`, `POST`, `DELETE`, etc…).
+
+For example, to create a `GET` API Route at `/hello-world`, create the file `src/api/hello-world/route.ts` with the following content:
+
+```ts title="src/api/hello-world/route.ts"
+import type {
+  MedusaRequest,
+  MedusaResponse,
+} from "@medusajs/framework/http"
+
+export const GET = (
+  req: MedusaRequest,
+  res: MedusaResponse
+) => {
+  res.json({
+    message: "[GET] Hello world!",
+  })
+}
+```
+
+### Test API Route
+
+To test the API route above, start the Medusa application:
+
+```bash npm2yarn
+npm run dev
+```
+
+Then, send a `GET` request to the `/hello-world` API Route:
+
+```bash
+curl http://localhost:9000/hello-world
+```
+
+***
+
+## When to Use API Routes
+
+You're exposing custom functionality to be used by a storefront, admin dashboard, or any external application.
+
+
 # Data Models
 
 In this chapter, you'll learn what a data model is and how to create a data model.
@@ -2634,6 +2561,108 @@ You should opt for setting configurations in `medusa-config.ts` where possible.
 ||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/references/events/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.
@@ -3404,108 +3433,6 @@ To learn more about the different concepts useful for building plugins, check ou
 - [Plugins](https://docs.medusajs.com/learn/fundamentals/plugins/index.html.md)
 
 
-# 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/references/events/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).
-
-
 # Medusa Container
 
 In this chapter, you’ll learn about the Medusa container and how to use it.
@@ -3871,138 +3798,6 @@ npx medusa db:migrate
 ```
 
 
-# Plugins
-
-In this chapter, you'll learn what a plugin is in Medusa.
-
-Plugins are available starting from [Medusa v2.3.0](https://github.com/medusajs/medusa/releases/tag/v2.3.0).
-
-## What is a Plugin?
-
-A plugin is a package of reusable Medusa customizations that you can install in any Medusa application. The supported customizations are [Modules](https://docs.medusajs.com/learn/fundamentals/modules/index.html.md), [API Routes](https://docs.medusajs.com/learn/fundamentals/api-routes/index.html.md), [Workflows](https://docs.medusajs.com/learn/fundamentals/workflows/index.html.md), [Workflow Hooks](https://docs.medusajs.com/learn/fundamentals/workflows/workflow-hooks/index.html.md), [Links](https://docs.medusajs.com/learn/fundamentals/module-links/index.html.md), [Subscribers](https://docs.medusajs.com/learn/fundamentals/events-and-subscribers/index.html.md), [Scheduled Jobs](https://docs.medusajs.com/learn/fundamentals/scheduled-jobs/index.html.md), and [Admin Extensions](https://docs.medusajs.com/learn/fundamentals/admin/index.html.md).
-
-Plugins allow you to reuse your Medusa customizations across multiple projects or share them with the community. They can be published to npm and installed in any Medusa project.
-
-![Diagram showcasing a wishlist plugin installed in a Medusa application](https://res.cloudinary.com/dza7lstvk/image/upload/v1737540762/Medusa%20Book/plugin-diagram_oepiis.jpg)
-
-Learn how to create a wishlist plugin in [this guide](https://docs.medusajs.com/resources/plugins/guides/wishlist/index.html.md).
-
-***
-
-## Plugin vs Module
-
-A [module](https://docs.medusajs.com/learn/fundamentals/modules/index.html.md) is an isolated package related to a single domain or functionality, such as product reviews or integrating a Content Management System. A module can't access any resources in the Medusa application that are outside its codebase.
-
-A plugin, on the other hand, can contain multiple Medusa customizations, including modules. Your plugin can define a module, then build flows around it.
-
-For example, in a plugin, you can define a module that integrates a third-party service, then add a workflow that uses the module when a certain event occurs to sync data to that service.
-
-- You want to reuse your Medusa customizations across multiple projects.
-- You want to share your Medusa customizations with the community.
-
-- You want to build a custom feature related to a single domain or integrate a third-party service. Instead, use a [module](https://docs.medusajs.com/learn/fundamentals/modules/index.html.md). You can wrap that module in a plugin if it's used in other customizations, such as if it has a module link or it's used in a workflow.
-
-***
-
-## How to Create a Plugin?
-
-The next chapter explains how you can create and publish a plugin.
-
-
-# Scheduled Jobs
-
-In this chapter, you’ll learn about scheduled jobs and how to use them.
-
-## What is a Scheduled Job?
-
-When building your commerce application, you may need to automate tasks and run them repeatedly at a specific schedule. For example, you need to automatically sync products to a third-party service once a day.
-
-In other commerce platforms, this feature isn't natively supported. Instead, you have to setup a separate application to execute cron jobs, which adds complexity as to how you expose this task to be executed in a cron job, or how do you debug it when it's not running within the platform's tooling.
-
-Medusa removes this overhead by supporting this feature natively with scheduled jobs. A scheduled job is an asynchronous function that the Medusa application runs at the interval you specify during the Medusa application's runtime. Your efforts are only spent on implementing the functionality performed by the job, such as syncing products to an ERP.
-
-- You want the action to execute at a specified schedule while the Medusa application **isn't** running. Instead, use the operating system's equivalent of a cron job.
-- You want to execute the action once when the application loads. Use [loaders](https://docs.medusajs.com/learn/fundamentals/modules/loaders/index.html.md) instead.
-- You want to execute the action if an event occurs. Use [subscribers](https://docs.medusajs.com/learn/fundamentals/events-and-subscribers/index.html.md) instead.
-
-***
-
-## How to Create a Scheduled Job?
-
-You create a scheduled job in a TypeScript or JavaScript file under the `src/jobs` directory. The file exports the asynchronous function to run, and the configurations indicating the schedule to run the function.
-
-For example, create the file `src/jobs/hello-world.ts` with the following content:
-
-![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.
-
-
 # Modules
 
 In this chapter, you’ll learn about modules and how to create them.
@@ -4303,6 +4098,211 @@ This will create a post and return it in the response:
 You can also execute the workflow from a [subscriber](https://docs.medusajs.com/learn/fundamentals/events-and-subscribers/index.html.md) when an event occurs, or from a [scheduled job](https://docs.medusajs.com/learn/fundamentals/scheduled-jobs/index.html.md) to run it at a specified interval.
 
 
+# Plugins
+
+In this chapter, you'll learn what a plugin is in Medusa.
+
+Plugins are available starting from [Medusa v2.3.0](https://github.com/medusajs/medusa/releases/tag/v2.3.0).
+
+## What is a Plugin?
+
+A plugin is a package of reusable Medusa customizations that you can install in any Medusa application. The supported customizations are [Modules](https://docs.medusajs.com/learn/fundamentals/modules/index.html.md), [API Routes](https://docs.medusajs.com/learn/fundamentals/api-routes/index.html.md), [Workflows](https://docs.medusajs.com/learn/fundamentals/workflows/index.html.md), [Workflow Hooks](https://docs.medusajs.com/learn/fundamentals/workflows/workflow-hooks/index.html.md), [Links](https://docs.medusajs.com/learn/fundamentals/module-links/index.html.md), [Subscribers](https://docs.medusajs.com/learn/fundamentals/events-and-subscribers/index.html.md), [Scheduled Jobs](https://docs.medusajs.com/learn/fundamentals/scheduled-jobs/index.html.md), and [Admin Extensions](https://docs.medusajs.com/learn/fundamentals/admin/index.html.md).
+
+Plugins allow you to reuse your Medusa customizations across multiple projects or share them with the community. They can be published to npm and installed in any Medusa project.
+
+![Diagram showcasing a wishlist plugin installed in a Medusa application](https://res.cloudinary.com/dza7lstvk/image/upload/v1737540762/Medusa%20Book/plugin-diagram_oepiis.jpg)
+
+Learn how to create a wishlist plugin in [this guide](https://docs.medusajs.com/resources/plugins/guides/wishlist/index.html.md).
+
+***
+
+## Plugin vs Module
+
+A [module](https://docs.medusajs.com/learn/fundamentals/modules/index.html.md) is an isolated package related to a single domain or functionality, such as product reviews or integrating a Content Management System. A module can't access any resources in the Medusa application that are outside its codebase.
+
+A plugin, on the other hand, can contain multiple Medusa customizations, including modules. Your plugin can define a module, then build flows around it.
+
+For example, in a plugin, you can define a module that integrates a third-party service, then add a workflow that uses the module when a certain event occurs to sync data to that service.
+
+- You want to reuse your Medusa customizations across multiple projects.
+- You want to share your Medusa customizations with the community.
+
+- You want to build a custom feature related to a single domain or integrate a third-party service. Instead, use a [module](https://docs.medusajs.com/learn/fundamentals/modules/index.html.md). You can wrap that module in a plugin if it's used in other customizations, such as if it has a module link or it's used in a workflow.
+
+***
+
+## How to Create a Plugin?
+
+The next chapter explains how you can create and publish a plugin.
+
+
+# Scheduled Jobs
+
+In this chapter, you’ll learn about scheduled jobs and how to use them.
+
+## What is a Scheduled Job?
+
+When building your commerce application, you may need to automate tasks and run them repeatedly at a specific schedule. For example, you need to automatically sync products to a third-party service once a day.
+
+In other commerce platforms, this feature isn't natively supported. Instead, you have to setup a separate application to execute cron jobs, which adds complexity as to how you expose this task to be executed in a cron job, or how do you debug it when it's not running within the platform's tooling.
+
+Medusa removes this overhead by supporting this feature natively with scheduled jobs. A scheduled job is an asynchronous function that the Medusa application runs at the interval you specify during the Medusa application's runtime. Your efforts are only spent on implementing the functionality performed by the job, such as syncing products to an ERP.
+
+- You want the action to execute at a specified schedule while the Medusa application **isn't** running. Instead, use the operating system's equivalent of a cron job.
+- You want to execute the action once when the application loads. Use [loaders](https://docs.medusajs.com/learn/fundamentals/modules/loaders/index.html.md) instead.
+- You want to execute the action if an event occurs. Use [subscribers](https://docs.medusajs.com/learn/fundamentals/events-and-subscribers/index.html.md) instead.
+
+***
+
+## How to Create a Scheduled Job?
+
+You create a scheduled job in a TypeScript or JavaScript file under the `src/jobs` directory. The file exports the asynchronous function to run, and the configurations indicating the schedule to run the function.
+
+For example, create the file `src/jobs/hello-world.ts` with the following content:
+
+![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.
+
+
+# Medusa's Architecture
+
+In this chapter, you'll learn about the architectural layers in Medusa.
+
+Find the full architectural diagram at the [end of this chapter](#full-diagram-of-medusas-architecture).
+
+## HTTP, Workflow, and Module Layers
+
+Medusa is a headless commerce platform. So, storefronts, admin dashboards, and other clients consume Medusa's functionalities through its API routes.
+
+In a common Medusa application, requests go through four layers in the stack. In order of entry, those are:
+
+1. API Routes (HTTP): Our API Routes are the typical entry point. The Medusa server is based on Express.js, which handles incoming requests. It can also connect to a Redis database that stores the server session data.
+2. Workflows: API Routes consume workflows that hold the opinionated business logic of your application.
+3. Modules: Workflows use domain-specific modules for resource management.
+4. Data store: Modules query the underlying datastore, which is a PostgreSQL database in common cases.
+
+These layers of stack can be implemented within [plugins](https://docs.medusajs.com/learn/fundamentals/plugins/index.html.md).
+
+![This diagram illustrates the entry point of requests into the Medusa application through API routes. It shows a storefront and an admin that can send a request to the HTTP layer. The HTTP layer then uses workflows to handle the business logic. Finally, the workflows use modules to query and manipulate data in the data stores.](https://res.cloudinary.com/dza7lstvk/image/upload/v1727175296/Medusa%20Book/http-layer_sroafr.jpg)
+
+***
+
+## Database Layer
+
+The Medusa application injects into each module, including your [custom modules](https://docs.medusajs.com/learn/fundamentals/modules/index.html.md), a connection to the configured PostgreSQL database. Modules use that connection to read and write data to the database.
+
+Modules can be implemented within [plugins](https://docs.medusajs.com/learn/fundamentals/plugins/index.html.md).
+
+![This diagram illustrates how modules connect to the database.](https://res.cloudinary.com/dza7lstvk/image/upload/v1727175379/Medusa%20Book/db-layer_pi7tix.jpg)
+
+***
+
+## Third-Party Integrations Layer
+
+Third-party services and systems are integrated through Medusa's Commerce and Infrastructure Modules. You also create custom third-party integrations through a [custom module](https://docs.medusajs.com/learn/fundamentals/modules/index.html.md).
+
+Modules can be implemented within [plugins](https://docs.medusajs.com/learn/fundamentals/plugins/index.html.md).
+
+### Commerce Modules
+
+[Commerce Modules](https://docs.medusajs.com/resources/commerce-modules/index.html.md) integrate third-party services relevant for commerce or user-facing features. For example, you can integrate [Stripe](https://docs.medusajs.com/resources/commerce-modules/payment/payment-provider/stripe/index.html.md) through a Payment Module Provider, or [ShipStation](https://docs.medusajs.com/resources/integrations/guides/shipstation/index.html.md) through a Fulfillment Module Provider.
+
+You can also integrate third-party services for custom functionalities. For example, you can integrate [Sanity](https://docs.medusajs.com/resources/integrations/guides/sanity/index.html.md) for rich CMS capabilities, or [Odoo](https://docs.medusajs.com/resources/recipes/erp/odoo/index.html.md) to sync your Medusa application with your ERP system.
+
+You can replace any of the third-party services mentioned above to build your preferred commerce ecosystem.
+
+![Diagram illustrating the Commerce Modules integration to third-party services](https://res.cloudinary.com/dza7lstvk/image/upload/v1727175357/Medusa%20Book/service-commerce_qcbdsl.jpg)
+
+### Infrastructure Modules
+
+[Infrastructure Modules](https://docs.medusajs.com/resources/infrastructure-modules/index.html.md) integrate third-party services and systems that customize Medusa's infrastructure. Medusa has the following Infrastructure Modules:
+
+- [Cache Module](https://docs.medusajs.com/resources/infrastructure-modules/cache/index.html.md): Caches data that require heavy computation. You can integrate a custom module to handle the caching with services like Memcached, or use the existing [Redis Cache Module](https://docs.medusajs.com/resources/infrastructure-modules/cache/redis/index.html.md).
+- [Event Module](https://docs.medusajs.com/resources/infrastructure-modules/event/index.html.md): A pub/sub system that allows you to subscribe to events and trigger them. You can integrate [Redis](https://docs.medusajs.com/resources/infrastructure-modules/event/redis/index.html.md) as the pub/sub system.
+- [File Module](https://docs.medusajs.com/resources/infrastructure-modules/file/index.html.md): Manages file uploads and storage, such as upload of product images. You can integrate [AWS S3](https://docs.medusajs.com/resources/infrastructure-modules/file/s3/index.html.md) for file storage.
+- [Locking Module](https://docs.medusajs.com/resources/infrastructure-modules/locking/index.html.md): Manages access to shared resources by multiple processes or threads, preventing conflict between processes and ensuring data consistency. You can integrate [Redis](https://docs.medusajs.com/resources/infrastructure-modules/locking/redis/index.html.md) for locking.
+- [Notification Module](https://docs.medusajs.com/resources/infrastructure-modules/notification/index.html.md): Sends notifications to customers and users, such as for order updates or newsletters. You can integrate [SendGrid](https://docs.medusajs.com/resources/infrastructure-modules/notification/sendgrid/index.html.md) for sending emails.
+- [Workflow Engine Module](https://docs.medusajs.com/resources/infrastructure-modules/workflow-engine/index.html.md): Orchestrates workflows that hold the business logic of your application. You can integrate [Redis](https://docs.medusajs.com/resources/infrastructure-modules/workflow-engine/redis/index.html.md) to orchestrate workflows.
+
+All of the third-party services mentioned above can be replaced to help you build your preferred architecture and ecosystem.
+
+![Diagram illustrating the Infrastructure Modules integration to third-party services and systems](https://res.cloudinary.com/dza7lstvk/image/upload/v1727175342/Medusa%20Book/service-arch_ozvryw.jpg)
+
+***
+
+## Full Diagram of Medusa's Architecture
+
+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)
+
+
 # Workflows
 
 In this chapter, you’ll learn about workflows and how to define and execute them.
@@ -4739,207 +4739,6 @@ MEDUSA_FF_ANALYTICS=false
 ```
 
 
-# Write Integration Tests
-
-In this chapter, you'll learn about `medusaIntegrationTestRunner` from Medusa's Testing Framework and how to use it to write integration tests.
-
-### Prerequisites
-
-- [Testing Tools Setup](https://docs.medusajs.com/learn/debugging-and-testing/testing-tools/index.html.md)
-
-## medusaIntegrationTestRunner Utility
-
-The `medusaIntegrationTestRunner` is from Medusa's Testing Framework and it's used to create integration tests in your Medusa project. It runs a full Medusa application, allowing you test API routes, workflows, or other customizations.
-
-For example:
-
-```ts title="integration-tests/http/test.spec.ts" highlights={highlights}
-import { medusaIntegrationTestRunner } from "@medusajs/test-utils"
-
-medusaIntegrationTestRunner({
-  testSuite: ({ api, getContainer }) => {
-    // TODO write tests...
-  },
-})
-
-jest.setTimeout(60 * 1000)
-```
-
-The `medusaIntegrationTestRunner` function accepts an object as a parameter. The object has a required property `testSuite`.
-
-`testSuite`'s value is a function that defines the tests to run. The function accepts as a parameter an object that has the following properties:
-
-- `api`: a set of utility methods used to send requests to the Medusa application. It has the following methods:
-  - `get`: Send a `GET` request to an API route.
-  - `post`: Send a `POST` request to an API route.
-  - `delete`: Send a `DELETE` request to an API route.
-- `getContainer`: a function that retrieves the Medusa Container. Use the `getContainer().resolve` method to resolve resources from the Medusa Container.
-
-The tests in the `testSuite` function are written using [Jest](https://jestjs.io/).
-
-### Jest Timeout
-
-Since your tests connect to the database and perform actions that require more time than the typical tests, make sure to increase the timeout in your test:
-
-```ts title="integration-tests/http/test.spec.ts"
-// in your test's file
-jest.setTimeout(60 * 1000)
-```
-
-***
-
-### Run Tests
-
-Run the following command to run your tests:
-
-```bash npm2yarn
-npm run test:integration
-```
-
-If you don't have a `test:integration` script in `package.json`, refer to the [Medusa Testing Tools chapter](https://docs.medusajs.com/learn/debugging-and-testing/testing-tools#add-test-commands/index.html.md).
-
-This runs your Medusa application and runs the tests available under the `src/integrations/http` directory.
-
-***
-
-## Other Options and Inputs
-
-Refer to [the Test Tooling Reference](https://docs.medusajs.com/resources/test-tools-reference/medusaIntegrationTestRunner/index.html.md) for other available parameter options and inputs of the `testSuite` function.
-
-***
-
-## Database Used in Tests
-
-The `medusaIntegrationTestRunner` function creates a database with a random name before running the tests. Then, it drops that database after all the tests end.
-
-To manage that database, such as changing its name or perform operations on it in your tests, refer to [the Test Tooling Reference](https://docs.medusajs.com/resources/test-tools-reference/medusaIntegrationTestRunner/index.html.md).
-
-***
-
-## Example Integration Tests
-
-The next chapters provide examples of writing integration tests for API routes and workflows.
-
-
-# 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: 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.
@@ -5148,144 +4947,6 @@ Now that you have brands in your Medusa application, you want to associate a bra
 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: Implement Brand Module
 
 In this chapter, you'll build a Brand Module that adds a `brand` table to the database and provides data-management features for it.
@@ -5444,6 +5105,416 @@ 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 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: 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.
+
+In another previous chapter, you [added a workflow](https://docs.medusajs.com/learn/customization/custom-features/workflow/index.html.md) that creates a brand. After integrating the CMS, you want to sync that brand to the third-party system as well.
+
+Medusa has an event system that emits events when an operation is performed. It allows you to listen to those events and perform an asynchronous action in a function called a [subscriber](https://docs.medusajs.com/learn/fundamentals/events-and-subscribers/index.html.md). This is useful to perform actions that aren't integral to the original flow, such as syncing data to a third-party system.
+
+Learn more about Medusa's event system and subscribers in [this chapter](https://docs.medusajs.com/learn/fundamentals/events-and-subscribers/index.html.md).
+
+In this chapter, you'll modify the `createBrandWorkflow` you created before to emit a custom event that indicates a brand was created. Then, you'll listen to that event in a subscriber to sync the brand to the third-party CMS. You'll implement the sync logic within a workflow that you execute in the subscriber.
+
+### Prerequisites
+
+- [createBrandWorkflow](https://docs.medusajs.com/learn/customization/custom-features/workflow/index.html.md)
+- [CMS Module](https://docs.medusajs.com/learn/customization/integrate-systems/service/index.html.md)
+
+## 1. Emit Event in createBrandWorkflow
+
+Since syncing the brand to the third-party system isn't integral to creating a brand, you'll emit a custom event indicating that a brand was created.
+
+Medusa provides an `emitEventStep` that allows you to emit an event in your workflows. So, in the `createBrandWorkflow` defined in `src/workflows/create-brand.ts`, use the `emitEventStep` helper step after the `createBrandStep`:
+
+```ts title="src/workflows/create-brand.ts" highlights={eventHighlights}
+// other imports...
+import { 
+  emitEventStep,
+} from "@medusajs/medusa/core-flows"
+
+// ...
+
+export const createBrandWorkflow = createWorkflow(
+  "create-brand",
+  (input: CreateBrandInput) => {
+    // ...
+
+    emitEventStep({
+      eventName: "brand.created",
+      data: {
+        id: brand.id,
+      },
+    })
+
+    return new WorkflowResponse(brand)
+  }
+)
+```
+
+The `emitEventStep` accepts an object parameter having two properties:
+
+- `eventName`: The name of the event to emit. You'll use this name later to listen to the event in a subscriber.
+- `data`: The data payload to emit with the event. This data is passed to subscribers that listen to the event. You add the brand's ID to the data payload, informing the subscribers which brand was created.
+
+You'll learn how to handle this event in a later step.
+
+***
+
+## 2. Create Sync to Third-Party System Workflow
+
+The subscriber that will listen to the `brand.created` event will sync the created brand to the third-party CMS. So, you'll implement the syncing logic in a workflow, then execute the workflow in the subscriber.
+
+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).
+
+You'll create a `syncBrandToSystemWorkflow` that has two steps:
+
+- `useQueryGraphStep`: a step that Medusa provides to retrieve data using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query/index.html.md). You'll use this to retrieve the brand's details using its ID.
+- `syncBrandToCmsStep`: a step that you'll create to sync the brand to the CMS.
+
+### syncBrandToCmsStep
+
+To implement the step that syncs the brand to the CMS, create the file `src/workflows/sync-brands-to-cms.ts` with the following content:
+
+![Directory structure of the Medusa application after adding the file](https://res.cloudinary.com/dza7lstvk/image/upload/v1733493547/Medusa%20Book/cms-dir-overview-4_u5t0ug.jpg)
+
+```ts title="src/workflows/sync-brands-to-cms.ts" highlights={syncStepHighlights} collapsibleLines="1-6" expandButtonLabel="Show Imports"
+import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk"
+import { InferTypeOf } from "@medusajs/framework/types"
+import { Brand } from "../modules/brand/models/brand"
+import { CMS_MODULE } from "../modules/cms"
+import CmsModuleService from "../modules/cms/service"
+
+type SyncBrandToCmsStepInput = {
+  brand: InferTypeOf<typeof Brand>
+}
+
+const syncBrandToCmsStep = createStep(
+  "sync-brand-to-cms",
+  async ({ brand }: SyncBrandToCmsStepInput, { container }) => {
+    const cmsModuleService: CmsModuleService = container.resolve(CMS_MODULE)
+
+    await cmsModuleService.createBrand(brand)
+
+    return new StepResponse(null, brand.id)
+  },
+  async (id, { container }) => {
+    if (!id) {
+      return
+    }
+
+    const cmsModuleService: CmsModuleService = container.resolve(CMS_MODULE)
+
+    await cmsModuleService.deleteBrand(id)
+  }
+)
+```
+
+You create the `syncBrandToCmsStep` that accepts a brand as an input. In the step, you resolve the CMS Module's service from the [Medusa container](https://docs.medusajs.com/learn/fundamentals/medusa-container/index.html.md) and use its `createBrand` method. This method will create the brand in the third-party CMS.
+
+You also pass the brand's ID to the step's compensation function. In this function, you delete the brand in the third-party CMS 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).
+
+### Create Workflow
+
+You can now create the workflow that uses the above step. Add the workflow to the same `src/workflows/sync-brands-to-cms.ts` file:
+
+```ts title="src/workflows/sync-brands-to-cms.ts" highlights={syncWorkflowHighlights}
+// other imports...
+import { 
+  // ...
+  createWorkflow, 
+  WorkflowResponse,
+} from "@medusajs/framework/workflows-sdk"
+import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
+
+// ...
+
+type SyncBrandToCmsWorkflowInput = {
+  id: string
+}
+
+export const syncBrandToCmsWorkflow = createWorkflow(
+  "sync-brand-to-cms",
+  (input: SyncBrandToCmsWorkflowInput) => {
+    // @ts-ignore
+    const { data: brands } = useQueryGraphStep({
+      entity: "brand",
+      fields: ["*"],
+      filters: {
+        id: input.id,
+      },
+      options: {
+        throwIfKeyNotFound: true,
+      },
+    })
+
+    syncBrandToCmsStep({
+      brand: brands[0],
+    } as SyncBrandToCmsStepInput)
+
+    return new WorkflowResponse({})
+  }
+)
+```
+
+You create a `syncBrandToCmsWorkflow` that accepts the brand's ID as input. The workflow has the following steps:
+
+- `useQueryGraphStep`: Retrieve the brand's details using Query. You pass the brand's ID as a filter, and set the `throwIfKeyNotFound` option to true so that the step throws an error if a brand with the specified ID doesn't exist.
+- `syncBrandToCmsStep`: Create the brand in the third-party CMS.
+
+You'll execute this workflow in the subscriber next.
+
+Learn more about `useQueryGraphStep` in [this reference](https://docs.medusajs.com/resources/references/helper-steps/useQueryGraphStep/index.html.md).
+
+***
+
+## 3. Handle brand.created Event
+
+You now have a workflow with the logic to sync a brand to the CMS. You need to execute this workflow whenever the `brand.created` event is emitted. So, you'll create a subscriber that listens to and handle the event.
+
+Subscribers are created in a TypeScript or JavaScript file under the `src/subscribers` directory. So, create the file `src/subscribers/brand-created.ts` with the following content:
+
+![Directory structure of the Medusa application after adding the subscriber](https://res.cloudinary.com/dza7lstvk/image/upload/v1733493774/Medusa%20Book/cms-dir-overview-5_iqqwvg.jpg)
+
+```ts title="src/subscribers/brand-created.ts" highlights={subscriberHighlights}
+import type {
+  SubscriberConfig,
+  SubscriberArgs,
+} from "@medusajs/framework"
+import { syncBrandToCmsWorkflow } from "../workflows/sync-brands-to-cms"
+
+export default async function brandCreatedHandler({
+  event: { data },
+  container,
+}: SubscriberArgs<{ id: string }>) {
+  await syncBrandToCmsWorkflow(container).run({
+    input: data,
+  })
+}
+
+export const config: SubscriberConfig = {
+  event: "brand.created",
+}
+```
+
+A subscriber file must export:
+
+- The asynchronous function that's executed when the event is emitted. This must be the file's default export.
+- An object that holds the subscriber's configurations. It has an `event` property that indicates the name of the event that the subscriber is listening to.
+
+The subscriber function accepts an object parameter that has two properties:
+
+- `event`: An object of event details. Its `data` property holds the event's data payload, which is the brand's ID.
+- `container`: The Medusa container used to resolve Framework and commerce tools.
+
+In the function, you execute the `syncBrandToCmsWorkflow`, passing it the data payload as an input. So, everytime a brand is created, Medusa will execute this function, which in turn executes the workflow to sync the brand to the CMS.
+
+Learn more about subscribers in [this chapter](https://docs.medusajs.com/learn/fundamentals/events-and-subscribers/index.html.md).
+
+***
+
+## Test it Out
+
+To test the subscriber and workflow out, you'll use the [Create Brand API route](https://docs.medusajs.com/learn/customization/custom-features/api-route/index.html.md) you created in a previous chapter.
+
+First, start the Medusa application:
+
+```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 request returns the created brand. If you check the logs, you'll find the `brand.created` event was emitted, and that the request to the third-party system was simulated:
+
+```plain
+info:    Processing brand.created which has 1 subscribers
+http:    POST /admin/brands ← - (200) - 16.418 ms
+info:    Sending a POST request to /brands.
+info:    Request Data: {
+  "id": "01JEDWENYD361P664WRQPMC3J8",
+  "name": "Acme",
+  "created_at": "2024-12-06T11:42:32.909Z",
+  "updated_at": "2024-12-06T11:42:32.909Z",
+  "deleted_at": null
+}
+info:    API Key: "123"
+```
+
+***
+
+## Next Chapter: Sync Brand from Third-Party CMS to Medusa
+
+You can also automate syncing data from a third-party system to Medusa at a regular interval. In the next chapter, you'll learn how to sync brands from the third-party CMS to Medusa once a day.
+
+
 # Create Brands UI Route in Admin
 
 In this chapter, you'll add a UI route to the admin dashboard that shows all [brands](https://docs.medusajs.com/learn/customization/custom-features/module/index.html.md) in a new page. You'll retrieve the brands from the server and display them in a table with pagination.
@@ -5816,278 +5887,6 @@ Your customizations often span across systems, where you need to retrieve data o
 In the next chapters, you'll learn about the concepts that facilitate integrating third-party systems in your application. You'll integrate a dummy third-party system and sync the brands between it and the Medusa application.
 
 
-# Guide: 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.
-
-In another previous chapter, you [added a workflow](https://docs.medusajs.com/learn/customization/custom-features/workflow/index.html.md) that creates a brand. After integrating the CMS, you want to sync that brand to the third-party system as well.
-
-Medusa has an event system that emits events when an operation is performed. It allows you to listen to those events and perform an asynchronous action in a function called a [subscriber](https://docs.medusajs.com/learn/fundamentals/events-and-subscribers/index.html.md). This is useful to perform actions that aren't integral to the original flow, such as syncing data to a third-party system.
-
-Learn more about Medusa's event system and subscribers in [this chapter](https://docs.medusajs.com/learn/fundamentals/events-and-subscribers/index.html.md).
-
-In this chapter, you'll modify the `createBrandWorkflow` you created before to emit a custom event that indicates a brand was created. Then, you'll listen to that event in a subscriber to sync the brand to the third-party CMS. You'll implement the sync logic within a workflow that you execute in the subscriber.
-
-### Prerequisites
-
-- [createBrandWorkflow](https://docs.medusajs.com/learn/customization/custom-features/workflow/index.html.md)
-- [CMS Module](https://docs.medusajs.com/learn/customization/integrate-systems/service/index.html.md)
-
-## 1. Emit Event in createBrandWorkflow
-
-Since syncing the brand to the third-party system isn't integral to creating a brand, you'll emit a custom event indicating that a brand was created.
-
-Medusa provides an `emitEventStep` that allows you to emit an event in your workflows. So, in the `createBrandWorkflow` defined in `src/workflows/create-brand.ts`, use the `emitEventStep` helper step after the `createBrandStep`:
-
-```ts title="src/workflows/create-brand.ts" highlights={eventHighlights}
-// other imports...
-import { 
-  emitEventStep,
-} from "@medusajs/medusa/core-flows"
-
-// ...
-
-export const createBrandWorkflow = createWorkflow(
-  "create-brand",
-  (input: CreateBrandInput) => {
-    // ...
-
-    emitEventStep({
-      eventName: "brand.created",
-      data: {
-        id: brand.id,
-      },
-    })
-
-    return new WorkflowResponse(brand)
-  }
-)
-```
-
-The `emitEventStep` accepts an object parameter having two properties:
-
-- `eventName`: The name of the event to emit. You'll use this name later to listen to the event in a subscriber.
-- `data`: The data payload to emit with the event. This data is passed to subscribers that listen to the event. You add the brand's ID to the data payload, informing the subscribers which brand was created.
-
-You'll learn how to handle this event in a later step.
-
-***
-
-## 2. Create Sync to Third-Party System Workflow
-
-The subscriber that will listen to the `brand.created` event will sync the created brand to the third-party CMS. So, you'll implement the syncing logic in a workflow, then execute the workflow in the subscriber.
-
-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).
-
-You'll create a `syncBrandToSystemWorkflow` that has two steps:
-
-- `useQueryGraphStep`: a step that Medusa provides to retrieve data using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query/index.html.md). You'll use this to retrieve the brand's details using its ID.
-- `syncBrandToCmsStep`: a step that you'll create to sync the brand to the CMS.
-
-### syncBrandToCmsStep
-
-To implement the step that syncs the brand to the CMS, create the file `src/workflows/sync-brands-to-cms.ts` with the following content:
-
-![Directory structure of the Medusa application after adding the file](https://res.cloudinary.com/dza7lstvk/image/upload/v1733493547/Medusa%20Book/cms-dir-overview-4_u5t0ug.jpg)
-
-```ts title="src/workflows/sync-brands-to-cms.ts" highlights={syncStepHighlights} collapsibleLines="1-6" expandButtonLabel="Show Imports"
-import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk"
-import { InferTypeOf } from "@medusajs/framework/types"
-import { Brand } from "../modules/brand/models/brand"
-import { CMS_MODULE } from "../modules/cms"
-import CmsModuleService from "../modules/cms/service"
-
-type SyncBrandToCmsStepInput = {
-  brand: InferTypeOf<typeof Brand>
-}
-
-const syncBrandToCmsStep = createStep(
-  "sync-brand-to-cms",
-  async ({ brand }: SyncBrandToCmsStepInput, { container }) => {
-    const cmsModuleService: CmsModuleService = container.resolve(CMS_MODULE)
-
-    await cmsModuleService.createBrand(brand)
-
-    return new StepResponse(null, brand.id)
-  },
-  async (id, { container }) => {
-    if (!id) {
-      return
-    }
-
-    const cmsModuleService: CmsModuleService = container.resolve(CMS_MODULE)
-
-    await cmsModuleService.deleteBrand(id)
-  }
-)
-```
-
-You create the `syncBrandToCmsStep` that accepts a brand as an input. In the step, you resolve the CMS Module's service from the [Medusa container](https://docs.medusajs.com/learn/fundamentals/medusa-container/index.html.md) and use its `createBrand` method. This method will create the brand in the third-party CMS.
-
-You also pass the brand's ID to the step's compensation function. In this function, you delete the brand in the third-party CMS 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).
-
-### Create Workflow
-
-You can now create the workflow that uses the above step. Add the workflow to the same `src/workflows/sync-brands-to-cms.ts` file:
-
-```ts title="src/workflows/sync-brands-to-cms.ts" highlights={syncWorkflowHighlights}
-// other imports...
-import { 
-  // ...
-  createWorkflow, 
-  WorkflowResponse,
-} from "@medusajs/framework/workflows-sdk"
-import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
-
-// ...
-
-type SyncBrandToCmsWorkflowInput = {
-  id: string
-}
-
-export const syncBrandToCmsWorkflow = createWorkflow(
-  "sync-brand-to-cms",
-  (input: SyncBrandToCmsWorkflowInput) => {
-    // @ts-ignore
-    const { data: brands } = useQueryGraphStep({
-      entity: "brand",
-      fields: ["*"],
-      filters: {
-        id: input.id,
-      },
-      options: {
-        throwIfKeyNotFound: true,
-      },
-    })
-
-    syncBrandToCmsStep({
-      brand: brands[0],
-    } as SyncBrandToCmsStepInput)
-
-    return new WorkflowResponse({})
-  }
-)
-```
-
-You create a `syncBrandToCmsWorkflow` that accepts the brand's ID as input. The workflow has the following steps:
-
-- `useQueryGraphStep`: Retrieve the brand's details using Query. You pass the brand's ID as a filter, and set the `throwIfKeyNotFound` option to true so that the step throws an error if a brand with the specified ID doesn't exist.
-- `syncBrandToCmsStep`: Create the brand in the third-party CMS.
-
-You'll execute this workflow in the subscriber next.
-
-Learn more about `useQueryGraphStep` in [this reference](https://docs.medusajs.com/resources/references/helper-steps/useQueryGraphStep/index.html.md).
-
-***
-
-## 3. Handle brand.created Event
-
-You now have a workflow with the logic to sync a brand to the CMS. You need to execute this workflow whenever the `brand.created` event is emitted. So, you'll create a subscriber that listens to and handle the event.
-
-Subscribers are created in a TypeScript or JavaScript file under the `src/subscribers` directory. So, create the file `src/subscribers/brand-created.ts` with the following content:
-
-![Directory structure of the Medusa application after adding the subscriber](https://res.cloudinary.com/dza7lstvk/image/upload/v1733493774/Medusa%20Book/cms-dir-overview-5_iqqwvg.jpg)
-
-```ts title="src/subscribers/brand-created.ts" highlights={subscriberHighlights}
-import type {
-  SubscriberConfig,
-  SubscriberArgs,
-} from "@medusajs/framework"
-import { syncBrandToCmsWorkflow } from "../workflows/sync-brands-to-cms"
-
-export default async function brandCreatedHandler({
-  event: { data },
-  container,
-}: SubscriberArgs<{ id: string }>) {
-  await syncBrandToCmsWorkflow(container).run({
-    input: data,
-  })
-}
-
-export const config: SubscriberConfig = {
-  event: "brand.created",
-}
-```
-
-A subscriber file must export:
-
-- The asynchronous function that's executed when the event is emitted. This must be the file's default export.
-- An object that holds the subscriber's configurations. It has an `event` property that indicates the name of the event that the subscriber is listening to.
-
-The subscriber function accepts an object parameter that has two properties:
-
-- `event`: An object of event details. Its `data` property holds the event's data payload, which is the brand's ID.
-- `container`: The Medusa container used to resolve Framework and commerce tools.
-
-In the function, you execute the `syncBrandToCmsWorkflow`, passing it the data payload as an input. So, everytime a brand is created, Medusa will execute this function, which in turn executes the workflow to sync the brand to the CMS.
-
-Learn more about subscribers in [this chapter](https://docs.medusajs.com/learn/fundamentals/events-and-subscribers/index.html.md).
-
-***
-
-## Test it Out
-
-To test the subscriber and workflow out, you'll use the [Create Brand API route](https://docs.medusajs.com/learn/customization/custom-features/api-route/index.html.md) you created in a previous chapter.
-
-First, start the Medusa application:
-
-```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 request returns the created brand. If you check the logs, you'll find the `brand.created` event was emitted, and that the request to the third-party system was simulated:
-
-```plain
-info:    Processing brand.created which has 1 subscribers
-http:    POST /admin/brands ← - (200) - 16.418 ms
-info:    Sending a POST request to /brands.
-info:    Request Data: {
-  "id": "01JEDWENYD361P664WRQPMC3J8",
-  "name": "Acme",
-  "created_at": "2024-12-06T11:42:32.909Z",
-  "updated_at": "2024-12-06T11:42:32.909Z",
-  "deleted_at": null
-}
-info:    API Key: "123"
-```
-
-***
-
-## Next Chapter: Sync Brand from Third-Party CMS to Medusa
-
-You can also automate syncing data from a third-party system to Medusa at a regular interval. In the next chapter, you'll learn how to sync brands from the third-party CMS to Medusa once a day.
-
-
 # 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.
@@ -6710,154 +6509,6 @@ You can now use the CMS Module's service to perform actions on the third-party C
 In the next chapter, you'll learn how to emit an event when a brand is created, then handle that event to sync the brand from Medusa to the third-party service.
 
 
-# Guide: Query Product's Brands
-
-In the previous chapters, you [defined a link](https://docs.medusajs.com/learn/customization/extend-features/define-link/index.html.md) between the [custom Brand Module](https://docs.medusajs.com/learn/customization/custom-features/module/index.html.md) and Medusa's [Product Module](https://docs.medusajs.com/resources/commerce-modules/product/index.html.md), then [extended the create-product flow](https://docs.medusajs.com/learn/customization/extend-features/extend-create-product/index.html.md) to link a product to a brand.
-
-In this chapter, you'll learn how to retrieve a product's brand (and vice-versa) in two ways: Using Medusa's existing API route, or in customizations, such as a custom API route.
-
-### Prerequisites
-
-- [Brand Module](https://docs.medusajs.com/learn/customization/custom-features/module/index.html.md)
-- [Defined link between the Brand and Product data models.](https://docs.medusajs.com/learn/customization/extend-features/define-link/index.html.md)
-
-***
-
-## Approach 1: Retrieve Brands in Existing API Routes
-
-Medusa's existing API routes accept a `fields` query parameter that allows you to specify the fields and relations of a model to retrieve. So, when you send a request to the [List Products](https://docs.medusajs.com/api/admin#products_getproducts), [Get Product](https://docs.medusajs.com/api/admin#products_getproductsid), or any product-related store or admin routes that accept a `fields` query parameter, you can specify in this parameter to return the product's brands.
-
-Learn more about using the `fields` query parameter to retrieve custom linked data models in the [Retrieve Custom Linked Data Models from Medusa's API Routes](https://docs.medusajs.com/learn/fundamentals/api-routes/retrieve-custom-links/index.html.md) chapter.
-
-For example, send the following request to retrieve the list of products with their brands:
-
-```bash
-curl 'http://localhost:9000/admin/products?fields=+brand.*' \
---header 'Authorization: Bearer {token}'
-```
-
-Make sure to replace `{token}` with your admin user's authentication token. Learn how to retrieve it in the [API reference](https://docs.medusajs.com/api/store#authentication).
-
-Any product that is linked to a brand will have a `brand` property in its object:
-
-```json title="Example Product Object"
-{
-  "id": "prod_123",
-  // ...
-  "brand": {
-    "id": "01JEB44M61BRM3ARM2RRMK7GJF",
-    "name": "Acme",
-    "created_at": "2024-12-05T09:59:08.737Z",
-    "updated_at": "2024-12-05T09:59:08.737Z",
-    "deleted_at": null
-  }
-}
-```
-
-By using the `fields` query parameter, you don't have to re-create existing API routes to get custom data models that you linked to core data models.
-
-### Limitations: Filtering by Brands in Existing API Routes
-
-While you can retrieve linked records using the `fields` query parameter of an existing API route, you can't filter by linked records.
-
-Instead, you'll have to create a custom API route that uses Query to retrieve linked records with filters, as explained in the [Query documentation](https://docs.medusajs.com/learn/fundamentals/module-links/query#apply-filters-and-pagination-on-linked-records/index.html.md).
-
-***
-
-## Approach 2: Use Query to Retrieve Linked Records
-
-You can also retrieve linked records using Query. Query allows you to retrieve data across modules with filters, pagination, and more. You can resolve Query from the Medusa container and use it in your API route or workflow.
-
-Learn more about Query in [this chapter](https://docs.medusajs.com/learn/fundamentals/module-links/query/index.html.md).
-
-For example, you can create an API route that retrieves brands and their products. If you followed the [Create Brands API route chapter](https://docs.medusajs.com/learn/customization/custom-features/api-route/index.html.md), you'll have the file `src/api/admin/brands/route.ts` with a `POST` API route. Add a new `GET` function to the same file:
-
-```ts title="src/api/admin/brands/route.ts" highlights={highlights}
-// other imports...
-import {
-  MedusaRequest,
-  MedusaResponse,
-} from "@medusajs/framework/http"
-
-export const GET = async (
-  req: MedusaRequest,
-  res: MedusaResponse
-) => {
-  const query = req.scope.resolve("query")
-  
-  const { data: brands } = await query.graph({
-    entity: "brand",
-    fields: ["*", "products.*"],
-  })
-
-  res.json({ brands })
-}
-```
-
-This adds a `GET` API route at `/admin/brands`. In the API route, you resolve Query from the Medusa container. Query has a `graph` method that runs a query to retrieve data. It accepts an object having the following properties:
-
-- `entity`: The data model's name as specified in the first parameter of `model.define`.
-- `fields`: An array of properties and relations to retrieve. You can pass:
-  - A property's name, such as `id`, or `*` for all properties.
-  - A relation or linked model's name, such as `products` (use the plural name since brands are linked to list of products). You suffix the name with `.*` to retrieve all its properties.
-
-`graph` returns an object having a `data` property, which is the retrieved brands. You return the brands in the response.
-
-### Test it Out
-
-To test the API route out, send a `GET` request to `/admin/brands`:
-
-```bash
-curl 'http://localhost:9000/admin/brands' \
--H 'Authorization: Bearer {token}'
-```
-
-Make sure to replace `{token}` with your admin user's authentication token. Learn how to retrieve it in the [API reference](https://docs.medusajs.com/api/store#authentication).
-
-This returns the brands in your store with their linked products. For example:
-
-```json title="Example Response"
-{
-  "brands": [
-    {
-      "id": "123",
-      // ...
-      "products": [
-        {
-          "id": "prod_123",
-          // ...
-        }
-      ]
-    }
-  ]
-}
-```
-
-### Limitations: Filtering by Brand in Query
-
-While you can use Query to retrieve linked records, you can't filter by linked records.
-
-For an alternative approach, refer to the [Query documentation](https://docs.medusajs.com/learn/fundamentals/module-links/query#apply-filters-and-pagination-on-linked-records/index.html.md).
-
-***
-
-## Summary
-
-By following the examples of the previous chapters, you:
-
-- Defined a link between the Brand and Product modules's data models, allowing you to associate a product with a brand.
-- Extended the create-product workflow and route to allow setting the product's brand while creating the product.
-- Queried a product's brand, and vice versa.
-
-***
-
-## Next Steps: Customize Medusa Admin
-
-Clients, such as the Medusa Admin dashboard, can now use brand-related features, such as creating a brand or setting the brand of a product.
-
-In the next chapters, you'll learn how to customize the Medusa Admin to show a product's brand on its details page, and to show a new page with the list of brands in your store.
-
-
 # Guide: 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.
@@ -7140,6 +6791,154 @@ You can also run the `npx medusa db:sync-links` to just sync module links withou
 In the next chapter, you'll extend Medusa's workflow and API route that create a product to allow associating a brand with a product. You'll also learn how to link brand and product records.
 
 
+# Guide: Query Product's Brands
+
+In the previous chapters, you [defined a link](https://docs.medusajs.com/learn/customization/extend-features/define-link/index.html.md) between the [custom Brand Module](https://docs.medusajs.com/learn/customization/custom-features/module/index.html.md) and Medusa's [Product Module](https://docs.medusajs.com/resources/commerce-modules/product/index.html.md), then [extended the create-product flow](https://docs.medusajs.com/learn/customization/extend-features/extend-create-product/index.html.md) to link a product to a brand.
+
+In this chapter, you'll learn how to retrieve a product's brand (and vice-versa) in two ways: Using Medusa's existing API route, or in customizations, such as a custom API route.
+
+### Prerequisites
+
+- [Brand Module](https://docs.medusajs.com/learn/customization/custom-features/module/index.html.md)
+- [Defined link between the Brand and Product data models.](https://docs.medusajs.com/learn/customization/extend-features/define-link/index.html.md)
+
+***
+
+## Approach 1: Retrieve Brands in Existing API Routes
+
+Medusa's existing API routes accept a `fields` query parameter that allows you to specify the fields and relations of a model to retrieve. So, when you send a request to the [List Products](https://docs.medusajs.com/api/admin#products_getproducts), [Get Product](https://docs.medusajs.com/api/admin#products_getproductsid), or any product-related store or admin routes that accept a `fields` query parameter, you can specify in this parameter to return the product's brands.
+
+Learn more about using the `fields` query parameter to retrieve custom linked data models in the [Retrieve Custom Linked Data Models from Medusa's API Routes](https://docs.medusajs.com/learn/fundamentals/api-routes/retrieve-custom-links/index.html.md) chapter.
+
+For example, send the following request to retrieve the list of products with their brands:
+
+```bash
+curl 'http://localhost:9000/admin/products?fields=+brand.*' \
+--header 'Authorization: Bearer {token}'
+```
+
+Make sure to replace `{token}` with your admin user's authentication token. Learn how to retrieve it in the [API reference](https://docs.medusajs.com/api/store#authentication).
+
+Any product that is linked to a brand will have a `brand` property in its object:
+
+```json title="Example Product Object"
+{
+  "id": "prod_123",
+  // ...
+  "brand": {
+    "id": "01JEB44M61BRM3ARM2RRMK7GJF",
+    "name": "Acme",
+    "created_at": "2024-12-05T09:59:08.737Z",
+    "updated_at": "2024-12-05T09:59:08.737Z",
+    "deleted_at": null
+  }
+}
+```
+
+By using the `fields` query parameter, you don't have to re-create existing API routes to get custom data models that you linked to core data models.
+
+### Limitations: Filtering by Brands in Existing API Routes
+
+While you can retrieve linked records using the `fields` query parameter of an existing API route, you can't filter by linked records.
+
+Instead, you'll have to create a custom API route that uses Query to retrieve linked records with filters, as explained in the [Query documentation](https://docs.medusajs.com/learn/fundamentals/module-links/query#apply-filters-and-pagination-on-linked-records/index.html.md).
+
+***
+
+## Approach 2: Use Query to Retrieve Linked Records
+
+You can also retrieve linked records using Query. Query allows you to retrieve data across modules with filters, pagination, and more. You can resolve Query from the Medusa container and use it in your API route or workflow.
+
+Learn more about Query in [this chapter](https://docs.medusajs.com/learn/fundamentals/module-links/query/index.html.md).
+
+For example, you can create an API route that retrieves brands and their products. If you followed the [Create Brands API route chapter](https://docs.medusajs.com/learn/customization/custom-features/api-route/index.html.md), you'll have the file `src/api/admin/brands/route.ts` with a `POST` API route. Add a new `GET` function to the same file:
+
+```ts title="src/api/admin/brands/route.ts" highlights={highlights}
+// other imports...
+import {
+  MedusaRequest,
+  MedusaResponse,
+} from "@medusajs/framework/http"
+
+export const GET = async (
+  req: MedusaRequest,
+  res: MedusaResponse
+) => {
+  const query = req.scope.resolve("query")
+  
+  const { data: brands } = await query.graph({
+    entity: "brand",
+    fields: ["*", "products.*"],
+  })
+
+  res.json({ brands })
+}
+```
+
+This adds a `GET` API route at `/admin/brands`. In the API route, you resolve Query from the Medusa container. Query has a `graph` method that runs a query to retrieve data. It accepts an object having the following properties:
+
+- `entity`: The data model's name as specified in the first parameter of `model.define`.
+- `fields`: An array of properties and relations to retrieve. You can pass:
+  - A property's name, such as `id`, or `*` for all properties.
+  - A relation or linked model's name, such as `products` (use the plural name since brands are linked to list of products). You suffix the name with `.*` to retrieve all its properties.
+
+`graph` returns an object having a `data` property, which is the retrieved brands. You return the brands in the response.
+
+### Test it Out
+
+To test the API route out, send a `GET` request to `/admin/brands`:
+
+```bash
+curl 'http://localhost:9000/admin/brands' \
+-H 'Authorization: Bearer {token}'
+```
+
+Make sure to replace `{token}` with your admin user's authentication token. Learn how to retrieve it in the [API reference](https://docs.medusajs.com/api/store#authentication).
+
+This returns the brands in your store with their linked products. For example:
+
+```json title="Example Response"
+{
+  "brands": [
+    {
+      "id": "123",
+      // ...
+      "products": [
+        {
+          "id": "prod_123",
+          // ...
+        }
+      ]
+    }
+  ]
+}
+```
+
+### Limitations: Filtering by Brand in Query
+
+While you can use Query to retrieve linked records, you can't filter by linked records.
+
+For an alternative approach, refer to the [Query documentation](https://docs.medusajs.com/learn/fundamentals/module-links/query#apply-filters-and-pagination-on-linked-records/index.html.md).
+
+***
+
+## Summary
+
+By following the examples of the previous chapters, you:
+
+- Defined a link between the Brand and Product modules's data models, allowing you to associate a product with a brand.
+- Extended the create-product workflow and route to allow setting the product's brand while creating the product.
+- Queried a product's brand, and vice versa.
+
+***
+
+## Next Steps: Customize Medusa Admin
+
+Clients, such as the Medusa Admin dashboard, can now use brand-related features, such as creating a brand or setting the brand of a product.
+
+In the next chapters, you'll learn how to customize the Medusa Admin to show a product's brand on its details page, and to show a new page with the list of brands in your store.
+
+
 # Admin Development Constraints
 
 This chapter lists some constraints of admin widgets and UI routes.
@@ -7185,6 +6984,284 @@ export const config = defineWidgetConfig({
 ```
 
 
+# Write Integration Tests
+
+In this chapter, you'll learn about `medusaIntegrationTestRunner` from Medusa's Testing Framework and how to use it to write integration tests.
+
+### Prerequisites
+
+- [Testing Tools Setup](https://docs.medusajs.com/learn/debugging-and-testing/testing-tools/index.html.md)
+
+## medusaIntegrationTestRunner Utility
+
+The `medusaIntegrationTestRunner` is from Medusa's Testing Framework and it's used to create integration tests in your Medusa project. It runs a full Medusa application, allowing you test API routes, workflows, or other customizations.
+
+For example:
+
+```ts title="integration-tests/http/test.spec.ts" highlights={highlights}
+import { medusaIntegrationTestRunner } from "@medusajs/test-utils"
+
+medusaIntegrationTestRunner({
+  testSuite: ({ api, getContainer }) => {
+    // TODO write tests...
+  },
+})
+
+jest.setTimeout(60 * 1000)
+```
+
+The `medusaIntegrationTestRunner` function accepts an object as a parameter. The object has a required property `testSuite`.
+
+`testSuite`'s value is a function that defines the tests to run. The function accepts as a parameter an object that has the following properties:
+
+- `api`: a set of utility methods used to send requests to the Medusa application. It has the following methods:
+  - `get`: Send a `GET` request to an API route.
+  - `post`: Send a `POST` request to an API route.
+  - `delete`: Send a `DELETE` request to an API route.
+- `getContainer`: a function that retrieves the Medusa Container. Use the `getContainer().resolve` method to resolve resources from the Medusa Container.
+
+The tests in the `testSuite` function are written using [Jest](https://jestjs.io/).
+
+### Jest Timeout
+
+Since your tests connect to the database and perform actions that require more time than the typical tests, make sure to increase the timeout in your test:
+
+```ts title="integration-tests/http/test.spec.ts"
+// in your test's file
+jest.setTimeout(60 * 1000)
+```
+
+***
+
+### Run Tests
+
+Run the following command to run your tests:
+
+```bash npm2yarn
+npm run test:integration
+```
+
+If you don't have a `test:integration` script in `package.json`, refer to the [Medusa Testing Tools chapter](https://docs.medusajs.com/learn/debugging-and-testing/testing-tools#add-test-commands/index.html.md).
+
+This runs your Medusa application and runs the tests available under the `src/integrations/http` directory.
+
+***
+
+## Other Options and Inputs
+
+Refer to [the Test Tooling Reference](https://docs.medusajs.com/resources/test-tools-reference/medusaIntegrationTestRunner/index.html.md) for other available parameter options and inputs of the `testSuite` function.
+
+***
+
+## Database Used in Tests
+
+The `medusaIntegrationTestRunner` function creates a database with a random name before running the tests. Then, it drops that database after all the tests end.
+
+To manage that database, such as changing its name or perform operations on it in your tests, refer to [the Test Tooling Reference](https://docs.medusajs.com/resources/test-tools-reference/medusaIntegrationTestRunner/index.html.md).
+
+***
+
+## Example Integration Tests
+
+The next chapters provide examples of writing integration tests for API routes and workflows.
+
+
+# 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).
+
+
+# Environment Variables in Admin Customizations
+
+In this chapter, you'll learn how to use environment variables in your admin customizations.
+
+To learn how environment variables are generally loaded in Medusa based on your application's environment, check out [this chapter](https://docs.medusajs.com/learn/fundamentals/environment-variables/index.html.md).
+
+## How to Set Environment Variables
+
+The Medusa Admin is built on top of [Vite](https://vite.dev/). To set an environment variable that you want to use in a widget or UI route, prefix the environment variable with `VITE_`.
+
+For example:
+
+```plain
+VITE_MY_API_KEY=sk_123
+```
+
+***
+
+## How to Use Environment Variables
+
+To access or use an environment variable starting with `VITE_`, use the `import.meta.env` object.
+
+For example:
+
+```tsx highlights={[["8"]]}
+import { defineWidgetConfig } from "@medusajs/admin-sdk"
+import { Container, Heading } from "@medusajs/ui"
+
+const ProductWidget = () => {
+  return (
+    <Container className="divide-y p-0">
+      <div className="flex items-center justify-between px-6 py-4">
+        <Heading level="h2">API Key: {import.meta.env.VITE_MY_API_KEY}</Heading>
+      </div>
+    </Container>
+  )
+}
+
+export const config = defineWidgetConfig({
+  zone: "product.details.before",
+})
+
+export default ProductWidget
+```
+
+In this example, you display the API key in a widget using `import.meta.env.VITE_MY_API_KEY`.
+
+### Type Error on import.meta.env
+
+If you receive a type error on `import.meta.env`, create the file `src/admin/vite-env.d.ts` with the following content:
+
+```ts title="src/admin/vite-env.d.ts"
+/// <reference types="vite/client" />
+```
+
+This file tells TypeScript to recognize the `import.meta.env` object and enhances the types of your custom environment variables.
+
+***
+
+## Check Node Environment in Admin Customizations
+
+To check the current environment, Vite exposes two variables:
+
+- `import.meta.env.DEV`: Returns `true` if the current environment is development.
+- `import.meta.env.PROD`: Returns `true` if the current environment is production.
+
+Learn more about other Vite environment variables in the [Vite documentation](https://vite.dev/guide/env-and-mode).
+
+***
+
+## Environment Variables in Production
+
+When you build the Medusa application, including the Medusa Admin, with the `build` command, the environment variables are inlined into the build. This means that you can't change the environment variables without rebuilding the application.
+
+For example, the `VITE_MY_API_KEY` environment variable in the example above will be replaced with the actual value during the build process.
+
+
 # Admin Routing Customizations
 
 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.
@@ -7338,214 +7415,6 @@ export const handle = {
 Refer to [react-router-dom’s documentation](https://reactrouter.com/en/6.29.0) for components and hooks that you can use in your admin customizations.
 
 
-# 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).
-
-
-# Environment Variables in Admin Customizations
-
-In this chapter, you'll learn how to use environment variables in your admin customizations.
-
-To learn how environment variables are generally loaded in Medusa based on your application's environment, check out [this chapter](https://docs.medusajs.com/learn/fundamentals/environment-variables/index.html.md).
-
-## How to Set Environment Variables
-
-The Medusa Admin is built on top of [Vite](https://vite.dev/). To set an environment variable that you want to use in a widget or UI route, prefix the environment variable with `VITE_`.
-
-For example:
-
-```plain
-VITE_MY_API_KEY=sk_123
-```
-
-***
-
-## How to Use Environment Variables
-
-To access or use an environment variable starting with `VITE_`, use the `import.meta.env` object.
-
-For example:
-
-```tsx highlights={[["8"]]}
-import { defineWidgetConfig } from "@medusajs/admin-sdk"
-import { Container, Heading } from "@medusajs/ui"
-
-const ProductWidget = () => {
-  return (
-    <Container className="divide-y p-0">
-      <div className="flex items-center justify-between px-6 py-4">
-        <Heading level="h2">API Key: {import.meta.env.VITE_MY_API_KEY}</Heading>
-      </div>
-    </Container>
-  )
-}
-
-export const config = defineWidgetConfig({
-  zone: "product.details.before",
-})
-
-export default ProductWidget
-```
-
-In this example, you display the API key in a widget using `import.meta.env.VITE_MY_API_KEY`.
-
-### Type Error on import.meta.env
-
-If you receive a type error on `import.meta.env`, create the file `src/admin/vite-env.d.ts` with the following content:
-
-```ts title="src/admin/vite-env.d.ts"
-/// <reference types="vite/client" />
-```
-
-This file tells TypeScript to recognize the `import.meta.env` object and enhances the types of your custom environment variables.
-
-***
-
-## Check Node Environment in Admin Customizations
-
-To check the current environment, Vite exposes two variables:
-
-- `import.meta.env.DEV`: Returns `true` if the current environment is development.
-- `import.meta.env.PROD`: Returns `true` if the current environment is production.
-
-Learn more about other Vite environment variables in the [Vite documentation](https://vite.dev/guide/env-and-mode).
-
-***
-
-## Environment Variables in Production
-
-When you build the Medusa application, including the Medusa Admin, with the `build` command, the environment variables are inlined into the build. This means that you can't change the environment variables without rebuilding the application.
-
-For example, the `VITE_MY_API_KEY` environment variable in the example above will be replaced with the actual value during the build process.
-
-
 # Admin UI Routes
 
 In this chapter, you’ll learn how to create a UI route in the admin dashboard.
@@ -7782,6 +7651,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).
+
+
 # Admin Widgets
 
 In this chapter, you’ll learn more about widgets and how to use them.
@@ -7901,6 +7901,306 @@ Refer to [this reference](https://docs.medusajs.com/resources/admin-widget-injec
 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.
 
 
+# Seed Data with Custom CLI Script
+
+In this chapter, you'll learn how to seed data using a custom CLI script.
+
+## How to Seed Data
+
+To seed dummy data for development or demo purposes, use a custom CLI script.
+
+In the CLI script, use your custom workflows or Medusa's existing workflows, which you can browse in [this reference](https://docs.medusajs.com/resources/medusa-workflows-reference/index.html.md), to seed data.
+
+### Example: Seed Dummy Products
+
+In this section, you'll follow an example of creating a custom CLI script that seeds fifty dummy products.
+
+First, install the [Faker](https://fakerjs.dev/) library to generate random data in your script:
+
+```bash npm2yarn
+npm install --save-dev @faker-js/faker
+```
+
+Then, create the file `src/scripts/demo-products.ts` with the following content:
+
+```ts title="src/scripts/demo-products.ts" highlights={highlights} collapsibleLines="1-12" expandButtonLabel="Show Imports"
+import { ExecArgs } from "@medusajs/framework/types"
+import { faker } from "@faker-js/faker"
+import { 
+  ContainerRegistrationKeys, 
+  Modules, 
+  ProductStatus,
+} from "@medusajs/framework/utils"
+import { 
+  createInventoryLevelsWorkflow,
+  createProductsWorkflow,
+} from "@medusajs/medusa/core-flows"
+
+export default async function seedDummyProducts({
+  container,
+}: ExecArgs) {
+  const salesChannelModuleService = container.resolve(
+    Modules.SALES_CHANNEL
+  )
+  const logger = container.resolve(
+    ContainerRegistrationKeys.LOGGER
+  )
+  const query = container.resolve(
+    ContainerRegistrationKeys.QUERY
+  )
+
+  const defaultSalesChannel = await salesChannelModuleService
+    .listSalesChannels({
+      name: "Default Sales Channel",
+    })
+
+  const sizeOptions = ["S", "M", "L", "XL"]
+  const colorOptions = ["Black", "White"]
+  const currency_code = "eur"
+  const productsNum = 50
+
+  // TODO seed products
+}
+```
+
+So far, in the script, you:
+
+- Resolve the Sales Channel Module's main service to retrieve the application's default sales channel. This is the sales channel the dummy products will be available in.
+- Resolve the Logger to log messages in the terminal, and Query to later retrieve data useful for the seeded products.
+- Initialize some default data to use when seeding the products next.
+
+Next, replace the `TODO` with the following:
+
+```ts title="src/scripts/demo-products.ts"
+const productsData = new Array(productsNum).fill(0).map((_, index) => {
+  const title = faker.commerce.product() + "_" + index
+  return {
+    title,
+    is_giftcard: true,
+    description: faker.commerce.productDescription(),
+    status: ProductStatus.PUBLISHED,
+    options: [
+      {
+        title: "Size",
+        values: sizeOptions,
+      },
+      {
+        title: "Color",
+        values: colorOptions,
+      },
+    ],
+    images: [
+      {
+        url: faker.image.urlPlaceholder({
+          text: title,
+        }),
+      },
+      {
+        url: faker.image.urlPlaceholder({
+          text: title,
+        }),
+      },
+    ],
+    variants: new Array(10).fill(0).map((_, variantIndex) => ({
+      title: `${title} ${variantIndex}`,
+      sku: `variant-${variantIndex}${index}`,
+      prices: new Array(10).fill(0).map((_, priceIndex) => ({
+        currency_code,
+        amount: 10 * priceIndex,
+      })),
+      options: {
+        Size: sizeOptions[Math.floor(Math.random() * 3)],
+      },
+    })),
+    shipping_profile_id: "sp_123",
+    sales_channels: [
+      {
+        id: defaultSalesChannel[0].id,
+      },
+    ],
+  }
+})
+
+// TODO seed products
+```
+
+You generate fifty products using the sales channel and variables you initialized, and using Faker for random data, such as the product's title or images.
+
+Then, replace the new `TODO` with the following:
+
+```ts title="src/scripts/demo-products.ts"
+const { result: products } = await createProductsWorkflow(container).run({
+  input: {
+    products: productsData,
+  },
+})
+
+logger.info(`Seeded ${products.length} products.`)
+
+// TODO add inventory levels
+```
+
+You create the generated products using the `createProductsWorkflow` imported previously from `@medusajs/medusa/core-flows`. It accepts the product data as input, and returns the created products.
+
+Only thing left is to create inventory levels for the products. So, replace the last `TODO` with the following:
+
+```ts title="src/scripts/demo-products.ts"
+logger.info("Seeding inventory levels.")
+
+const { data: stockLocations } = await query.graph({
+  entity: "stock_location",
+  fields: ["id"],
+})
+
+const { data: inventoryItems } = await query.graph({
+  entity: "inventory_item",
+  fields: ["id"],
+})
+
+const inventoryLevels = inventoryItems.map((inventoryItem) => ({
+  location_id: stockLocations[0].id,
+  stocked_quantity: 1000000,
+  inventory_item_id: inventoryItem.id,
+}))
+
+await createInventoryLevelsWorkflow(container).run({
+  input: {
+    inventory_levels: inventoryLevels,
+  },
+})
+
+logger.info("Finished seeding inventory levels data.")
+```
+
+You use Query to retrieve the stock location, to use the first location in the application, and the inventory items.
+
+Then, you generate inventory levels for each inventory item, associating it with the first stock location.
+
+Finally, you use the `createInventoryLevelsWorkflow` from Medusa's core workflows to create the inventory levels.
+
+### Test Script
+
+To test out the script, run the following command in your project's directory:
+
+```bash
+npx medusa exec ./src/scripts/demo-products.ts
+```
+
+This seeds the products to your database. If you run your Medusa application and view the products in the dashboard, you'll find fifty new products.
+
+
+# Handling CORS in API Routes
+
+In this chapter, you’ll learn about the CORS middleware and how to configure it for custom API routes.
+
+## CORS Overview
+
+Cross-Origin Resource Sharing (CORS) allows only configured origins to access your API Routes.
+
+For example, if you allow only origins starting with `http://localhost:7001` to access your Admin API Routes, other origins accessing those routes get a CORS error.
+
+### CORS Configurations
+
+The `storeCors` and `adminCors` properties of Medusa's `http` configuration set the allowed origins for routes starting with `/store` and `/admin` respectively.
+
+These configurations accept a URL pattern to identify allowed origins.
+
+For example:
+
+```js title="medusa-config.ts"
+module.exports = defineConfig({
+  projectConfig: {
+    http: {
+      storeCors: "http://localhost:8000",
+      adminCors: "http://localhost:7001",
+      // ...
+    },
+  },
+})
+```
+
+This allows the `http://localhost:7001` origin to access the Admin API Routes, and the `http://localhost:8000` origin to access Store API Routes.
+
+Learn more about the CORS configurations in [this resource guide](https://docs.medusajs.com/learn/configurations/medusa-config#http/index.html.md).
+
+***
+
+## CORS in Store and Admin Routes
+
+To disable the CORS middleware for a route, export a `CORS` variable in the route file with its value set to `false`.
+
+For example:
+
+```ts title="src/api/store/custom/route.ts" highlights={[["15"]]}
+import type { 
+  MedusaRequest, 
+  MedusaResponse,
+} from "@medusajs/framework/http"
+
+export const GET = (
+  req: MedusaRequest,
+  res: MedusaResponse
+) => {
+  res.json({
+    message: "[GET] Hello world!",
+  })
+}
+
+export const CORS = false
+```
+
+This disables the CORS middleware on API Routes at the path `/store/custom`.
+
+***
+
+## CORS in Custom Routes
+
+If you create a route that doesn’t start with `/store` or `/admin`, you must apply the CORS middleware manually. Otherwise, all requests to your API route lead to a CORS error.
+
+You can do that in the exported middlewares configurations in `src/api/middlewares.ts`.
+
+For example:
+
+```ts title="src/api/middlewares.ts" highlights={highlights} collapsibleLines="1-10" expandButtonLabel="Show Imports"
+import { defineMiddlewares } from "@medusajs/framework/http"
+import type { 
+  MedusaNextFunction, 
+  MedusaRequest, 
+  MedusaResponse, 
+} from "@medusajs/framework/http"
+import { ConfigModule } from "@medusajs/framework/types"
+import { parseCorsOrigins } from "@medusajs/framework/utils"
+import cors from "cors"
+
+export default defineMiddlewares({
+  routes: [
+    {
+      matcher: "/custom*",
+      middlewares: [
+        (
+          req: MedusaRequest, 
+          res: MedusaResponse, 
+          next: MedusaNextFunction
+        ) => {
+          const configModule: ConfigModule =
+            req.scope.resolve("configModule")
+
+          return cors({
+            origin: parseCorsOrigins(
+              configModule.projectConfig.http.storeCors
+            ),
+            credentials: true,
+          })(req, res, next)
+        },
+      ],
+    },
+  ],
+})
+```
+
+This retrieves the configurations exported from `medusa-config.ts` and applies the `storeCors` to routes starting with `/custom`.
+
+
 # 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.
@@ -8100,118 +8400,6 @@ createProductsWorkflow.hooks.productsCreated(
 This updates the products to their original state before adding the brand to their `metadata` property.
 
 
-# Handling CORS in API Routes
-
-In this chapter, you’ll learn about the CORS middleware and how to configure it for custom API routes.
-
-## CORS Overview
-
-Cross-Origin Resource Sharing (CORS) allows only configured origins to access your API Routes.
-
-For example, if you allow only origins starting with `http://localhost:7001` to access your Admin API Routes, other origins accessing those routes get a CORS error.
-
-### CORS Configurations
-
-The `storeCors` and `adminCors` properties of Medusa's `http` configuration set the allowed origins for routes starting with `/store` and `/admin` respectively.
-
-These configurations accept a URL pattern to identify allowed origins.
-
-For example:
-
-```js title="medusa-config.ts"
-module.exports = defineConfig({
-  projectConfig: {
-    http: {
-      storeCors: "http://localhost:8000",
-      adminCors: "http://localhost:7001",
-      // ...
-    },
-  },
-})
-```
-
-This allows the `http://localhost:7001` origin to access the Admin API Routes, and the `http://localhost:8000` origin to access Store API Routes.
-
-Learn more about the CORS configurations in [this resource guide](https://docs.medusajs.com/learn/configurations/medusa-config#http/index.html.md).
-
-***
-
-## CORS in Store and Admin Routes
-
-To disable the CORS middleware for a route, export a `CORS` variable in the route file with its value set to `false`.
-
-For example:
-
-```ts title="src/api/store/custom/route.ts" highlights={[["15"]]}
-import type { 
-  MedusaRequest, 
-  MedusaResponse,
-} from "@medusajs/framework/http"
-
-export const GET = (
-  req: MedusaRequest,
-  res: MedusaResponse
-) => {
-  res.json({
-    message: "[GET] Hello world!",
-  })
-}
-
-export const CORS = false
-```
-
-This disables the CORS middleware on API Routes at the path `/store/custom`.
-
-***
-
-## CORS in Custom Routes
-
-If you create a route that doesn’t start with `/store` or `/admin`, you must apply the CORS middleware manually. Otherwise, all requests to your API route lead to a CORS error.
-
-You can do that in the exported middlewares configurations in `src/api/middlewares.ts`.
-
-For example:
-
-```ts title="src/api/middlewares.ts" highlights={highlights} collapsibleLines="1-10" expandButtonLabel="Show Imports"
-import { defineMiddlewares } from "@medusajs/framework/http"
-import type { 
-  MedusaNextFunction, 
-  MedusaRequest, 
-  MedusaResponse, 
-} from "@medusajs/framework/http"
-import { ConfigModule } from "@medusajs/framework/types"
-import { parseCorsOrigins } from "@medusajs/framework/utils"
-import cors from "cors"
-
-export default defineMiddlewares({
-  routes: [
-    {
-      matcher: "/custom*",
-      middlewares: [
-        (
-          req: MedusaRequest, 
-          res: MedusaResponse, 
-          next: MedusaNextFunction
-        ) => {
-          const configModule: ConfigModule =
-            req.scope.resolve("configModule")
-
-          return cors({
-            origin: parseCorsOrigins(
-              configModule.projectConfig.http.storeCors
-            ),
-            credentials: true,
-          })(req, res, next)
-        },
-      ],
-    },
-  ],
-})
-```
-
-This retrieves the configurations exported from `medusa-config.ts` and applies the `storeCors` to routes starting with `/custom`.
-
-
 # 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.
@@ -8319,57 +8507,6 @@ The `errorHandler` property's value is a function that accepts four parameters:
 This example overrides Medusa's default error handler with a handler that always returns a `400` status code with the same message.
 
 
-# Override API Routes
-
-In this chapter, you'll learn the approach recommended when you need to override an existing API route in Medusa.
-
-## Approaches to Consider Before Overriding API Routes
-
-While building customizations in your Medusa application, you may need to make changes to existing API routes for your business use case.
-
-Medusa provides the following approaches to customize API routes:
-
-|Approach|Description|
-|---|---|
-|Pass Additional Data|Pass custom data to the API route with custom validation.|
-|Perform Custom Logic within an Existing Flows|API routes execute workflows to perform business logic, which may have hooks that allow you to perform custom logic.|
-|Use Custom Middlewares|Use custom middlewares to perform custom logic before the API route is executed. However, you cannot remove or replace middlewares applied to existing API routes.|
-|Listen to Events in Subscribers|Functionalities in API routes may trigger events that you can handle in subscribers. This is useful if you're performing an action that isn't integral to the API route's core functionality or response.|
-
-If the above approaches do not meet your needs, you can consider the approaches mentioned in the rest of this chapter.
-
-***
-
-## Replicate, Don't Override API Routes
-
-If the approaches mentioned in the [section above](#approaches-to-consider-before-overriding-api-routes) do not meet your needs, you can replicate an existing API route and modify it to suit your requirements.
-
-By replicating instead of overriding, the original API route remains intact, allowing you to easily revert to the original functionality if needed. You can also update your Medusa version without worrying about breaking changes in the original API route.
-
-***
-
-## How to Replicate an API Route?
-
-Medusa's API routes are generally slim and use logic contained in [workflows](https://docs.medusajs.com/learn/fundamentals/workflows/index.html.md). So, creating a custom route based on the original route is straightforward.
-
-You can view the source code for Medusa's API routes in the [Medusa GitHub repository](https://github.com/medusajs/medusa/tree/develop/packages/medusa/src/api).
-
-For example, if you need to allow vendors to access the `POST /admin/products` API route, you can create an API route in your Medusa project at `src/api/vendor/products/route.ts` with the [same code as the original route](https://github.com/medusajs/medusa/blob/develop/packages/medusa/src/api/admin/products/route.ts#L88). Then, you can make changes to it or its middlewares.
-
-***
-
-## When to Replicate an API Route?
-
-Some examples of when you might want to replicate an API route include:
-
-|Use Case|Description|
-|---|---|
-|Custom Validation|You want to change the validation logic for a specific API route, and the |
-|Change Authentication|You want to remove required authentication for a specific API route, or you want to allow custom |
-|Custom Response|You want to change the response format of an existing API route.|
-|Override Middleware|You want to override the middleware applied on existing API routes. Because of |
-
-
 # HTTP Methods
 
 In this chapter, you'll learn about how to add new API routes for each HTTP method.
@@ -8793,253 +8930,6 @@ If you need to change the middlewares applied to a route, you can create a custo
 Learn more in the [Override API Routes](https://docs.medusajs.com/learn/fundamentals/api-routes/override/index.html.md) chapter.
 
 
-# API Route Parameters
-
-In this chapter, you’ll learn about path, query, and request body parameters.
-
-## Path Parameters
-
-To create an API route that accepts a path parameter, create a directory within the route file's path whose name is of the format `[param]`.
-
-For example, to create an API Route at the path `/hello-world/:id`, where `:id` is a path parameter, create the file `src/api/hello-world/[id]/route.ts` with the following content:
-
-```ts title="src/api/hello-world/[id]/route.ts" highlights={singlePathHighlights}
-import type {
-  MedusaRequest,
-  MedusaResponse,
-} from "@medusajs/framework/http"
-
-export const GET = async (
-  req: MedusaRequest,
-  res: MedusaResponse
-) => {
-  res.json({
-    message: `[GET] Hello ${req.params.id}!`,
-  })
-}
-```
-
-The `MedusaRequest` object has a `params` property. `params` holds the path parameters in key-value pairs.
-
-### Multiple Path Parameters
-
-To create an API route that accepts multiple path parameters, create within the file's path multiple directories whose names are of the format `[param]`.
-
-For example, to create an API route at `/hello-world/:id/name/:name`, create the file `src/api/hello-world/[id]/name/[name]/route.ts` with the following content:
-
-```ts title="src/api/hello-world/[id]/name/[name]/route.ts" highlights={multiplePathHighlights}
-import type {
-  MedusaRequest,
-  MedusaResponse,
-} from "@medusajs/framework/http"
-
-export const GET = async (
-  req: MedusaRequest,
-  res: MedusaResponse
-) => {
-  res.json({
-    message: `[GET] Hello ${
-      req.params.id
-    } - ${req.params.name}!`,
-  })
-}
-```
-
-You access the `id` and `name` path parameters using the `req.params` property.
-
-***
-
-## Query Parameters
-
-You can access all query parameters in the `query` property of the `MedusaRequest` object. `query` is an object of key-value pairs, where the key is a query parameter's name, and the value is its value.
-
-For example:
-
-```ts title="src/api/hello-world/route.ts" highlights={queryHighlights}
-import type {
-  MedusaRequest,
-  MedusaResponse,
-} from "@medusajs/framework/http"
-
-export const GET = async (
-  req: MedusaRequest,
-  res: MedusaResponse
-) => {
-  res.json({
-    message: `Hello ${req.query.name}`,
-  })
-}
-```
-
-The value of `req.query.name` is the value passed in `?name=John`, for example.
-
-### Validate Query Parameters
-
-You can apply validation rules on received query parameters to ensure they match specified rules and types.
-
-Learn more in [this documentation](https://docs.medusajs.com/learn/fundamentals/api-routes/validation#how-to-validate-request-query-paramters/index.html.md).
-
-***
-
-## Request Body Parameters
-
-The Medusa application parses the body of any request having a JSON, URL-encoded, or text request content types. The request body parameters are set in the `MedusaRequest`'s `body` property.
-
-Learn more about configuring body parsing in [this guide](https://docs.medusajs.com/learn/fundamentals/api-routes/parse-body/index.html.md).
-
-For example:
-
-```ts title="src/api/hello-world/route.ts" highlights={bodyHighlights}
-import type {
-  MedusaRequest,
-  MedusaResponse,
-} from "@medusajs/framework/http"
-
-type HelloWorldReq = {
-  name: string
-}
-
-export const POST = async (
-  req: MedusaRequest<HelloWorldReq>,
-  res: MedusaResponse
-) => {
-  res.json({
-    message: `[POST] Hello ${req.body.name}!`,
-  })
-}
-```
-
-In this example, you use the `name` request body parameter to create the message in the returned response.
-
-The `MedusaRequest` type accepts a type argument that indicates the type of the request body. This is useful for auto-completion and to avoid typing errors.
-
-To test it out, send the following request to your Medusa application:
-
-```bash
-curl -X POST 'http://localhost:9000/hello-world' \
--H 'Content-Type: application/json' \
---data-raw '{
-  "name": "John"
-}'
-```
-
-This returns the following JSON object:
-
-```json
-{
-  "message": "[POST] Hello John!"
-}
-```
-
-### Validate Body Parameters
-
-You can apply validation rules on received body parameters to ensure they match specified rules and types.
-
-Learn more in [this documentation](https://docs.medusajs.com/learn/fundamentals/api-routes/validation#how-to-validate-request-body/index.html.md).
-
-
-# API Route Response
-
-In this chapter, you'll learn how to send a response in your API route.
-
-## Send a JSON Response
-
-To send a JSON response, use the `json` method of the `MedusaResponse` object passed as the second parameter of your API route handler.
-
-For example:
-
-```ts title="src/api/custom/route.ts" highlights={jsonHighlights}
-import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
-
-export const GET = async (
-  req: MedusaRequest,
-  res: MedusaResponse
-) => {
-  res.json({
-    message: "Hello, World!",
-  })
-}
-```
-
-This API route returns the following JSON object:
-
-```json
-{
-  "message": "Hello, World!"
-}
-```
-
-***
-
-## Set Response Status Code
-
-By default, setting the JSON data using the `json` method returns a response with a `200` status code.
-
-To change the status code, use the `status` method of the `MedusaResponse` object.
-
-For example:
-
-```ts title="src/api/custom/route.ts" highlights={statusHighlight}
-import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
-
-export const GET = async (
-  req: MedusaRequest,
-  res: MedusaResponse
-) => {
-  res.status(201).json({
-    message: "Hello, World!",
-  })
-}
-```
-
-The response of this API route has the status code `201`.
-
-***
-
-## Change Response Content Type
-
-To return response data other than a JSON object, use the `writeHead` method of the `MedusaResponse` object. It allows you to set the response headers, including the content type.
-
-For example, to create an API route that returns an event stream:
-
-```ts highlights={streamHighlights}
-import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
-
-export const GET = async (
-  req: MedusaRequest,
-  res: MedusaResponse
-) => {
-  res.writeHead(200, {
-    "Content-Type": "text/event-stream",
-    "Cache-Control": "no-cache",
-    Connection: "keep-alive",
-  })
-
-  const interval = setInterval(() => {
-    res.write("Streaming data...\n")
-  }, 3000)
-
-  req.on("end", () => {
-    clearInterval(interval)
-    res.end()
-  })
-}
-```
-
-The `writeHead` method accepts two parameters:
-
-1. The first one is the response's status code.
-2. The second is an object of key-value pairs to set the headers of the response.
-
-This API route opens a stream by setting the `Content-Type` in the header to `text/event-stream`. It then simulates a stream by creating an interval that writes the stream data every three seconds.
-
-***
-
-## Do More with Responses
-
-The `MedusaResponse` type is based on [Express's Response](https://expressjs.com/en/api.html#res). Refer to their API reference for other uses of responses.
-
-
 # Protected API Routes
 
 In this chapter, you’ll learn how to create protected API routes.
@@ -9305,6 +9195,151 @@ Then, you use Query to retrieve the user details. The `throwIfKeyNotFound` optio
 After that, you can use the user's details in your API route.
 
 
+# API Route Parameters
+
+In this chapter, you’ll learn about path, query, and request body parameters.
+
+## Path Parameters
+
+To create an API route that accepts a path parameter, create a directory within the route file's path whose name is of the format `[param]`.
+
+For example, to create an API Route at the path `/hello-world/:id`, where `:id` is a path parameter, create the file `src/api/hello-world/[id]/route.ts` with the following content:
+
+```ts title="src/api/hello-world/[id]/route.ts" highlights={singlePathHighlights}
+import type {
+  MedusaRequest,
+  MedusaResponse,
+} from "@medusajs/framework/http"
+
+export const GET = async (
+  req: MedusaRequest,
+  res: MedusaResponse
+) => {
+  res.json({
+    message: `[GET] Hello ${req.params.id}!`,
+  })
+}
+```
+
+The `MedusaRequest` object has a `params` property. `params` holds the path parameters in key-value pairs.
+
+### Multiple Path Parameters
+
+To create an API route that accepts multiple path parameters, create within the file's path multiple directories whose names are of the format `[param]`.
+
+For example, to create an API route at `/hello-world/:id/name/:name`, create the file `src/api/hello-world/[id]/name/[name]/route.ts` with the following content:
+
+```ts title="src/api/hello-world/[id]/name/[name]/route.ts" highlights={multiplePathHighlights}
+import type {
+  MedusaRequest,
+  MedusaResponse,
+} from "@medusajs/framework/http"
+
+export const GET = async (
+  req: MedusaRequest,
+  res: MedusaResponse
+) => {
+  res.json({
+    message: `[GET] Hello ${
+      req.params.id
+    } - ${req.params.name}!`,
+  })
+}
+```
+
+You access the `id` and `name` path parameters using the `req.params` property.
+
+***
+
+## Query Parameters
+
+You can access all query parameters in the `query` property of the `MedusaRequest` object. `query` is an object of key-value pairs, where the key is a query parameter's name, and the value is its value.
+
+For example:
+
+```ts title="src/api/hello-world/route.ts" highlights={queryHighlights}
+import type {
+  MedusaRequest,
+  MedusaResponse,
+} from "@medusajs/framework/http"
+
+export const GET = async (
+  req: MedusaRequest,
+  res: MedusaResponse
+) => {
+  res.json({
+    message: `Hello ${req.query.name}`,
+  })
+}
+```
+
+The value of `req.query.name` is the value passed in `?name=John`, for example.
+
+### Validate Query Parameters
+
+You can apply validation rules on received query parameters to ensure they match specified rules and types.
+
+Learn more in [this documentation](https://docs.medusajs.com/learn/fundamentals/api-routes/validation#how-to-validate-request-query-paramters/index.html.md).
+
+***
+
+## Request Body Parameters
+
+The Medusa application parses the body of any request having a JSON, URL-encoded, or text request content types. The request body parameters are set in the `MedusaRequest`'s `body` property.
+
+Learn more about configuring body parsing in [this guide](https://docs.medusajs.com/learn/fundamentals/api-routes/parse-body/index.html.md).
+
+For example:
+
+```ts title="src/api/hello-world/route.ts" highlights={bodyHighlights}
+import type {
+  MedusaRequest,
+  MedusaResponse,
+} from "@medusajs/framework/http"
+
+type HelloWorldReq = {
+  name: string
+}
+
+export const POST = async (
+  req: MedusaRequest<HelloWorldReq>,
+  res: MedusaResponse
+) => {
+  res.json({
+    message: `[POST] Hello ${req.body.name}!`,
+  })
+}
+```
+
+In this example, you use the `name` request body parameter to create the message in the returned response.
+
+The `MedusaRequest` type accepts a type argument that indicates the type of the request body. This is useful for auto-completion and to avoid typing errors.
+
+To test it out, send the following request to your Medusa application:
+
+```bash
+curl -X POST 'http://localhost:9000/hello-world' \
+-H 'Content-Type: application/json' \
+--data-raw '{
+  "name": "John"
+}'
+```
+
+This returns the following JSON object:
+
+```json
+{
+  "message": "[POST] Hello John!"
+}
+```
+
+### Validate Body Parameters
+
+You can apply validation rules on received body parameters to ensure they match specified rules and types.
+
+Learn more in [this documentation](https://docs.medusajs.com/learn/fundamentals/api-routes/validation#how-to-validate-request-body/index.html.md).
+
+
 # Configure Request Body Parser
 
 In this chapter, you'll learn how to configure the request body parser for your API routes.
@@ -9476,158 +9511,157 @@ export async function POST(
 Check out the [uploadFilesWorkflow reference](https://docs.medusajs.com/resources/references/medusa-workflows/uploadFilesWorkflow/index.html.md) for details on the expected input and output of the workflow.
 
 
-# Retrieve Custom Links from Medusa's API Route
+# Override API Routes
 
-In this chapter, you'll learn how to retrieve custom data models linked to existing Medusa data models from Medusa's API routes.
+In this chapter, you'll learn the approach recommended when you need to override an existing API route in Medusa.
 
-## Why Retrieve Custom Linked Data Models?
+## Approaches to Consider Before Overriding API Routes
 
-Often, you'll link custom data models to existing Medusa data models to implement custom features or expand on existing ones.
+While building customizations in your Medusa application, you may need to make changes to existing API routes for your business use case.
 
-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.
+Medusa provides the following approaches to customize API routes:
 
-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.
+|Approach|Description|
+|---|---|
+|Pass Additional Data|Pass custom data to the API route with custom validation.|
+|Perform Custom Logic within an Existing Flows|API routes execute workflows to perform business logic, which may have hooks that allow you to perform custom logic.|
+|Use Custom Middlewares|Use custom middlewares to perform custom logic before the API route is executed. However, you cannot remove or replace middlewares applied to existing API routes.|
+|Listen to Events in Subscribers|Functionalities in API routes may trigger events that you can handle in subscribers. This is useful if you're performing an action that isn't integral to the API route's core functionality or response.|
+
+If the above approaches do not meet your needs, you can consider the approaches mentioned in the rest of this chapter.
 
 ***
 
-## How to Retrieve Custom Linked Data Models Using `fields`?
+## Replicate, Don't Override API Routes
 
-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.
+If the approaches mentioned in the [section above](#approaches-to-consider-before-overriding-api-routes) do not meet your needs, you can replicate an existing API route and modify it to suit your requirements.
 
-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.
+By replicating instead of overriding, the original API route remains intact, allowing you to easily revert to the original functionality if needed. You can also update your Medusa version without worrying about breaking changes in the original API route.
 
 ***
 
-## API Routes that Restrict Retrievable Fields
+## How to Replicate an API Route?
 
-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.
+Medusa's API routes are generally slim and use logic contained in [workflows](https://docs.medusajs.com/learn/fundamentals/workflows/index.html.md). So, creating a custom route based on the original route is straightforward.
 
-The API routes that restrict the fields and relations you can retrieve are:
+You can view the source code for Medusa's API routes in the [Medusa GitHub repository](https://github.com/medusajs/medusa/tree/develop/packages/medusa/src/api).
 
-- [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.
-
-
-# Add Data Model Check Constraints
-
-In this chapter, you'll learn how to add check constraints to your data model.
-
-## What is a Check Constraint?
-
-A check constraint is a condition that must be satisfied by records inserted into a database table, otherwise an error is thrown.
-
-For example, if you have a data model with a `price` property, you want to only allow positive number values. So, you add a check constraint that fails when inserting a record with a negative price value.
+For example, if you need to allow vendors to access the `POST /admin/products` API route, you can create an API route in your Medusa project at `src/api/vendor/products/route.ts` with the [same code as the original route](https://github.com/medusajs/medusa/blob/develop/packages/medusa/src/api/admin/products/route.ts#L88). Then, you can make changes to it or its middlewares.
 
 ***
 
-## How to Set a Check Constraint?
+## When to Replicate an API Route?
 
-To set check constraints on a data model, use the `checks` method. This method accepts an array of check constraints to apply on the data model.
+Some examples of when you might want to replicate an API route include:
 
-For example, to set a check constraint on a `price` property that ensures its value can only be a positive number:
+|Use Case|Description|
+|---|---|
+|Custom Validation|You want to change the validation logic for a specific API route, and the |
+|Change Authentication|You want to remove required authentication for a specific API route, or you want to allow custom |
+|Custom Response|You want to change the response format of an existing API route.|
+|Override Middleware|You want to override the middleware applied on existing API routes. Because of |
 
-```ts highlights={checks1Highlights}
-import { model } from "@medusajs/framework/utils"
 
-const CustomProduct = model.define("custom_product", {
-  // ...
-  price: model.bigNumber(),
-})
-.checks([
-  (columns) => `${columns.price} >= 0`,
-])
+# API Route Response
+
+In this chapter, you'll learn how to send a response in your API route.
+
+## Send a JSON Response
+
+To send a JSON response, use the `json` method of the `MedusaResponse` object passed as the second parameter of your API route handler.
+
+For example:
+
+```ts title="src/api/custom/route.ts" highlights={jsonHighlights}
+import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
+
+export const GET = async (
+  req: MedusaRequest,
+  res: MedusaResponse
+) => {
+  res.json({
+    message: "Hello, World!",
+  })
+}
 ```
 
-The item passed in the array parameter of `checks` can be a callback function that accepts as a parameter an object whose keys are the names of the properties in the data model schema, and values the respective column name in the database.
+This API route returns the following JSON object:
 
-The function returns a string indicating the [SQL check constraint expression](https://www.postgresql.org/docs/current/ddl-constraints.html#DDL-CONSTRAINTS-CHECK-CONSTRAINTS). In the expression, use the `columns` parameter to access a property's column name.
-
-You can also pass an object to the `checks` method:
-
-```ts highlights={checks2Highlights}
-import { model } from "@medusajs/framework/utils"
-
-const CustomProduct = model.define("custom_product", {
-  // ...
-  price: model.bigNumber(),
-})
-.checks([
-  {
-    name: "custom_product_price_check",
-    expression: (columns) => `${columns.price} >= 0`,
-  },
-])
+```json
+{
+  "message": "Hello, World!"
+}
 ```
 
-The object accepts the following properties:
-
-- `name`: The check constraint's name.
-- `expression`: A function similar to the one that can be passed to the array. It accepts an object of columns and returns an [SQL check constraint expression](https://www.postgresql.org/docs/current/ddl-constraints.html#DDL-CONSTRAINTS-CHECK-CONSTRAINTS).
-
 ***
 
-## Apply in Migrations
+## Set Response Status Code
 
-After adding the check constraint, make sure to generate and run migrations if you already have the table in the database. Otherwise, the check constraint won't be reflected.
+By default, setting the JSON data using the `json` method returns a response with a `200` status code.
 
-To generate a migration for the data model's module then reflect it on the database, run the following command:
+To change the status code, use the `status` method of the `MedusaResponse` object.
 
-```bash
-npx medusa db:generate custom_module
-npx medusa db:migrate
+For example:
+
+```ts title="src/api/custom/route.ts" highlights={statusHighlight}
+import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
+
+export const GET = async (
+  req: MedusaRequest,
+  res: MedusaResponse
+) => {
+  res.status(201).json({
+    message: "Hello, World!",
+  })
+}
 ```
 
-The first command generates the migration under the `migrations` directory of your module's directory, and the second reflects it on the database.
+The response of this API route has the status code `201`.
+
+***
+
+## Change Response Content Type
+
+To return response data other than a JSON object, use the `writeHead` method of the `MedusaResponse` object. It allows you to set the response headers, including the content type.
+
+For example, to create an API route that returns an event stream:
+
+```ts highlights={streamHighlights}
+import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
+
+export const GET = async (
+  req: MedusaRequest,
+  res: MedusaResponse
+) => {
+  res.writeHead(200, {
+    "Content-Type": "text/event-stream",
+    "Cache-Control": "no-cache",
+    Connection: "keep-alive",
+  })
+
+  const interval = setInterval(() => {
+    res.write("Streaming data...\n")
+  }, 3000)
+
+  req.on("end", () => {
+    clearInterval(interval)
+    res.end()
+  })
+}
+```
+
+The `writeHead` method accepts two parameters:
+
+1. The first one is the response's status code.
+2. The second is an object of key-value pairs to set the headers of the response.
+
+This API route opens a stream by setting the `Content-Type` in the header to `text/event-stream`. It then simulates a stream by creating an interval that writes the stream data every three seconds.
+
+***
+
+## Do More with Responses
+
+The `MedusaResponse` type is based on [Express's Response](https://expressjs.com/en/api.html#res). Refer to their API reference for other uses of responses.
 
 
 # Request Body and Query Parameter Validation
@@ -9879,192 +9913,418 @@ 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).
 
 
-# Seed Data with Custom CLI Script
+# Retrieve Custom Links from Medusa's API Route
 
-In this chapter, you'll learn how to seed data using a custom CLI script.
+In this chapter, you'll learn how to retrieve custom data models linked to existing Medusa data models from Medusa's API routes.
 
-## How to Seed Data
+## Why Retrieve Custom Linked Data Models?
 
-To seed dummy data for development or demo purposes, use a custom CLI script.
+Often, you'll link custom data models to existing Medusa data models to implement custom features or expand on existing ones.
 
-In the CLI script, use your custom workflows or Medusa's existing workflows, which you can browse in [this reference](https://docs.medusajs.com/resources/medusa-workflows-reference/index.html.md), to seed data.
+For example, 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.
 
-### Example: Seed Dummy Products
+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.
 
-In this section, you'll follow an example of creating a custom CLI script that seeds fifty dummy products.
+***
 
-First, install the [Faker](https://fakerjs.dev/) library to generate random data in your script:
+## How to Retrieve Custom Linked Data Models Using `fields`?
 
-```bash npm2yarn
-npm install --save-dev @faker-js/faker
+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}'
 ```
 
-Then, create the file `src/scripts/demo-products.ts` with the following content:
+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).
 
-```ts title="src/scripts/demo-products.ts" highlights={highlights} collapsibleLines="1-12" expandButtonLabel="Show Imports"
-import { ExecArgs } from "@medusajs/framework/types"
-import { faker } from "@faker-js/faker"
-import { 
-  ContainerRegistrationKeys, 
-  Modules, 
-  ProductStatus,
-} from "@medusajs/framework/utils"
-import { 
-  createInventoryLevelsWorkflow,
-  createProductsWorkflow,
-} from "@medusajs/medusa/core-flows"
+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.
 
-export default async function seedDummyProducts({
-  container,
-}: ExecArgs) {
-  const salesChannelModuleService = container.resolve(
-    Modules.SALES_CHANNEL
-  )
-  const logger = container.resolve(
-    ContainerRegistrationKeys.LOGGER
-  )
-  const query = container.resolve(
-    ContainerRegistrationKeys.QUERY
-  )
+***
 
-  const defaultSalesChannel = await salesChannelModuleService
-    .listSalesChannels({
-      name: "Default Sales Channel",
-    })
+## API Routes that Restrict Retrievable Fields
 
-  const sizeOptions = ["S", "M", "L", "XL"]
-  const colorOptions = ["Black", "White"]
-  const currency_code = "eur"
-  const productsNum = 50
+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.
 
-  // TODO seed products
+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.
+
+
+# Add Data Model Check Constraints
+
+In this chapter, you'll learn how to add check constraints to your data model.
+
+## What is a Check Constraint?
+
+A check constraint is a condition that must be satisfied by records inserted into a database table, otherwise an error is thrown.
+
+For example, if you have a data model with a `price` property, you want to only allow positive number values. So, you add a check constraint that fails when inserting a record with a negative price value.
+
+***
+
+## How to Set a Check Constraint?
+
+To set check constraints on a data model, use the `checks` method. This method accepts an array of check constraints to apply on the data model.
+
+For example, to set a check constraint on a `price` property that ensures its value can only be a positive number:
+
+```ts highlights={checks1Highlights}
+import { model } from "@medusajs/framework/utils"
+
+const CustomProduct = model.define("custom_product", {
+  // ...
+  price: model.bigNumber(),
+})
+.checks([
+  (columns) => `${columns.price} >= 0`,
+])
+```
+
+The item passed in the array parameter of `checks` can be a callback function that accepts as a parameter an object whose keys are the names of the properties in the data model schema, and values the respective column name in the database.
+
+The function returns a string indicating the [SQL check constraint expression](https://www.postgresql.org/docs/current/ddl-constraints.html#DDL-CONSTRAINTS-CHECK-CONSTRAINTS). In the expression, use the `columns` parameter to access a property's column name.
+
+You can also pass an object to the `checks` method:
+
+```ts highlights={checks2Highlights}
+import { model } from "@medusajs/framework/utils"
+
+const CustomProduct = model.define("custom_product", {
+  // ...
+  price: model.bigNumber(),
+})
+.checks([
+  {
+    name: "custom_product_price_check",
+    expression: (columns) => `${columns.price} >= 0`,
+  },
+])
+```
+
+The object accepts the following properties:
+
+- `name`: The check constraint's name.
+- `expression`: A function similar to the one that can be passed to the array. It accepts an object of columns and returns an [SQL check constraint expression](https://www.postgresql.org/docs/current/ddl-constraints.html#DDL-CONSTRAINTS-CHECK-CONSTRAINTS).
+
+***
+
+## Apply in Migrations
+
+After adding the check constraint, make sure to generate and run migrations if you already have the table in the database. Otherwise, the check constraint won't be reflected.
+
+To generate a migration for the data model's module then reflect it on the database, run the following command:
+
+```bash
+npx medusa db:generate custom_module
+npx medusa db:migrate
+```
+
+The first command generates the migration under the `migrations` directory of your module's directory, and the second reflects it on the database.
+
+
+# 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> {
+    // ...
+  }
 }
 ```
 
-So far, in the script, you:
 
-- Resolve the Sales Channel Module's main service to retrieve the application's default sales channel. This is the sales channel the dummy products will be available in.
-- Resolve the Logger to log messages in the terminal, and Query to later retrieve data useful for the seeded products.
-- Initialize some default data to use when seeding the products next.
+# Manage Relationships
 
-Next, replace the `TODO` with the following:
+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.
 
-```ts title="src/scripts/demo-products.ts"
-const productsData = new Array(productsNum).fill(0).map((_, index) => {
-  const title = faker.commerce.product() + "_" + index
-  return {
-    title,
-    is_giftcard: true,
-    description: faker.commerce.productDescription(),
-    status: ProductStatus.PUBLISHED,
-    options: [
-      {
-        title: "Size",
-        values: sizeOptions,
-      },
-      {
-        title: "Color",
-        values: colorOptions,
-      },
-    ],
-    images: [
-      {
-        url: faker.image.urlPlaceholder({
-          text: title,
-        }),
-      },
-      {
-        url: faker.image.urlPlaceholder({
-          text: title,
-        }),
-      },
-    ],
-    variants: new Array(10).fill(0).map((_, variantIndex) => ({
-      title: `${title} ${variantIndex}`,
-      sku: `variant-${variantIndex}${index}`,
-      prices: new Array(10).fill(0).map((_, priceIndex) => ({
-        currency_code,
-        amount: 10 * priceIndex,
-      })),
-      options: {
-        Size: sizeOptions[Math.floor(Math.random() * 3)],
-      },
-    })),
-    shipping_profile_id: "sp_123",
-    sales_channels: [
-      {
-        id: defaultSalesChannel[0].id,
-      },
-    ],
+This chapter applies to data model relationships within the same module. To manage linked data models across modules, check out [Links](https://docs.medusajs.com/learn/fundamentals/module-links/index.html.md) and [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query/index.html.md).
+
+## 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"],
   }
-})
+)
 
-// TODO seed products
+const updatedProduct = await helloModuleService.updateProducts({
+  id: product.id,
+  // other properties...
+  orders: [
+    ...product.orders.map((order) => order.id),
+    "321",
+  ],
+})
 ```
 
-You generate fifty products using the sales channel and variables you initialized, and using Faker for random data, such as the product's title or images.
+This keeps existing associations between the product and orders, and adds a new one.
 
-Then, replace the new `TODO` with the following:
+***
 
-```ts title="src/scripts/demo-products.ts"
-const { result: products } = await createProductsWorkflow(container).run({
-  input: {
-    products: productsData,
+## 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,
   },
 })
 
-logger.info(`Seeded ${products.length} products.`)
-
-// TODO add inventory levels
-```
-
-You create the generated products using the `createProductsWorkflow` imported previously from `@medusajs/medusa/core-flows`. It accepts the product data as input, and returns the created products.
-
-Only thing left is to create inventory levels for the products. So, replace the last `TODO` with the following:
-
-```ts title="src/scripts/demo-products.ts"
-logger.info("Seeding inventory levels.")
-
-const { data: stockLocations } = await query.graph({
-  entity: "stock_location",
-  fields: ["id"],
-})
-
-const { data: inventoryItems } = await query.graph({
-  entity: "inventory_item",
-  fields: ["id"],
-})
-
-const inventoryLevels = inventoryItems.map((inventoryItem) => ({
-  location_id: stockLocations[0].id,
-  stocked_quantity: 1000000,
-  inventory_item_id: inventoryItem.id,
-}))
-
-await createInventoryLevelsWorkflow(container).run({
-  input: {
-    inventory_levels: inventoryLevels,
+// update order-product association
+const orderProduct = await blogModuleService.updateOrderProducts({
+  id: "123",
+  metadata: {
+    test: false,
   },
 })
 
-logger.info("Finished seeding inventory levels data.")
+// delete order-product association
+await blogModuleService.deleteOrderProducts("123")
 ```
 
-You use Query to retrieve the stock location, to use the first location in the application, and the inventory items.
+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`.
 
-Then, you generate inventory levels for each inventory item, associating it with the first stock location.
+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.
 
-Finally, you use the `createInventoryLevelsWorkflow` from Medusa's core workflows to create the inventory levels.
+***
 
-### Test Script
+## Retrieve Records of Relation
 
-To test out the script, run the following command in your project's directory:
+The `list`, `listAndCount`, and `retrieve` methods of a module's main service accept as a second parameter an object of options.
 
-```bash
-npx medusa exec ./src/scripts/demo-products.ts
+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"],
+  }
+)
 ```
 
-This seeds the products to your database. If you run your Medusa application and view the products in the dashboard, you'll find fifty new products.
+In the example above, the retrieved product has an `orders` property, whose value is an array of orders associated with the product.
 
 
 # Data Model Database Index
@@ -10179,46 +10439,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> {
-    // ...
-  }
-}
-```
-
-
 # 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.
@@ -10866,324 +11086,6 @@ 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.
 
 
-# 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.
-
-This chapter applies to data model relationships within the same module. To manage linked data models across modules, check out [Links](https://docs.medusajs.com/learn/fundamentals/module-links/index.html.md) and [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query/index.html.md).
-
-## 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).
-
-
 # Event Data Payload
 
 In this chapter, you'll learn how subscribers receive an event's data payload.
@@ -11397,6 +11299,104 @@ If you execute the `performAction` method of your service, the event is emitted
 Any subscribers listening to the event are also executed.
 
 
+# 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).
+
+
 # Add Columns to a Link Table
 
 In this chapter, you'll learn how to add custom columns to a link definition's table and manage them.
@@ -11555,210 +11555,6 @@ await link.create({
 ```
 
 
-# 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",
-  },
-})
-```
-
-
 # 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.
@@ -11820,6 +11616,232 @@ export default defineLink(
 ```
 
 
+# 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).
+
+
 # Query
 
 In this chapter, you’ll learn about Query and how to use it to fetch data from modules.
@@ -12376,665 +12398,209 @@ 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.
 
 
-# Query Context
+# Link
 
-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).
+In this chapter, you’ll learn what Link is and how to use it to manage links.
 
-## What is Query Context?
+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.
 
-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.
+## What is Link?
 
-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).
+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.
 
 ***
 
-## How to Use Query Context
+## Create Link
 
-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`).
+To create a link between records of two data models, use the `create` method of Link.
 
-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:
+For example:
 
 ```ts
-const { data } = await query.graph({
-  entity: "post",
-  fields: ["*"],
-  context: QueryContext({
-    lang: "es",
-  }),
-})
-```
+import { Modules } from "@medusajs/framework/utils"
 
-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",
-    }),
+await link.create({
+  [Modules.PRODUCT]: {
+    product_id: "prod_123",
+  },
+  "helloModuleService": {
+    my_custom_id: "mc_123",
   },
 })
 ```
 
-In this example, you retrieve products and their associated posts. You also pass a context for `post`, indicating the customer's language.
+The `create` method accepts as a parameter an object. The object’s keys are the names of the linked modules.
 
-To handle the context, you override the generated `listPosts` method of the Blog Module as explained [previously](#how-to-use-query-context).
+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.
 
-# Create a Plugin
+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.
 
-In this chapter, you'll learn how to create a Medusa plugin and publish it.
+### Enforced Integrity Constraints on Link Creation
 
-A [plugin](https://docs.medusajs.com/learn/fundamentals/plugins/index.html.md) is a package of reusable Medusa customizations that you can install in any Medusa application. By creating and publishing a plugin, you can reuse your Medusa customizations across multiple projects or share them with the community.
+Medusa enforces integrity constraints on links based on the link's relation type. So, an error is thrown in the following scenarios:
 
-Plugins are available starting from [Medusa v2.3.0](https://github.com/medusajs/medusa/releases/tag/v2.3.0).
-
-## 1. Create a Plugin Project
-
-Plugins are created in a separate Medusa project. This makes the development and publishing of the plugin easier. Later, you'll install that plugin in your Medusa application to test it out and use it.
-
-Medusa's `create-medusa-app` CLI tool provides the option to create a plugin project. Run the following command to create a new plugin project:
-
-```bash
-npx create-medusa-app my-plugin --plugin
-```
-
-This will create a new Medusa plugin project in the `my-plugin` directory.
-
-### Plugin Directory Structure
-
-After the installation is done, the plugin structure will look like this:
-
-![Directory structure of a plugin project](https://res.cloudinary.com/dza7lstvk/image/upload/v1737019441/Medusa%20Book/project-dir_q4xtri.jpg)
-
-- `src/`: Contains the Medusa customizations.
-- `src/admin`: Contains [admin extensions](https://docs.medusajs.com/learn/fundamentals/admin/index.html.md).
-- `src/api`: Contains [API routes](https://docs.medusajs.com/learn/fundamentals/api-routes/index.html.md) and [middlewares](https://docs.medusajs.com/learn/fundamentals/api-routes/middlewares/index.html.md). You can add store, admin, or any custom API routes.
-- `src/jobs`: Contains [scheduled jobs](https://docs.medusajs.com/learn/fundamentals/scheduled-jobs/index.html.md).
-- `src/links`: Contains [module links](https://docs.medusajs.com/learn/fundamentals/module-links/index.html.md).
-- `src/modules`: Contains [modules](https://docs.medusajs.com/learn/fundamentals/modules/index.html.md).
-- `src/provider`: Contains [module providers](#create-module-providers).
-- `src/subscribers`: Contains [subscribers](https://docs.medusajs.com/learn/fundamentals/events-and-subscribers/index.html.md).
-- `src/workflows`: Contains [workflows](https://docs.medusajs.com/learn/fundamentals/workflows/index.html.md). You can also add [hooks](https://docs.medusajs.com/learn/fundamentals/workflows/add-workflow-hook/index.html.md) under `src/workflows/hooks`.
-- `package.json`: Contains the plugin's package information, including general information and dependencies.
-- `tsconfig.json`: Contains the TypeScript configuration for the plugin.
-
-***
-
-## 2. Prepare Plugin
-
-### Package Name
-
-Before developing, testing, and publishing your plugin, make sure its name in `package.json` is correct. This is the name you'll use to install the plugin in your Medusa application.
-
-For example:
-
-```json title="package.json"
-{
-  "name": "@myorg/plugin-name",
-  // ...
-}
-```
-
-### Package Keywords
-
-Medusa scrapes NPM for a list of plugins that integrate third-party services, to later showcase them on the Medusa website. If you want your plugin to appear in that listing, make sure to add the `medusa-v2` and `medusa-plugin-integration` keywords to the `keywords` field in `package.json`.
-
-Only plugins that integrate third-party services are listed in the Medusa integrations page. If your plugin doesn't integrate a third-party service, you can skip this step.
-
-```json title="package.json"
-{
-  "keywords": [
-    "medusa-plugin-integration",
-    "medusa-v2"
-  ],
-  // ...
-}
-```
-
-In addition, make sure to use one of the following keywords based on your integration type:
-
-|Keyword|Description|Example|
-|---|---|---|
-|\`medusa-plugin-analytics\`|Analytics service integration|Google Analytics|
-|\`medusa-plugin-auth\`|Authentication service integration|Auth0|
-|\`medusa-plugin-cms\`|CMS service integration|Contentful|
-|\`medusa-plugin-notification\`|Notification service integration|Twilio SMS|
-|\`medusa-plugin-payment\`|Payment service integration|PayPal|
-|\`medusa-plugin-search\`|Search service integration|MeiliSearch|
-|\`medusa-plugin-shipping\`|Shipping service integration|DHL|
-|\`medusa-plugin-other\`|Other third-party integrations|Sentry|
-
-### Package Dependencies
-
-Your plugin project will already have the dependencies mentioned in this section. Unless you made changes to the dependencies, you can skip this section.
-
-In the `package.json` file you must have the Medusa dependencies as `devDependencies` and `peerDependencies`. In addition, you must have `@swc/core` as a `devDependency`, as it's used by the plugin CLI tools.
-
-For example, assuming `2.5.0` is the latest Medusa version:
-
-```json title="package.json"
-{
-  "devDependencies": {
-    "@medusajs/admin-sdk": "2.5.0",
-    "@medusajs/cli": "2.5.0",
-    "@medusajs/framework": "2.5.0",
-    "@medusajs/medusa": "2.5.0",
-    "@medusajs/test-utils": "2.5.0",
-    "@medusajs/ui": "4.0.4",
-    "@medusajs/icons": "2.5.0",
-    "@swc/core": "1.5.7",
-  },
-  "peerDependencies": {
-    "@medusajs/admin-sdk": "2.5.0",
-    "@medusajs/cli": "2.5.0",
-    "@medusajs/framework": "2.5.0",
-    "@medusajs/test-utils": "2.5.0",
-    "@medusajs/medusa": "2.5.0",
-    "@medusajs/ui": "4.0.3",
-    "@medusajs/icons": "2.5.0",
-  }
-}
-```
-
-### Package Exports
-
-Your plugin project will already have the exports mentioned in this section. Unless you made changes to the exports or you created your plugin before [Medusa v2.7.0](https://github.com/medusajs/medusa/releases/tag/v2.7.0), you can skip this section.
-
-In the `package.json` file, make sure your plugin has the following exports:
-
-```json title="package.json"
-{
-  "exports": {
-    "./package.json": "./package.json",
-    "./workflows": "./.medusa/server/src/workflows/index.js",
-    "./.medusa/server/src/modules/*": "./.medusa/server/src/modules/*/index.js",
-    "./providers/*": "./.medusa/server/src/providers/*/index.js",
-    "./admin": {
-      "import": "./.medusa/server/src/admin/index.mjs",
-      "require": "./.medusa/server/src/admin/index.js",
-      "default": "./.medusa/server/src/admin/index.js"
-    },
-    "./*": "./.medusa/server/src/*.js"
-  }
-}
-```
-
-Aside from the `./package.json`, `./providers`, and `./admin`, these exports are only a recommendation. You can cherry-pick the files and directories you want to export.
-
-The plugin exports the following files and directories:
-
-- `./package.json`: The `package.json` file. Medusa needs to access the `package.json` when registering the plugin.
-- `./workflows`: The workflows exported in `./src/workflows/index.ts`.
-- `./.medusa/server/src/modules/*`: The definition file of modules. This is useful if you create links to the plugin's modules in the Medusa application.
-- `./providers/*`: The definition file of module providers. This is useful if your plugin includes a module provider, allowing you to register the plugin's providers in Medusa applications. Learn more in the [Create Module Providers](#create-module-providers) section.
-- `./admin`: The admin extensions exported in `./src/admin/index.ts`.
-- `./*`: Any other files in the plugin's `src` directory.
-
-***
-
-## 3. Publish Plugin Locally for Development and Testing
-
-Medusa's CLI tool provides commands to simplify developing and testing your plugin in a local Medusa application. You start by publishing your plugin in the local package registry, then install it in your Medusa application. You can then watch for changes in the plugin as you develop it.
-
-### Publish and Install Local Package
-
-### Prerequisites
-
-- [Medusa application installed.](https://docs.medusajs.com/learn/installation/index.html.md)
-
-The first time you create your plugin, you need to publish the package into a local package registry, then install it in your Medusa application. This is a one-time only process.
-
-To publish the plugin to the local registry, run the following command in your plugin project:
-
-```bash title="Plugin project"
-npx medusa plugin:publish
-```
-
-This command uses [Yalc](https://github.com/wclr/yalc) under the hood to publish the plugin to a local package registry. The plugin is published locally under the name you specified in `package.json`.
-
-Next, navigate to your Medusa application:
-
-```bash title="Medusa application"
-cd ~/path/to/medusa-app
-```
-
-Make sure to replace `~/path/to/medusa-app` with the path to your Medusa application.
-
-Then, if your project was created before v2.3.1 of Medusa, make sure to install `yalc` as a development dependency:
-
-```bash npm2yarn badgeLabel="Medusa Application" badgeColor="green"
-npm install --save-dev yalc
-```
-
-After that, run the following Medusa CLI command to install the plugin:
-
-```bash title="Medusa application"
-npx medusa plugin:add @myorg/plugin-name
-```
-
-Make sure to replace `@myorg/plugin-name` with the name of your plugin as specified in `package.json`. Your plugin will be installed from the local package registry into your Medusa application.
-
-### Register Plugin in Medusa Application
-
-After installing the plugin, you need to register it in your Medusa application in the configurations defined in `medusa-config.ts`.
-
-Add the plugin to the `plugins` array in the `medusa-config.ts` file:
-
-```ts title="medusa-config.ts" highlights={pluginHighlights}
-module.exports = defineConfig({
-  // ...
-  plugins: [
-    {
-      resolve: "@myorg/plugin-name",
-      options: {},
-    },
-  ],
-})
-```
-
-The `plugins` configuration is an array of objects where each object has a `resolve` key whose value is the name of the plugin package.
-
-#### Pass Module Options through Plugin
-
-Each plugin configuration also accepts an `options` property, whose value is an object of options to pass to the plugin's modules.
-
-For example:
-
-```ts title="medusa-config.ts" highlights={pluginOptionsHighlight}
-module.exports = defineConfig({
-  // ...
-  plugins: [
-    {
-      resolve: "@myorg/plugin-name",
-      options: {
-        apiKey: true,
-      },
-    },
-  ],
-})
-```
-
-The `options` property in the plugin configuration is passed to all modules in the plugin. Learn more about module options in [this chapter](https://docs.medusajs.com/learn/fundamentals/modules/options/index.html.md).
-
-### Watch Plugin Changes During Development
-
-While developing your plugin, you can watch for changes in the plugin and automatically update the plugin in the Medusa application using it. This is the only command you'll continuously need during your plugin development.
-
-To do that, run the following command in your plugin project:
-
-```bash title="Plugin project"
-npx medusa plugin:develop
-```
-
-This command will:
-
-- Watch for changes in the plugin. Whenever a file is changed, the plugin is automatically built.
-- Publish the plugin changes to the local package registry. This will automatically update the plugin in the Medusa application using it. You can also benefit from real-time HMR updates of admin extensions.
-
-### Start Medusa Application
-
-You can start your Medusa application's development server to test out your plugin:
-
-```bash npm2yarn badgeLabel="Medusa Application" badgeColor="green"
-npm run dev
-```
-
-While your Medusa application is running and the plugin is being watched, you can test your plugin while developing it in the Medusa application.
-
-***
-
-## 4. Create Customizations in the Plugin
-
-You can now build your plugin's customizations. The following guide explains how to build different customizations in your plugin.
-
-- [Create a module](https://docs.medusajs.com/learn/fundamentals/modules/index.html.md)
-- [Create a module link](https://docs.medusajs.com/learn/fundamentals/module-links/index.html.md)
-- [Create a workflow](https://docs.medusajs.com/learn/fundamentals/workflows/index.html.md)
-- [Add a workflow hook](https://docs.medusajs.com/learn/fundamentals/workflows/add-workflow-hook/index.html.md)
-- [Create an API route](https://docs.medusajs.com/learn/fundamentals/api-routes/index.html.md)
-- [Add a subscriber](https://docs.medusajs.com/learn/fundamentals/events-and-subscribers/index.html.md)
-- [Add a scheduled job](https://docs.medusajs.com/learn/fundamentals/scheduled-jobs/index.html.md)
-- [Add an admin widget](https://docs.medusajs.com/learn/fundamentals/admin/widgets/index.html.md)
-- [Add an admin UI route](https://docs.medusajs.com/learn/fundamentals/admin/ui-routes/index.html.md)
-
-While building those customizations, you can test them in your Medusa application by [watching the plugin changes](#watch-plugin-changes-during-development) and [starting the Medusa application](#start-medusa-application).
-
-### Generating Migrations for Modules
-
-During your development, you may need to generate migrations for modules in your plugin. To do that, first, add the following environment variables in your plugin project:
-
-```plain title="Plugin project"
-DB_USERNAME=postgres
-DB_PASSWORD=123...
-DB_HOST=localhost
-DB_PORT=5432
-DB_NAME=db_name
-```
-
-You can add these environment variables in a `.env` file in your plugin project. The variables are:
-
-- `DB_USERNAME`: The username of the PostgreSQL user to connect to the database.
-- `DB_PASSWORD`: The password of the PostgreSQL user to connect to the database.
-- `DB_HOST`: The host of the PostgreSQL database. Typically, it's `localhost` if you're running the database locally.
-- `DB_PORT`: The port of the PostgreSQL database. Typically, it's `5432` if you're running the database locally.
-- `DB_NAME`: The name of the PostgreSQL database to connect to.
-
-Then, run the following command in your plugin project to generate migrations for the modules in your plugin:
-
-```bash title="Plugin project"
-npx medusa plugin:db:generate
-```
-
-This command generates migrations for all modules in the plugin.
-
-Finally, run these migrations on the Medusa application that the plugin is installed in using the `db:migrate` command:
-
-```bash title="Medusa application"
-npx medusa db:migrate
-```
-
-The migrations in your application, including your plugin, will run and update the database.
-
-### Importing Module Resources
-
-In the [Prepare Plugin](#2-prepare-plugin) section, you learned about [exported resources](#package-exports) in your plugin.
-
-These exports allow you to import your plugin resources in your Medusa application, including workflows, links and modules.
-
-For example, to import the plugin's workflow in your Medusa application:
-
-`@myorg/plugin-name` is the plugin package's name.
+- 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
-import { Workflow1, Workflow2 } from "@myorg/plugin-name/workflows"
-import BlogModule from "@myorg/plugin-name/modules/blog"
-// import other files created in plugin like ./src/types/blog.ts
-import BlogType from "@myorg/plugin-name/types/blog"
-```
+// no error
+await link.create({
+  [Modules.PRODUCT]: {
+    product_id: "prod_123",
+  },
+  "helloModuleService": {
+    my_custom_id: "mc_123",
+  },
+})
 
-### Create Module Providers
-
-The [exported resources](#package-exports) also allow you to import module providers in your plugin and register them in the Medusa application's configuration. A module provider is a module that provides the underlying logic or integration related to a commerce or Infrastructure Module.
-
-For example, assuming your plugin has a [Notification Module Provider](https://docs.medusajs.com/resources/infrastructure-modules/notification/index.html.md) called `my-notification`, you can register it in your Medusa application's configuration like this:
-
-`@myorg/plugin-name` is the plugin package's name.
-
-```ts highlights={[["9"]]} title="medusa-config.ts"
-module.exports = defineConfig({
-  // ...
-  modules: [
-    {
-      resolve: "@medusajs/medusa/notification",
-      options: {
-        providers: [
-          {
-            resolve: "@myorg/plugin-name/providers/my-notification",
-            id: "my-notification",
-            options: {
-              channels: ["email"],
-              // provider options...
-            },
-          },
-        ],
-      },
-    },
-  ],
+// 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",
+  },
 })
 ```
 
-You pass to `resolve` the path to the provider relative to the plugin package. So, in this example, the `my-notification` provider is located in `./src/providers/my-notification/index.ts` of the plugin.
+- 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:
 
-To learn how to create module providers, refer to the following guides:
+```ts
+// no error
+await link.create({
+  [Modules.PRODUCT]: {
+    product_id: "prod_123",
+  },
+  "helloModuleService": {
+    my_custom_id: "mc_123",
+  },
+})
 
-- [File Module Provider](https://docs.medusajs.com/resources/references/file-provider-module/index.html.md)
-- [Notification Module Provider](https://docs.medusajs.com/resources/references/notification-provider-module/index.html.md)
-- [Auth Module Provider](https://docs.medusajs.com/resources/references/auth/provider/index.html.md)
-- [Payment Module Provider](https://docs.medusajs.com/resources/references/payment/provider/index.html.md)
-- [Fulfillment Module Provider](https://docs.medusajs.com/resources/references/fulfillment/provider/index.html.md)
-- [Tax Module Provider](https://docs.medusajs.com/resources/references/tax/provider/index.html.md)
+// 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.
 
 ***
 
-## 5. Publish Plugin to NPM
+## Dismiss Link
 
-Make sure to add the keywords mentioned in the [Package Keywords](#package-keywords) section in your plugin's `package.json` file.
+To remove a link between records of two data models, use the `dismiss` method of Link.
 
-Medusa's CLI tool provides a command that bundles your plugin to be published to npm. Once you're ready to publish your plugin publicly, run the following command in your plugin project:
+For example:
 
-```bash
-npx medusa plugin:build
+```ts
+import { Modules } from "@medusajs/framework/utils"
+
+// ...
+
+await link.dismiss({
+  [Modules.PRODUCT]: {
+    product_id: "prod_123",
+  },
+  "helloModuleService": {
+    my_custom_id: "mc_123",
+  },
+})
 ```
 
-The command will compile an output in the `.medusa/server` directory.
+The `dismiss` method accepts the same parameter type as the [create method](#create-link).
 
-You can now publish the plugin to npm using the [NPM CLI tool](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm). Run the following command to publish the plugin to npm:
-
-```bash
-npm publish
-```
-
-If you haven't logged in before with your NPM account, you'll be asked to log in first. Then, your package is published publicly to be used in any Medusa application.
-
-### Install Public Plugin in Medusa Application
-
-You install a plugin that's published publicly using your package manager. For example:
-
-```bash npm2yarn
-npm install @myorg/plugin-name
-```
-
-Where `@myorg/plugin-name` is the name of your plugin as published on NPM.
-
-Then, register the plugin in your Medusa application's configurations as explained in [this section](#register-plugin-in-medusa-application).
+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.
 
 ***
 
-## Update a Published Plugin
+## Cascade Delete Linked Records
 
-To update the Medusa dependencies in a plugin, refer to [this documentation](https://docs.medusajs.com/learn/update#update-plugin-project/index.html.md).
+If a record is deleted, use the `delete` method of Link to delete all linked records.
 
-If you've published a plugin and you've made changes to it, you'll have to publish the update to NPM again.
+For example:
 
-First, run the following command to change the version of the plugin:
+```ts
+import { Modules } from "@medusajs/framework/utils"
 
-```bash
-npm version <type>
+// ...
+
+await productModuleService.deleteVariants([variant.id])
+
+await link.delete({
+  [Modules.PRODUCT]: {
+    product_id: "prod_123",
+  },
+})
 ```
 
-Where `<type>` indicates the type of version update you’re publishing. For example, it can be `major` or `minor`. Refer to the [npm version documentation](https://docs.npmjs.com/cli/v10/commands/npm-version) for more information.
+This deletes all records linked to the deleted product.
 
-Then, re-run the same commands for publishing a plugin:
+***
 
-```bash
-npx medusa plugin:build
-npm publish
+## 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",
+  },
+})
 ```
 
-This will publish an updated version of your plugin under a new version.
-
 
 # Read-Only Module Link
 
@@ -13542,6 +13108,50 @@ If multiple posts have their `product_id` set to a product's ID, an array of pos
 [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.
+
+
 # Module Container
 
 In this chapter, you'll learn about the module's container and how to resolve resources in that container.
@@ -13608,80 +13218,6 @@ export default async function helloWorldLoader({
 ```
 
 
-# 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.
-
-
-# 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.
@@ -14289,6 +13825,107 @@ class BlogModuleService {
 ```
 
 
+# Module Isolation
+
+In this chapter, you'll learn how modules are isolated, and what that means for your custom development.
+
+- Modules can't access resources, such as services or data models, from other modules.
+- Use Medusa's linking concepts, as explained in the [Module Links chapters](https://docs.medusajs.com/learn/fundamentals/module-links/index.html.md), to extend a module's data models and retrieve data across modules.
+
+## How are Modules Isolated?
+
+A module is unaware of any resources other than its own, such as services or data models. This means it can't access these resources if they're implemented in another module.
+
+For example, your custom module can't resolve the Product Module's main service or have direct relationships from its data model to the Product Module's data models.
+
+***
+
+## Why are Modules Isolated
+
+Some of the module isolation's benefits include:
+
+- Integrate your module into any Medusa application without side-effects to your setup.
+- Replace existing modules with your custom implementation, if your use case is drastically different.
+- Use modules in other environments, such as Edge functions and Next.js apps.
+
+***
+
+## How to Extend Data Model of Another Module?
+
+To extend the data model of another module, such as the `product` data model of the Product Module, use Medusa's linking concepts as explained in the [Module Links chapters](https://docs.medusajs.com/learn/fundamentals/module-links/index.html.md).
+
+***
+
+## How to Use Services of Other Modules?
+
+If you're building a feature that uses functionalities from different modules, use a workflow whose steps resolve the modules' services to perform these functionalities.
+
+Workflows ensure data consistency through their roll-back mechanism and tracking of each execution's status, steps, input, and output.
+
+### Example
+
+For example, consider you have two modules:
+
+1. A module that stores and manages brands in your application.
+2. A module that integrates a third-party Content Management System (CMS).
+
+To sync brands from your application to the third-party system, create the following steps:
+
+```ts title="Example Steps" highlights={stepsHighlights}
+const retrieveBrandsStep = createStep(
+  "retrieve-brands",
+  async (_, { container }) => {
+    const brandModuleService = container.resolve(
+      "brandModuleService"
+    )
+
+    const brands = await brandModuleService.listBrands()
+
+    return new StepResponse(brands)
+  }
+)
+
+const createBrandsInCmsStep = createStep(
+  "create-brands-in-cms",
+  async ({ brands }, { container }) => {
+    const cmsModuleService = container.resolve(
+      "cmsModuleService"
+    )
+
+    const cmsBrands = await cmsModuleService.createBrands(brands)
+
+    return new StepResponse(cmsBrands, cmsBrands)
+  },
+  async (brands, { container }) => {
+    const cmsModuleService = container.resolve(
+      "cmsModuleService"
+    )
+
+    await cmsModuleService.deleteBrands(
+      brands.map((brand) => brand.id)
+    )
+  }
+)
+```
+
+The `retrieveBrandsStep` retrieves the brands from a brand module, and the `createBrandsInCmsStep` creates the brands in a third-party system using a CMS module.
+
+Then, create the following workflow that uses these steps:
+
+```ts title="Example Workflow"
+export const syncBrandsWorkflow = createWorkflow(
+  "sync-brands",
+  () => {
+    const brands = retrieveBrandsStep()
+
+    createBrandsInCmsStep({ brands })
+  }
+)
+```
+
+You can then use this workflow in an API route, scheduled job, or other resources that use this functionality.
+
+
 # Infrastructure Modules
 
 In this chapter, you’ll learn about Infrastructure Modules.
@@ -14574,107 +14211,6 @@ info:    Connected to MongoDB
 You can now resolve the MongoDB Module's main service in your customizations to perform operations on the MongoDB database.
 
 
-# Module Isolation
-
-In this chapter, you'll learn how modules are isolated, and what that means for your custom development.
-
-- Modules can't access resources, such as services or data models, from other modules.
-- Use Medusa's linking concepts, as explained in the [Module Links chapters](https://docs.medusajs.com/learn/fundamentals/module-links/index.html.md), to extend a module's data models and retrieve data across modules.
-
-## How are Modules Isolated?
-
-A module is unaware of any resources other than its own, such as services or data models. This means it can't access these resources if they're implemented in another module.
-
-For example, your custom module can't resolve the Product Module's main service or have direct relationships from its data model to the Product Module's data models.
-
-***
-
-## Why are Modules Isolated
-
-Some of the module isolation's benefits include:
-
-- Integrate your module into any Medusa application without side-effects to your setup.
-- Replace existing modules with your custom implementation, if your use case is drastically different.
-- Use modules in other environments, such as Edge functions and Next.js apps.
-
-***
-
-## How to Extend Data Model of Another Module?
-
-To extend the data model of another module, such as the `product` data model of the Product Module, use Medusa's linking concepts as explained in the [Module Links chapters](https://docs.medusajs.com/learn/fundamentals/module-links/index.html.md).
-
-***
-
-## How to Use Services of Other Modules?
-
-If you're building a feature that uses functionalities from different modules, use a workflow whose steps resolve the modules' services to perform these functionalities.
-
-Workflows ensure data consistency through their roll-back mechanism and tracking of each execution's status, steps, input, and output.
-
-### Example
-
-For example, consider you have two modules:
-
-1. A module that stores and manages brands in your application.
-2. A module that integrates a third-party Content Management System (CMS).
-
-To sync brands from your application to the third-party system, create the following steps:
-
-```ts title="Example Steps" highlights={stepsHighlights}
-const retrieveBrandsStep = createStep(
-  "retrieve-brands",
-  async (_, { container }) => {
-    const brandModuleService = container.resolve(
-      "brandModuleService"
-    )
-
-    const brands = await brandModuleService.listBrands()
-
-    return new StepResponse(brands)
-  }
-)
-
-const createBrandsInCmsStep = createStep(
-  "create-brands-in-cms",
-  async ({ brands }, { container }) => {
-    const cmsModuleService = container.resolve(
-      "cmsModuleService"
-    )
-
-    const cmsBrands = await cmsModuleService.createBrands(brands)
-
-    return new StepResponse(cmsBrands, cmsBrands)
-  },
-  async (brands, { container }) => {
-    const cmsModuleService = container.resolve(
-      "cmsModuleService"
-    )
-
-    await cmsModuleService.deleteBrands(
-      brands.map((brand) => brand.id)
-    )
-  }
-)
-```
-
-The `retrieveBrandsStep` retrieves the brands from a brand module, and the `createBrandsInCmsStep` creates the brands in a third-party system using a CMS module.
-
-Then, create the following workflow that uses these steps:
-
-```ts title="Example Workflow"
-export const syncBrandsWorkflow = createWorkflow(
-  "sync-brands",
-  () => {
-    const brands = retrieveBrandsStep()
-
-    createBrandsInCmsStep({ brands })
-  }
-)
-```
-
-You can then use this workflow in an API route, scheduled job, or other resources that use this functionality.
-
-
 # Modules Directory Structure
 
 In this document, you'll learn about the expected files and directories in your module.
@@ -14702,172 +14238,6 @@ The following directories are optional and their content are explained more in t
 - `loaders`: Holds the scripts to run on the Medusa application's start-up.
 
 
-# Multiple Services in a Module
-
-In this chapter, you'll learn how to use multiple services in a module.
-
-## Module's Main and Internal Services
-
-A module has one main service only, which is the service exported in the module's definition.
-
-However, you may use other services in your module to better organize your code or split functionalities. These are called internal services that can be resolved within your module, but not in external resources.
-
-***
-
-## How to Add an Internal Service
-
-### 1. Create Service
-
-To add an internal service, create it in the `services` directory of your module.
-
-For example, create the file `src/modules/blog/services/client.ts` with the following content:
-
-```ts title="src/modules/blog/services/client.ts"
-export class ClientService {
-  async getMessage(): Promise<string> {
-    return "Hello, World!"
-  }
-}
-```
-
-### 2. Export Service in Index
-
-Next, create an `index.ts` file under the `services` directory of the module that exports your internal services.
-
-For example, create the file `src/modules/blog/services/index.ts` with the following content:
-
-```ts title="src/modules/blog/services/index.ts"
-export * from "./client"
-```
-
-This exports the `ClientService`.
-
-### 3. Resolve Internal Service
-
-Internal services exported in the `services/index.ts` file of your module are now registered in the container and can be resolved in other services in the module as well as loaders.
-
-For example, in your main service:
-
-```ts title="src/modules/blog/service.ts" highlights={[["5"], ["13"]]}
-// other imports...
-import { ClientService } from "./services"
-
-type InjectedDependencies = {
-  clientService: ClientService
-}
-
-class BlogModuleService extends MedusaService({
-  Post,
-}){
-  protected clientService_: ClientService
-
-  constructor({ clientService }: InjectedDependencies) {
-    super(...arguments)
-    this.clientService_ = clientService
-  }
-}
-```
-
-You can now use your internal service in your main service.
-
-***
-
-## Resolve Resources in Internal Service
-
-Resolve dependencies from your module's container in the constructor of your internal service.
-
-For example:
-
-```ts
-import { Logger } from "@medusajs/framework/types"
-
-type InjectedDependencies = {
-  logger: Logger
-}
-
-export class ClientService {
-  protected logger_: Logger
-
-  constructor({ logger }: InjectedDependencies) {
-    this.logger_ = logger
-  }
-}
-```
-
-***
-
-## Access Module Options
-
-Your internal service can't access the module's options.
-
-To retrieve the module's options, use the `configModule` registered in the module's container, which is the configurations in `medusa-config.ts`.
-
-For example:
-
-```ts
-import { ConfigModule } from "@medusajs/framework/types"
-import { BLOG_MODULE } from ".."
-
-export type InjectedDependencies = {
-  configModule: ConfigModule
-}
-
-export class ClientService {
-  protected options: Record<string, any>
-
-  constructor({ configModule }: InjectedDependencies) {
-    const moduleDef = configModule.modules[BLOG_MODULE]
-
-    if (typeof moduleDef !== "boolean") {
-      this.options = moduleDef.options
-    }
-  }
-}
-```
-
-The `configModule` has a `modules` property that includes all registered modules. Retrieve the module's configuration using its registration key.
-
-If its value is not a `boolean`, set the service's options to the module configuration's `options` property.
-
-
-# Service Constraints
-
-This chapter lists constraints to keep in mind when creating a service.
-
-## Use Async Methods
-
-Medusa wraps service method executions to inject useful context or transactions. However, since Medusa can't detect whether the method is asynchronous, it always executes methods in the wrapper with the `await` keyword.
-
-For example, if you have a synchronous `getMessage` method, and you use it in other resources like workflows, Medusa executes it as an async method:
-
-```ts
-await blogModuleService.getMessage()
-```
-
-So, make sure your service's methods are always async to avoid unexpected errors or behavior.
-
-```ts highlights={[["8", "", "Method must be async."], ["13", "async", "Correct way of defining the method."]]}
-import { MedusaService } from "@medusajs/framework/utils"
-import Post from "./models/post"
-
-class BlogModuleService extends MedusaService({
-  Post,
-}){
-  // Don't
-  getMessage(): string {
-    return "Hello, World!"
-  }
-
-  // Do
-  async getMessage(): Promise<string> {
-    return "Hello, World!"
-  }
-}
-
-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.
@@ -15033,6 +14403,44 @@ export default Module(BLOG_MODULE, {
 Now, when the Medusa application starts, the loader will run, validating the module's options and throwing an error if the `apiKey` option is missing.
 
 
+# Service Constraints
+
+This chapter lists constraints to keep in mind when creating a service.
+
+## Use Async Methods
+
+Medusa wraps service method executions to inject useful context or transactions. However, since Medusa can't detect whether the method is asynchronous, it always executes methods in the wrapper with the `await` keyword.
+
+For example, if you have a synchronous `getMessage` method, and you use it in other resources like workflows, Medusa executes it as an async method:
+
+```ts
+await blogModuleService.getMessage()
+```
+
+So, make sure your service's methods are always async to avoid unexpected errors or behavior.
+
+```ts highlights={[["8", "", "Method must be async."], ["13", "async", "Correct way of defining the method."]]}
+import { MedusaService } from "@medusajs/framework/utils"
+import Post from "./models/post"
+
+class BlogModuleService extends MedusaService({
+  Post,
+}){
+  // Don't
+  getMessage(): string {
+    return "Hello, World!"
+  }
+
+  // Do
+  async getMessage(): Promise<string> {
+    return "Hello, World!"
+  }
+}
+
+export default BlogModuleService
+```
+
+
 # Service Factory
 
 In this chapter, you’ll learn about what the service factory is and how to use it.
@@ -15208,6 +14616,667 @@ export default BlogModuleService
 ```
 
 
+# Multiple Services in a Module
+
+In this chapter, you'll learn how to use multiple services in a module.
+
+## Module's Main and Internal Services
+
+A module has one main service only, which is the service exported in the module's definition.
+
+However, you may use other services in your module to better organize your code or split functionalities. These are called internal services that can be resolved within your module, but not in external resources.
+
+***
+
+## How to Add an Internal Service
+
+### 1. Create Service
+
+To add an internal service, create it in the `services` directory of your module.
+
+For example, create the file `src/modules/blog/services/client.ts` with the following content:
+
+```ts title="src/modules/blog/services/client.ts"
+export class ClientService {
+  async getMessage(): Promise<string> {
+    return "Hello, World!"
+  }
+}
+```
+
+### 2. Export Service in Index
+
+Next, create an `index.ts` file under the `services` directory of the module that exports your internal services.
+
+For example, create the file `src/modules/blog/services/index.ts` with the following content:
+
+```ts title="src/modules/blog/services/index.ts"
+export * from "./client"
+```
+
+This exports the `ClientService`.
+
+### 3. Resolve Internal Service
+
+Internal services exported in the `services/index.ts` file of your module are now registered in the container and can be resolved in other services in the module as well as loaders.
+
+For example, in your main service:
+
+```ts title="src/modules/blog/service.ts" highlights={[["5"], ["13"]]}
+// other imports...
+import { ClientService } from "./services"
+
+type InjectedDependencies = {
+  clientService: ClientService
+}
+
+class BlogModuleService extends MedusaService({
+  Post,
+}){
+  protected clientService_: ClientService
+
+  constructor({ clientService }: InjectedDependencies) {
+    super(...arguments)
+    this.clientService_ = clientService
+  }
+}
+```
+
+You can now use your internal service in your main service.
+
+***
+
+## Resolve Resources in Internal Service
+
+Resolve dependencies from your module's container in the constructor of your internal service.
+
+For example:
+
+```ts
+import { Logger } from "@medusajs/framework/types"
+
+type InjectedDependencies = {
+  logger: Logger
+}
+
+export class ClientService {
+  protected logger_: Logger
+
+  constructor({ logger }: InjectedDependencies) {
+    this.logger_ = logger
+  }
+}
+```
+
+***
+
+## Access Module Options
+
+Your internal service can't access the module's options.
+
+To retrieve the module's options, use the `configModule` registered in the module's container, which is the configurations in `medusa-config.ts`.
+
+For example:
+
+```ts
+import { ConfigModule } from "@medusajs/framework/types"
+import { BLOG_MODULE } from ".."
+
+export type InjectedDependencies = {
+  configModule: ConfigModule
+}
+
+export class ClientService {
+  protected options: Record<string, any>
+
+  constructor({ configModule }: InjectedDependencies) {
+    const moduleDef = configModule.modules[BLOG_MODULE]
+
+    if (typeof moduleDef !== "boolean") {
+      this.options = moduleDef.options
+    }
+  }
+}
+```
+
+The `configModule` has a `modules` property that includes all registered modules. Retrieve the module's configuration using its registration key.
+
+If its value is not a `boolean`, set the service's options to the module configuration's `options` property.
+
+
+# Create a Plugin
+
+In this chapter, you'll learn how to create a Medusa plugin and publish it.
+
+A [plugin](https://docs.medusajs.com/learn/fundamentals/plugins/index.html.md) is a package of reusable Medusa customizations that you can install in any Medusa application. By creating and publishing a plugin, you can reuse your Medusa customizations across multiple projects or share them with the community.
+
+Plugins are available starting from [Medusa v2.3.0](https://github.com/medusajs/medusa/releases/tag/v2.3.0).
+
+## 1. Create a Plugin Project
+
+Plugins are created in a separate Medusa project. This makes the development and publishing of the plugin easier. Later, you'll install that plugin in your Medusa application to test it out and use it.
+
+Medusa's `create-medusa-app` CLI tool provides the option to create a plugin project. Run the following command to create a new plugin project:
+
+```bash
+npx create-medusa-app my-plugin --plugin
+```
+
+This will create a new Medusa plugin project in the `my-plugin` directory.
+
+### Plugin Directory Structure
+
+After the installation is done, the plugin structure will look like this:
+
+![Directory structure of a plugin project](https://res.cloudinary.com/dza7lstvk/image/upload/v1737019441/Medusa%20Book/project-dir_q4xtri.jpg)
+
+- `src/`: Contains the Medusa customizations.
+- `src/admin`: Contains [admin extensions](https://docs.medusajs.com/learn/fundamentals/admin/index.html.md).
+- `src/api`: Contains [API routes](https://docs.medusajs.com/learn/fundamentals/api-routes/index.html.md) and [middlewares](https://docs.medusajs.com/learn/fundamentals/api-routes/middlewares/index.html.md). You can add store, admin, or any custom API routes.
+- `src/jobs`: Contains [scheduled jobs](https://docs.medusajs.com/learn/fundamentals/scheduled-jobs/index.html.md).
+- `src/links`: Contains [module links](https://docs.medusajs.com/learn/fundamentals/module-links/index.html.md).
+- `src/modules`: Contains [modules](https://docs.medusajs.com/learn/fundamentals/modules/index.html.md).
+- `src/provider`: Contains [module providers](#create-module-providers).
+- `src/subscribers`: Contains [subscribers](https://docs.medusajs.com/learn/fundamentals/events-and-subscribers/index.html.md).
+- `src/workflows`: Contains [workflows](https://docs.medusajs.com/learn/fundamentals/workflows/index.html.md). You can also add [hooks](https://docs.medusajs.com/learn/fundamentals/workflows/add-workflow-hook/index.html.md) under `src/workflows/hooks`.
+- `package.json`: Contains the plugin's package information, including general information and dependencies.
+- `tsconfig.json`: Contains the TypeScript configuration for the plugin.
+
+***
+
+## 2. Prepare Plugin
+
+### Package Name
+
+Before developing, testing, and publishing your plugin, make sure its name in `package.json` is correct. This is the name you'll use to install the plugin in your Medusa application.
+
+For example:
+
+```json title="package.json"
+{
+  "name": "@myorg/plugin-name",
+  // ...
+}
+```
+
+### Package Keywords
+
+Medusa scrapes NPM for a list of plugins that integrate third-party services, to later showcase them on the Medusa website. If you want your plugin to appear in that listing, make sure to add the `medusa-v2` and `medusa-plugin-integration` keywords to the `keywords` field in `package.json`.
+
+Only plugins that integrate third-party services are listed in the Medusa integrations page. If your plugin doesn't integrate a third-party service, you can skip this step.
+
+```json title="package.json"
+{
+  "keywords": [
+    "medusa-plugin-integration",
+    "medusa-v2"
+  ],
+  // ...
+}
+```
+
+In addition, make sure to use one of the following keywords based on your integration type:
+
+|Keyword|Description|Example|
+|---|---|---|
+|\`medusa-plugin-analytics\`|Analytics service integration|Google Analytics|
+|\`medusa-plugin-auth\`|Authentication service integration|Auth0|
+|\`medusa-plugin-cms\`|CMS service integration|Contentful|
+|\`medusa-plugin-notification\`|Notification service integration|Twilio SMS|
+|\`medusa-plugin-payment\`|Payment service integration|PayPal|
+|\`medusa-plugin-search\`|Search service integration|MeiliSearch|
+|\`medusa-plugin-shipping\`|Shipping service integration|DHL|
+|\`medusa-plugin-other\`|Other third-party integrations|Sentry|
+
+### Package Dependencies
+
+Your plugin project will already have the dependencies mentioned in this section. Unless you made changes to the dependencies, you can skip this section.
+
+In the `package.json` file you must have the Medusa dependencies as `devDependencies` and `peerDependencies`. In addition, you must have `@swc/core` as a `devDependency`, as it's used by the plugin CLI tools.
+
+For example, assuming `2.5.0` is the latest Medusa version:
+
+```json title="package.json"
+{
+  "devDependencies": {
+    "@medusajs/admin-sdk": "2.5.0",
+    "@medusajs/cli": "2.5.0",
+    "@medusajs/framework": "2.5.0",
+    "@medusajs/medusa": "2.5.0",
+    "@medusajs/test-utils": "2.5.0",
+    "@medusajs/ui": "4.0.4",
+    "@medusajs/icons": "2.5.0",
+    "@swc/core": "1.5.7",
+  },
+  "peerDependencies": {
+    "@medusajs/admin-sdk": "2.5.0",
+    "@medusajs/cli": "2.5.0",
+    "@medusajs/framework": "2.5.0",
+    "@medusajs/test-utils": "2.5.0",
+    "@medusajs/medusa": "2.5.0",
+    "@medusajs/ui": "4.0.3",
+    "@medusajs/icons": "2.5.0",
+  }
+}
+```
+
+### Package Exports
+
+Your plugin project will already have the exports mentioned in this section. Unless you made changes to the exports or you created your plugin before [Medusa v2.7.0](https://github.com/medusajs/medusa/releases/tag/v2.7.0), you can skip this section.
+
+In the `package.json` file, make sure your plugin has the following exports:
+
+```json title="package.json"
+{
+  "exports": {
+    "./package.json": "./package.json",
+    "./workflows": "./.medusa/server/src/workflows/index.js",
+    "./.medusa/server/src/modules/*": "./.medusa/server/src/modules/*/index.js",
+    "./providers/*": "./.medusa/server/src/providers/*/index.js",
+    "./admin": {
+      "import": "./.medusa/server/src/admin/index.mjs",
+      "require": "./.medusa/server/src/admin/index.js",
+      "default": "./.medusa/server/src/admin/index.js"
+    },
+    "./*": "./.medusa/server/src/*.js"
+  }
+}
+```
+
+Aside from the `./package.json`, `./providers`, and `./admin`, these exports are only a recommendation. You can cherry-pick the files and directories you want to export.
+
+The plugin exports the following files and directories:
+
+- `./package.json`: The `package.json` file. Medusa needs to access the `package.json` when registering the plugin.
+- `./workflows`: The workflows exported in `./src/workflows/index.ts`.
+- `./.medusa/server/src/modules/*`: The definition file of modules. This is useful if you create links to the plugin's modules in the Medusa application.
+- `./providers/*`: The definition file of module providers. This is useful if your plugin includes a module provider, allowing you to register the plugin's providers in Medusa applications. Learn more in the [Create Module Providers](#create-module-providers) section.
+- `./admin`: The admin extensions exported in `./src/admin/index.ts`.
+- `./*`: Any other files in the plugin's `src` directory.
+
+***
+
+## 3. Publish Plugin Locally for Development and Testing
+
+Medusa's CLI tool provides commands to simplify developing and testing your plugin in a local Medusa application. You start by publishing your plugin in the local package registry, then install it in your Medusa application. You can then watch for changes in the plugin as you develop it.
+
+### Publish and Install Local Package
+
+### Prerequisites
+
+- [Medusa application installed.](https://docs.medusajs.com/learn/installation/index.html.md)
+
+The first time you create your plugin, you need to publish the package into a local package registry, then install it in your Medusa application. This is a one-time only process.
+
+To publish the plugin to the local registry, run the following command in your plugin project:
+
+```bash title="Plugin project"
+npx medusa plugin:publish
+```
+
+This command uses [Yalc](https://github.com/wclr/yalc) under the hood to publish the plugin to a local package registry. The plugin is published locally under the name you specified in `package.json`.
+
+Next, navigate to your Medusa application:
+
+```bash title="Medusa application"
+cd ~/path/to/medusa-app
+```
+
+Make sure to replace `~/path/to/medusa-app` with the path to your Medusa application.
+
+Then, if your project was created before v2.3.1 of Medusa, make sure to install `yalc` as a development dependency:
+
+```bash npm2yarn badgeLabel="Medusa Application" badgeColor="green"
+npm install --save-dev yalc
+```
+
+After that, run the following Medusa CLI command to install the plugin:
+
+```bash title="Medusa application"
+npx medusa plugin:add @myorg/plugin-name
+```
+
+Make sure to replace `@myorg/plugin-name` with the name of your plugin as specified in `package.json`. Your plugin will be installed from the local package registry into your Medusa application.
+
+### Register Plugin in Medusa Application
+
+After installing the plugin, you need to register it in your Medusa application in the configurations defined in `medusa-config.ts`.
+
+Add the plugin to the `plugins` array in the `medusa-config.ts` file:
+
+```ts title="medusa-config.ts" highlights={pluginHighlights}
+module.exports = defineConfig({
+  // ...
+  plugins: [
+    {
+      resolve: "@myorg/plugin-name",
+      options: {},
+    },
+  ],
+})
+```
+
+The `plugins` configuration is an array of objects where each object has a `resolve` key whose value is the name of the plugin package.
+
+#### Pass Module Options through Plugin
+
+Each plugin configuration also accepts an `options` property, whose value is an object of options to pass to the plugin's modules.
+
+For example:
+
+```ts title="medusa-config.ts" highlights={pluginOptionsHighlight}
+module.exports = defineConfig({
+  // ...
+  plugins: [
+    {
+      resolve: "@myorg/plugin-name",
+      options: {
+        apiKey: true,
+      },
+    },
+  ],
+})
+```
+
+The `options` property in the plugin configuration is passed to all modules in the plugin. Learn more about module options in [this chapter](https://docs.medusajs.com/learn/fundamentals/modules/options/index.html.md).
+
+### Watch Plugin Changes During Development
+
+While developing your plugin, you can watch for changes in the plugin and automatically update the plugin in the Medusa application using it. This is the only command you'll continuously need during your plugin development.
+
+To do that, run the following command in your plugin project:
+
+```bash title="Plugin project"
+npx medusa plugin:develop
+```
+
+This command will:
+
+- Watch for changes in the plugin. Whenever a file is changed, the plugin is automatically built.
+- Publish the plugin changes to the local package registry. This will automatically update the plugin in the Medusa application using it. You can also benefit from real-time HMR updates of admin extensions.
+
+### Start Medusa Application
+
+You can start your Medusa application's development server to test out your plugin:
+
+```bash npm2yarn badgeLabel="Medusa Application" badgeColor="green"
+npm run dev
+```
+
+While your Medusa application is running and the plugin is being watched, you can test your plugin while developing it in the Medusa application.
+
+***
+
+## 4. Create Customizations in the Plugin
+
+You can now build your plugin's customizations. The following guide explains how to build different customizations in your plugin.
+
+- [Create a module](https://docs.medusajs.com/learn/fundamentals/modules/index.html.md)
+- [Create a module link](https://docs.medusajs.com/learn/fundamentals/module-links/index.html.md)
+- [Create a workflow](https://docs.medusajs.com/learn/fundamentals/workflows/index.html.md)
+- [Add a workflow hook](https://docs.medusajs.com/learn/fundamentals/workflows/add-workflow-hook/index.html.md)
+- [Create an API route](https://docs.medusajs.com/learn/fundamentals/api-routes/index.html.md)
+- [Add a subscriber](https://docs.medusajs.com/learn/fundamentals/events-and-subscribers/index.html.md)
+- [Add a scheduled job](https://docs.medusajs.com/learn/fundamentals/scheduled-jobs/index.html.md)
+- [Add an admin widget](https://docs.medusajs.com/learn/fundamentals/admin/widgets/index.html.md)
+- [Add an admin UI route](https://docs.medusajs.com/learn/fundamentals/admin/ui-routes/index.html.md)
+
+While building those customizations, you can test them in your Medusa application by [watching the plugin changes](#watch-plugin-changes-during-development) and [starting the Medusa application](#start-medusa-application).
+
+### Generating Migrations for Modules
+
+During your development, you may need to generate migrations for modules in your plugin. To do that, first, add the following environment variables in your plugin project:
+
+```plain title="Plugin project"
+DB_USERNAME=postgres
+DB_PASSWORD=123...
+DB_HOST=localhost
+DB_PORT=5432
+DB_NAME=db_name
+```
+
+You can add these environment variables in a `.env` file in your plugin project. The variables are:
+
+- `DB_USERNAME`: The username of the PostgreSQL user to connect to the database.
+- `DB_PASSWORD`: The password of the PostgreSQL user to connect to the database.
+- `DB_HOST`: The host of the PostgreSQL database. Typically, it's `localhost` if you're running the database locally.
+- `DB_PORT`: The port of the PostgreSQL database. Typically, it's `5432` if you're running the database locally.
+- `DB_NAME`: The name of the PostgreSQL database to connect to.
+
+Then, run the following command in your plugin project to generate migrations for the modules in your plugin:
+
+```bash title="Plugin project"
+npx medusa plugin:db:generate
+```
+
+This command generates migrations for all modules in the plugin.
+
+Finally, run these migrations on the Medusa application that the plugin is installed in using the `db:migrate` command:
+
+```bash title="Medusa application"
+npx medusa db:migrate
+```
+
+The migrations in your application, including your plugin, will run and update the database.
+
+### Importing Module Resources
+
+In the [Prepare Plugin](#2-prepare-plugin) section, you learned about [exported resources](#package-exports) in your plugin.
+
+These exports allow you to import your plugin resources in your Medusa application, including workflows, links and modules.
+
+For example, to import the plugin's workflow in your Medusa application:
+
+`@myorg/plugin-name` is the plugin package's name.
+
+```ts
+import { Workflow1, Workflow2 } from "@myorg/plugin-name/workflows"
+import BlogModule from "@myorg/plugin-name/modules/blog"
+// import other files created in plugin like ./src/types/blog.ts
+import BlogType from "@myorg/plugin-name/types/blog"
+```
+
+### Create Module Providers
+
+The [exported resources](#package-exports) also allow you to import module providers in your plugin and register them in the Medusa application's configuration. A module provider is a module that provides the underlying logic or integration related to a commerce or Infrastructure Module.
+
+For example, assuming your plugin has a [Notification Module Provider](https://docs.medusajs.com/resources/infrastructure-modules/notification/index.html.md) called `my-notification`, you can register it in your Medusa application's configuration like this:
+
+`@myorg/plugin-name` is the plugin package's name.
+
+```ts highlights={[["9"]]} title="medusa-config.ts"
+module.exports = defineConfig({
+  // ...
+  modules: [
+    {
+      resolve: "@medusajs/medusa/notification",
+      options: {
+        providers: [
+          {
+            resolve: "@myorg/plugin-name/providers/my-notification",
+            id: "my-notification",
+            options: {
+              channels: ["email"],
+              // provider options...
+            },
+          },
+        ],
+      },
+    },
+  ],
+})
+```
+
+You pass to `resolve` the path to the provider relative to the plugin package. So, in this example, the `my-notification` provider is located in `./src/providers/my-notification/index.ts` of the plugin.
+
+To learn how to create module providers, refer to the following guides:
+
+- [File Module Provider](https://docs.medusajs.com/resources/references/file-provider-module/index.html.md)
+- [Notification Module Provider](https://docs.medusajs.com/resources/references/notification-provider-module/index.html.md)
+- [Auth Module Provider](https://docs.medusajs.com/resources/references/auth/provider/index.html.md)
+- [Payment Module Provider](https://docs.medusajs.com/resources/references/payment/provider/index.html.md)
+- [Fulfillment Module Provider](https://docs.medusajs.com/resources/references/fulfillment/provider/index.html.md)
+- [Tax Module Provider](https://docs.medusajs.com/resources/references/tax/provider/index.html.md)
+
+***
+
+## 5. Publish Plugin to NPM
+
+Make sure to add the keywords mentioned in the [Package Keywords](#package-keywords) section in your plugin's `package.json` file.
+
+Medusa's CLI tool provides a command that bundles your plugin to be published to npm. Once you're ready to publish your plugin publicly, run the following command in your plugin project:
+
+```bash
+npx medusa plugin:build
+```
+
+The command will compile an output in the `.medusa/server` directory.
+
+You can now publish the plugin to npm using the [NPM CLI tool](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm). Run the following command to publish the plugin to npm:
+
+```bash
+npm publish
+```
+
+If you haven't logged in before with your NPM account, you'll be asked to log in first. Then, your package is published publicly to be used in any Medusa application.
+
+### Install Public Plugin in Medusa Application
+
+You install a plugin that's published publicly using your package manager. For example:
+
+```bash npm2yarn
+npm install @myorg/plugin-name
+```
+
+Where `@myorg/plugin-name` is the name of your plugin as published on NPM.
+
+Then, register the plugin in your Medusa application's configurations as explained in [this section](#register-plugin-in-medusa-application).
+
+***
+
+## Update a Published Plugin
+
+To update the Medusa dependencies in a plugin, refer to [this documentation](https://docs.medusajs.com/learn/update#update-plugin-project/index.html.md).
+
+If you've published a plugin and you've made changes to it, you'll have to publish the update to NPM again.
+
+First, run the following command to change the version of the plugin:
+
+```bash
+npm version <type>
+```
+
+Where `<type>` indicates the type of version update you’re publishing. For example, it can be `major` or `minor`. Refer to the [npm version documentation](https://docs.npmjs.com/cli/v10/commands/npm-version) for more information.
+
+Then, re-run the same commands for publishing a plugin:
+
+```bash
+npx medusa plugin:build
+npm publish
+```
+
+This will publish an updated version of your plugin under a new version.
+
+
+# Expose a Workflow Hook
+
+In this chapter, you'll learn how to expose a hook in your workflow.
+
+## When to Expose a Hook
+
+Your workflow is reusable in other applications, and you allow performing an external action at some point in your workflow.
+
+Your workflow isn't reusable by other applications. Use a step that performs what a hook handler would instead.
+
+***
+
+## How to Expose a Hook in a Workflow?
+
+To expose a hook in your workflow, use `createHook` from the Workflows SDK.
+
+For example:
+
+```ts title="src/workflows/my-workflow/index.ts" highlights={hookHighlights}
+import {
+  createStep,
+  createHook,
+  createWorkflow,
+  WorkflowResponse,
+} from "@medusajs/framework/workflows-sdk"
+import { createProductStep } from "./steps/create-product"
+
+export const myWorkflow = createWorkflow(
+  "my-workflow", 
+  function (input) {
+    const product = createProductStep(input)
+    const productCreatedHook = createHook(
+      "productCreated", 
+      { productId: product.id }
+    )
+
+    return new WorkflowResponse(product, {
+      hooks: [productCreatedHook],
+    })
+  }
+)
+```
+
+The `createHook` function accepts two parameters:
+
+1. The first is a string indicating the hook's name. You use this to consume the hook later.
+2. The second is the input to pass to the hook handler.
+
+The workflow must also pass an object having a `hooks` property as a second parameter to the `WorkflowResponse` constructor. Its value is an array of the workflow's hooks.
+
+### How to Consume the Hook?
+
+To consume the hook of the workflow, create the file `src/workflows/hooks/my-workflow.ts` with the following content:
+
+```ts title="src/workflows/hooks/my-workflow.ts" highlights={handlerHighlights}
+import { myWorkflow } from "../my-workflow"
+
+myWorkflow.hooks.productCreated(
+  async ({ productId }, { container }) => {
+    // TODO perform an action
+  }
+)
+```
+
+The hook is available on the workflow's `hooks` property using its name `productCreated`.
+
+You invoke the hook, passing a step function (the hook handler) as a parameter.
+
+
+# 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.
+
+
 # Compensation Function
 
 In this chapter, you'll learn what a compensation function is and how to add it to a step.
@@ -15464,429 +15533,6 @@ So, if an error occurs during the loop, the compensation function will still rec
 For more details on error handling in workflows and steps, check the [Handling Errors chapter](https://docs.medusajs.com/learn/fundamentals/workflows/errors/index.html.md).
 
 
-# Workflow Constraints
-
-This chapter lists constraints of defining a workflow or its steps.
-
-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.
-
-This creates restrictions related to variable manipulations, using if-conditions, and other constraints. This chapter lists these constraints and provides their alternatives.
-
-## Workflow Constraints
-
-### No Async Functions
-
-The function passed to `createWorkflow` can’t be an async function:
-
-```ts highlights={[["4", "async", "Function can't be async."], ["11", "", "Correct way of defining the function."]]}
-// Don't
-const myWorkflow = createWorkflow(
-  "hello-world", 
-  async function (input: WorkflowInput) {
-  // ...
-})
-
-// Do
-const myWorkflow = createWorkflow(
-  "hello-world", 
-  function (input: WorkflowInput) {
-  // ...
-})
-```
-
-### No Direct Variable Manipulation
-
-You can’t directly manipulate variables within the workflow's constructor function.
-
-Learn more about why you can't manipulate variables [in this chapter](https://docs.medusajs.com/learn/fundamentals/workflows/variable-manipulation/index.html.md)
-
-Instead, use `transform` from the Workflows SDK:
-
-```ts highlights={highlights}
-// Don't
-const myWorkflow = createWorkflow(
-  "hello-world", 
-  function (input: WorkflowInput) {
-  const str1 = step1(input)
-  const str2 = step2(input)
-
-  return new WorkflowResponse({
-    message: `${str1}${str2}`,
-  })
-})
-
-// Do
-const myWorkflow = createWorkflow(
-  "hello-world", 
-  function (input: WorkflowInput) {
-  const str1 = step1(input)
-  const str2 = step2(input)
-
-  const result = transform(
-    {
-      str1,
-      str2,
-    },
-    (input) => ({
-      message: `${input.str1}${input.str2}`,
-    })
-  )
-
-  return new WorkflowResponse(result)
-})
-```
-
-#### Create Dates in transform
-
-When you use `new Date()` in a workflow's constructor function, the date is evaluated when Medusa creates the internal representation of the workflow, not during execution.
-
-Instead, create the date using `transform`.
-
-Learn more about how Medusa creates an internal representation of a workflow [in this chapter](https://docs.medusajs.com/learn/fundamentals/workflows/variable-manipulation/index.html.md).
-
-For example:
-
-```ts highlights={dateHighlights}
-// Don't
-const myWorkflow = createWorkflow(
-  "hello-world", 
-  function (input: WorkflowInput) {
-  const today = new Date()
-
-  return new WorkflowResponse({
-    today,
-  })
-})
-
-// Do
-const myWorkflow = createWorkflow(
-  "hello-world", 
-  function (input: WorkflowInput) {
-  const today = transform({}, () => new Date())
-
-  return new WorkflowResponse({
-    today,
-  })
-})
-```
-
-### No If Conditions
-
-You can't use if-conditions in a workflow.
-
-Learn more about why you can't use if-conditions [in this chapter](https://docs.medusajs.com/learn/fundamentals/workflows/conditions#why-if-conditions-arent-allowed-in-workflows/index.html.md)
-
-Instead, use when-then from the Workflows SDK:
-
-```ts
-// Don't
-const myWorkflow = createWorkflow(
-  "hello-world", 
-  function (input: WorkflowInput) {
-  if (input.is_active) {
-    // perform an action
-  }
-})
-
-// Do (explained in the next chapter)
-const myWorkflow = createWorkflow(
-  "hello-world", 
-  function (input: WorkflowInput) {
-  when(input, (input) => {
-    return input.is_active
-  })
-  .then(() => {
-    // perform an action
-  })
-})
-```
-
-You can also pair multiple `when-then` blocks to implement an `if-else` condition as explained in [this chapter](https://docs.medusajs.com/learn/fundamentals/workflows/conditions/index.html.md).
-
-### No Conditional Operators
-
-You can't use conditional operators in a workflow, such as `??` or `||`.
-
-Learn more about why you can't use conditional operators [in this chapter](https://docs.medusajs.com/learn/fundamentals/workflows/conditions#why-if-conditions-arent-allowed-in-workflows/index.html.md)
-
-Instead, use `transform` to store the desired value in a variable.
-
-#### Logical Or (||) Alternative
-
-```ts
-// Don't
-const myWorkflow = createWorkflow(
-  "hello-world", 
-  function (input: WorkflowInput) {
-    const message = input.message || "Hello"
-})
-
-// Do
-// other imports...
-import { transform } from "@medusajs/framework/workflows-sdk"
-
-const myWorkflow = createWorkflow(
-  "hello-world", 
-  function (input: WorkflowInput) {
-    const message = transform(
-      {
-        input,
-      },
-      (data) => data.input.message || "hello"
-    )
-})
-```
-
-#### Nullish Coalescing (??) Alternative
-
-```ts
-// Don't
-const myWorkflow = createWorkflow(
-  "hello-world", 
-  function (input: WorkflowInput) {
-    const message = input.message ?? "Hello"
-})
-
-// Do
-// other imports...
-import { transform } from "@medusajs/framework/workflows-sdk"
-
-const myWorkflow = createWorkflow(
-  "hello-world", 
-  function (input: WorkflowInput) {
-    const message = transform(
-      {
-        input,
-      },
-      (data) => data.input.message ?? "hello"
-    )
-})
-```
-
-#### Double Not (!!) Alternative
-
-```ts
-// Don't
-const myWorkflow = createWorkflow(
-  "hello-world", 
-  function (input: WorkflowInput) {
-    step1({
-      isActive: !!input.is_active,
-    })
-})
-
-// Do
-// other imports...
-import { transform } from "@medusajs/framework/workflows-sdk"
-
-const myWorkflow = createWorkflow(
-  "hello-world", 
-  function (input: WorkflowInput) {
-    const isActive = transform(
-      {
-        input,
-      },
-      (data) => !!data.input.is_active
-    )
-    
-    step1({
-      isActive,
-    })
-})
-```
-
-#### Ternary Alternative
-
-```ts
-// Don't
-const myWorkflow = createWorkflow(
-  "hello-world", 
-  function (input: WorkflowInput) {
-    step1({
-      message: input.is_active ? "active" : "inactive",
-    })
-})
-
-// Do
-// other imports...
-import { transform } from "@medusajs/framework/workflows-sdk"
-
-const myWorkflow = createWorkflow(
-  "hello-world", 
-  function (input: WorkflowInput) {
-    const message = transform(
-      {
-        input,
-      },
-      (data) => {
-        return data.input.is_active ? "active" : "inactive"
-      }
-    )
-    
-    step1({
-      message,
-    })
-})
-```
-
-#### Optional Chaining (?.) Alternative
-
-```ts
-// Don't
-const myWorkflow = createWorkflow(
-  "hello-world", 
-  function (input: WorkflowInput) {
-    step1({
-      name: input.customer?.name,
-    })
-})
-
-// Do
-// other imports...
-import { transform } from "@medusajs/framework/workflows-sdk"
-
-const myWorkflow = createWorkflow(
-  "hello-world", 
-  function (input: WorkflowInput) {
-    const name = transform(
-      {
-        input,
-      },
-      (data) => data.input.customer?.name
-    )
-    
-    step1({
-      name,
-    })
-})
-```
-
-### No Try-Catch
-
-In a workflow, don't use try-catch blocks to handle errors.
-
-Instead, refer to the [Error Handling](https://docs.medusajs.com/learn/fundamentals/workflows/errors/index.html.md) chapter for alternative ways to handle errors.
-
-***
-
-## Step Constraints
-
-### Returned Values
-
-A step must only return serializable values, such as [primitive values](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#primitive_values) or an object.
-
-Values of other types, such as Maps, aren't allowed.
-
-```ts
-// Don't
-import { 
-  createStep,
-  StepResponse,
-} from "@medusajs/framework/workflows-sdk"
-
-const step1 = createStep(
-  "step-1",
-  (input, { container }) => {
-    const myMap = new Map()
-
-    // ...
-
-    return new StepResponse({
-      myMap,
-    })
-  }
-)
-
-// Do
-import { 
-  createStep,
-  StepResponse,
-} from "@medusajs/framework/workflows-sdk"
-
-const step1 = createStep(
-  "step-1",
-  (input, { container }) => {
-    const myObj: Record<string, unknown> = {}
-
-    // ...
-
-    return new StepResponse({
-      myObj,
-    })
-  }
-)
-```
-
-
-# Expose a Workflow Hook
-
-In this chapter, you'll learn how to expose a hook in your workflow.
-
-## When to Expose a Hook
-
-Your workflow is reusable in other applications, and you allow performing an external action at some point in your workflow.
-
-Your workflow isn't reusable by other applications. Use a step that performs what a hook handler would instead.
-
-***
-
-## How to Expose a Hook in a Workflow?
-
-To expose a hook in your workflow, use `createHook` from the Workflows SDK.
-
-For example:
-
-```ts title="src/workflows/my-workflow/index.ts" highlights={hookHighlights}
-import {
-  createStep,
-  createHook,
-  createWorkflow,
-  WorkflowResponse,
-} from "@medusajs/framework/workflows-sdk"
-import { createProductStep } from "./steps/create-product"
-
-export const myWorkflow = createWorkflow(
-  "my-workflow", 
-  function (input) {
-    const product = createProductStep(input)
-    const productCreatedHook = createHook(
-      "productCreated", 
-      { productId: product.id }
-    )
-
-    return new WorkflowResponse(product, {
-      hooks: [productCreatedHook],
-    })
-  }
-)
-```
-
-The `createHook` function accepts two parameters:
-
-1. The first is a string indicating the hook's name. You use this to consume the hook later.
-2. The second is the input to pass to the hook handler.
-
-The workflow must also pass an object having a `hooks` property as a second parameter to the `WorkflowResponse` constructor. Its value is an array of the workflow's hooks.
-
-### How to Consume the Hook?
-
-To consume the hook of the workflow, create the file `src/workflows/hooks/my-workflow.ts` with the following content:
-
-```ts title="src/workflows/hooks/my-workflow.ts" highlights={handlerHighlights}
-import { myWorkflow } from "../my-workflow"
-
-myWorkflow.hooks.productCreated(
-  async ({ productId }, { container }) => {
-    // TODO perform an action
-  }
-)
-```
-
-The hook is available on the workflow's `hooks` property using its name `productCreated`.
-
-You invoke the hook, passing a step function (the hook handler) as a parameter.
-
-
 # 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.
@@ -16291,78 +15937,488 @@ In this example, if the `actionThatThrowsError` step throws an error, the `moreA
 You can then access the error that occurred in that step as explained in the [Disable Error Throwing](#disable-error-throwing-in-workflow) section.
 
 
-# Multiple Step Usage in Workflow
+# Execute Another Workflow
 
-In this chapter, you'll learn how to use a step multiple times in a workflow.
+In this chapter, you'll learn how to execute a workflow in another.
 
-## Problem Reusing a Step in a Workflow
+## Execute in a Workflow
 
-In some cases, you may need to use a step multiple times in the same workflow.
+To execute a workflow in another, use the `runAsStep` method that every workflow has.
 
-The most common example is using the `useQueryGraphStep` multiple times in a workflow to retrieve multiple unrelated data, such as customers and products.
+For example:
 
-Each workflow step must have a unique ID, which is the ID passed as a first parameter when creating the step:
+```ts highlights={workflowsHighlights} collapsibleLines="1-7" expandMoreButton="Show Imports"
+import {
+  createWorkflow,
+} from "@medusajs/framework/workflows-sdk"
+import { 
+  createProductsWorkflow,
+} from "@medusajs/medusa/core-flows"
 
-```ts
-const useQueryGraphStep = createStep(
-  "use-query-graph"
-  // ...
-)
-```
-
-This causes an error when you use the same step multiple times in a workflow, as it's registered in the workflow as two steps having the same ID:
-
-```ts
-const helloWorkflow = createWorkflow(
-  "hello",
-  () => {
-    const { data: products } = useQueryGraphStep({
-      entity: "product",
-      fields: ["id"],
+const workflow = createWorkflow(
+  "hello-world",
+  async (input) => {
+    const products = createProductsWorkflow.runAsStep({
+      input: {
+        products: [
+          // ...
+        ],
+      },
     })
 
-    // ERROR OCCURS HERE: A STEP HAS THE SAME ID AS ANOTHER IN THE WORKFLOW
-    const { data: customers } = useQueryGraphStep({
-      entity: "customer",
-      fields: ["id"],
-    })
+    // ...
   }
 )
 ```
 
-The next section explains how to fix this issue to use the same step multiple times in a workflow.
+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.
 
 ***
 
-## How to Use a Step Multiple Times in a Workflow?
+## Preparing Input Data
 
-When you execute a step in a workflow, you can chain a `config` method to it to change the step's config.
+If you need to perform some data manipulation to prepare the other workflow's input data, use `transform` from the Workflows SDK.
 
-Use the `config` method to change a step's ID for a single execution.
+Learn about transform in [this chapter](https://docs.medusajs.com/learn/fundamentals/workflows/variable-manipulation/index.html.md).
 
-So, this is the correct way to write the example above:
+For example:
 
-```ts highlights={highlights}
-const helloWorkflow = createWorkflow(
-  "hello",
-  () => {
-    const { data: products } = useQueryGraphStep({
-      entity: "product",
-      fields: ["id"],
+```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,
+      },
     })
 
-    // ✓ No error occurs, the step has a different ID.
-    const { data: customers } = useQueryGraphStep({
-      entity: "customer",
-      fields: ["id"],
-    }).config({ name: "fetch-customers" })
+    // ...
   }
 )
 ```
 
-The `config` method accepts an object with a `name` property. Its value is a new ID of the step to use for this execution only.
+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`.
 
-The first `useQueryGraphStep` usage has the ID `use-query-graph`, and the second `useQueryGraphStep` usage has the ID `fetch-customers`.
+***
+
+## 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.
+
+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.
+
+This creates restrictions related to variable manipulations, using if-conditions, and other constraints. This chapter lists these constraints and provides their alternatives.
+
+## Workflow Constraints
+
+### No Async Functions
+
+The function passed to `createWorkflow` can’t be an async function:
+
+```ts highlights={[["4", "async", "Function can't be async."], ["11", "", "Correct way of defining the function."]]}
+// Don't
+const myWorkflow = createWorkflow(
+  "hello-world", 
+  async function (input: WorkflowInput) {
+  // ...
+})
+
+// Do
+const myWorkflow = createWorkflow(
+  "hello-world", 
+  function (input: WorkflowInput) {
+  // ...
+})
+```
+
+### No Direct Variable Manipulation
+
+You can’t directly manipulate variables within the workflow's constructor function.
+
+Learn more about why you can't manipulate variables [in this chapter](https://docs.medusajs.com/learn/fundamentals/workflows/variable-manipulation/index.html.md)
+
+Instead, use `transform` from the Workflows SDK:
+
+```ts highlights={highlights}
+// Don't
+const myWorkflow = createWorkflow(
+  "hello-world", 
+  function (input: WorkflowInput) {
+  const str1 = step1(input)
+  const str2 = step2(input)
+
+  return new WorkflowResponse({
+    message: `${str1}${str2}`,
+  })
+})
+
+// Do
+const myWorkflow = createWorkflow(
+  "hello-world", 
+  function (input: WorkflowInput) {
+  const str1 = step1(input)
+  const str2 = step2(input)
+
+  const result = transform(
+    {
+      str1,
+      str2,
+    },
+    (input) => ({
+      message: `${input.str1}${input.str2}`,
+    })
+  )
+
+  return new WorkflowResponse(result)
+})
+```
+
+#### Create Dates in transform
+
+When you use `new Date()` in a workflow's constructor function, the date is evaluated when Medusa creates the internal representation of the workflow, not during execution.
+
+Instead, create the date using `transform`.
+
+Learn more about how Medusa creates an internal representation of a workflow [in this chapter](https://docs.medusajs.com/learn/fundamentals/workflows/variable-manipulation/index.html.md).
+
+For example:
+
+```ts highlights={dateHighlights}
+// Don't
+const myWorkflow = createWorkflow(
+  "hello-world", 
+  function (input: WorkflowInput) {
+  const today = new Date()
+
+  return new WorkflowResponse({
+    today,
+  })
+})
+
+// Do
+const myWorkflow = createWorkflow(
+  "hello-world", 
+  function (input: WorkflowInput) {
+  const today = transform({}, () => new Date())
+
+  return new WorkflowResponse({
+    today,
+  })
+})
+```
+
+### No If Conditions
+
+You can't use if-conditions in a workflow.
+
+Learn more about why you can't use if-conditions [in this chapter](https://docs.medusajs.com/learn/fundamentals/workflows/conditions#why-if-conditions-arent-allowed-in-workflows/index.html.md)
+
+Instead, use when-then from the Workflows SDK:
+
+```ts
+// Don't
+const myWorkflow = createWorkflow(
+  "hello-world", 
+  function (input: WorkflowInput) {
+  if (input.is_active) {
+    // perform an action
+  }
+})
+
+// Do (explained in the next chapter)
+const myWorkflow = createWorkflow(
+  "hello-world", 
+  function (input: WorkflowInput) {
+  when(input, (input) => {
+    return input.is_active
+  })
+  .then(() => {
+    // perform an action
+  })
+})
+```
+
+You can also pair multiple `when-then` blocks to implement an `if-else` condition as explained in [this chapter](https://docs.medusajs.com/learn/fundamentals/workflows/conditions/index.html.md).
+
+### No Conditional Operators
+
+You can't use conditional operators in a workflow, such as `??` or `||`.
+
+Learn more about why you can't use conditional operators [in this chapter](https://docs.medusajs.com/learn/fundamentals/workflows/conditions#why-if-conditions-arent-allowed-in-workflows/index.html.md)
+
+Instead, use `transform` to store the desired value in a variable.
+
+#### Logical Or (||) Alternative
+
+```ts
+// Don't
+const myWorkflow = createWorkflow(
+  "hello-world", 
+  function (input: WorkflowInput) {
+    const message = input.message || "Hello"
+})
+
+// Do
+// other imports...
+import { transform } from "@medusajs/framework/workflows-sdk"
+
+const myWorkflow = createWorkflow(
+  "hello-world", 
+  function (input: WorkflowInput) {
+    const message = transform(
+      {
+        input,
+      },
+      (data) => data.input.message || "hello"
+    )
+})
+```
+
+#### Nullish Coalescing (??) Alternative
+
+```ts
+// Don't
+const myWorkflow = createWorkflow(
+  "hello-world", 
+  function (input: WorkflowInput) {
+    const message = input.message ?? "Hello"
+})
+
+// Do
+// other imports...
+import { transform } from "@medusajs/framework/workflows-sdk"
+
+const myWorkflow = createWorkflow(
+  "hello-world", 
+  function (input: WorkflowInput) {
+    const message = transform(
+      {
+        input,
+      },
+      (data) => data.input.message ?? "hello"
+    )
+})
+```
+
+#### Double Not (!!) Alternative
+
+```ts
+// Don't
+const myWorkflow = createWorkflow(
+  "hello-world", 
+  function (input: WorkflowInput) {
+    step1({
+      isActive: !!input.is_active,
+    })
+})
+
+// Do
+// other imports...
+import { transform } from "@medusajs/framework/workflows-sdk"
+
+const myWorkflow = createWorkflow(
+  "hello-world", 
+  function (input: WorkflowInput) {
+    const isActive = transform(
+      {
+        input,
+      },
+      (data) => !!data.input.is_active
+    )
+    
+    step1({
+      isActive,
+    })
+})
+```
+
+#### Ternary Alternative
+
+```ts
+// Don't
+const myWorkflow = createWorkflow(
+  "hello-world", 
+  function (input: WorkflowInput) {
+    step1({
+      message: input.is_active ? "active" : "inactive",
+    })
+})
+
+// Do
+// other imports...
+import { transform } from "@medusajs/framework/workflows-sdk"
+
+const myWorkflow = createWorkflow(
+  "hello-world", 
+  function (input: WorkflowInput) {
+    const message = transform(
+      {
+        input,
+      },
+      (data) => {
+        return data.input.is_active ? "active" : "inactive"
+      }
+    )
+    
+    step1({
+      message,
+    })
+})
+```
+
+#### Optional Chaining (?.) Alternative
+
+```ts
+// Don't
+const myWorkflow = createWorkflow(
+  "hello-world", 
+  function (input: WorkflowInput) {
+    step1({
+      name: input.customer?.name,
+    })
+})
+
+// Do
+// other imports...
+import { transform } from "@medusajs/framework/workflows-sdk"
+
+const myWorkflow = createWorkflow(
+  "hello-world", 
+  function (input: WorkflowInput) {
+    const name = transform(
+      {
+        input,
+      },
+      (data) => data.input.customer?.name
+    )
+    
+    step1({
+      name,
+    })
+})
+```
+
+### No Try-Catch
+
+In a workflow, don't use try-catch blocks to handle errors.
+
+Instead, refer to the [Error Handling](https://docs.medusajs.com/learn/fundamentals/workflows/errors/index.html.md) chapter for alternative ways to handle errors.
+
+***
+
+## Step Constraints
+
+### Returned Values
+
+A step must only return serializable values, such as [primitive values](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#primitive_values) or an object.
+
+Values of other types, such as Maps, aren't allowed.
+
+```ts
+// Don't
+import { 
+  createStep,
+  StepResponse,
+} from "@medusajs/framework/workflows-sdk"
+
+const step1 = createStep(
+  "step-1",
+  (input, { container }) => {
+    const myMap = new Map()
+
+    // ...
+
+    return new StepResponse({
+      myMap,
+    })
+  }
+)
+
+// Do
+import { 
+  createStep,
+  StepResponse,
+} from "@medusajs/framework/workflows-sdk"
+
+const step1 = createStep(
+  "step-1",
+  (input, { container }) => {
+    const myObj: Record<string, unknown> = {}
+
+    // ...
+
+    return new StepResponse({
+      myObj,
+    })
+  }
+)
+```
 
 
 # Long-Running Workflows
@@ -16660,134 +16716,78 @@ 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.
 
 
-# Execute Another Workflow
+# Multiple Step Usage in Workflow
 
-In this chapter, you'll learn how to execute a workflow in another.
+In this chapter, you'll learn how to use a step multiple times in a workflow.
 
-## Execute in a Workflow
+## Problem Reusing a Step in a Workflow
 
-To execute a workflow in another, use the `runAsStep` method that every workflow has.
+In some cases, you may need to use a step multiple times in the same workflow.
 
-For example:
+The most common example is using the `useQueryGraphStep` multiple times in a workflow to retrieve multiple unrelated data, such as customers and products.
 
-```ts highlights={workflowsHighlights} collapsibleLines="1-7" expandMoreButton="Show Imports"
-import {
-  createWorkflow,
-} from "@medusajs/framework/workflows-sdk"
-import { 
-  createProductsWorkflow,
-} from "@medusajs/medusa/core-flows"
+Each workflow step must have a unique ID, which is the ID passed as a first parameter when creating the step:
 
-const workflow = createWorkflow(
-  "hello-world",
-  async (input) => {
-    const products = createProductsWorkflow.runAsStep({
-      input: {
-        products: [
-          // ...
-        ],
-      },
+```ts
+const useQueryGraphStep = createStep(
+  "use-query-graph"
+  // ...
+)
+```
+
+This causes an error when you use the same step multiple times in a workflow, as it's registered in the workflow as two steps having the same ID:
+
+```ts
+const helloWorkflow = createWorkflow(
+  "hello",
+  () => {
+    const { data: products } = useQueryGraphStep({
+      entity: "product",
+      fields: ["id"],
     })
 
-    // ...
+    // ERROR OCCURS HERE: A STEP HAS THE SAME ID AS ANOTHER IN THE WORKFLOW
+    const { data: customers } = useQueryGraphStep({
+      entity: "customer",
+      fields: ["id"],
+    })
   }
 )
 ```
 
-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.
+The next section explains how to fix this issue to use the same step multiple times in a workflow.
 
 ***
 
-## Preparing Input Data
+## How to Use a Step Multiple Times in a Workflow?
 
-If you need to perform some data manipulation to prepare the other workflow's input data, use `transform` from the Workflows SDK.
+When you execute a step in a workflow, you can chain a `config` method to it to change the step's config.
 
-Learn about transform in [this chapter](https://docs.medusajs.com/learn/fundamentals/workflows/variable-manipulation/index.html.md).
+Use the `config` method to change a step's ID for a single execution.
 
-For example:
+So, this is the correct way to write the example above:
 
-```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,
-      },
+```ts highlights={highlights}
+const helloWorkflow = createWorkflow(
+  "hello",
+  () => {
+    const { data: products } = useQueryGraphStep({
+      entity: "product",
+      fields: ["id"],
     })
 
-    // ...
+    // ✓ No error occurs, the step has a different ID.
+    const { data: customers } = useQueryGraphStep({
+      entity: "customer",
+      fields: ["id"],
+    }).config({ name: "fetch-customers" })
   }
 )
 ```
 
-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`.
+The `config` method accepts an object with a `name` property. Its value is a new ID of the step to use for this execution only.
 
-***
-
-## 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.
+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
@@ -17620,270 +17620,6 @@ export const languages: Language[] = [
 Our team will perform a general review on your PR and merge it if no issues are found. The translation will be available in the admin after the next release.
 
 
-# Docs Contribution Guidelines
-
-Thank you for your interest in contributing to the documentation! You will be helping the open source community and other developers interested in learning more about Medusa and using it.
-
-This guide is specific to contributing to the documentation. If you’re interested in contributing to Medusa’s codebase, check out the [contributing guidelines in the Medusa GitHub repository](https://github.com/medusajs/medusa/blob/develop/CONTRIBUTING.md).
-
-## What Can You Contribute?
-
-You can contribute to the Medusa documentation in the following ways:
-
-- Fixes to existing content. This includes small fixes like typos, or adding missing information.
-- Additions to the documentation. If you think a documentation page can be useful to other developers, you can contribute by adding it.
-  - Make sure to open an issue first in the [medusa repository](https://github.com/medusajs/medusa) to confirm that you can add that documentation page.
-- Fixes to UI components and tooling. If you find a bug while browsing the documentation, you can contribute by fixing it.
-
-***
-
-## Documentation Workspace
-
-Medusa's documentation projects are all part of the documentation yarn workspace, which you can find in the [medusa repository](https://github.com/medusajs/medusa) under the `www` directory.
-
-The workspace has the following two directories:
-
-- `apps`: this directory holds the different documentation websites and projects.
-  - `book`: includes the codebase for the [main Medusa documentation](https://docs.medusajs.com//index.html.md). It's built with [Next.js 15](https://nextjs.org/).
-  - `resources`: includes the codebase for the resources documentation, which powers different sections of the docs such as the [Integrations](https://docs.medusajs.com/resources/integrations/index.html.md) or [How-to & Tutorials](https://docs.medusajs.com/resources/how-to-tutorials/index.html.md) sections. It's built with [Next.js 15](https://nextjs.org/).
-  - `api-reference`: includes the codebase for the API reference website. It's built with [Next.js 15](https://nextjs.org/).
-  - `ui`: includes the codebase for the Medusa UI documentation website. It's built with [Next.js 15](https://nextjs.org/).
-- `packages`: this directory holds the shared packages and components necessary for the development of the projects in the `apps` directory.
-  - `docs-ui` includes the shared React components between the different apps.
-  - `remark-rehype-plugins` includes Remark and Rehype plugins used by the documentation projects.
-
-***
-
-## Documentation Content
-
-All documentation projects are built with Next.js. The content is writtin in MDX files.
-
-### Medusa Main Docs Content
-
-The content of the Medusa main docs are under the `www/apps/book/app` directory.
-
-### Medusa Resources Content
-
-The content of all pages under the `/resources` path are under the `www/apps/resources/app` directory.
-
-Documentation pages under the `www/apps/resources/references` directory are generated automatically from the source code under the `packages/medusa` directory. So, you can't directly make changes to them. Instead, you'll have to make changes to the comments in the original source code.
-
-### API Reference
-
-The API reference's content is split into two types:
-
-1. Static content, which are the content related to getting started, expanding fields, and more. These are located in the `www/apps/api-reference/markdown` directory. They are MDX files.
-2. OpenAPI specs that are shown to developers when checking the reference of an API Route. These are generated from OpenApi Spec comments, which are under the `www/utils/generated/oas-output` directory.
-
-### Medusa UI Documentation
-
-The content of the Medusa UI documentation are located under the `www/apps/ui/src/content/docs` directory. They are MDX files.
-
-The UI documentation also shows code examples, which are under the `www/apps/ui/src/examples` directory.
-
-The UI component props are generated from the source code and placed into the `www/apps/ui/src/specs` directory. To contribute to these props and their comments, check the comments in the source code under the `packages/design-system/ui` directory.
-
-***
-
-## Style Guide
-
-When you contribute to the documentation content, make sure to follow the [documentation style guide](https://www.notion.so/Style-Guide-Docs-fad86dd1c5f84b48b145e959f36628e0).
-
-***
-
-## How to Contribute
-
-If you’re fixing errors in an existing documentation page, you can scroll down to the end of the page and click on the “Edit this page” link. You’ll be redirected to the GitHub edit form of that page and you can make edits directly and submit a pull request (PR).
-
-If you’re adding a new page or contributing to the codebase, fork the repository, create a new branch, and make all changes necessary in your repository. Then, once you’re done,  create a PR in the Medusa repository.
-
-### Base Branch
-
-When you make an edit to an existing documentation page or fork the repository to make changes to the documentation, create a new branch.
-
-Documentation contributions always use `develop` as the base branch. Make sure to also open your PR against the `develop` branch.
-
-### Branch Name
-
-Make sure that the branch name starts with `docs/`. For example, `docs/fix-services`. Vercel deployed previews are only triggered for branches starting with `docs/`.
-
-### Pull Request Conventions
-
-When you create a pull request, prefix the title with `docs:` or `docs(PROJECT_NAME):`, where `PROJECT_NAME` is the name of the documentation project this pull request pertains to. For example, `docs(ui): fix titles`.
-
-In the body of the PR, explain clearly what the PR does. If the PR solves an issue, use [closing keywords](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword) with the issue number. For example, “Closes #1333”.
-
-***
-
-## Images
-
-If you are adding images to a documentation page, you can host the image on [Imgur](https://imgur.com) for free to include it in the PR. Our team will later upload it to our image hosting.
-
-***
-
-## NPM and Yarn Code Blocks
-
-If you’re adding code blocks that use NPM and Yarn, you must add the `npm2yarn` meta field.
-
-For example:
-
-````md
-```bash npm2yarn
-npm run start
-```
-````
-
-The code snippet must be written using NPM.
-
-### Global Option
-
-When a command uses the global option `-g`, add it at the end of the NPM command to ensure that it’s transformed to a Yarn command properly. For example:
-
-```bash npm2yarn
-npm install @medusajs/cli -g
-```
-
-***
-
-## Linting with Vale
-
-Medusa uses [Vale](https://vale.sh/) to lint documentation pages and perform checks on incoming PRs into the repository.
-
-### Result of Vale PR Checks
-
-You can check the result of running the "lint" action on your PR by clicking the Details link next to it. You can find there all errors that you need to fix.
-
-### Run Vale Locally
-
-If you want to check your work locally, you can do that by:
-
-1. [Installing Vale](https://vale.sh/docs/vale-cli/installation/) on your machine.
-2. Changing to the `www/vale` directory:
-
-```bash
-cd www/vale
-```
-
-3\. Running the `run-vale` script:
-
-```bash
-# to lint content for the main documentation
-./run-vale.sh book/app/learn error resources
-# to lint content for the resources documentation
-./run-vale.sh resources/app error
-# to lint content for the API reference
-./run-vale.sh api-reference/markdown error
-# to lint content for the Medusa UI documentation
-./run-vale.sh ui/src/content/docs error
-# to lint content for the user guide
-./run-vale.sh user-guide/app error
-```
-
-{/* TODO need to enable MDX v1 comments first. */}
-
-{/* ### Linter Exceptions
-
-If it's needed to break some style guide rules in a document, you can wrap the parts that the linter shouldn't scan with the following comments in the `md` or `mdx` files:
-
-```md
-<!-- vale off -->
-
-content that shouldn't be scanned for errors here...
-
-<!-- vale on -->
-```
-
-You can also disable specific rules. For example:
-
-```md
-<!-- vale docs.Numbers = NO -->
-
-Medusa supports Node versions 14 and 16.
-
-<!-- vale docs.Numbers = YES -->
-```
-
-If you use this in your PR, you must justify its usage. */}
-
-***
-
-## Linting with ESLint
-
-Medusa uses ESlint to lint code blocks both in the content and the code base of the documentation apps.
-
-### Linting Content with ESLint
-
-Each PR runs through a check that lints the code in the content files using ESLint. The action's name is `content-eslint`.
-
-If you want to check content ESLint errors locally and fix them, you can do that by:
-
-1\. Install the dependencies in the `www` directory:
-
-```bash
-yarn install
-```
-
-2\. Run the turbo command in the `www` directory:
-
-```bash
-turbo run lint:content
-```
-
-This will fix any fixable errors, and show errors that require your action.
-
-### Linting Code with ESLint
-
-Each PR runs through a check that lints the code in the content files using ESLint. The action's name is `code-docs-eslint`.
-
-If you want to check code ESLint errors locally and fix them, you can do that by:
-
-1\. Install the dependencies in the `www` directory:
-
-```bash
-yarn install
-```
-
-2\. Run the turbo command in the `www` directory:
-
-```bash
-yarn lint
-```
-
-This will fix any fixable errors, and show errors that require your action.
-
-{/* TODO need to enable MDX v1 comments first. */}
-
-{/* ### ESLint Exceptions
-
-If some code blocks have errors that can't or shouldn't be fixed, you can add the following command before the code block:
-
-~~~md
-<!-- eslint-skip -->
-
-```js
-console.log("This block isn't linted")
-```
-
-```js
-console.log("This block is linted")
-```
-~~~
-
-You can also disable specific rules. For example:
-
-~~~md
-<!-- eslint-disable semi -->
-
-```js
-console.log("This block can use semicolons");
-```
-
-```js
-console.log("This block can't use semi colons")
-```
-~~~ */}
-
-
 # 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.
@@ -18453,6 +18189,270 @@ const response = await api.post(`/custom`, form, {
 ```
 
 
+# Docs Contribution Guidelines
+
+Thank you for your interest in contributing to the documentation! You will be helping the open source community and other developers interested in learning more about Medusa and using it.
+
+This guide is specific to contributing to the documentation. If you’re interested in contributing to Medusa’s codebase, check out the [contributing guidelines in the Medusa GitHub repository](https://github.com/medusajs/medusa/blob/develop/CONTRIBUTING.md).
+
+## What Can You Contribute?
+
+You can contribute to the Medusa documentation in the following ways:
+
+- Fixes to existing content. This includes small fixes like typos, or adding missing information.
+- Additions to the documentation. If you think a documentation page can be useful to other developers, you can contribute by adding it.
+  - Make sure to open an issue first in the [medusa repository](https://github.com/medusajs/medusa) to confirm that you can add that documentation page.
+- Fixes to UI components and tooling. If you find a bug while browsing the documentation, you can contribute by fixing it.
+
+***
+
+## Documentation Workspace
+
+Medusa's documentation projects are all part of the documentation yarn workspace, which you can find in the [medusa repository](https://github.com/medusajs/medusa) under the `www` directory.
+
+The workspace has the following two directories:
+
+- `apps`: this directory holds the different documentation websites and projects.
+  - `book`: includes the codebase for the [main Medusa documentation](https://docs.medusajs.com//index.html.md). It's built with [Next.js 15](https://nextjs.org/).
+  - `resources`: includes the codebase for the resources documentation, which powers different sections of the docs such as the [Integrations](https://docs.medusajs.com/resources/integrations/index.html.md) or [How-to & Tutorials](https://docs.medusajs.com/resources/how-to-tutorials/index.html.md) sections. It's built with [Next.js 15](https://nextjs.org/).
+  - `api-reference`: includes the codebase for the API reference website. It's built with [Next.js 15](https://nextjs.org/).
+  - `ui`: includes the codebase for the Medusa UI documentation website. It's built with [Next.js 15](https://nextjs.org/).
+- `packages`: this directory holds the shared packages and components necessary for the development of the projects in the `apps` directory.
+  - `docs-ui` includes the shared React components between the different apps.
+  - `remark-rehype-plugins` includes Remark and Rehype plugins used by the documentation projects.
+
+***
+
+## Documentation Content
+
+All documentation projects are built with Next.js. The content is writtin in MDX files.
+
+### Medusa Main Docs Content
+
+The content of the Medusa main docs are under the `www/apps/book/app` directory.
+
+### Medusa Resources Content
+
+The content of all pages under the `/resources` path are under the `www/apps/resources/app` directory.
+
+Documentation pages under the `www/apps/resources/references` directory are generated automatically from the source code under the `packages/medusa` directory. So, you can't directly make changes to them. Instead, you'll have to make changes to the comments in the original source code.
+
+### API Reference
+
+The API reference's content is split into two types:
+
+1. Static content, which are the content related to getting started, expanding fields, and more. These are located in the `www/apps/api-reference/markdown` directory. They are MDX files.
+2. OpenAPI specs that are shown to developers when checking the reference of an API Route. These are generated from OpenApi Spec comments, which are under the `www/utils/generated/oas-output` directory.
+
+### Medusa UI Documentation
+
+The content of the Medusa UI documentation are located under the `www/apps/ui/src/content/docs` directory. They are MDX files.
+
+The UI documentation also shows code examples, which are under the `www/apps/ui/src/examples` directory.
+
+The UI component props are generated from the source code and placed into the `www/apps/ui/src/specs` directory. To contribute to these props and their comments, check the comments in the source code under the `packages/design-system/ui` directory.
+
+***
+
+## Style Guide
+
+When you contribute to the documentation content, make sure to follow the [documentation style guide](https://www.notion.so/Style-Guide-Docs-fad86dd1c5f84b48b145e959f36628e0).
+
+***
+
+## How to Contribute
+
+If you’re fixing errors in an existing documentation page, you can scroll down to the end of the page and click on the “Edit this page” link. You’ll be redirected to the GitHub edit form of that page and you can make edits directly and submit a pull request (PR).
+
+If you’re adding a new page or contributing to the codebase, fork the repository, create a new branch, and make all changes necessary in your repository. Then, once you’re done,  create a PR in the Medusa repository.
+
+### Base Branch
+
+When you make an edit to an existing documentation page or fork the repository to make changes to the documentation, create a new branch.
+
+Documentation contributions always use `develop` as the base branch. Make sure to also open your PR against the `develop` branch.
+
+### Branch Name
+
+Make sure that the branch name starts with `docs/`. For example, `docs/fix-services`. Vercel deployed previews are only triggered for branches starting with `docs/`.
+
+### Pull Request Conventions
+
+When you create a pull request, prefix the title with `docs:` or `docs(PROJECT_NAME):`, where `PROJECT_NAME` is the name of the documentation project this pull request pertains to. For example, `docs(ui): fix titles`.
+
+In the body of the PR, explain clearly what the PR does. If the PR solves an issue, use [closing keywords](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword) with the issue number. For example, “Closes #1333”.
+
+***
+
+## Images
+
+If you are adding images to a documentation page, you can host the image on [Imgur](https://imgur.com) for free to include it in the PR. Our team will later upload it to our image hosting.
+
+***
+
+## NPM and Yarn Code Blocks
+
+If you’re adding code blocks that use NPM and Yarn, you must add the `npm2yarn` meta field.
+
+For example:
+
+````md
+```bash npm2yarn
+npm run start
+```
+````
+
+The code snippet must be written using NPM.
+
+### Global Option
+
+When a command uses the global option `-g`, add it at the end of the NPM command to ensure that it’s transformed to a Yarn command properly. For example:
+
+```bash npm2yarn
+npm install @medusajs/cli -g
+```
+
+***
+
+## Linting with Vale
+
+Medusa uses [Vale](https://vale.sh/) to lint documentation pages and perform checks on incoming PRs into the repository.
+
+### Result of Vale PR Checks
+
+You can check the result of running the "lint" action on your PR by clicking the Details link next to it. You can find there all errors that you need to fix.
+
+### Run Vale Locally
+
+If you want to check your work locally, you can do that by:
+
+1. [Installing Vale](https://vale.sh/docs/vale-cli/installation/) on your machine.
+2. Changing to the `www/vale` directory:
+
+```bash
+cd www/vale
+```
+
+3\. Running the `run-vale` script:
+
+```bash
+# to lint content for the main documentation
+./run-vale.sh book/app/learn error resources
+# to lint content for the resources documentation
+./run-vale.sh resources/app error
+# to lint content for the API reference
+./run-vale.sh api-reference/markdown error
+# to lint content for the Medusa UI documentation
+./run-vale.sh ui/src/content/docs error
+# to lint content for the user guide
+./run-vale.sh user-guide/app error
+```
+
+{/* TODO need to enable MDX v1 comments first. */}
+
+{/* ### Linter Exceptions
+
+If it's needed to break some style guide rules in a document, you can wrap the parts that the linter shouldn't scan with the following comments in the `md` or `mdx` files:
+
+```md
+<!-- vale off -->
+
+content that shouldn't be scanned for errors here...
+
+<!-- vale on -->
+```
+
+You can also disable specific rules. For example:
+
+```md
+<!-- vale docs.Numbers = NO -->
+
+Medusa supports Node versions 14 and 16.
+
+<!-- vale docs.Numbers = YES -->
+```
+
+If you use this in your PR, you must justify its usage. */}
+
+***
+
+## Linting with ESLint
+
+Medusa uses ESlint to lint code blocks both in the content and the code base of the documentation apps.
+
+### Linting Content with ESLint
+
+Each PR runs through a check that lints the code in the content files using ESLint. The action's name is `content-eslint`.
+
+If you want to check content ESLint errors locally and fix them, you can do that by:
+
+1\. Install the dependencies in the `www` directory:
+
+```bash
+yarn install
+```
+
+2\. Run the turbo command in the `www` directory:
+
+```bash
+turbo run lint:content
+```
+
+This will fix any fixable errors, and show errors that require your action.
+
+### Linting Code with ESLint
+
+Each PR runs through a check that lints the code in the content files using ESLint. The action's name is `code-docs-eslint`.
+
+If you want to check code ESLint errors locally and fix them, you can do that by:
+
+1\. Install the dependencies in the `www` directory:
+
+```bash
+yarn install
+```
+
+2\. Run the turbo command in the `www` directory:
+
+```bash
+yarn lint
+```
+
+This will fix any fixable errors, and show errors that require your action.
+
+{/* TODO need to enable MDX v1 comments first. */}
+
+{/* ### ESLint Exceptions
+
+If some code blocks have errors that can't or shouldn't be fixed, you can add the following command before the code block:
+
+~~~md
+<!-- eslint-skip -->
+
+```js
+console.log("This block isn't linted")
+```
+
+```js
+console.log("This block is linted")
+```
+~~~
+
+You can also disable specific rules. For example:
+
+~~~md
+<!-- eslint-disable semi -->
+
+```js
+console.log("This block can use semicolons");
+```
+
+```js
+console.log("This block can't use semi colons")
+```
+~~~ */}
+
+
 # Example: Write Integration Tests for Workflows
 
 In this chapter, you'll learn how to write integration tests for workflows using [medusaIntegrationTestRunner](https://docs.medusajs.com/learn/debugging-and-testing/testing-tools/integration-tests/index.html.md) from Medusa's Testing Framwork.
@@ -18834,6 +18834,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.
+
+***
+
+
 # Cart Module
 
 In this section of the documentation, you will find resources to learn more about the Cart Module and how to use it in your application.
@@ -19132,277 +19262,6 @@ Learn more about workflows in [this documentation](https://docs.medusajs.com/doc
 ***
 
 
-# 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.
-
-Refer to the [Medusa Admin User Guide](https://docs.medusajs.com/user-guide/customers/index.html.md) to learn how to manage customers and groups using the dashboard.
-
-Medusa has customer related features available out-of-the-box through the Customer 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 Customer Module.
-
-Learn more about why modules are isolated in [this documentation](https://docs.medusajs.com/docs/learn/fundamentals/modules/isolation/index.html.md).
-
-## Customer Features
-
-- [Customer Management](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/customer/customer-accounts/index.html.md): Store and manage guest and registered customers in your store.
-- [Customer Organization](https://docs.medusajs.com/references/customer/models/index.html.md): Organize customers into groups. This has a lot of benefits and supports many use cases, such as provide discounts for specific customer groups using the [Promotion Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/promotion/index.html.md).
-
-***
-
-## How to Use the Customer 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-customer.ts" highlights={highlights}
-import { 
-  createWorkflow, 
-  WorkflowResponse,
-  createStep,
-  StepResponse,
-} from "@medusajs/framework/workflows-sdk"
-import { Modules } from "@medusajs/framework/utils"
-
-const createCustomerStep = createStep(
-  "create-customer",
-  async ({}, { container }) => {
-    const customerModuleService = container.resolve(Modules.CUSTOMER)
-
-    const customer = await customerModuleService.createCustomers({
-      first_name: "Peter",
-      last_name: "Hayes",
-      email: "peter.hayes@example.com",
-    })
-
-    return new StepResponse({ customer }, customer.id)
-  },
-  async (customerId, { container }) => {
-    if (!customerId) {
-      return
-    }
-    const customerModuleService = container.resolve(Modules.CUSTOMER)
-
-    await customerModuleService.deleteCustomers([customerId])
-  }
-)
-
-export const createCustomerWorkflow = createWorkflow(
-  "create-customer",
-  () => {
-    const { customer } = createCustomerStep()
-
-    return new WorkflowResponse({
-      customer,
-    })
-  }
-)
-```
-
-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 { createCustomerWorkflow } from "../../workflows/create-customer"
-
-export async function GET(
-  req: MedusaRequest,
-  res: MedusaResponse
-) {
-  const { result } = await createCustomerWorkflow(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 { createCustomerWorkflow } from "../workflows/create-customer"
-
-export default async function handleUserCreated({
-  event: { data },
-  container,
-}: SubscriberArgs<{ id: string }>) {
-  const { result } = await createCustomerWorkflow(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 { createCustomerWorkflow } from "../workflows/create-customer"
-
-export default async function myCustomJob(
-  container: MedusaContainer
-) {
-  const { result } = await createCustomerWorkflow(container)
-    .run()
-
-  console.log(result)
-}
-
-export const config = {
-  name: "run-once-a-day",
-  schedule: `0 0 * * *`,
-}
-```
-
-Learn more about workflows in [this documentation](https://docs.medusajs.com/docs/learn/fundamentals/workflows/index.html.md).
-
-***
-
-
-# Auth Module
-
-In this section of the documentation, you will find resources to learn more about the Auth Module and how to use it in your application.
-
-Medusa has auth related features available out-of-the-box through the Auth Module. A [module](https://docs.medusajs.com/docs/learn/fundamentals/modules/index.html.md) is a standalone package that provides features for a single domain. Each of Medusa's commerce features are placed in Commerce Modules, such as this Auth Module.
-
-Learn more about why modules are isolated in [this documentation](https://docs.medusajs.com/docs/learn/fundamentals/modules/isolation/index.html.md).
-
-## Auth Features
-
-- [Basic User Authentication](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/auth/authentication-route#1-basic-authentication-flow/index.html.md): Authenticate users using their email and password credentials.
-- [Third-Party and Social Authentication](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/auth/authentication-route#2-third-party-service-authenticate-flow/index.html.md): Authenticate users using third-party services and social platforms, such as [Google](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/auth/auth-providers/google/index.html.md) and [GitHub](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/auth/auth-providers/github/index.html.md).
-- [Authenticate Custom Actor Types](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/auth/create-actor-type/index.html.md): Create custom user or actor types, such as managers, authenticate them in your application, and guard routes based on the custom user types.
-- [Custom Authentication Providers](https://docs.medusajs.com/references/auth/provider/index.html.md): Integrate third-party services with custom authentication providors.
-
-***
-
-## How to Use the Auth Module
-
-In your Medusa application, you build flows around Commerce Modules. A flow is built as a [Workflow](https://docs.medusajs.com/docs/learn/fundamentals/workflows/index.html.md), which is a special function composed of a series of steps that guarantees data consistency and reliable roll-back mechanism.
-
-You can build custom workflows and steps. You can also re-use Medusa's workflows and steps, which are provided by the `@medusajs/medusa/core-flows` package.
-
-For example:
-
-```ts title="src/workflows/authenticate-user.ts" highlights={highlights}
-import { 
-  createWorkflow, 
-  WorkflowResponse,
-  createStep,
-  StepResponse,
-} from "@medusajs/framework/workflows-sdk"
-import { Modules, MedusaError } from "@medusajs/framework/utils"
-import { MedusaRequest } from "@medusajs/framework/http"
-import { AuthenticationInput } from "@medusajs/framework/types"
-
-type Input = {
-  req: MedusaRequest
-}
-
-const authenticateUserStep = createStep(
-  "authenticate-user",
-  async ({ req }: Input, { container }) => {
-    const authModuleService = container.resolve(Modules.AUTH)
-
-    const { success, authIdentity, error } = await authModuleService
-      .authenticate(
-        "emailpass",
-       {
-          url: req.url,
-          headers: req.headers,
-          query: req.query,
-          body: req.body,
-          authScope: "admin", // or custom actor type
-          protocol: req.protocol,
-        } as AuthenticationInput
-      )
-
-    if (!success) {
-      // incorrect authentication details
-      throw new MedusaError(
-        MedusaError.Types.UNAUTHORIZED,
-        error || "Incorrect authentication details"
-      )
-    }
-
-    return new StepResponse({ authIdentity }, authIdentity?.id)
-  },
-  async (authIdentityId, { container }) => {
-    if (!authIdentityId) {
-      return
-    }
-    
-    const authModuleService = container.resolve(Modules.AUTH)
-
-    await authModuleService.deleteAuthIdentities([authIdentityId])
-  }
-)
-
-export const authenticateUserWorkflow = createWorkflow(
-  "authenticate-user",
-  (input: Input) => {
-    const { authIdentity } = authenticateUserStep(input)
-
-    return new WorkflowResponse({
-      authIdentity,
-    })
-  }
-)
-```
-
-You can then execute the workflow in your custom API routes, scheduled jobs, or subscribers:
-
-```ts title="API Route" highlights={[["11"], ["12"]]} collapsibleLines="1-6" expandButtonLabel="Show Imports"
-import type {
-  MedusaRequest,
-  MedusaResponse,
-} from "@medusajs/framework/http"
-import { authenticateUserWorkflow } from "../../workflows/authenticate-user"
-
-export async function GET(
-  req: MedusaRequest,
-  res: MedusaResponse
-) {
-  const { result } = await authenticateUserWorkflow(req.scope)
-    .run({
-      req,
-    })
-
-  res.send(result)
-}
-```
-
-Learn more about workflows in [this documentation](https://docs.medusajs.com/docs/learn/fundamentals/workflows/index.html.md).
-
-***
-
-## Configure Auth Module
-
-The Auth Module accepts options for further configurations. Refer to [this documentation](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/auth/module-options/index.html.md) for details on the module's options.
-
-***
-
-## Providers
-
-Medusa provides the following authentication providers out-of-the-box. You can use them to authenticate admin users, customers, or custom actor types.
-
-***
-
-
 # Fulfillment Module
 
 In this section of the documentation, you will find resources to learn more about the Fulfillment Module and how to use it in your application.
@@ -19570,6 +19429,147 @@ The Fulfillment Module accepts options for further configurations. Refer to [thi
 ***
 
 
+# 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.
+
+Refer to the [Medusa Admin User Guide](https://docs.medusajs.com/user-guide/customers/index.html.md) to learn how to manage customers and groups using the dashboard.
+
+Medusa has customer related features available out-of-the-box through the Customer 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 Customer Module.
+
+Learn more about why modules are isolated in [this documentation](https://docs.medusajs.com/docs/learn/fundamentals/modules/isolation/index.html.md).
+
+## Customer Features
+
+- [Customer Management](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/customer/customer-accounts/index.html.md): Store and manage guest and registered customers in your store.
+- [Customer Organization](https://docs.medusajs.com/references/customer/models/index.html.md): Organize customers into groups. This has a lot of benefits and supports many use cases, such as provide discounts for specific customer groups using the [Promotion Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/promotion/index.html.md).
+
+***
+
+## How to Use the Customer 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-customer.ts" highlights={highlights}
+import { 
+  createWorkflow, 
+  WorkflowResponse,
+  createStep,
+  StepResponse,
+} from "@medusajs/framework/workflows-sdk"
+import { Modules } from "@medusajs/framework/utils"
+
+const createCustomerStep = createStep(
+  "create-customer",
+  async ({}, { container }) => {
+    const customerModuleService = container.resolve(Modules.CUSTOMER)
+
+    const customer = await customerModuleService.createCustomers({
+      first_name: "Peter",
+      last_name: "Hayes",
+      email: "peter.hayes@example.com",
+    })
+
+    return new StepResponse({ customer }, customer.id)
+  },
+  async (customerId, { container }) => {
+    if (!customerId) {
+      return
+    }
+    const customerModuleService = container.resolve(Modules.CUSTOMER)
+
+    await customerModuleService.deleteCustomers([customerId])
+  }
+)
+
+export const createCustomerWorkflow = createWorkflow(
+  "create-customer",
+  () => {
+    const { customer } = createCustomerStep()
+
+    return new WorkflowResponse({
+      customer,
+    })
+  }
+)
+```
+
+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 { createCustomerWorkflow } from "../../workflows/create-customer"
+
+export async function GET(
+  req: MedusaRequest,
+  res: MedusaResponse
+) {
+  const { result } = await createCustomerWorkflow(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 { createCustomerWorkflow } from "../workflows/create-customer"
+
+export default async function handleUserCreated({
+  event: { data },
+  container,
+}: SubscriberArgs<{ id: string }>) {
+  const { result } = await createCustomerWorkflow(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 { createCustomerWorkflow } from "../workflows/create-customer"
+
+export default async function myCustomJob(
+  container: MedusaContainer
+) {
+  const { result } = await createCustomerWorkflow(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).
+
+***
+
+
 # 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.
@@ -19714,316 +19714,6 @@ Learn more about workflows in [this documentation](https://docs.medusajs.com/doc
 ***
 
 
-# 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.
-
-Refer to the [Medusa Admin User Guide](https://docs.medusajs.com/user-guide/orders/index.html.md) to learn how to manage orders using the dashboard.
-
-Medusa has order related features available out-of-the-box through the Order 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 Order Module.
-
-Learn more about why modules are isolated in [this documentation](https://docs.medusajs.com/docs/learn/fundamentals/modules/isolation/index.html.md).
-
-## Order Features
-
-- [Order Management](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/order/concepts/index.html.md): Store and manage your orders to retrieve, create, cancel, and perform other operations.
-- Draft Orders: Allow merchants to create orders on behalf of their customers as draft orders that later are transformed to regular orders.
-- [Apply Promotion Adjustments](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/order/promotion-adjustments/index.html.md): Apply promotions or discounts to the order's items and shipping methods by adding adjustment lines that are factored into their subtotals.
-- [Apply Tax Lines](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/order/tax-lines/index.html.md): Apply tax lines to an order's line items and shipping methods.
-- [Returns](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/order/return/index.html.md), [Edits](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/order/edit/index.html.md), [Exchanges](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/order/exchange/index.html.md), and [Claims](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/order/claim/index.html.md): Make [changes](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/order/order-change/index.html.md) to an order to edit, return, or exchange its items, with [version-based control](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/order/order-versioning/index.html.md) over the order's timeline.
-
-***
-
-## How to Use the Order 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-draft-order.ts" highlights={highlights}
-import { 
-  createWorkflow, 
-  WorkflowResponse,
-  createStep,
-  StepResponse,
-} from "@medusajs/framework/workflows-sdk"
-import { Modules } from "@medusajs/framework/utils"
-
-const createDraftOrderStep = createStep(
-  "create-order",
-  async ({}, { container }) => {
-    const orderModuleService = container.resolve(Modules.ORDER)
-
-    const draftOrder = await orderModuleService.createOrders({
-      currency_code: "usd",
-      items: [
-        {
-          title: "Shirt",
-          quantity: 1,
-          unit_price: 3000,
-        },
-      ],
-      shipping_methods: [
-        {
-          name: "Express shipping",
-          amount: 3000,
-        },
-      ],
-      status: "draft",
-    })
-
-    return new StepResponse({ draftOrder }, draftOrder.id)
-  },
-  async (draftOrderId, { container }) => {
-    if (!draftOrderId) {
-      return
-    }
-    const orderModuleService = container.resolve(Modules.ORDER)
-
-    await orderModuleService.deleteOrders([draftOrderId])
-  }
-)
-
-export const createDraftOrderWorkflow = createWorkflow(
-  "create-draft-order",
-  () => {
-    const { draftOrder } = createDraftOrderStep()
-
-    return new WorkflowResponse({
-      draftOrder,
-    })
-  }
-)
-```
-
-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 { createDraftOrderWorkflow } from "../../workflows/create-draft-order"
-
-export async function GET(
-  req: MedusaRequest,
-  res: MedusaResponse
-) {
-  const { result } = await createDraftOrderWorkflow(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 { createDraftOrderWorkflow } from "../workflows/create-draft-order"
-
-export default async function handleUserCreated({
-  event: { data },
-  container,
-}: SubscriberArgs<{ id: string }>) {
-  const { result } = await createDraftOrderWorkflow(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 { createDraftOrderWorkflow } from "../workflows/create-draft-order"
-
-export default async function myCustomJob(
-  container: MedusaContainer
-) {
-  const { result } = await createDraftOrderWorkflow(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).
-
-***
-
-
-# Pricing Module
-
-In this section of the documentation, you will find resources to learn more about the Pricing Module and how to use it in your application.
-
-Refer to the [Medusa Admin User Guide](https://docs.medusajs.com/user-guide/price-lists/index.html.md) to learn how to manage price lists using the dashboard.
-
-Medusa has pricing related features available out-of-the-box through the Pricing 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 Pricing Module.
-
-Learn more about why modules are isolated in [this documentation](https://docs.medusajs.com/docs/learn/fundamentals/modules/isolation/index.html.md).
-
-## Pricing Features
-
-- [Price Management](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/pricing/concepts/index.html.md): Store and manage prices of a resource, such as a product or a variant.
-- [Advanced Rule Engine](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/pricing/price-rules/index.html.md): Create prices with tiers and custom rules to condition prices based on different contexts.
-- [Price Lists](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/pricing/concepts#price-list/index.html.md): Group prices and apply them only in specific conditions with price lists.
-- [Price Calculation Strategy](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/pricing/price-calculation/index.html.md): Retrieve the best price in a given context and for the specified rule values.
-- [Tax-Inclusive Pricing](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/pricing/tax-inclusive-pricing/index.html.md): Calculate prices with taxes included in the price, and Medusa will handle calculating the taxes automatically.
-
-***
-
-## How to Use the Pricing 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-price-set.ts" highlights={highlights}
-import { 
-  createWorkflow, 
-  WorkflowResponse,
-  createStep,
-  StepResponse,
-} from "@medusajs/framework/workflows-sdk"
-import { Modules } from "@medusajs/framework/utils"
-
-const createPriceSetStep = createStep(
-  "create-price-set",
-  async ({}, { container }) => {
-    const pricingModuleService = container.resolve(Modules.PRICING)
-
-    const priceSet = await pricingModuleService.createPriceSets({
-      prices: [
-        {
-          amount: 500,
-          currency_code: "USD",
-        },
-        {
-          amount: 400,
-          currency_code: "EUR",
-          min_quantity: 0,
-          max_quantity: 4,
-          rules: {},
-        },
-      ],
-    })
-
-    return new StepResponse({ priceSet }, priceSet.id)
-  },
-  async (priceSetId, { container }) => {
-    if (!priceSetId) {
-      return
-    }
-    const pricingModuleService = container.resolve(Modules.PRICING)
-
-    await pricingModuleService.deletePriceSets([priceSetId])
-  }
-)
-
-export const createPriceSetWorkflow = createWorkflow(
-  "create-price-set",
-  () => {
-    const { priceSet } = createPriceSetStep()
-
-    return new WorkflowResponse({
-      priceSet,
-    })
-  }
-)
-```
-
-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 { createPriceSetWorkflow } from "../../workflows/create-price-set"
-
-export async function GET(
-  req: MedusaRequest,
-  res: MedusaResponse
-) {
-  const { result } = await createPriceSetWorkflow(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 { createPriceSetWorkflow } from "../workflows/create-price-set"
-
-export default async function handleUserCreated({
-  event: { data },
-  container,
-}: SubscriberArgs<{ id: string }>) {
-  const { result } = await createPriceSetWorkflow(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 { createPriceSetWorkflow } from "../workflows/create-price-set"
-
-export default async function myCustomJob(
-  container: MedusaContainer
-) {
-  const { result } = await createPriceSetWorkflow(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).
-
-***
-
-
 # Payment Module
 
 In this section of the documentation, you will find resources to learn more about the Payment Module and how to use it in your application.
@@ -20179,6 +19869,160 @@ Medusa provides the following payment providers out-of-the-box. You can use them
 ***
 
 
+# Pricing Module
+
+In this section of the documentation, you will find resources to learn more about the Pricing Module and how to use it in your application.
+
+Refer to the [Medusa Admin User Guide](https://docs.medusajs.com/user-guide/price-lists/index.html.md) to learn how to manage price lists using the dashboard.
+
+Medusa has pricing related features available out-of-the-box through the Pricing 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 Pricing Module.
+
+Learn more about why modules are isolated in [this documentation](https://docs.medusajs.com/docs/learn/fundamentals/modules/isolation/index.html.md).
+
+## Pricing Features
+
+- [Price Management](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/pricing/concepts/index.html.md): Store and manage prices of a resource, such as a product or a variant.
+- [Advanced Rule Engine](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/pricing/price-rules/index.html.md): Create prices with tiers and custom rules to condition prices based on different contexts.
+- [Price Lists](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/pricing/concepts#price-list/index.html.md): Group prices and apply them only in specific conditions with price lists.
+- [Price Calculation Strategy](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/pricing/price-calculation/index.html.md): Retrieve the best price in a given context and for the specified rule values.
+- [Tax-Inclusive Pricing](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/pricing/tax-inclusive-pricing/index.html.md): Calculate prices with taxes included in the price, and Medusa will handle calculating the taxes automatically.
+
+***
+
+## How to Use the Pricing 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-price-set.ts" highlights={highlights}
+import { 
+  createWorkflow, 
+  WorkflowResponse,
+  createStep,
+  StepResponse,
+} from "@medusajs/framework/workflows-sdk"
+import { Modules } from "@medusajs/framework/utils"
+
+const createPriceSetStep = createStep(
+  "create-price-set",
+  async ({}, { container }) => {
+    const pricingModuleService = container.resolve(Modules.PRICING)
+
+    const priceSet = await pricingModuleService.createPriceSets({
+      prices: [
+        {
+          amount: 500,
+          currency_code: "USD",
+        },
+        {
+          amount: 400,
+          currency_code: "EUR",
+          min_quantity: 0,
+          max_quantity: 4,
+          rules: {},
+        },
+      ],
+    })
+
+    return new StepResponse({ priceSet }, priceSet.id)
+  },
+  async (priceSetId, { container }) => {
+    if (!priceSetId) {
+      return
+    }
+    const pricingModuleService = container.resolve(Modules.PRICING)
+
+    await pricingModuleService.deletePriceSets([priceSetId])
+  }
+)
+
+export const createPriceSetWorkflow = createWorkflow(
+  "create-price-set",
+  () => {
+    const { priceSet } = createPriceSetStep()
+
+    return new WorkflowResponse({
+      priceSet,
+    })
+  }
+)
+```
+
+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 { createPriceSetWorkflow } from "../../workflows/create-price-set"
+
+export async function GET(
+  req: MedusaRequest,
+  res: MedusaResponse
+) {
+  const { result } = await createPriceSetWorkflow(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 { createPriceSetWorkflow } from "../workflows/create-price-set"
+
+export default async function handleUserCreated({
+  event: { data },
+  container,
+}: SubscriberArgs<{ id: string }>) {
+  const { result } = await createPriceSetWorkflow(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 { createPriceSetWorkflow } from "../workflows/create-price-set"
+
+export default async function myCustomJob(
+  container: MedusaContainer
+) {
+  const { result } = await createPriceSetWorkflow(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.
@@ -20625,24 +20469,27 @@ Learn more about workflows in [this documentation](https://docs.medusajs.com/doc
 ***
 
 
-# Stock Location Module
+# Order 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.
+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.
 
-Refer to the [Medusa Admin User Guide](https://docs.medusajs.com/user-guide/settings/locations-and-shipping/index.html.md) to learn how to manage stock locations using the dashboard.
+Refer to the [Medusa Admin User Guide](https://docs.medusajs.com/user-guide/orders/index.html.md) to learn how to manage orders using the dashboard.
 
-Medusa has stock location related features available out-of-the-box through the Stock Location Module. A [module](https://docs.medusajs.com/docs/learn/fundamentals/modules/index.html.md) is a standalone package that provides features for a single domain. Each of Medusa's commerce features are placed in Commerce Modules, such as this Stock Location Module.
+Medusa has order related features available out-of-the-box through the Order 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 Order Module.
 
 Learn more about why modules are isolated in [this documentation](https://docs.medusajs.com/docs/learn/fundamentals/modules/isolation/index.html.md).
 
-## Stock Location Features
+## Order Features
 
-- [Stock Location Management](https://docs.medusajs.com/references/stock-location-next/models/index.html.md): Store and manage stock locations. Medusa links stock locations with data models of other modules that require a location, such as the [Inventory Module's InventoryLevel](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/stock-location/links-to-other-modules/index.html.md).
-- [Address Management](https://docs.medusajs.com/references/stock-location-next/models/StockLocationAddress/index.html.md): Manage the address of each stock location.
+- [Order Management](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/order/concepts/index.html.md): Store and manage your orders to retrieve, create, cancel, and perform other operations.
+- Draft Orders: Allow merchants to create orders on behalf of their customers as draft orders that later are transformed to regular orders.
+- [Apply Promotion Adjustments](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/order/promotion-adjustments/index.html.md): Apply promotions or discounts to the order's items and shipping methods by adding adjustment lines that are factored into their subtotals.
+- [Apply Tax Lines](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/order/tax-lines/index.html.md): Apply tax lines to an order's line items and shipping methods.
+- [Returns](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/order/return/index.html.md), [Edits](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/order/edit/index.html.md), [Exchanges](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/order/exchange/index.html.md), and [Claims](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/order/claim/index.html.md): Make [changes](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/order/order-change/index.html.md) to an order to edit, return, or exchange its items, with [version-based control](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/order/order-versioning/index.html.md) over the order's timeline.
 
 ***
 
-## How to Use Stock Location Module's Service
+## How to Use the Order 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.
 
@@ -20650,7 +20497,7 @@ You can build custom workflows and steps. You can also re-use Medusa's workflows
 
 For example:
 
-```ts title="src/workflows/create-stock-location.ts" highlights={highlights}
+```ts title="src/workflows/create-draft-order.ts" highlights={highlights}
 import { 
   createWorkflow, 
   WorkflowResponse,
@@ -20659,33 +20506,49 @@ import {
 } from "@medusajs/framework/workflows-sdk"
 import { Modules } from "@medusajs/framework/utils"
 
-const createStockLocationStep = createStep(
-  "create-stock-location",
+const createDraftOrderStep = createStep(
+  "create-order",
   async ({}, { container }) => {
-    const stockLocationModuleService = container.resolve(Modules.STOCK_LOCATION)
+    const orderModuleService = container.resolve(Modules.ORDER)
 
-    const stockLocation = await stockLocationModuleService.createStockLocations({
-      name: "Warehouse 1",
+    const draftOrder = await orderModuleService.createOrders({
+      currency_code: "usd",
+      items: [
+        {
+          title: "Shirt",
+          quantity: 1,
+          unit_price: 3000,
+        },
+      ],
+      shipping_methods: [
+        {
+          name: "Express shipping",
+          amount: 3000,
+        },
+      ],
+      status: "draft",
     })
 
-    return new StepResponse({ stockLocation }, stockLocation.id)
+    return new StepResponse({ draftOrder }, draftOrder.id)
   },
-  async (stockLocationId, { container }) => {
-    if (!stockLocationId) {
+  async (draftOrderId, { container }) => {
+    if (!draftOrderId) {
       return
     }
-    const stockLocationModuleService = container.resolve(Modules.STOCK_LOCATION)
+    const orderModuleService = container.resolve(Modules.ORDER)
 
-    await stockLocationModuleService.deleteStockLocations([stockLocationId])
+    await orderModuleService.deleteOrders([draftOrderId])
   }
 )
 
-export const createStockLocationWorkflow = createWorkflow(
-  "create-stock-location",
+export const createDraftOrderWorkflow = createWorkflow(
+  "create-draft-order",
   () => {
-    const { stockLocation } = createStockLocationStep()
+    const { draftOrder } = createDraftOrderStep()
 
-    return new WorkflowResponse({ stockLocation })
+    return new WorkflowResponse({
+      draftOrder,
+    })
   }
 )
 ```
@@ -20699,13 +20562,13 @@ import type {
   MedusaRequest,
   MedusaResponse,
 } from "@medusajs/framework/http"
-import { createStockLocationWorkflow } from "../../workflows/create-stock-location"
+import { createDraftOrderWorkflow } from "../../workflows/create-draft-order"
 
 export async function GET(
   req: MedusaRequest,
   res: MedusaResponse
 ) {
-  const { result } = await createStockLocationWorkflow(req.scope)
+  const { result } = await createDraftOrderWorkflow(req.scope)
     .run()
 
   res.send(result)
@@ -20719,13 +20582,13 @@ import {
   type SubscriberConfig,
   type SubscriberArgs,
 } from "@medusajs/framework"
-import { createStockLocationWorkflow } from "../workflows/create-stock-location"
+import { createDraftOrderWorkflow } from "../workflows/create-draft-order"
 
 export default async function handleUserCreated({
   event: { data },
   container,
 }: SubscriberArgs<{ id: string }>) {
-  const { result } = await createStockLocationWorkflow(container)
+  const { result } = await createDraftOrderWorkflow(container)
     .run()
 
   console.log(result)
@@ -20740,12 +20603,12 @@ export const config: SubscriberConfig = {
 
 ```ts title="src/jobs/run-daily.ts" highlights={[["7"], ["8"]]}
 import { MedusaContainer } from "@medusajs/framework/types"
-import { createStockLocationWorkflow } from "../workflows/create-stock-location"
+import { createDraftOrderWorkflow } from "../workflows/create-draft-order"
 
 export default async function myCustomJob(
   container: MedusaContainer
 ) {
-  const { result } = await createStockLocationWorkflow(container)
+  const { result } = await createDraftOrderWorkflow(container)
     .run()
 
   console.log(result)
@@ -20762,6 +20625,298 @@ Learn more about workflows in [this documentation](https://docs.medusajs.com/doc
 ***
 
 
+# Tax Module
+
+In this section of the documentation, you will find resources to learn more about the Tax Module and how to use it in your application.
+
+Refer to the [Medusa Admin User Guide](https://docs.medusajs.com/user-guide/settings/tax-regions/index.html.md) to learn how to manage tax regions using the dashboard.
+
+Medusa has tax related features available out-of-the-box through the Tax Module. A [module](https://docs.medusajs.com/docs/learn/fundamentals/modules/index.html.md) is a standalone package that provides features for a single domain. Each of Medusa's commerce features are placed in Commerce Modules, such as this Tax Module.
+
+Learn more about why modules are isolated in [this documentation](https://docs.medusajs.com/docs/learn/fundamentals/modules/isolation/index.html.md).
+
+## Tax Features
+
+- [Tax Settings Per Region](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/tax/tax-region/index.html.md): Set different tax settings for each tax region.
+- [Tax Rates and Rules](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/tax/tax-rates-and-rules/index.html.md): Manage each region's default tax rates and override them with conditioned tax rates.
+- [Retrieve Tax Lines for carts and orders](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/tax/tax-calculation-with-provider/index.html.md): Calculate and retrieve the tax lines of a cart or order's line items and shipping methods with tax providers.
+- [Custom Tax Providers](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/tax/tax-provider/index.html.md): Create custom tax providers to calculate tax lines differently for each tax region.
+
+***
+
+## How to Use Tax Module's Service
+
+In your Medusa application, you build flows around Commerce Modules. A flow is built as a [Workflow](https://docs.medusajs.com/docs/learn/fundamentals/workflows/index.html.md), which is a special function composed of a series of steps that guarantees data consistency and reliable roll-back mechanism.
+
+You can build custom workflows and steps. You can also re-use Medusa's workflows and steps, which are provided by the `@medusajs/medusa/core-flows` package.
+
+For example:
+
+```ts title="src/workflows/create-tax-region.ts" highlights={highlights}
+import { 
+  createWorkflow, 
+  WorkflowResponse,
+  createStep,
+  StepResponse,
+} from "@medusajs/framework/workflows-sdk"
+import { Modules } from "@medusajs/framework/utils"
+
+const createTaxRegionStep = createStep(
+  "create-tax-region",
+  async ({}, { container }) => {
+    const taxModuleService = container.resolve(Modules.TAX)
+
+    const taxRegion = await taxModuleService.createTaxRegions({
+      country_code: "us",
+    })
+
+    return new StepResponse({ taxRegion }, taxRegion.id)
+  },
+  async (taxRegionId, { container }) => {
+    if (!taxRegionId) {
+      return
+    }
+    const taxModuleService = container.resolve(Modules.TAX)
+
+    await taxModuleService.deleteTaxRegions([taxRegionId])
+  }
+)
+
+export const createTaxRegionWorkflow = createWorkflow(
+  "create-tax-region",
+  () => {
+    const { taxRegion } = createTaxRegionStep()
+
+    return new WorkflowResponse({ taxRegion })
+  }
+)
+```
+
+You can then execute the workflow in your custom API routes, scheduled jobs, or subscribers:
+
+### API Route
+
+```ts title="src/api/workflow/route.ts" highlights={[["11"], ["12"]]} collapsibleLines="1-6" expandButtonLabel="Show Imports"
+import type {
+  MedusaRequest,
+  MedusaResponse,
+} from "@medusajs/framework/http"
+import { createTaxRegionWorkflow } from "../../workflows/create-tax-region"
+
+export async function GET(
+  req: MedusaRequest,
+  res: MedusaResponse
+) {
+  const { result } = await createTaxRegionWorkflow(req.scope)
+    .run()
+
+  res.send(result)
+}
+```
+
+### Subscriber
+
+```ts title="src/subscribers/user-created.ts" highlights={[["11"], ["12"]]} collapsibleLines="1-6" expandButtonLabel="Show Imports"
+import {
+  type SubscriberConfig,
+  type SubscriberArgs,
+} from "@medusajs/framework"
+import { createTaxRegionWorkflow } from "../workflows/create-tax-region"
+
+export default async function handleUserCreated({
+  event: { data },
+  container,
+}: SubscriberArgs<{ id: string }>) {
+  const { result } = await createTaxRegionWorkflow(container)
+    .run()
+
+  console.log(result)
+}
+
+export const config: SubscriberConfig = {
+  event: "user.created",
+}
+```
+
+### Scheduled Job
+
+```ts title="src/jobs/run-daily.ts" highlights={[["7"], ["8"]]}
+import { MedusaContainer } from "@medusajs/framework/types"
+import { createTaxRegionWorkflow } from "../workflows/create-tax-region"
+
+export default async function myCustomJob(
+  container: MedusaContainer
+) {
+  const { result } = await createTaxRegionWorkflow(container)
+    .run()
+
+  console.log(result)
+}
+
+export const config = {
+  name: "run-once-a-day",
+  schedule: `0 0 * * *`,
+}
+```
+
+Learn more about workflows in [this documentation](https://docs.medusajs.com/docs/learn/fundamentals/workflows/index.html.md).
+
+***
+
+## Configure Tax Module
+
+The Tax Module accepts options for further configurations. Refer to [this documentation](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/tax/module-options/index.html.md) for details on the module's options.
+
+***
+
+
+# User Module
+
+In this section of the documentation, you will find resources to learn more about the User Module and how to use it in your application.
+
+Refer to the [Medusa Admin User Guide](https://docs.medusajs.com/user-guide/settings/users/index.html.md) to learn how to manage users using the dashboard.
+
+Medusa has user related features available out-of-the-box through the User 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 User Module.
+
+Learn more about why modules are isolated in [this documentation](https://docs.medusajs.com/docs/learn/fundamentals/modules/isolation/index.html.md).
+
+## User Features
+
+- [User Management](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/user/user-creation-flows/index.html.md): Store and manage users in your store.
+- [Invite Users](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/user/user-creation-flows#invite-users/index.html.md): Invite users to join your store and manage those invites.
+
+***
+
+## How to Use User 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-user.ts" highlights={highlights}
+import { 
+  createWorkflow, 
+  WorkflowResponse,
+  createStep,
+  StepResponse,
+} from "@medusajs/framework/workflows-sdk"
+import { Modules } from "@medusajs/framework/utils"
+
+const createUserStep = createStep(
+  "create-user",
+  async ({}, { container }) => {
+    const userModuleService = container.resolve(Modules.USER)
+
+    const user = await userModuleService.createUsers({
+      email: "user@example.com",
+      first_name: "John",
+      last_name: "Smith",
+    })
+
+    return new StepResponse({ user }, user.id)
+  },
+  async (userId, { container }) => {
+    if (!userId) {
+      return
+    }
+    const userModuleService = container.resolve(Modules.USER)
+
+    await userModuleService.deleteUsers([userId])
+  }
+)
+
+export const createUserWorkflow = createWorkflow(
+  "create-user",
+  () => {
+    const { user } = createUserStep()
+
+    return new WorkflowResponse({
+      user,
+    })
+  }
+)
+```
+
+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 { createUserWorkflow } from "../../workflows/create-user"
+
+export async function GET(
+  req: MedusaRequest,
+  res: MedusaResponse
+) {
+  const { result } = await createUserWorkflow(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 { createUserWorkflow } from "../workflows/create-user"
+
+export default async function handleUserCreated({
+  event: { data },
+  container,
+}: SubscriberArgs<{ id: string }>) {
+  const { result } = await createUserWorkflow(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 { createUserWorkflow } from "../workflows/create-user"
+
+export default async function myCustomJob(
+  container: MedusaContainer
+) {
+  const { result } = await createUserWorkflow(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 User Module
+
+The User Module accepts options for further configurations. Refer to [this documentation](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/user/module-options/index.html.md) for details on the module's options.
+
+***
+
+
 # Sales Channel Module
 
 In this section of the documentation, you will find resources to learn more about the Sales Channel Module and how to use it in your application.
@@ -20922,25 +21077,24 @@ Learn more about workflows in [this documentation](https://docs.medusajs.com/doc
 ***
 
 
-# Tax Module
+# Stock Location Module
 
-In this section of the documentation, you will find resources to learn more about the Tax Module and how to use it in your application.
+In this section of the documentation, you will find resources to learn more about the Stock Location Module and how to use it in your application.
 
-Refer to the [Medusa Admin User Guide](https://docs.medusajs.com/user-guide/settings/tax-regions/index.html.md) to learn how to manage tax regions using the dashboard.
+Refer to the [Medusa Admin User Guide](https://docs.medusajs.com/user-guide/settings/locations-and-shipping/index.html.md) to learn how to manage stock locations using the dashboard.
 
-Medusa has tax related features available out-of-the-box through the Tax Module. A [module](https://docs.medusajs.com/docs/learn/fundamentals/modules/index.html.md) is a standalone package that provides features for a single domain. Each of Medusa's commerce features are placed in Commerce Modules, such as this Tax Module.
+Medusa has stock location related features available out-of-the-box through the Stock Location Module. A [module](https://docs.medusajs.com/docs/learn/fundamentals/modules/index.html.md) is a standalone package that provides features for a single domain. Each of Medusa's commerce features are placed in Commerce Modules, such as this Stock Location Module.
 
 Learn more about why modules are isolated in [this documentation](https://docs.medusajs.com/docs/learn/fundamentals/modules/isolation/index.html.md).
 
-## Tax Features
+## Stock Location Features
 
-- [Tax Settings Per Region](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/tax/tax-region/index.html.md): Set different tax settings for each tax region.
-- [Tax Rates and Rules](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/tax/tax-rates-and-rules/index.html.md): Manage each region's default tax rates and override them with conditioned tax rates.
-- [Retrieve Tax Lines for carts and orders](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/tax/tax-calculation-with-provider/index.html.md): Calculate and retrieve the tax lines of a cart or order's line items and shipping methods with tax providers.
+- [Stock Location Management](https://docs.medusajs.com/references/stock-location-next/models/index.html.md): Store and manage stock locations. Medusa links stock locations with data models of other modules that require a location, such as the [Inventory Module's InventoryLevel](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/stock-location/links-to-other-modules/index.html.md).
+- [Address Management](https://docs.medusajs.com/references/stock-location-next/models/StockLocationAddress/index.html.md): Manage the address of each stock location.
 
 ***
 
-## How to Use Tax Module's Service
+## How to Use Stock Location Module's Service
 
 In your Medusa application, you build flows around Commerce Modules. A flow is built as a [Workflow](https://docs.medusajs.com/docs/learn/fundamentals/workflows/index.html.md), which is a special function composed of a series of steps that guarantees data consistency and reliable roll-back mechanism.
 
@@ -20948,7 +21102,7 @@ You can build custom workflows and steps. You can also re-use Medusa's workflows
 
 For example:
 
-```ts title="src/workflows/create-tax-region.ts" highlights={highlights}
+```ts title="src/workflows/create-stock-location.ts" highlights={highlights}
 import { 
   createWorkflow, 
   WorkflowResponse,
@@ -20957,33 +21111,33 @@ import {
 } from "@medusajs/framework/workflows-sdk"
 import { Modules } from "@medusajs/framework/utils"
 
-const createTaxRegionStep = createStep(
-  "create-tax-region",
+const createStockLocationStep = createStep(
+  "create-stock-location",
   async ({}, { container }) => {
-    const taxModuleService = container.resolve(Modules.TAX)
+    const stockLocationModuleService = container.resolve(Modules.STOCK_LOCATION)
 
-    const taxRegion = await taxModuleService.createTaxRegions({
-      country_code: "us",
+    const stockLocation = await stockLocationModuleService.createStockLocations({
+      name: "Warehouse 1",
     })
 
-    return new StepResponse({ taxRegion }, taxRegion.id)
+    return new StepResponse({ stockLocation }, stockLocation.id)
   },
-  async (taxRegionId, { container }) => {
-    if (!taxRegionId) {
+  async (stockLocationId, { container }) => {
+    if (!stockLocationId) {
       return
     }
-    const taxModuleService = container.resolve(Modules.TAX)
+    const stockLocationModuleService = container.resolve(Modules.STOCK_LOCATION)
 
-    await taxModuleService.deleteTaxRegions([taxRegionId])
+    await stockLocationModuleService.deleteStockLocations([stockLocationId])
   }
 )
 
-export const createTaxRegionWorkflow = createWorkflow(
-  "create-tax-region",
+export const createStockLocationWorkflow = createWorkflow(
+  "create-stock-location",
   () => {
-    const { taxRegion } = createTaxRegionStep()
+    const { stockLocation } = createStockLocationStep()
 
-    return new WorkflowResponse({ taxRegion })
+    return new WorkflowResponse({ stockLocation })
   }
 )
 ```
@@ -20997,13 +21151,13 @@ import type {
   MedusaRequest,
   MedusaResponse,
 } from "@medusajs/framework/http"
-import { createTaxRegionWorkflow } from "../../workflows/create-tax-region"
+import { createStockLocationWorkflow } from "../../workflows/create-stock-location"
 
 export async function GET(
   req: MedusaRequest,
   res: MedusaResponse
 ) {
-  const { result } = await createTaxRegionWorkflow(req.scope)
+  const { result } = await createStockLocationWorkflow(req.scope)
     .run()
 
   res.send(result)
@@ -21017,13 +21171,13 @@ import {
   type SubscriberConfig,
   type SubscriberArgs,
 } from "@medusajs/framework"
-import { createTaxRegionWorkflow } from "../workflows/create-tax-region"
+import { createStockLocationWorkflow } from "../workflows/create-stock-location"
 
 export default async function handleUserCreated({
   event: { data },
   container,
 }: SubscriberArgs<{ id: string }>) {
-  const { result } = await createTaxRegionWorkflow(container)
+  const { result } = await createStockLocationWorkflow(container)
     .run()
 
   console.log(result)
@@ -21038,12 +21192,12 @@ export const config: SubscriberConfig = {
 
 ```ts title="src/jobs/run-daily.ts" highlights={[["7"], ["8"]]}
 import { MedusaContainer } from "@medusajs/framework/types"
-import { createTaxRegionWorkflow } from "../workflows/create-tax-region"
+import { createStockLocationWorkflow } from "../workflows/create-stock-location"
 
 export default async function myCustomJob(
   container: MedusaContainer
 ) {
-  const { result } = await createTaxRegionWorkflow(container)
+  const { result } = await createStockLocationWorkflow(container)
     .run()
 
   console.log(result)
@@ -21059,12 +21213,6 @@ Learn more about workflows in [this documentation](https://docs.medusajs.com/doc
 
 ***
 
-## Configure Tax Module
-
-The Tax Module accepts options for further configurations. Refer to [this documentation](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/tax/module-options/index.html.md) for details on the module's options.
-
-***
-
 
 # Store Module
 
@@ -21207,181 +21355,6 @@ Learn more about workflows in [this documentation](https://docs.medusajs.com/doc
 ***
 
 
-# User Module
-
-In this section of the documentation, you will find resources to learn more about the User Module and how to use it in your application.
-
-Refer to the [Medusa Admin User Guide](https://docs.medusajs.com/user-guide/settings/users/index.html.md) to learn how to manage users using the dashboard.
-
-Medusa has user related features available out-of-the-box through the User 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 User Module.
-
-Learn more about why modules are isolated in [this documentation](https://docs.medusajs.com/docs/learn/fundamentals/modules/isolation/index.html.md).
-
-## User Features
-
-- [User Management](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/user/user-creation-flows/index.html.md): Store and manage users in your store.
-- [Invite Users](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/user/user-creation-flows#invite-users/index.html.md): Invite users to join your store and manage those invites.
-
-***
-
-## How to Use User 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-user.ts" highlights={highlights}
-import { 
-  createWorkflow, 
-  WorkflowResponse,
-  createStep,
-  StepResponse,
-} from "@medusajs/framework/workflows-sdk"
-import { Modules } from "@medusajs/framework/utils"
-
-const createUserStep = createStep(
-  "create-user",
-  async ({}, { container }) => {
-    const userModuleService = container.resolve(Modules.USER)
-
-    const user = await userModuleService.createUsers({
-      email: "user@example.com",
-      first_name: "John",
-      last_name: "Smith",
-    })
-
-    return new StepResponse({ user }, user.id)
-  },
-  async (userId, { container }) => {
-    if (!userId) {
-      return
-    }
-    const userModuleService = container.resolve(Modules.USER)
-
-    await userModuleService.deleteUsers([userId])
-  }
-)
-
-export const createUserWorkflow = createWorkflow(
-  "create-user",
-  () => {
-    const { user } = createUserStep()
-
-    return new WorkflowResponse({
-      user,
-    })
-  }
-)
-```
-
-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 { createUserWorkflow } from "../../workflows/create-user"
-
-export async function GET(
-  req: MedusaRequest,
-  res: MedusaResponse
-) {
-  const { result } = await createUserWorkflow(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 { createUserWorkflow } from "../workflows/create-user"
-
-export default async function handleUserCreated({
-  event: { data },
-  container,
-}: SubscriberArgs<{ id: string }>) {
-  const { result } = await createUserWorkflow(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 { createUserWorkflow } from "../workflows/create-user"
-
-export default async function myCustomJob(
-  container: MedusaContainer
-) {
-  const { result } = await createUserWorkflow(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 User Module
-
-The User Module accepts options for further configurations. Refer to [this documentation](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/user/module-options/index.html.md) for details on the module's options.
-
-***
-
-
-# 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.
-
-
 # Links between API Key Module and Other Modules
 
 This document showcases the module links defined between the API Key Module and other Commerce Modules.
@@ -21480,6 +21453,1166 @@ createRemoteLinkStep({
 ```
 
 
+# Auth Module Provider
+
+In this guide, you’ll learn about the Auth Module Provider and how it's used.
+
+## What is 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)
+
+***
+
+## How to Create an Auth Module Provider?
+
+An Auth Module Provider is a module whose service extends the `AbstractAuthModuleProvider` imported from `@medusajs/framework/utils`.
+
+The module can have multiple auth provider services, where each is registered as a separate auth provider.
+
+Refer to the [Create Auth Module Provider](https://docs.medusajs.com/references/auth/provider/index.html.md) guide to learn how to create an Auth Module Provider.
+
+***
+
+## 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.
+
+
+# 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.
+
+
+# Auth Identity and Actor Types
+
+In this document, you’ll learn about concepts related to identity and actors in the Auth Module.
+
+## What is an Auth Identity?
+
+The [AuthIdentity data model](https://docs.medusajs.com/references/auth/models/AuthIdentity/index.html.md) represents a user registered by an [authentication provider](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/auth/auth-providers/index.html.md). When a user is registered using an authentication provider, the provider creates a record of `AuthIdentity`.
+
+Then, when the user logs-in in the future with the same authentication provider, the associated auth identity is used to validate their credentials.
+
+***
+
+## Actor Types
+
+An actor type is a type of user that can be authenticated. The Auth Module doesn't store or manage any user-like models, such as for customers or users. Instead, the user types are created and managed by other modules. For example, a customer is managed by the [Customer Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/customer/index.html.md).
+
+Then, when an auth identity is created for the actor type, the ID of the user is stored in the `app_metadata` property of the auth identity.
+
+For example, an auth identity of a customer has the following `app_metadata` property:
+
+```json
+{
+  "app_metadata": {
+    "customer_id": "cus_123"
+  }
+}
+```
+
+The ID of the user is stored in the key `{actor_type}_id` of the `app_metadata` property.
+
+***
+
+## Protect Routes by Actor Type
+
+When you protect routes with the `authenticate` middleware, you specify in its first parameter the actor type that must be authenticated to access the specified API routes.
+
+For example:
+
+```ts title="src/api/middlewares.ts" highlights={highlights}
+import { 
+  defineMiddlewares,
+  authenticate,
+} from "@medusajs/framework/http"
+
+export default defineMiddlewares({
+  routes: [
+    {
+      matcher: "/custom/admin*",
+      middlewares: [
+        authenticate("user", ["session", "bearer", "api-key"]),
+      ],
+    },
+  ],
+})
+```
+
+By specifying `user` as the first parameter of `authenticate`, only authenticated users of actor type `user` (admin users) can access API routes starting with `/custom/admin`.
+
+***
+
+## Custom Actor Types
+
+You can define custom actor types that allows a custom user, managed by your custom module, to authenticate into Medusa.
+
+For example, if you have a custom module with a `Manager` data model, you can authenticate managers with the `manager` actor type.
+
+Learn how to create a custom actor type in [this guide](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/auth/create-actor-type/index.html.md).
+
+
+# How to 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("manager")
+
+    const manager = await managerModuleService.createManager(
+      managerData
+    )
+
+    return new StepResponse(manager)
+  }
+)
+
+const createManagerWorkflow = createWorkflow(
+  "create-manager",
+  function (input: CreateManagerWorkflowInput) {
+    const manager = createManagerStep({
+      manager: input.manager,
+    })
+
+    setAuthAppMetadataStep({
+      authIdentityId: input.authIdentityId,
+      actorType: "manager",
+      value: manager.id,
+    })
+
+    return new WorkflowResponse(manager)
+  }
+)
+
+export default createManagerWorkflow
+```
+
+This workflow accepts the manager’s data and the associated auth identity’s ID as inputs. The next sections explain how the auth identity ID is retrieved.
+
+The workflow has two steps:
+
+1. Create the manager using the `createManagerStep`.
+2. Set the `app_metadata` property of the associated auth identity using the `setAuthAppMetadataStep` from Medusa's core workflows. You specify the actor type `manager` in the `actorType` property of the step’s input.
+
+***
+
+## 2. Define the Create API Route
+
+Next, you’ll use the workflow defined in the previous section in an API route that creates a manager.
+
+So, create the file `src/api/manager/route.ts` with the following content:
+
+```ts title="src/api/manager/route.ts" highlights={createRouteHighlights}
+import type { 
+  AuthenticatedMedusaRequest,
+  MedusaResponse,
+} from "@medusajs/framework/http"
+import { MedusaError } from "@medusajs/framework/utils"
+import createManagerWorkflow from "../../workflows/create-manager"
+
+type RequestBody = {
+  first_name: string
+  last_name: string
+  email: string
+}
+
+export async function POST(
+  req: AuthenticatedMedusaRequest<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 query = req.scope.resolve("query")
+  const managerId = req.auth_context?.actor_id
+
+  const { data: [manager] } = await query.graph({
+    entity: "manager",
+    fields: ["*"],
+    filters: {
+      id: managerId,
+    },
+  }, {
+    throwIfKeyNotFound: true,
+  })
+
+  res.json({ manager })
+}
+```
+
+This route is only accessible by authenticated managers. You access the manager’s ID using `req.auth_context.actor_id`.
+
+***
+
+## Test Custom Actor Type Authentication Flow
+
+To authenticate managers:
+
+1. Send a `POST` request to `/auth/manager/emailpass/register` to create an auth identity for the manager:
+
+```bash
+curl -X POST 'http://localhost:9000/auth/manager/emailpass/register' \
+-H 'Content-Type: application/json' \
+--data-raw '{
+    "email": "manager@gmail.com",
+    "password": "supersecret"
+}'
+```
+
+Copy the returned token to use it in the next request.
+
+2. Send a `POST` request to `/manager` to create a manager:
+
+```bash
+curl -X POST 'http://localhost:9000/manager' \
+-H 'Content-Type: application/json' \
+-H 'Authorization: Bearer {token}' \
+--data-raw '{
+    "first_name": "John",
+    "last_name": "Doe",
+    "email": "manager@gmail.com"
+}'
+```
+
+Replace `{token}` with the token returned in the previous step.
+
+3. Send a `POST` request to `/auth/manager/emailpass` again to retrieve an authenticated token for the manager:
+
+```bash
+curl -X POST 'http://localhost:9000/auth/manager/emailpass' \
+-H 'Content-Type: application/json' \
+--data-raw '{
+    "email": "manager@gmail.com",
+    "password": "supersecret"
+}'
+```
+
+4. You can now send authenticated requests as a manager. For example, send a `GET` request to `/manager/me` to retrieve the authenticated manager’s details:
+
+```bash
+curl 'http://localhost:9000/manager/me' \
+-H 'Authorization: Bearer {token}'
+```
+
+Whenever you want to log in as a manager, use the `/auth/manager/emailpass` API route, as explained in step 3.
+
+***
+
+## Delete User of Actor Type
+
+When you delete a user of the actor type, you must update its auth identity to remove the association to the user.
+
+For example, create the following workflow that deletes a manager and updates its auth identity, create the file `src/workflows/delete-manager.ts` with the following content:
+
+```ts title="src/workflows/delete-manager.ts" collapsibleLines="1-6" expandButtonLabel="Show Imports"
+import {
+  createStep,
+  StepResponse,
+} from "@medusajs/framework/workflows-sdk"
+import ManagerModuleService from "../modules/manager/service"
+
+export type DeleteManagerWorkflow = {
+  id: string
+}
+
+const deleteManagerStep = createStep(
+  "delete-manager-step",
+  async (
+    { id }: DeleteManagerWorkflow, 
+    { container }) => {
+      const managerModuleService: ManagerModuleService = 
+        container.resolve("manager")
+
+      const manager = await managerModuleService.retrieve(id)
+
+      await managerModuleService.deleteManagers(id)
+
+      return new StepResponse(undefined, { manager })
+    },
+    async ({ manager }, { container }) => {
+      const managerModuleService: ManagerModuleService = 
+        container.resolve("manager")
+
+      await managerModuleService.createManagers(manager)
+    }
+  )
+```
+
+You add a step that deletes the manager using the `deleteManagers` method of the module's main service. In the compensation function, you create the manager again.
+
+Next, in the same file, add the workflow that deletes a manager:
+
+```ts title="src/workflows/delete-manager.ts" collapsibleLines="1-15" expandButtonLabel="Show Imports" highlights={deleteHighlights}
+// other imports
+import { MedusaError } from "@medusajs/framework/utils"
+import {
+  WorkflowData,
+  WorkflowResponse,
+  createWorkflow,
+  transform,
+} from "@medusajs/framework/workflows-sdk"
+import { 
+  setAuthAppMetadataStep,
+  useQueryGraphStep,
+} from "@medusajs/medusa/core-flows"
+
+// ...
+
+export const deleteManagerWorkflow = createWorkflow(
+  "delete-manager",
+  (
+    input: WorkflowData<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.
+
+
+# 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 Module Options
+
+In this document, you'll learn about the options of the Auth Module.
+
+## providers
+
+The `providers` option is an array of auth module providers.
+
+When the Medusa application starts, these providers are registered and can be used to handle authentication.
+
+By default, the `emailpass` provider is registered to authenticate customers and admin users.
+
+For example:
+
+```ts title="medusa-config.ts"
+import { Modules, ContainerRegistrationKeys } from "@medusajs/framework/utils"
+
+// ...
+
+module.exports = defineConfig({
+  // ...
+  modules: [
+    {
+      resolve: "@medusajs/medusa/auth",
+      dependencies: [Modules.CACHE, ContainerRegistrationKeys.LOGGER],
+      options: {
+        providers: [
+          {
+            resolve: "@medusajs/medusa/auth-emailpass",
+            id: "emailpass",
+            options: {
+              // provider options...
+            },
+          },
+        ],
+      },
+    },
+  ],
+})
+```
+
+The `providers` option is an array of objects that accept the following properties:
+
+- `resolve`: A string indicating the package name of the module provider or the path to it relative to the `src` directory.
+- `id`: A string indicating the provider's unique name or ID.
+- `options`: An optional object of the module provider's options.
+
+***
+
+## Auth CORS
+
+The Medusa application's authentication API routes are defined under the `/auth` prefix that requires setting the `authCors` property of the `http` configuration.
+
+By default, the Medusa application you created will have an `AUTH_CORS` environment variable, which is used as the value of `authCors`.
+
+Refer to [Medusa's configuration guide](https://docs.medusajs.com/docs/learn/configurations/medusa-config#httpauthCors/index.html.md) to learn more about the `authCors` configuration.
+
+***
+
+## authMethodsPerActor Configuration
+
+The Medusa application's configuration accept an `authMethodsPerActor` configuration which restricts the allowed auth providers used with an actor type.
+
+Learn more about the `authMethodsPerActor` configuration in [this guide](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/auth/auth-providers#configure-allowed-auth-providers-of-actor-types/index.html.md).
+
+
+# How to 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"
+}
+```
+
+
 # Cart Concepts
 
 In this document, you’ll get an overview of the main concepts of a cart.
@@ -21517,122 +22650,118 @@ If the fulfillment provider requires additional custom data to be passed along f
 The `data` property is an object used to store custom data relevant later for fulfillment.
 
 
-# Promotions Adjustments in Carts
+# How to Handle Password Reset Token Event
 
-In this document, you’ll learn how a promotion is applied to a cart’s line items and shipping methods using adjustment lines.
+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).
 
-## What are Adjustment Lines?
+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.
 
-An adjustment line indicates a change to an item or a shipping method’s amount. It’s used to apply promotions or discounts on a cart.
+You'll create a subscriber that listens to the event. When the event is emitted, the subscriber sends an email notification to the user.
 
-The [LineItemAdjustment](https://docs.medusajs.com/references/cart/models/LineItemAdjustment/index.html.md) data model represents changes on a line item, and the [ShippingMethodAdjustment](https://docs.medusajs.com/references/cart/models/ShippingMethodAdjustment/index.html.md) data model represents changes on a shipping method.
+### Prerequisites
 
-![A diagram showcasing the relations between other data models and adjustment line models](https://res.cloudinary.com/dza7lstvk/image/upload/v1711534248/Medusa%20Resources/cart-adjustments_k4sttb.jpg)
+- [A notification provider module, such as SendGrid](https://docs.medusajs.com/infrastructure-modules/notification/sendgrid/index.html.md)
 
-The `amount` property of the adjustment line indicates the amount to be discounted from the original amount. Also, the ID of the applied promotion is stored in the `promotion_id` property of the adjustment line.
+## 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.
 
 ***
 
-## Discountable Option
+## 2. Test it Out: Generate Reset Password Token
 
-The [LineItem](https://docs.medusajs.com/references/cart/models/LineItem/index.html.md) data model has an `is_discountable` property that indicates whether promotions can be applied to the line item. It’s enabled by default.
+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.
 
-When disabled, a promotion can’t be applied to a line item. In the context of the Promotion Module, the promotion isn’t applied to the line item even if it matches its rules.
+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.
 
 ***
 
-## Promotion Actions
+## Next Steps: Implementing Frontend
 
-When using the Cart and Promotion modules together, such as in the Medusa application, use the [computeActions method of the Promotion Module’s main service](https://docs.medusajs.com/references/promotion/computeActions/index.html.md). It retrieves the actions of line items and shipping methods.
+In your frontend, you must have a page that accepts `token` and `email` query parameters.
 
-Learn more about actions in the [Promotion Module’s documentation](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/promotion/actions/index.html.md).
+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).
 
-For example:
+### Examples
 
-```ts collapsibleLines="1-8" expandButtonLabel="Show Imports"
-import {
-  ComputeActionAdjustmentLine,
-  ComputeActionItemLine,
-  ComputeActionShippingLine,
-  // ...
-} from "@medusajs/framework/types"
-
-// retrieve the cart
-const cart = await cartModuleService.retrieveCart("cart_123", {
-  relations: [
-    "items.adjustments",
-    "shipping_methods.adjustments",
-  ],
-})
-
-// retrieve line item adjustments
-const lineItemAdjustments: ComputeActionItemLine[] = []
-cart.items.forEach((item) => {
-  const filteredAdjustments = item.adjustments?.filter(
-    (adjustment) => adjustment.code !== undefined
-  ) as unknown as ComputeActionAdjustmentLine[]
-  if (filteredAdjustments.length) {
-    lineItemAdjustments.push({
-      ...item,
-      adjustments: filteredAdjustments,
-    })
-  }
-})
-
-// retrieve shipping method adjustments
-const shippingMethodAdjustments: ComputeActionShippingLine[] =
-  []
-cart.shipping_methods.forEach((shippingMethod) => {
-  const filteredAdjustments =
-    shippingMethod.adjustments?.filter(
-      (adjustment) => adjustment.code !== undefined
-    ) as unknown as ComputeActionAdjustmentLine[]
-  if (filteredAdjustments.length) {
-    shippingMethodAdjustments.push({
-      ...shippingMethod,
-      adjustments: filteredAdjustments,
-    })
-  }
-})
-
-// compute actions
-const actions = await promotionModuleService.computeActions(
-  ["promo_123"],
-  {
-    items: lineItemAdjustments,
-    shipping_methods: shippingMethodAdjustments,
-  }
-)
-```
-
-The `computeActions` method accepts the existing adjustments of line items and shipping methods to compute the actions accurately.
-
-Then, use the returned `addItemAdjustment` and `addShippingMethodAdjustment` actions to set the cart’s line item and the shipping method’s adjustments.
-
-```ts collapsibleLines="1-8" expandButtonLabel="Show Imports"
-import {
-  AddItemAdjustmentAction,
-  AddShippingMethodAdjustment,
-  // ...
-} from "@medusajs/framework/types"
-
-// ...
-
-await cartModuleService.setLineItemAdjustments(
-  cart.id,
-  actions.filter(
-    (action) => action.action === "addItemAdjustment"
-  ) as AddItemAdjustmentAction[]
-)
-
-await cartModuleService.setShippingMethodAdjustments(
-  cart.id,
-  actions.filter(
-    (action) =>
-      action.action === "addShippingMethodAdjustment"
-  ) as AddShippingMethodAdjustment[]
-)
-```
+- [Storefront Guide: Reset Customer Password](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/storefront-development/customers/reset-password/index.html.md)
 
 
 # Links between Cart Module and Other Modules
@@ -22074,6 +23203,124 @@ const { data: carts } = useQueryGraphStep({
 ```
 
 
+# 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.
+
+## What are Adjustment Lines?
+
+An adjustment line indicates a change to an item or a shipping method’s amount. It’s used to apply promotions or discounts on a cart.
+
+The [LineItemAdjustment](https://docs.medusajs.com/references/cart/models/LineItemAdjustment/index.html.md) data model represents changes on a line item, and the [ShippingMethodAdjustment](https://docs.medusajs.com/references/cart/models/ShippingMethodAdjustment/index.html.md) data model represents changes on a shipping method.
+
+![A diagram showcasing the relations between other data models and adjustment line models](https://res.cloudinary.com/dza7lstvk/image/upload/v1711534248/Medusa%20Resources/cart-adjustments_k4sttb.jpg)
+
+The `amount` property of the adjustment line indicates the amount to be discounted from the original amount. Also, the ID of the applied promotion is stored in the `promotion_id` property of the adjustment line.
+
+***
+
+## Discountable Option
+
+The [LineItem](https://docs.medusajs.com/references/cart/models/LineItem/index.html.md) data model has an `is_discountable` property that indicates whether promotions can be applied to the line item. It’s enabled by default.
+
+When disabled, a promotion can’t be applied to a line item. In the context of the Promotion Module, the promotion isn’t applied to the line item even if it matches its rules.
+
+***
+
+## Promotion Actions
+
+When using the Cart and Promotion modules together, such as in the Medusa application, use the [computeActions method of the Promotion Module’s main service](https://docs.medusajs.com/references/promotion/computeActions/index.html.md). It retrieves the actions of line items and shipping methods.
+
+Learn more about actions in the [Promotion Module’s documentation](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/promotion/actions/index.html.md).
+
+For example:
+
+```ts collapsibleLines="1-8" expandButtonLabel="Show Imports"
+import {
+  ComputeActionAdjustmentLine,
+  ComputeActionItemLine,
+  ComputeActionShippingLine,
+  // ...
+} from "@medusajs/framework/types"
+
+// retrieve the cart
+const cart = await cartModuleService.retrieveCart("cart_123", {
+  relations: [
+    "items.adjustments",
+    "shipping_methods.adjustments",
+  ],
+})
+
+// retrieve line item adjustments
+const lineItemAdjustments: ComputeActionItemLine[] = []
+cart.items.forEach((item) => {
+  const filteredAdjustments = item.adjustments?.filter(
+    (adjustment) => adjustment.code !== undefined
+  ) as unknown as ComputeActionAdjustmentLine[]
+  if (filteredAdjustments.length) {
+    lineItemAdjustments.push({
+      ...item,
+      adjustments: filteredAdjustments,
+    })
+  }
+})
+
+// retrieve shipping method adjustments
+const shippingMethodAdjustments: ComputeActionShippingLine[] =
+  []
+cart.shipping_methods.forEach((shippingMethod) => {
+  const filteredAdjustments =
+    shippingMethod.adjustments?.filter(
+      (adjustment) => adjustment.code !== undefined
+    ) as unknown as ComputeActionAdjustmentLine[]
+  if (filteredAdjustments.length) {
+    shippingMethodAdjustments.push({
+      ...shippingMethod,
+      adjustments: filteredAdjustments,
+    })
+  }
+})
+
+// compute actions
+const actions = await promotionModuleService.computeActions(
+  ["promo_123"],
+  {
+    items: lineItemAdjustments,
+    shipping_methods: shippingMethodAdjustments,
+  }
+)
+```
+
+The `computeActions` method accepts the existing adjustments of line items and shipping methods to compute the actions accurately.
+
+Then, use the returned `addItemAdjustment` and `addShippingMethodAdjustment` actions to set the cart’s line item and the shipping method’s adjustments.
+
+```ts collapsibleLines="1-8" expandButtonLabel="Show Imports"
+import {
+  AddItemAdjustmentAction,
+  AddShippingMethodAdjustment,
+  // ...
+} from "@medusajs/framework/types"
+
+// ...
+
+await cartModuleService.setLineItemAdjustments(
+  cart.id,
+  actions.filter(
+    (action) => action.action === "addItemAdjustment"
+  ) as AddItemAdjustmentAction[]
+)
+
+await cartModuleService.setShippingMethodAdjustments(
+  cart.id,
+  actions.filter(
+    (action) =>
+      action.action === "addShippingMethodAdjustment"
+  ) as AddShippingMethodAdjustment[]
+)
+```
+
+
 # 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.
@@ -22149,6 +23396,183 @@ await cartModuleService.setLineItemTaxLines(
 ```
 
 
+# Fulfillment Concepts
+
+In this document, you’ll learn about some basic fulfillment concepts.
+
+## Fulfillment Set
+
+A fulfillment set is a general form or way of fulfillment. For example, shipping is a form of fulfillment, and pick-up is another form of fulfillment. Each of these can be created as fulfillment sets.
+
+A fulfillment set is represented by the [FulfillmentSet data model](https://docs.medusajs.com/references/fulfillment/models/FulfillmentSet/index.html.md). All other configurations, options, and management features are related to a fulfillment set, in one way or another.
+
+```ts
+const fulfillmentSets = await fulfillmentModuleService.createFulfillmentSets(
+  [
+    {
+      name: "Shipping",
+      type: "shipping",
+    },
+    {
+      name: "Pick-up",
+      type: "pick-up",
+    },
+  ]
+)
+```
+
+***
+
+## Service Zone
+
+A service zone is a collection of geographical zones or areas. It’s used to restrict available shipping options to a defined set of locations.
+
+A service zone is represented by the [ServiceZone data model](https://docs.medusajs.com/references/fulfillment/models/ServiceZone/index.html.md). It’s associated with a fulfillment set, as each service zone is specific to a form of fulfillment. For example, if a customer chooses to pick up items, you can restrict the available shipping options based on their location.
+
+![A 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.
+
+
+# Fulfillment Module Provider
+
+In this guide, you’ll learn about the Fulfillment Module Provider and how it's used.
+
+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 is 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).
+
+![Diagram showcasing the communication between Medusa, the Fulfillment Module Provider, and the third-party fulfillment provider.](https://res.cloudinary.com/dza7lstvk/image/upload/v1746794800/Medusa%20Resources/fulfillment-provider-service_ljsqpq.jpg)
+
+***
+
+## Default Fulfillment Provider
+
+Medusa provides a Manual Fulfillment Provider that acts as a placeholder fulfillment provider. It doesn't process fulfillment and delegates that to the merchant.
+
+This provider is installed by default in your application and you can use it to fulfill items manually.
+
+The identifier of the manual fulfillment provider is `fp_manual_manual`.
+
+***
+
+## How to Create a Custom Fulfillment Provider?
+
+A Fulfillment Module Provider is a module whose service implements the `IFulfillmentProvider` imported from `@medusajs/framework/types`.
+
+The module can have multiple fulfillment provider services, where each are registered as separate fulfillment providers.
+
+Refer to the [Create Fulfillment Module Provider](https://docs.medusajs.com/references/fulfillment/provider/index.html.md) guide to learn how to create a Fulfillment Module Provider.
+
+{/* TODO add link to user guide */}
+
+After you create a fulfillment provider, you can choose it as the default Fulfillment Module Provider for a stock location in the Medusa Admin dashboard.
+
+***
+
+## How are Fulfillment Providers Registered?
+
+### Configure Fulfillment Module's Providers
+
+The Fulfillment Module accepts a `providers` option that allows you to configure the providers registered in your application.
+
+Learn more about this option in the [Module Options](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/fulfillment/module-options/index.html.md) guide.
+
+### Registration on Application Start
+
+When the Medusa application starts, it registers the Fulfillment Module Providers defined in the `providers` option of the Fulfillment Module.
+
+For each Fulfillment Module Provider, the Medusa application finds all fulfillment provider services defined in them to register.
+
+### FulfillmentProvider Data Model
+
+A registered fulfillment provider is represented by the [FulfillmentProvider data model](https://docs.medusajs.com/references/fulfillment/models/FulfillmentProvider/index.html.md) in the Medusa application.
+
+This data model is used to reference a service in the Fulfillment Module Provider and determine whether it's installed in the application.
+
+![Diagram showcasing the FulfillmentProvider data model](https://res.cloudinary.com/dza7lstvk/image/upload/v1746794803/Medusa%20Resources/fulfillment-provider-model_wo2ato.jpg)
+
+The `FulfillmentProvider` data model has the following properties:
+
+- `id`: The unique identifier of the fulfillment provider. The ID's format is `fp_{identifier}_{id}`, where:
+  - `identifier` is the value of the `identifier` property in the Fulfillment Module Provider's service.
+  - `id` is the value of the `id` property of the Fulfillment Module Provider in `medusa-config.ts`.
+- `is_enabled`: A boolean indicating whether the fulfillment provider is enabled.
+
+### How to Remove a Fulfillment Provider?
+
+You can remove a registered fulfillment provider from the Medusa application by removing it from the `providers` option in the Fulfillment Module's configuration.
+
+Then, the next time the Medusa application starts, it will set the `is_enabled` property of the `FulfillmentProvider`'s record to `false`. This allows you to re-enable the fulfillment provider later if needed by adding it back to the `providers` option.
+
+
+# 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 Currency Module and Other Modules
 
 This document showcases the module links defined between the Currency Module and other Commerce Modules.
@@ -22206,885 +23630,20 @@ const { data: stores } = useQueryGraphStep({
 ```
 
 
-# Customer Accounts
+# Fulfillment Module Options
 
-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.
-
-## Summary
-
-The Customer Module has the following links to other modules:
-
-Read-only links are used to query data across modules, but the relations aren't stored in a pivot table in the database.
-
-|First Data Model|Second Data Model|Type|Description|
-|---|---|---|---|
-|Customer|AccountHolder|Stored - many-to-many|Learn more|
-|Cart|Customer|Read-only - has one|Learn more|
-|Order|Customer|Read-only - has one|Learn more|
-
-***
-
-## Payment Module
-
-Medusa defines a link between the `Customer` and `AccountHolder` data models, allowing payment providers to save payment methods for a customer, if the payment provider supports it.
-
-This link is available starting from Medusa `v2.5.0`.
-
-### Retrieve with Query
-
-To retrieve the account holder associated with a customer with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `customer.*` in `fields`:
-
-### query.graph
-
-```ts
-const { data: customers } = await query.graph({
-  entity: "customer",
-  fields: [
-    "account_holder_link.account_holder.*",
-  ],
-})
-
-// customers[0].account_holder_link?.[0]?.account_holder
-```
-
-### useQueryGraphStep
-
-```ts
-import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
-
-// ...
-
-const { data: customers } = useQueryGraphStep({
-  entity: "customer",
-  fields: [
-    "account_holder_link.account_holder.*",
-  ],
-})
-
-// customers[0].account_holder_link?.[0]?.account_holder
-```
-
-### Manage with Link
-
-To manage the account holders of a customer, use [Link](https://docs.medusajs.com/docs/learn/fundamentals/module-links/link/index.html.md):
-
-### link.create
-
-```ts
-import { Modules } from "@medusajs/framework/utils"
-
-// ...
-
-await link.create({
-  [Modules.CUSTOMER]: {
-    customer_id: "cus_123",
-  },
-  [Modules.PAYMENT]: {
-    account_holder_id: "acchld_123",
-  },
-})
-```
-
-### createRemoteLinkStep
-
-```ts
-import { createRemoteLinkStep } from "@medusajs/medusa/core-flows"
-
-// ...
-
-createRemoteLinkStep({
-  [Modules.CUSTOMER]: {
-    customer_id: "cus_123",
-  },
-  [Modules.PAYMENT]: {
-    account_holder_id: "acchld_123",
-  },
-})
-```
-
-***
-
-## Cart Module
-
-Medusa defines a read-only link between the [Cart Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/cart/index.html.md)'s `Cart` data model and the `Customer` data model. Because the link is read-only from the `Cart`'s side, you can only retrieve the customer of a cart, and not the other way around.
-
-### Retrieve with Query
-
-To retrieve the customer of a cart with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `customer.*` in `fields`:
-
-### query.graph
-
-```ts
-const { data: carts } = await query.graph({
-  entity: "cart",
-  fields: [
-    "customer.*",
-  ],
-})
-
-// carts.customer
-```
-
-### useQueryGraphStep
-
-```ts
-import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
-
-// ...
-
-const { data: carts } = useQueryGraphStep({
-  entity: "cart",
-  fields: [
-    "customer.*",
-  ],
-})
-
-// carts.customer
-```
-
-***
-
-## Order Module
-
-Medusa defines a read-only link between the [Order Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/order/index.html.md)'s `Order` data model and the `Customer` data model. Because the link is read-only from the `Order`'s side, you can only retrieve the customer of an order, and not the other way around.
-
-### Retrieve with Query
-
-To retrieve the customer of an order with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `customer.*` in `fields`:
-
-### query.graph
-
-```ts
-const { data: orders } = await query.graph({
-  entity: "order",
-  fields: [
-    "customer.*",
-  ],
-})
-
-// orders.customer
-```
-
-### useQueryGraphStep
-
-```ts
-import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
-
-// ...
-
-const { data: orders } = useQueryGraphStep({
-  entity: "order",
-  fields: [
-    "customer.*",
-  ],
-})
-
-// orders.customer
-```
-
-
-# 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"
-}
-```
-
-
-# Auth Module Options
-
-In this document, you'll learn about the options of the Auth Module.
+In this document, you'll learn about the options of the Fulfillment Module.
 
 ## providers
 
-The `providers` option is an array of auth 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 handle authentication.
-
-By default, the `emailpass` provider is registered to authenticate customers and admin users.
+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, ContainerRegistrationKeys } from "@medusajs/framework/utils"
+import { Modules } from "@medusajs/framework/utils"
 
 // ...
 
@@ -23092,13 +23651,12 @@ module.exports = defineConfig({
   // ...
   modules: [
     {
-      resolve: "@medusajs/medusa/auth",
-      dependencies: [Modules.CACHE, ContainerRegistrationKeys.LOGGER],
+      resolve: "@medusajs/medusa/fulfillment",
       options: {
         providers: [
           {
-            resolve: "@medusajs/medusa/auth-emailpass",
-            id: "emailpass",
+            resolve: `@medusajs/medusa/fulfillment-manual`,
+            id: "manual",
             options: {
               // provider options...
             },
@@ -23112,668 +23670,77 @@ module.exports = defineConfig({
 
 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.
+- `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.
 
-***
 
-## Auth CORS
+# Shipping Option
 
-The Medusa application's authentication API routes are defined under the `/auth` prefix that requires setting the `authCors` property of the `http` configuration.
+In this document, you’ll learn about shipping options and their rules.
 
-By default, the Medusa application you created will have an `AUTH_CORS` environment variable, which is used as the value of `authCors`.
+## What’s a Shipping Option?
 
-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.
+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).
 
 ***
 
-## authMethodsPerActor Configuration
+## Service Zone Restrictions
 
-The Medusa application's configuration accept an `authMethodsPerActor` configuration which restricts the allowed auth providers used with an actor type.
+A shipping option is restricted by a service zone, limiting the locations a shipping option be used in.
 
-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).
+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)
 
-# 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("manager")
-
-    const manager = await managerModuleService.createManager(
-      managerData
-    )
-
-    return new StepResponse(manager)
-  }
-)
-
-const createManagerWorkflow = createWorkflow(
-  "create-manager",
-  function (input: CreateManagerWorkflowInput) {
-    const manager = createManagerStep({
-      manager: input.manager,
-    })
-
-    setAuthAppMetadataStep({
-      authIdentityId: input.authIdentityId,
-      actorType: "manager",
-      value: manager.id,
-    })
-
-    return new WorkflowResponse(manager)
-  }
-)
-
-export default createManagerWorkflow
-```
-
-This workflow accepts the manager’s data and the associated auth identity’s ID as inputs. The next sections explain how the auth identity ID is retrieved.
-
-The workflow has two steps:
-
-1. Create the manager using the `createManagerStep`.
-2. Set the `app_metadata` property of the associated auth identity using the `setAuthAppMetadataStep` from Medusa's core workflows. You specify the actor type `manager` in the `actorType` property of the step’s input.
-
-***
-
-## 2. Define the Create API Route
-
-Next, you’ll use the workflow defined in the previous section in an API route that creates a manager.
-
-So, create the file `src/api/manager/route.ts` with the following content:
-
-```ts title="src/api/manager/route.ts" highlights={createRouteHighlights}
-import type { 
-  AuthenticatedMedusaRequest,
-  MedusaResponse,
-} from "@medusajs/framework/http"
-import { MedusaError } from "@medusajs/framework/utils"
-import createManagerWorkflow from "../../workflows/create-manager"
-
-type RequestBody = {
-  first_name: string
-  last_name: string
-  email: string
-}
-
-export async function POST(
-  req: AuthenticatedMedusaRequest<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 query = req.scope.resolve("query")
-  const managerId = req.auth_context?.actor_id
-
-  const { data: [manager] } = await query.graph({
-    entity: "manager",
-    fields: ["*"],
-    filters: {
-      id: managerId,
-    },
-  }, {
-    throwIfKeyNotFound: true,
-  })
-
-  res.json({ manager })
-}
-```
-
-This route is only accessible by authenticated managers. You access the manager’s ID using `req.auth_context.actor_id`.
-
-***
-
-## Test Custom Actor Type Authentication Flow
-
-To authenticate managers:
-
-1. Send a `POST` request to `/auth/manager/emailpass/register` to create an auth identity for the manager:
-
-```bash
-curl -X POST 'http://localhost:9000/auth/manager/emailpass/register' \
--H 'Content-Type: application/json' \
---data-raw '{
-    "email": "manager@gmail.com",
-    "password": "supersecret"
-}'
-```
-
-Copy the returned token to use it in the next request.
-
-2. Send a `POST` request to `/manager` to create a manager:
-
-```bash
-curl -X POST 'http://localhost:9000/manager' \
--H 'Content-Type: application/json' \
--H 'Authorization: Bearer {token}' \
---data-raw '{
-    "first_name": "John",
-    "last_name": "Doe",
-    "email": "manager@gmail.com"
-}'
-```
-
-Replace `{token}` with the token returned in the previous step.
-
-3. Send a `POST` request to `/auth/manager/emailpass` again to retrieve an authenticated token for the manager:
-
-```bash
-curl -X POST 'http://localhost:9000/auth/manager/emailpass' \
--H 'Content-Type: application/json' \
---data-raw '{
-    "email": "manager@gmail.com",
-    "password": "supersecret"
-}'
-```
-
-4. You can now send authenticated requests as a manager. For example, send a `GET` request to `/manager/me` to retrieve the authenticated manager’s details:
-
-```bash
-curl 'http://localhost:9000/manager/me' \
--H 'Authorization: Bearer {token}'
-```
-
-Whenever you want to log in as a manager, use the `/auth/manager/emailpass` API route, as explained in step 3.
-
-***
-
-## Delete User of Actor Type
-
-When you delete a user of the actor type, you must update its auth identity to remove the association to the user.
-
-For example, create the following workflow that deletes a manager and updates its auth identity, create the file `src/workflows/delete-manager.ts` with the following content:
-
-```ts title="src/workflows/delete-manager.ts" collapsibleLines="1-6" expandButtonLabel="Show Imports"
-import {
-  createStep,
-  StepResponse,
-} from "@medusajs/framework/workflows-sdk"
-import ManagerModuleService from "../modules/manager/service"
-
-export type DeleteManagerWorkflow = {
-  id: string
-}
-
-const deleteManagerStep = createStep(
-  "delete-manager-step",
-  async (
-    { id }: DeleteManagerWorkflow, 
-    { container }) => {
-      const managerModuleService: ManagerModuleService = 
-        container.resolve("manager")
-
-      const manager = await managerModuleService.retrieve(id)
-
-      await managerModuleService.deleteManagers(id)
-
-      return new StepResponse(undefined, { manager })
-    },
-    async ({ manager }, { container }) => {
-      const managerModuleService: ManagerModuleService = 
-        container.resolve("manager")
-
-      await managerModuleService.createManagers(manager)
-    }
-  )
-```
-
-You add a step that deletes the manager using the `deleteManagers` method of the module's main service. In the compensation function, you create the manager again.
-
-Next, in the same file, add the workflow that deletes a manager:
-
-```ts title="src/workflows/delete-manager.ts" collapsibleLines="1-15" expandButtonLabel="Show Imports" highlights={deleteHighlights}
-// other imports
-import { MedusaError } from "@medusajs/framework/utils"
-import {
-  WorkflowData,
-  WorkflowResponse,
-  createWorkflow,
-  transform,
-} from "@medusajs/framework/workflows-sdk"
-import { 
-  setAuthAppMetadataStep,
-  useQueryGraphStep,
-} from "@medusajs/medusa/core-flows"
-
-// ...
-
-export const deleteManagerWorkflow = createWorkflow(
-  "delete-manager",
-  (
-    input: WorkflowData<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)
-
-
-# Fulfillment Concepts
-
-In this document, you’ll learn about some basic fulfillment concepts.
-
-## Fulfillment Set
-
-A fulfillment set is a general form or way of fulfillment. For example, shipping is a form of fulfillment, and pick-up is another form of fulfillment. Each of these can be created as fulfillment sets.
-
-A fulfillment set is represented by the [FulfillmentSet data model](https://docs.medusajs.com/references/fulfillment/models/FulfillmentSet/index.html.md). All other configurations, options, and management features are related to a fulfillment set, in one way or another.
-
-```ts
-const fulfillmentSets = await fulfillmentModuleService.createFulfillmentSets(
-  [
-    {
-      name: "Shipping",
-      type: "shipping",
-    },
-    {
-      name: "Pick-up",
-      type: "pick-up",
-    },
-  ]
-)
-```
-
-***
-
-## Service Zone
-
-A service zone is a collection of geographical zones or areas. It’s used to restrict available shipping options to a defined set of locations.
-
-A service zone is represented by the [ServiceZone data model](https://docs.medusajs.com/references/fulfillment/models/ServiceZone/index.html.md). It’s associated with a fulfillment set, as each service zone is specific to a form of fulfillment. For example, if a customer chooses to pick up items, you can restrict the available shipping options based on their location.
-
-![A 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.
+Service zones can be more restrictive, such as restricting to certain cities or province codes.
 
 The province code is always in lower-case and in [ISO 3166-2 format](https://en.wikipedia.org/wiki/ISO_3166-2).
 
-***
-
-## Shipping 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).
+![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)
 
 ***
 
-## Configure Fulfillment Providers
+## Shipping Option Rules
 
-The Fulfillment Module accepts a `providers` option that allows you to register providers in your application.
+You can restrict shipping options by custom rules, such as the item’s weight or the customer’s group.
 
-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).
+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)
 
 ***
 
-## How to Create a Fulfillment Provider?
+## Shipping Profile and Types
 
-Refer to [this guide](https://docs.medusajs.com/references/fulfillment/provider/index.html.md) to learn how to create a fulfillment module provider.
+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).
 
-
-# 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)
+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
 
-The `Fulfillment` data model has a `data` property that holds any necessary data for the third-party fulfillment provider to process the fulfillment.
+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.
 
-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.
+The `ShippingOption` data model has a `data` property. It's an object that stores custom data relevant later when creating and processing a fulfillment.
 
 
 # Links between Fulfillment Module and Other Modules
@@ -24136,117 +24103,308 @@ createRemoteLinkStep({
 ```
 
 
-# Shipping Option
+# Customer Accounts
 
-In this document, you’ll learn about shipping options and their rules.
+In this document, you’ll learn how registered and unregistered accounts are distinguished in the Medusa application.
 
-## What’s a Shipping Option?
+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.
 
-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.
+## `has_account` Property
 
-When the customer places their order, they choose a shipping option to be used to fulfill their items.
+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.
 
-A shipping option is represented by the [ShippingOption data model](https://docs.medusajs.com/references/fulfillment/models/ShippingOption/index.html.md).
+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`.
 
 ***
 
-## Service Zone Restrictions
+## Email Uniqueness
 
-A shipping option is restricted by a service zone, limiting the locations a shipping option be used in.
+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.
 
-For example, a fulfillment provider may have a shipping option that can be used in the United States, and another in Canada.
+So, there can only be one guest customer (having `has_account=false`) and one registered customer (having `has_account=true`) with the same email.
 
-![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.
+# Links between Customer Module and Other Modules
 
-The province code is always in lower-case and in [ISO 3166-2 format](https://en.wikipedia.org/wiki/ISO_3166-2).
+This document showcases the module links defined between the Customer Module and other Commerce Modules.
 
-![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)
+## Summary
+
+The Customer Module has the following links to other modules:
+
+Read-only links are used to query data across modules, but the relations aren't stored in a pivot table in the database.
+
+|First Data Model|Second Data Model|Type|Description|
+|---|---|---|---|
+|Customer|AccountHolder|Stored - many-to-many|Learn more|
+|Cart|Customer|Read-only - has one|Learn more|
+|Order|Customer|Read-only - has one|Learn more|
 
 ***
 
-## Shipping Option Rules
+## Payment Module
 
-You can restrict shipping options by custom rules, such as the item’s weight or the customer’s group.
+Medusa defines a link between the `Customer` and `AccountHolder` data models, allowing payment providers to save payment methods for a customer, if the payment provider supports it.
 
-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.
+This link is available starting from Medusa `v2.5.0`.
 
-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:
+### Retrieve with Query
 
-- `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.
+To retrieve the account holder associated with a customer with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `customer.*` in `fields`:
 
-![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)
+### query.graph
 
-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.
+```ts
+const { data: customers } = await query.graph({
+  entity: "customer",
+  fields: [
+    "account_holder_link.account_holder.*",
+  ],
+})
 
-![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)
+// customers[0].account_holder_link?.[0]?.account_holder
+```
 
-***
+### useQueryGraphStep
 
-## Shipping Profile and Types
+```ts
+import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
 
-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.
+const { data: customers } = useQueryGraphStep({
+  entity: "customer",
+  fields: [
+    "account_holder_link.account_holder.*",
+  ],
+})
 
-***
+// customers[0].account_holder_link?.[0]?.account_holder
+```
 
-## data Property
+### Manage with Link
 
-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.
+To manage the account holders of a customer, use [Link](https://docs.medusajs.com/docs/learn/fundamentals/module-links/link/index.html.md):
 
-The `ShippingOption` data model has a `data` property. It's an object that stores custom data relevant later when creating and processing a fulfillment.
+### link.create
 
-
-# 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"
+```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...
-            },
-          },
-        ],
-      },
-    },
-  ],
+await link.create({
+  [Modules.CUSTOMER]: {
+    customer_id: "cus_123",
+  },
+  [Modules.PAYMENT]: {
+    account_holder_id: "acchld_123",
+  },
 })
 ```
 
-The `providers` option is an array of objects that accept the following properties:
+### createRemoteLinkStep
 
-- `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.
+```ts
+import { createRemoteLinkStep } from "@medusajs/medusa/core-flows"
+
+// ...
+
+createRemoteLinkStep({
+  [Modules.CUSTOMER]: {
+    customer_id: "cus_123",
+  },
+  [Modules.PAYMENT]: {
+    account_holder_id: "acchld_123",
+  },
+})
+```
+
+***
+
+## Cart Module
+
+Medusa defines a read-only link between the [Cart Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/cart/index.html.md)'s `Cart` data model and the `Customer` data model. Because the link is read-only from the `Cart`'s side, you can only retrieve the customer of a cart, and not the other way around.
+
+### Retrieve with Query
+
+To retrieve the customer of a cart with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `customer.*` in `fields`:
+
+### query.graph
+
+```ts
+const { data: carts } = await query.graph({
+  entity: "cart",
+  fields: [
+    "customer.*",
+  ],
+})
+
+// carts.customer
+```
+
+### useQueryGraphStep
+
+```ts
+import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
+
+// ...
+
+const { data: carts } = useQueryGraphStep({
+  entity: "cart",
+  fields: [
+    "customer.*",
+  ],
+})
+
+// carts.customer
+```
+
+***
+
+## Order Module
+
+Medusa defines a read-only link between the [Order Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/order/index.html.md)'s `Order` data model and the `Customer` data model. Because the link is read-only from the `Order`'s side, you can only retrieve the customer of an order, and not the other way around.
+
+### Retrieve with Query
+
+To retrieve the customer of an order with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `customer.*` in `fields`:
+
+### query.graph
+
+```ts
+const { data: orders } = await query.graph({
+  entity: "order",
+  fields: [
+    "customer.*",
+  ],
+})
+
+// orders.customer
+```
+
+### useQueryGraphStep
+
+```ts
+import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
+
+// ...
+
+const { data: orders } = useQueryGraphStep({
+  entity: "order",
+  fields: [
+    "customer.*",
+  ],
+})
+
+// orders.customer
+```
+
+
+# Inventory Concepts
+
+In this document, you’ll learn about the main concepts in the Inventory Module, and how data is stored and related.
+
+## InventoryItem
+
+An inventory item, represented by the [InventoryItem data model](https://docs.medusajs.com/references/inventory-next/models/InventoryItem/index.html.md), is a stock-kept item, such as a product, whose inventory can be managed.
+
+The `InventoryItem` data model mainly holds details related to the underlying stock item, but has relations to other data models that include its inventory details.
+
+![A diagram showcasing the relation between data models in the Inventory Module](https://res.cloudinary.com/dza7lstvk/image/upload/v1709658103/Medusa%20Resources/inventory-architecture_kxr2ql.png)
+
+### Inventory Shipping Requirement
+
+An inventory item has a `requires_shipping` field (enabled by default) that indicates whether the item requires shipping. For example, if you're selling a digital license that has limited stock quantity but doesn't require shipping.
+
+When a product variant is purchased in the Medusa application, this field is used to determine whether the item requires shipping. Learn more in [this documentation](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/product/selling-products/index.html.md).
+
+***
+
+## InventoryLevel
+
+An inventory level, represented by the [InventoryLevel data model](https://docs.medusajs.com/references/inventory-next/models/InventoryLevel/index.html.md), holds the inventory and quantity details of an inventory item in a specific location.
+
+It has three quantity-related properties:
+
+- `stocked_quantity`: The available stock quantity of an item in the associated location.
+- `reserved_quantity`: The quantity reserved from the available `stocked_quantity`. It indicates the quantity that's still not removed from stock, but considered as unavailable when checking whether an item is in stock.
+- `incoming_quantity`: The incoming stock quantity of an item into the associated location. This property doesn't play into the `stocked_quantity` or when checking whether an item is in stock.
+
+### Associated Location
+
+The inventory level's location is determined by the `location_id` property. Medusa links the `InventoryLevel` data model with the `StockLocation` data model from the Stock Location Module.
+
+***
+
+## ReservationItem
+
+A reservation item, represented by the [ReservationItem](https://docs.medusajs.com/references/inventory-next/models/ReservationItem/index.html.md) data model, represents unavailable quantity of an inventory item in a location. It's used when an order is placed but not fulfilled yet.
+
+The reserved quantity is associated with a location, so it has a similar relation to that of the `InventoryLevel` with the Stock Location Module.
+
+
+# Inventory Module in Medusa Flows
+
+This document explains how the Inventory Module is used within the Medusa application's flows.
+
+## Product Variant Creation
+
+When a product variant is created and its `manage_inventory` property's value is `true`, the Medusa application creates an inventory item associated with that product variant.
+
+This flow is implemented within the [createProductVariantsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createProductVariantsWorkflow/index.html.md)
+
+![A diagram showcasing how the Inventory Module is used in the product variant creation form](https://res.cloudinary.com/dza7lstvk/image/upload/v1709661511/Medusa%20Resources/inventory-product-create_khz2hk.jpg)
+
+***
+
+## Add to Cart
+
+When a product variant with `manage_inventory` set to `true` is added to cart, the Medusa application checks whether there's sufficient stocked quantity. If not, an error is thrown and the product variant won't be added to the cart.
+
+This flow is implemented within the [addToCartWorkflow](https://docs.medusajs.com/references/medusa-workflows/addToCartWorkflow/index.html.md)
+
+![A diagram showcasing how the Inventory Module is used in the add to cart flow](https://res.cloudinary.com/dza7lstvk/image/upload/v1709711645/Medusa%20Resources/inventory-cart-flow_achwq9.jpg)
+
+***
+
+## Order Placed
+
+When an order is placed, the Medusa application creates a reservation item for each product variant with `manage_inventory` set to `true`.
+
+This flow is implemented within the [completeCartWorkflow](https://docs.medusajs.com/references/medusa-workflows/completeCartWorkflow/index.html.md)
+
+![A diagram showcasing how the Inventory Module is used in the order placed flow](https://res.cloudinary.com/dza7lstvk/image/upload/v1709712005/Medusa%20Resources/inventory-order-placed_qdxqdn.jpg)
+
+***
+
+## Order Fulfillment
+
+When an item in an order is fulfilled and the associated variant has its `manage_inventory` property set to `true`, the Medusa application:
+
+- Subtracts the `reserved_quantity` from the `stocked_quantity` in the inventory level associated with the variant's inventory item.
+- Resets the `reserved_quantity` to `0`.
+- Deletes the associated reservation item.
+
+This flow is implemented within the [createOrderFulfillmentWorkflow](https://docs.medusajs.com/references/medusa-workflows/createOrderFulfillmentWorkflow/index.html.md)
+
+![A diagram showcasing how the Inventory Module is used in the order fulfillment flow](https://res.cloudinary.com/dza7lstvk/image/upload/v1709712390/Medusa%20Resources/inventory-order-fulfillment_o9wdxh.jpg)
+
+***
+
+## Order Return
+
+When an item in an order is returned and the associated variant has its `manage_inventory` property set to `true`, the Medusa application increments the `stocked_quantity` of the inventory item's level with the returned quantity.
+
+This flow is implemented within the [confirmReturnReceiveWorkflow](https://docs.medusajs.com/references/medusa-workflows/confirmReturnReceiveWorkflow/index.html.md)
+
+![A diagram showcasing how the Inventory Module is used in the order return flow](https://res.cloudinary.com/dza7lstvk/image/upload/v1709712457/Medusa%20Resources/inventory-order-return_ihftyk.jpg)
+
+### Dismissed Returned Items
+
+If a returned item is considered damaged or is dismissed, its quantity doesn't increment the `stocked_quantity` of the inventory item's level.
 
 
 # Inventory Kits
@@ -24639,110 +24797,6 @@ The bundled product has the same inventory items as those of the products part o
 You can now [execute the workflow](https://docs.medusajs.com/docs/learn/fundamentals/workflows#3-execute-the-workflow/index.html.md) in [API routes](https://docs.medusajs.com/docs/learn/fundamentals/api-routes/index.html.md), [scheduled jobs](https://docs.medusajs.com/docs/learn/fundamentals/scheduled-jobs/index.html.md), or [subscribers](https://docs.medusajs.com/docs/learn/fundamentals/events-and-subscribers/index.html.md).
 
 
-# Inventory Concepts
-
-In this document, you’ll learn about the main concepts in the Inventory Module, and how data is stored and related.
-
-## InventoryItem
-
-An inventory item, represented by the [InventoryItem data model](https://docs.medusajs.com/references/inventory-next/models/InventoryItem/index.html.md), is a stock-kept item, such as a product, whose inventory can be managed.
-
-The `InventoryItem` data model mainly holds details related to the underlying stock item, but has relations to other data models that include its inventory details.
-
-![A diagram showcasing the relation between data models in the Inventory Module](https://res.cloudinary.com/dza7lstvk/image/upload/v1709658103/Medusa%20Resources/inventory-architecture_kxr2ql.png)
-
-### Inventory Shipping Requirement
-
-An inventory item has a `requires_shipping` field (enabled by default) that indicates whether the item requires shipping. For example, if you're selling a digital license that has limited stock quantity but doesn't require shipping.
-
-When a product variant is purchased in the Medusa application, this field is used to determine whether the item requires shipping. Learn more in [this documentation](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/product/selling-products/index.html.md).
-
-***
-
-## InventoryLevel
-
-An inventory level, represented by the [InventoryLevel data model](https://docs.medusajs.com/references/inventory-next/models/InventoryLevel/index.html.md), holds the inventory and quantity details of an inventory item in a specific location.
-
-It has three quantity-related properties:
-
-- `stocked_quantity`: The available stock quantity of an item in the associated location.
-- `reserved_quantity`: The quantity reserved from the available `stocked_quantity`. It indicates the quantity that's still not removed from stock, but considered as unavailable when checking whether an item is in stock.
-- `incoming_quantity`: The incoming stock quantity of an item into the associated location. This property doesn't play into the `stocked_quantity` or when checking whether an item is in stock.
-
-### Associated Location
-
-The inventory level's location is determined by the `location_id` property. Medusa links the `InventoryLevel` data model with the `StockLocation` data model from the Stock Location Module.
-
-***
-
-## ReservationItem
-
-A reservation item, represented by the [ReservationItem](https://docs.medusajs.com/references/inventory-next/models/ReservationItem/index.html.md) data model, represents unavailable quantity of an inventory item in a location. It's used when an order is placed but not fulfilled yet.
-
-The reserved quantity is associated with a location, so it has a similar relation to that of the `InventoryLevel` with the Stock Location Module.
-
-
-# Inventory Module in Medusa Flows
-
-This document explains how the Inventory Module is used within the Medusa application's flows.
-
-## Product Variant Creation
-
-When a product variant is created and its `manage_inventory` property's value is `true`, the Medusa application creates an inventory item associated with that product variant.
-
-This flow is implemented within the [createProductVariantsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createProductVariantsWorkflow/index.html.md)
-
-![A diagram showcasing how the Inventory Module is used in the product variant creation form](https://res.cloudinary.com/dza7lstvk/image/upload/v1709661511/Medusa%20Resources/inventory-product-create_khz2hk.jpg)
-
-***
-
-## Add to Cart
-
-When a product variant with `manage_inventory` set to `true` is added to cart, the Medusa application checks whether there's sufficient stocked quantity. If not, an error is thrown and the product variant won't be added to the cart.
-
-This flow is implemented within the [addToCartWorkflow](https://docs.medusajs.com/references/medusa-workflows/addToCartWorkflow/index.html.md)
-
-![A diagram showcasing how the Inventory Module is used in the add to cart flow](https://res.cloudinary.com/dza7lstvk/image/upload/v1709711645/Medusa%20Resources/inventory-cart-flow_achwq9.jpg)
-
-***
-
-## Order Placed
-
-When an order is placed, the Medusa application creates a reservation item for each product variant with `manage_inventory` set to `true`.
-
-This flow is implemented within the [completeCartWorkflow](https://docs.medusajs.com/references/medusa-workflows/completeCartWorkflow/index.html.md)
-
-![A diagram showcasing how the Inventory Module is used in the order placed flow](https://res.cloudinary.com/dza7lstvk/image/upload/v1709712005/Medusa%20Resources/inventory-order-placed_qdxqdn.jpg)
-
-***
-
-## Order Fulfillment
-
-When an item in an order is fulfilled and the associated variant has its `manage_inventory` property set to `true`, the Medusa application:
-
-- Subtracts the `reserved_quantity` from the `stocked_quantity` in the inventory level associated with the variant's inventory item.
-- Resets the `reserved_quantity` to `0`.
-- Deletes the associated reservation item.
-
-This flow is implemented within the [createOrderFulfillmentWorkflow](https://docs.medusajs.com/references/medusa-workflows/createOrderFulfillmentWorkflow/index.html.md)
-
-![A diagram showcasing how the Inventory Module is used in the order fulfillment flow](https://res.cloudinary.com/dza7lstvk/image/upload/v1709712390/Medusa%20Resources/inventory-order-fulfillment_o9wdxh.jpg)
-
-***
-
-## Order Return
-
-When an item in an order is returned and the associated variant has its `manage_inventory` property set to `true`, the Medusa application increments the `stocked_quantity` of the inventory item's level with the returned quantity.
-
-This flow is implemented within the [confirmReturnReceiveWorkflow](https://docs.medusajs.com/references/medusa-workflows/confirmReturnReceiveWorkflow/index.html.md)
-
-![A diagram showcasing how the Inventory Module is used in the order return flow](https://res.cloudinary.com/dza7lstvk/image/upload/v1709712457/Medusa%20Resources/inventory-order-return_ihftyk.jpg)
-
-### Dismissed Returned Items
-
-If a returned item is considered damaged or is dismissed, its quantity doesn't increment the `stocked_quantity` of the inventory item's level.
-
-
 # Links between Inventory Module and Other Modules
 
 This document showcases the module links defined between the Inventory Module and other Commerce Modules.
@@ -24884,58 +24938,2875 @@ const { data: inventoryLevels } = useQueryGraphStep({
 ```
 
 
-# Order Claim
+# Links between Payment Module and Other Modules
 
-In this document, you’ll learn about order claims.
+This document showcases the module links defined between the Payment Module and other Commerce Modules.
 
-Refer to this [Medusa Admin User Guide](https://docs.medusajs.com/user-guide/orders/claims/index.html.md) to learn how to manage an order's claims using the dashboard.
+## Summary
 
-## What is a Claim?
+The Payment Module has the following links to other modules:
 
-When a customer receives a defective or incorrect item, the merchant can create a claim to refund or replace the item.
-
-The [OrderClaim data model](https://docs.medusajs.com/references/order/models/OrderClaim/index.html.md) represents a claim.
+|First Data Model|Second Data Model|Type|Description|
+|---|---|---|---|
+|Cart|PaymentCollection|Stored - one-to-one|Learn more|
+|Customer|AccountHolder|Stored - many-to-many|Learn more|
+|Order|PaymentCollection|Stored - one-to-many|Learn more|
+|OrderClaim|PaymentCollection|Stored - one-to-many|Learn more|
+|OrderExchange|PaymentCollection|Stored - one-to-many|Learn more|
+|Region|PaymentProvider|Stored - many-to-many|Learn more|
 
 ***
 
-## Claim Type
+## Cart Module
 
-The `Claim` data model has a `type` property whose value indicates the type of the claim:
+The Cart Module provides cart-related features, but not payment processing.
 
-- `refund`: the items are returned, and the customer is refunded.
-- `replace`: the items are returned, and the customer receives new items.
+Medusa defines a link between the `Cart` and `PaymentCollection` data models. A cart has a payment collection which holds all the authorized payment sessions and payments made related to the cart.
+
+Learn more about this relation in [this documentation](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/payment/payment-collection#usage-with-the-cart-module/index.html.md).
+
+### Retrieve with Query
+
+To retrieve the cart associated with the payment collection with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `cart.*` in `fields`:
+
+### query.graph
+
+```ts
+const { data: paymentCollections } = await query.graph({
+  entity: "payment_collection",
+  fields: [
+    "cart.*",
+  ],
+})
+
+// paymentCollections[0].cart
+```
+
+### useQueryGraphStep
+
+```ts
+import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
+
+// ...
+
+const { data: paymentCollections } = useQueryGraphStep({
+  entity: "payment_collection",
+  fields: [
+    "cart.*",
+  ],
+})
+
+// paymentCollections[0].cart
+```
+
+### Manage with Link
+
+To manage the payment collection of a cart, use [Link](https://docs.medusajs.com/docs/learn/fundamentals/module-links/link/index.html.md):
+
+### link.create
+
+```ts
+import { Modules } from "@medusajs/framework/utils"
+
+// ...
+
+await link.create({
+  [Modules.CART]: {
+    cart_id: "cart_123",
+  },
+  [Modules.PAYMENT]: {
+    payment_collection_id: "paycol_123",
+  },
+})
+```
+
+### createRemoteLinkStep
+
+```ts
+import { createRemoteLinkStep } from "@medusajs/medusa/core-flows"
+
+// ...
+
+createRemoteLinkStep({
+  [Modules.CART]: {
+    cart_id: "cart_123",
+  },
+  [Modules.PAYMENT]: {
+    payment_collection_id: "paycol_123",
+  },
+})
+```
 
 ***
 
-## Old and Replacement Items
+## Customer Module
 
-When the claim is created, a return, represented by the [Return data model](https://docs.medusajs.com/references/order/models/Return/index.html.md), is also created to handle receiving the old items from the customer.
+Medusa defines a link between the `Customer` and `AccountHolder` data models, allowing payment providers to save payment methods for a customer, if the payment provider supports it.
 
-Learn more about returns in [this guide](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/order/return/index.html.md).
+This link is available starting from Medusa `v2.5.0`.
 
-If the claim’s type is `replace`, replacement items are represented by the [ClaimItem data model](https://docs.medusajs.com/references/order/models/OrderClaimItem/index.html.md).
+### Retrieve with Query
+
+To retrieve the customer associated with an account holder with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `customer.*` in `fields`:
+
+### query.graph
+
+```ts
+const { data: accountHolders } = await query.graph({
+  entity: "account_holder",
+  fields: [
+    "customer.*",
+  ],
+})
+
+// accountHolders[0].customer
+```
+
+### useQueryGraphStep
+
+```ts
+import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
+
+// ...
+
+const { data: accountHolders } = useQueryGraphStep({
+  entity: "account_holder",
+  fields: [
+    "customer.*",
+  ],
+})
+
+// accountHolders[0].customer
+```
+
+### Manage with Link
+
+To manage the account holders of a customer, use [Link](https://docs.medusajs.com/docs/learn/fundamentals/module-links/link/index.html.md):
+
+### link.create
+
+```ts
+import { Modules } from "@medusajs/framework/utils"
+
+// ...
+
+await link.create({
+  [Modules.CUSTOMER]: {
+    customer_id: "cus_123",
+  },
+  [Modules.PAYMENT]: {
+    account_holder_id: "acchld_123",
+  },
+})
+```
+
+### createRemoteLinkStep
+
+```ts
+import { createRemoteLinkStep } from "@medusajs/medusa/core-flows"
+
+// ...
+
+createRemoteLinkStep({
+  [Modules.CUSTOMER]: {
+    customer_id: "cus_123",
+  },
+  [Modules.PAYMENT]: {
+    account_holder_id: "acchld_123",
+  },
+})
+```
 
 ***
 
-## Claim Shipping Methods
+## Order Module
 
-A claim uses shipping methods to send the replacement items to the customer. These methods are represented by the [OrderShippingMethod data model](https://docs.medusajs.com/references/order/models/OrderShippingMethod/index.html.md).
+An order's payment details are stored in a payment collection. This also applies for claims and exchanges.
 
-The shipping methods for the returned items are associated with the claim's return, as explained in [this guide](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/order/return#return-shipping-methods/index.html.md).
+So, Medusa defines links between the `PaymentCollection` data model and the `Order`, `OrderClaim`, and `OrderExchange` data models.
+
+![A diagram showcasing an example of how data models from the Order and Payment modules are linked](https://res.cloudinary.com/dza7lstvk/image/upload/v1716554726/Medusa%20Resources/order-payment_ubdwok.jpg)
+
+### Retrieve with Query
+
+To retrieve the order of a payment collection with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `order.*` in `fields`:
+
+### query.graph
+
+```ts
+const { data: paymentCollections } = await query.graph({
+  entity: "payment_collection",
+  fields: [
+    "order.*",
+  ],
+})
+
+// paymentCollections[0].order
+```
+
+### useQueryGraphStep
+
+```ts
+import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
+
+// ...
+
+const { data: paymentCollections } = useQueryGraphStep({
+  entity: "payment_collection",
+  fields: [
+    "order.*",
+  ],
+})
+
+// paymentCollections[0].order
+```
+
+### Manage with Link
+
+To manage the payment collections of an order, use [Link](https://docs.medusajs.com/docs/learn/fundamentals/module-links/link/index.html.md):
+
+### link.create
+
+```ts
+import { Modules } from "@medusajs/framework/utils"
+
+// ...
+
+await link.create({
+  [Modules.ORDER]: {
+    order_id: "order_123",
+  },
+  [Modules.PAYMENT]: {
+    payment_collection_id: "paycol_123",
+  },
+})
+```
+
+### createRemoteLinkStep
+
+```ts
+import { Modules } from "@medusajs/framework/utils"
+import { createRemoteLinkStep } from "@medusajs/medusa/core-flows"
+
+// ...
+
+createRemoteLinkStep({
+  [Modules.ORDER]: {
+    order_id: "order_123",
+  },
+  [Modules.PAYMENT]: {
+    payment_collection_id: "paycol_123",
+  },
+})
+```
 
 ***
 
-## Claim Refund
+## Region Module
 
-If the claim’s type is `refund`, the amount to be refunded is stored in the `refund_amount` property.
+You can specify for each region which payment providers are available. The Medusa application defines a link between the `PaymentProvider` and the `Region` data models.
 
-The [Transaction data model](https://docs.medusajs.com/references/order/models/OrderTransaction/index.html.md) represents the refunds made for the claim.
+![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)
+
+This increases the flexibility of your store. For example, you only show during checkout the payment providers associated with the cart's region.
+
+### Retrieve with Query
+
+To retrieve the regions of a payment provider with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `regions.*` in `fields`:
+
+### query.graph
+
+```ts
+const { data: paymentProviders } = await query.graph({
+  entity: "payment_provider",
+  fields: [
+    "regions.*",
+  ],
+})
+
+// paymentProviders[0].regions
+```
+
+### useQueryGraphStep
+
+```ts
+import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
+
+// ...
+
+const { data: paymentProviders } = useQueryGraphStep({
+  entity: "payment_provider",
+  fields: [
+    "regions.*",
+  ],
+})
+
+// paymentProviders[0].regions
+```
+
+### Manage with Link
+
+To manage the payment providers in a region, use [Link](https://docs.medusajs.com/docs/learn/fundamentals/module-links/link/index.html.md):
+
+### link.create
+
+```ts
+import { Modules } from "@medusajs/framework/utils"
+
+// ...
+
+await link.create({
+  [Modules.REGION]: {
+    region_id: "reg_123",
+  },
+  [Modules.PAYMENT]: {
+    payment_provider_id: "pp_stripe_stripe",
+  },
+})
+```
+
+### createRemoteLinkStep
+
+```ts
+import { Modules } from "@medusajs/framework/utils"
+import { createRemoteLinkStep } from "@medusajs/medusa/core-flows"
+
+// ...
+
+createRemoteLinkStep({
+  [Modules.REGION]: {
+    region_id: "reg_123",
+  },
+  [Modules.PAYMENT]: {
+    payment_provider_id: "pp_stripe_stripe",
+  },
+})
+```
+
+
+# Payment 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|-|
 
 ***
 
-## How Claims Impact an Order’s Version
+## providers Option
 
-When a claim is confirmed, the order’s version is incremented.
+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.
+
+
+# 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 Collection
+
+In this document, you’ll learn what a payment collection is and how the Medusa application uses it with the Cart Module.
+
+## What's a Payment Collection?
+
+A payment collection stores payment details related to a resource, such as a cart or an order. It’s represented by the [PaymentCollection data model](https://docs.medusajs.com/references/payment/models/PaymentCollection/index.html.md).
+
+Every purchase or request for payment starts with a payment collection. The collection holds details necessary to complete the payment, including:
+
+- The [payment sessions](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/payment/payment-session/index.html.md) that represents the payment amount to authorize.
+- The [payments](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/payment/payment/index.html.md) that are created when a payment session is authorized. They can be captured and refunded.
+- The [payment providers](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/payment/payment-provider/index.html.md) that handle the processing of each payment session, including the authorization, capture, and refund.
+
+***
+
+## Multiple Payments
+
+The payment collection supports multiple payment sessions and payments.
+
+You can use this to accept payments in increments or split payments across payment providers.
+
+![Diagram showcasing how a payment collection can have multiple payment sessions and payments](https://res.cloudinary.com/dza7lstvk/image/upload/v1711554695/Medusa%20Resources/payment-collection-multiple-payments_oi3z3n.jpg)
+
+***
+
+## Usage with the Cart Module
+
+The Cart Module provides cart management features. However, it doesn’t provide any features related to accepting payment.
+
+During checkout, the Medusa application links a cart to a payment collection, which will be used for further payment processing.
+
+It also implements the payment flow during checkout as explained in [this documentation](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/payment/payment-flow/index.html.md).
+
+![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 Module Provider
+
+In this guide, you’ll learn about the Payment Module Provider and how it's used.
+
+Refer to this [Medusa Admin User Guide](https://docs.medusajs.com/user-guide/settings/regions/index.html.md) to learn how to manage the payment providers available in a region using the dashboard.
+
+***
+
+## What is a Payment Module Provider?
+
+The Payment Module Provider handles payment processing in the Medusa application. It integrates third-party payment services, such as [Stripe](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/payment/payment-provider/stripe/index.html.md).
+
+To authorize a payment amount with a payment provider, a payment session is created and associated with that payment provider. The payment provider is then used to handle the authorization.
+
+After the payment session is authorized, the payment provider is associated with the resulting payment and handles its payment processing, such as to capture or refund payment.
+
+![Diagram showcasing the communication between Medusa, the Payment Module Provider, and the third-party payment provider.](https://res.cloudinary.com/dza7lstvk/image/upload/v1746791374/Medusa%20Resources/payment-provider-service_l4zi6m.jpg)
+
+### List of Payment Module Providers
+
+- [Stripe](https://docs.medusajs.com/commerce-modules/payment/payment-provider/stripe/index.html.md)
+
+### Default Payment Provider
+
+The Payment Module provides a `system` payment provider that acts as a placeholder payment provider.
+
+It doesn’t handle payment processing and delegates that to the merchant. It acts similarly to a cash-on-delivery (COD) payment method.
+
+The identifier of the system payment provider is `pp_system`.
+
+***
+
+## How to Create a Custom Payment Provider?
+
+A payment provider is a module whose main service extends the `AbstractPaymentProvider` imported from `@medusajs/framework/utils`.
+
+The module can have multiple payment provider services, where each is registered as a separate payment provider.
+
+Refer to [this guide](https://docs.medusajs.com/references/payment/provider/index.html.md) on how to create a payment provider for the Payment Module.
+
+After you create a payment provider, you can enable it as a payment provider in a region using the [Medusa Admin dashboard](https://docs.medusajs.com/user-guide/settings/regions/index.html.md).
+
+***
+
+## How are Payment Providers Registered?
+
+### Configure Payment Module's Providers
+
+The Payment Module accepts a `providers` option that allows you to configure the providers registered in your application.
+
+Learn more about this option in the [Module Options](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/payment/module-options/index.html.md) guide.
+
+### Registration on Application Start
+
+When the Medusa application starts, it registers the Payment Module Providers defined in the `providers` option of the Payment Module.
+
+For each Payment Module Provider, the Medusa application finds all payment provider services defined in them to register.
+
+### PaymentProvider Data Model
+
+A registered payment provider is represented by the [PaymentProvider data model](https://docs.medusajs.com/references/payment/models/PaymentProvider/index.html.md) in the Medusa application.
+
+![Diagram showcasing the PaymentProvider data model](https://res.cloudinary.com/dza7lstvk/image/upload/v1746791364/Medusa%20Resources/payment-provider-model_lx91oa.jpg)
+
+This data model is used to reference a service in the Payment Module Provider and determine whether it's installed in the application.
+
+The `PaymentProvider` data model has the following properties:
+
+- `id`: The unique identifier of the Payment Module Provider. The ID's format is `pp_{identifier}_{id}`, where:
+  - `identifier` is the value of the `identifier` property in the Payment Module Provider's service.
+  - `id` is the value of the `id` property of the Payment Module Provider in `medusa-config.ts`.
+- `is_enabled`: A boolean indicating whether the payment provider is enabled.
+
+### How to Remove a Payment Provider?
+
+If you remove a payment provider from the `providers` option, the Medusa application will not remove the associated `PaymentProvider` data model record.
+
+Instead, the Medusa application will set the `is_enabled` property of the `PaymentProvider`'s record to `false`. This allows you to re-enable the payment provider later if needed by adding it back to the `providers` option.
+
+
+# Accept Payment Flow
+
+In this document, you’ll learn how to implement an accept-payment flow using workflows or the Payment Module's main service.
+
+It's highly recommended to use Medusa's workflows to implement this flow. Use the Payment Module's main service for more complex cases.
+
+For a guide on how to implement this flow in the storefront, check out [this guide](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/storefront-development/checkout/payment/index.html.md).
+
+## Flow Overview
+
+![A diagram showcasing the payment flow's steps](https://res.cloudinary.com/dza7lstvk/image/upload/v1711566781/Medusa%20Resources/payment-flow_jblrvw.jpg)
+
+***
+
+## 1. Create a Payment Collection
+
+A payment collection holds all details related to a resource’s payment operations. So, you start off by creating a payment collection.
+
+For example:
+
+### Using Workflow
+
+```ts
+import { createPaymentCollectionForCartWorkflow } from "@medusajs/medusa/core-flows"
+
+// ...
+
+await createPaymentCollectionForCartWorkflow(req.scope)
+  .run({
+    input: {
+      cart_id: "cart_123",
+    },
+  })
+```
+
+### Using Service
+
+```ts
+const paymentCollection =
+  await paymentModuleService.createPaymentCollections({
+    currency_code: "usd",
+    amount: 5000,
+  })
+```
+
+***
+
+## 2. Create Payment Sessions
+
+The payment collection has one or more payment sessions, each being a payment amount to be authorized by a payment provider.
+
+So, after creating the payment collection, create at least one payment session for a provider.
+
+For example:
+
+### Using Workflow
+
+```ts
+import { createPaymentSessionsWorkflow } from "@medusajs/medusa/core-flows"
+
+// ...
+
+const { result: paymentSesion } = await createPaymentSessionsWorkflow(req.scope)
+  .run({
+    input: {
+      payment_collection_id: "paycol_123",
+      provider_id: "stripe",
+    },
+  })
+```
+
+### Using Service
+
+```ts
+const paymentSession =
+  await paymentModuleService.createPaymentSession(
+    paymentCollection.id,
+    {
+      provider_id: "stripe",
+      currency_code: "usd",
+      amount: 5000,
+      data: {
+        // any necessary data for the
+        // payment provider
+      },
+    }
+  )
+```
+
+***
+
+## 3. Authorize Payment Session
+
+Once the customer chooses a payment session, start the authorization process. This may involve some action performed by the third-party payment provider, such as entering a 3DS code.
+
+For example:
+
+### Using Step
+
+```ts
+import { authorizePaymentSessionStep } from "@medusajs/medusa/core-flows"
+
+// ...
+
+authorizePaymentSessionStep({
+  id: "payses_123",
+  context: {},
+})
+```
+
+### Using Service
+
+```ts
+const payment = authorizePaymentSessionStep({
+  id: "payses_123",
+  context: {},
+})
+```
+
+When the payment authorization is successful, a payment is created and returned.
+
+### Handling Additional Action
+
+If you used the `authorizePaymentSessionStep`, you don't need to implement this logic as it's implemented in the step.
+
+If the payment authorization isn’t successful, whether because it requires additional action or for another reason, the method updates the payment session with the new status and throws an error.
+
+In that case, you can catch that error and, if the session's `status` property is `requires_more`, handle the additional action, then retry the authorization.
+
+For example:
+
+```ts
+try {
+  const payment =
+    await paymentModuleService.authorizePaymentSession(
+      paymentSession.id,
+      {}
+    )
+} catch (e) {
+  // retrieve the payment session again
+  const updatedPaymentSession = (
+    await paymentModuleService.listPaymentSessions({
+      id: [paymentSession.id],
+    })
+  )[0]
+
+  if (updatedPaymentSession.status === "requires_more") {
+    // TODO perform required action
+    // TODO authorize payment again.
+  }
+}
+```
+
+***
+
+## 4. Payment Flow Complete
+
+The payment flow is complete once the payment session is authorized and the payment is created.
+
+You can then:
+
+- Capture the payment either using the [capturePaymentWorkflow](https://docs.medusajs.com/references/medusa-workflows/capturePaymentWorkflow/index.html.md) or [capturePayment method](https://docs.medusajs.com/references/payment/capturePayment/index.html.md).
+- Refund captured amounts using the [refundPaymentWorkflow](https://docs.medusajs.com/references/medusa-workflows/refundPaymentWorkflow/index.html.md) or [refundPayment method](https://docs.medusajs.com/references/payment/refundPayment/index.html.md).
+
+Some payment providers allow capturing the payment automatically once it’s authorized. In that case, you don’t need to do it manually.
+
+
+# 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).
+
+
+# Webhook Events
+
+In this document, you’ll learn how the Payment Module supports listening to webhook events.
+
+## What's a Webhook Event?
+
+A webhook event is sent from a third-party payment provider to your application. It indicates a change in a payment’s status.
+
+This is useful in many cases such as when a payment is being processed asynchronously or when a request is interrupted and the payment provider is sending details on the process later.
+
+***
+
+## getWebhookActionAndData Method
+
+The Payment Module’s main service has a [getWebhookActionAndData method](https://docs.medusajs.com/references/payment/getWebhookActionAndData/index.html.md) used to handle incoming webhook events from third-party payment services. The method delegates the handling to the associated payment provider, which returns the event's details.
+
+Medusa implements a webhook listener route at the `/hooks/payment/[identifier]_[provider]` API route, where:
+
+- `[identifier]` is the `identifier` static property defined in the payment provider. For example, `stripe`.
+- `[provider]` is the ID of the provider. For example, `stripe`.
+
+For example, when integrating basic Stripe payments with the [Stripe Module Provider](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/payment/payment-provider/stripe/index.html.md), the webhook listener route is `/hooks/payment/stripe_stripe`. If you're integrating Stripe's Bancontact payments, the webhook listener route is `/hooks/payment/stripe-bancontact_stripe`.
+
+Use that webhook listener in your third-party payment provider's configurations.
+
+![A diagram showcasing the steps of how the getWebhookActionAndData method words](https://res.cloudinary.com/dza7lstvk/image/upload/v1711567415/Medusa%20Resources/payment-webhook_seaocg.jpg)
+
+If the event's details indicate that the payment should be authorized, then the [authorizePaymentSession method of the main service](https://docs.medusajs.com/references/payment/authorizePaymentSession/index.html.md) is executed on the specified payment session.
+
+If the event's details indicate that the payment should be captured, then the [capturePayment method of the main service](https://docs.medusajs.com/references/payment/capturePayment/index.html.md) is executed on the payment of the specified payment session.
+
+### Actions After Webhook Payment Processing
+
+After the payment webhook actions are processed and the payment is authorized or captured, the Medusa application completes the cart associated with the payment's collection if it's not completed yet.
+
+
+# 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.
+
+
+# Pricing Concepts
+
+In this document, you’ll learn about the main concepts in the Pricing Module.
+
+## Price Set
+
+A [PriceSet](https://docs.medusajs.com/references/pricing/models/PriceSet/index.html.md) represents a collection of prices that are linked to a resource (for example, a product or a shipping option).
+
+Each of these prices are represented by the [Price data module](https://docs.medusajs.com/references/pricing/models/Price/index.html.md).
+
+![A diagram showcasing the relation between the price set and price](https://res.cloudinary.com/dza7lstvk/image/upload/v1709648650/Medusa%20Resources/price-set-money-amount_xeees0.jpg)
+
+***
+
+## Price List
+
+A [PriceList](https://docs.medusajs.com/references/pricing/models/PriceList/index.html.md) is a group of prices only enabled if their conditions and rules are satisfied.
+
+A price list has optional `start_date` and `end_date` properties that indicate the date range in which a price list can be applied.
+
+Its associated prices are represented by the `Price` data model.
+
+
+# Prices Calculation
+
+In this document, you'll learn how prices are calculated when you use the [calculatePrices method](https://docs.medusajs.com/references/pricing/calculatePrices/index.html.md) of the Pricing Module's main service.
+
+## calculatePrices Method
+
+The [calculatePrices method](https://docs.medusajs.com/references/pricing/calculatePrices/index.html.md) accepts as parameters the ID of one or more price sets and a context.
+
+It returns a price object with the best matching price for each price set.
+
+### Calculation Context
+
+The calculation context is an optional object passed as a second parameter to the `calculatePrices` method. It accepts rules to restrict the selected prices in the price set.
+
+For example:
+
+```ts
+const price = await pricingModuleService.calculatePrices(
+  { id: [priceSetId] },
+  {
+    context: {
+      currency_code: currencyCode,
+      region_id: "reg_123",
+    },
+  }
+)
+```
+
+In this example, you retrieve the prices in a price set for the specified currency code and region ID.
+
+### Returned Price Object
+
+For each price set, the `calculatePrices` method selects two prices:
+
+- A calculated price: Either a price that belongs to a price list and best matches the specified context, or the same as the original price.
+- An original price, which is either:
+  - The same price as the calculated price if the price list it belongs to is of type `override`;
+  - Or a price that doesn't belong to a price list and best matches the specified context.
+
+Both prices are returned in an object that has the following properties:
+
+- id: (\`string\`) The ID of the price set from which the price was selected.
+- is\_calculated\_price\_price\_list: (\`boolean\`) Whether the calculated price belongs to a price list.
+- calculated\_amount: (\`number\`) The amount of the calculated price, or \`null\` if there isn't a calculated price. This is the amount shown to the customer.
+- is\_original\_price\_price\_list: (\`boolean\`) Whether the original price belongs to a price list.
+- original\_amount: (\`number\`) The amount of the original price, or \`null\` if there isn't an original price. This amount is useful to compare with the \`calculated\_amount\`, such as to check for discounted value.
+- currency\_code: (\`string\`) The currency code of the calculated price, or \`null\` if there isn't a calculated price.
+- is\_calculated\_price\_tax\_inclusive: (\`boolean\`) Whether the calculated price is tax inclusive. Learn more about tax-inclusivity in \[this document]\(../tax-inclusive-pricing/page.mdx)
+- is\_original\_price\_tax\_inclusive: (\`boolean\`) Whether the original price is tax inclusive. Learn more about tax-inclusivity in \[this document]\(../tax-inclusive-pricing/page.mdx)
+- calculated\_price: (\`object\`) The calculated price's price details.
+
+  - id: (\`string\`) The ID of the price.
+
+  - price\_list\_id: (\`string\`) The ID of the associated price list.
+
+  - price\_list\_type: (\`string\`) The price list's type. For example, \`sale\`.
+
+  - min\_quantity: (\`number\`) The price's min quantity condition.
+
+  - max\_quantity: (\`number\`) The price's max quantity condition.
+- original\_price: (\`object\`) The original price's price details.
+
+  - id: (\`string\`) The ID of the price.
+
+  - price\_list\_id: (\`string\`) The ID of the associated price list.
+
+  - price\_list\_type: (\`string\`) The price list's type. For example, \`sale\`.
+
+  - min\_quantity: (\`number\`) The price's min quantity condition.
+
+  - max\_quantity: (\`number\`) The price's max quantity condition.
+
+***
+
+## Examples
+
+Consider the following price set:
+
+```ts
+const priceSet = await pricingModuleService.createPriceSets({
+  prices: [
+    // default price
+    {
+      amount: 500,
+      currency_code: "EUR",
+      rules: {},
+    },
+    // prices with rules
+    {
+      amount: 400,
+      currency_code: "EUR",
+      rules: {
+        region_id: "reg_123",
+      },
+    },
+    {
+      amount: 450,
+      currency_code: "EUR",
+      rules: {
+        city: "krakow",
+      },
+    },
+    {
+      amount: 500,
+      currency_code: "EUR",
+      rules: {
+        city: "warsaw",
+        region_id: "reg_123",
+      },
+    },
+    {
+      amount: 200,
+      currency_code: "EUR",
+      min_quantity: 100,
+    },
+  ],
+})
+```
+
+### Default Price Selection
+
+### Code
+
+```ts
+const price = await pricingModuleService.calculatePrices(
+  { id: [priceSet.id] },
+  {
+    context: {
+      currency_code: "EUR"
+    }
+  }
+)
+```
+
+### Result
+
+### Calculate Prices with Rules
+
+### Code
+
+```ts
+const price = await pricingModuleService.calculatePrices(
+  { id: [priceSet.id] },
+  {
+    context: {
+      currency_code: "EUR",
+      region_id: "reg_123",
+      city: "krakow"
+    }
+  }
+)
+```
+
+### Result
+
+### Tiered Pricing Selection
+
+### Code
+
+```ts
+const price = await pricingModuleService.calculatePrices(
+  { id: [priceSet.id] },
+  {
+    context: {
+      cart: {
+        items: [
+          {
+            id: "item_1",
+            quantity: 200,
+            // assuming the price set belongs to this variant
+            variant_id: "variant_1",
+            // ...
+          }
+        ],
+        // ...
+      }
+    }
+  }
+)
+```
+
+### Result
+
+### Price Selection with Price List
+
+### Code
+
+```ts
+const priceList = pricingModuleService.createPriceLists([{
+  title: "Summer Price List",
+  description: "Price list for summer sale",
+  starts_at: Date.parse("01/10/2023").toString(),
+  ends_at: Date.parse("31/10/2023").toString(),
+  rules: {
+    region_id: ['PL']
+  },
+  type: "sale",
+  prices: [
+    {
+      amount: 400,
+      currency_code: "EUR",
+      price_set_id: priceSet.id,
+    },
+    {
+      amount: 450,
+      currency_code: "EUR",
+      price_set_id: priceSet.id,
+    },
+  ],
+}]);
+
+const price = await pricingModuleService.calculatePrices(
+  { id: [priceSet.id] },
+  {
+    context: {
+      currency_code: "EUR",
+      region_id: "PL",
+      city: "krakow"
+    }
+  }
+)
+```
+
+### Result
+
+
+# Price Tiers and Rules
+
+In this Pricing Module guide, you'll learn about tired prices, price rules for price sets and price lists, and how to add rules to a price.
+
+## Tiered Pricing
+
+Each price, represented by the [Price data model](https://docs.medusajs.com/references/pricing/models/Price/index.html.md), has two optional properties that can be used to create tiered prices:
+
+- `min_quantity`: The minimum quantity that must be in the cart for the price to be applied.
+- `max_quantity`: The maximum quantity that can be in the cart for the price to be applied.
+
+This is useful to set tiered pricing for resources like product variants and shipping options.
+
+For example, you can set a variant's price to:
+
+- `$10` by default.
+- `$8` when the customer adds `10` or more of the variant to the cart.
+- `$6` when the customer adds `20` or more of the variant to the cart.
+
+These price definitions would look like this:
+
+```json title="Example Prices"
+[
+  // default price
+  {
+    "amount": 10,
+    "currency_code": "usd",
+  },
+  {
+    "amount": 8,
+    "currency_code": "usd",
+    "min_quantity": 10,
+    "max_quantity": 19,
+  },
+  {
+    "amount": 6,
+    "currency_code": "usd",
+    "min_quantity": 20,
+  },
+],
+```
+
+### How to Create Tiered Prices?
+
+When you create prices, you can specify a `min_quantity` and `max_quantity` for each price. This allows you to create tiered pricing, where the price changes based on the quantity of items in the cart.
+
+For example:
+
+For most use cases where you're building customizations in the Medusa application, it's highly recommended to use [Medusa's workflows](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/medusa-workflows-reference/index.html.md) rather than using the Pricing Module directly. Medusa's workflows already implement extensive functionalities that you can re-use in your custom flows, with reliable roll-back mechanism.
+
+### Using Medusa Workflows
+
+```ts highlights={tieredPricingHighlights}
+const { result } = await createProductsWorkflow(container)
+  .run({
+    input: {
+      products: [{
+        variants: [{
+          id: "variant_1",
+          prices: [
+            // default price
+            {
+              amount: 10,
+              currency_code: "usd",
+            },
+            {
+              amount: 8,
+              currency_code: "usd",
+              min_quantity: 10,
+              max_quantity: 19,
+            },
+            {
+              amount: 6,
+              currency_code: "usd",
+              min_quantity: 20,
+            },
+          ],
+          // ...
+        }],
+      }],
+      // ...
+    },
+  })
+```
+
+### Using the Pricing Module
+
+```ts
+const priceSet = await pricingModule.addPrices({
+  priceSetId: "pset_1",
+  prices: [
+    // default price
+    {
+      amount: 10,
+      currency_code: "usd",
+    },
+    // tiered prices
+    {
+      amount: 8,
+      currency_code: "usd",
+      min_quantity: 10,
+      max_quantity: 19,
+    },
+    {
+      amount: 6,
+      currency_code: "usd",
+      min_quantity: 20,
+    },
+  ],
+})
+```
+
+In this example, you create a product with a variant whose default price is `$10`. You also add two tiered prices that set the price to `$8` when the quantity is between `10` and `19`, and to `$6` when the quantity is `20` or more.
+
+### How are Tiered Prices 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 the cart's items as a context when choosing the best price to apply.
+
+For example, consider the customer added the `variant_1` product variant (created in the workflow snippet of the [above section](#how-to-create-tiered-prices)) to their cart with a quantity of `15`.
+
+The price calculation mechanism will choose the second price, which is `$8`, because the quantity of `15` is between `10` and `19`.
+
+If there are other rules applied to the price, they may affect the price calculation. Keep reading to learn about other price rules, and refer to the [Price Calculation](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/pricing/price-calculation/index.html.md) guide for more details on the calculation mechanism.
+
+***
+
+## Price Rule
+
+You can also restrict prices by advanced rules, such as a customer's group, zip code, or a cart's total.
+
+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 Create Prices with Rules?
+
+When you create prices, you can specify rules for each price. This allows you to create complex pricing strategies based on different contexts.
+
+For example:
+
+For most use cases where you're building customizations in the Medusa application, it's highly recommended to use [Medusa's workflows](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/medusa-workflows-reference/index.html.md) rather than using the Pricing Module directly. Medusa's workflows already implement extensive functionalities that you can re-use in your custom flows, with reliable roll-back mechanism.
+
+### Using Medusa Workflows
+
+```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,
+            },
+          },
+        },
+      ],
+    }],
+  })
+```
+
+### Using the Pricing Module
+
+```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 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.
+
+### 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.
+
+
+# Links between Pricing Module and Other Modules
+
+This document showcases the module links defined between the Pricing Module and other Commerce Modules.
+
+## Summary
+
+The Pricing Module has the following links to other modules:
+
+|First Data Model|Second Data Model|Type|Description|
+|---|---|---|---|
+|ShippingOption|PriceSet|Stored - one-to-one|Learn more|
+|ProductVariant|PriceSet|Stored - one-to-one|Learn more|
+
+***
+
+## Fulfillment Module
+
+The Fulfillment Module provides fulfillment-related functionalities, including shipping options that the customer chooses from when they place their order. However, it doesn't provide pricing-related functionalities for these options.
+
+Medusa defines a link between the `PriceSet` and `ShippingOption` data models. A shipping option's price is stored as a price set.
+
+![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 shipping option of a price set with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `shipping_option.*` in `fields`:
+
+### query.graph
+
+```ts
+const { data: priceSets } = await query.graph({
+  entity: "price_set",
+  fields: [
+    "shipping_option.*",
+  ],
+})
+
+// priceSets[0].shipping_option
+```
+
+### useQueryGraphStep
+
+```ts
+import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
+
+// ...
+
+const { data: priceSets } = useQueryGraphStep({
+  entity: "price_set",
+  fields: [
+    "shipping_option.*",
+  ],
+})
+
+// priceSets[0].shipping_option
+```
+
+### Manage with Link
+
+To manage the price set of a shipping option, use [Link](https://docs.medusajs.com/docs/learn/fundamentals/module-links/link/index.html.md):
+
+### link.create
+
+```ts
+import { Modules } from "@medusajs/framework/utils"
+
+// ...
+
+await link.create({
+  [Modules.FULFILLMENT]: {
+    shipping_option_id: "so_123",
+  },
+  [Modules.PRICING]: {
+    price_set_id: "pset_123",
+  },
+})
+```
+
+### createRemoteLinkStep
+
+```ts
+import { Modules } from "@medusajs/framework/utils"
+import { createRemoteLinkStep } from "@medusajs/medusa/core-flows"
+
+// ...
+
+createRemoteLinkStep({
+  [Modules.FULFILLMENT]: {
+    shipping_option_id: "so_123",
+  },
+  [Modules.PRICING]: {
+    price_set_id: "pset_123",
+  },
+})
+```
+
+***
+
+## Product Module
+
+The Product Module doesn't store or manage the prices of product variants.
+
+Medusa defines a link between the `ProductVariant` and the `PriceSet`. A product variant’s prices are stored as prices belonging to a price set.
+
+![A diagram showcasing an example of how data models from the Pricing and Product Module are linked. The PriceSet is linked to the ProductVariant of the Product Module.](https://res.cloudinary.com/dza7lstvk/image/upload/v1709651039/Medusa%20Resources/pricing-product_m4xaut.jpg)
+
+So, when you want to add prices for a product variant, you create a price set and add the prices to it.
+
+You can then benefit from adding rules to prices or using the `calculatePrices` method to retrieve the price of a product variant within a specified context.
+
+### Retrieve with Query
+
+To retrieve the variant of a price set with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `variant.*` in `fields`:
+
+### query.graph
+
+```ts
+const { data: priceSets } = await query.graph({
+  entity: "price_set",
+  fields: [
+    "variant.*",
+  ],
+})
+
+// priceSets[0].variant
+```
+
+### useQueryGraphStep
+
+```ts
+import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
+
+// ...
+
+const { data: priceSets } = useQueryGraphStep({
+  entity: "price_set",
+  fields: [
+    "variant.*",
+  ],
+})
+
+// priceSets[0].variant
+```
+
+### Manage with Link
+
+To manage the price set of a variant, use [Link](https://docs.medusajs.com/docs/learn/fundamentals/module-links/link/index.html.md):
+
+### link.create
+
+```ts
+import { Modules } from "@medusajs/framework/utils"
+
+// ...
+
+await link.create({
+  [Modules.PRODUCT]: {
+    variant_id: "variant_123",
+  },
+  [Modules.PRICING]: {
+    price_set_id: "pset_123",
+  },
+})
+```
+
+### createRemoteLinkStep
+
+```ts
+import { Modules } from "@medusajs/framework/utils"
+import { createRemoteLinkStep } from "@medusajs/medusa/core-flows"
+
+// ...
+
+createRemoteLinkStep({
+  [Modules.PRODUCT]: {
+    variant_id: "variant_123",
+  },
+  [Modules.PRICING]: {
+    price_set_id: "pset_123",
+  },
+})
+```
+
+
+# Configure Selling Products
+
+In this guide, you'll learn how to set up and configure your products based on their shipping and inventory requirements, the product type, how you want to sell them, or your commerce ecosystem.
+
+The concepts in this guide are applicable starting from Medusa v2.5.1.
+
+## Scenario
+
+Businesses can have different selling requirements:
+
+1. They may sell physical or digital items.
+2. They may sell items that don't require shipping or inventory management, such as selling digital products, services, or booking appointments.
+3. They may sell items whose inventory is managed by an external system, such as an ERP.
+
+Medusa supports these different selling requirements by allowing you to configure shipping and inventory requirements for products and their variants. This guide explains how these configurations work, then provides examples of setting up different use cases.
+
+***
+
+## Configuring Shipping Requirements
+
+The Medusa application defines a link between the `Product` data model and a [ShippingProfile](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/fulfillment/concepts#shipping-profile/index.html.md) in the [Fulfillment Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/fulfillment/index.html.md), allowing you to associate a product with a shipping profile.
+
+When a product is associated with a shipping profile, its variants require shipping and fulfillment when purchased. This is useful for physical products or digital products that require custom fulfillment.
+
+If a product doesn't have an associated shipping profile, its variants don't require shipping and fulfillment when purchased. This is useful for digital products, for example, that don't require shipping.
+
+### Overriding Shipping Requirements for Variants
+
+A product variant whose inventory is managed by Medusa (its `manage_inventory` property is enabled) has an [inventory item](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/inventory/concepts#inventoryitem/index.html.md). The inventory item has a `requires_shipping` property that can be used to override its shipping requirement. This is useful if the product has an associated shipping profile but you want to disable shipping for a specific variant, or vice versa.
+
+Learn more about product variant's inventory in [this guide](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/product/variant-inventory/index.html.md).
+
+When a product variant is purchased, the Medusa application decides whether the purchased item requires shipping in the following order:
+
+1. The product variant has an inventory item. In this case, the Medusa application uses the inventory item's `requires_shipping` property to determine if the item requires shipping.
+2. If the product variant doesn't have an inventory item, the Medusa application checks whether the product has an associated shipping profile to determine if the item requires shipping.
+
+***
+
+## Use Case Examples
+
+By combining configurations of shipment requirements and inventory management, you can set up your products to support your use case:
+
+|Use Case|Configurations|Example|
+|---|---|---|---|---|
+|Item that's shipped on purchase, and its variant inventory is managed by the Medusa application.||Any stock-kept item (clothing, for example), whose inventory is managed in the Medusa application.|
+|Item that's shipped on purchase, but its variant inventory is managed externally (not by Medusa) or it has infinite stock.||Any stock-kept item (clothing, for example), whose inventory is managed in an ERP or has infinite stock.|
+|Item that's not shipped on purchase, but its variant inventory is managed by Medusa.||Digital products, such as licenses, that don't require shipping but have a limited quantity.|
+|Item that doesn't require shipping and its variant inventory isn't managed by Medusa.|||
+
+
+# Links between Product Module and Other Modules
+
+This document showcases the module links defined between the Product Module and other Commerce Modules.
+
+## Summary
+
+The Product Module has the following links to other modules:
+
+Read-only links are used to query data across modules, but the relations aren't stored in a pivot table in the database.
+
+|First Data Model|Second Data Model|Type|Description|
+|---|---|---|---|
+|LineItem|Product|Read-only - has one|Learn more|
+|Product|ShippingProfile|Stored - many-to-one|Learn more|
+|ProductVariant|InventoryItem|Stored - many-to-many|Learn more|
+|OrderLineItem|Product|Read-only - has one|Learn more|
+|ProductVariant|PriceSet|Stored - one-to-one|Learn more|
+|Product|SalesChannel|Stored - many-to-many|Learn more|
+
+***
+
+## Cart Module
+
+Medusa defines read-only links between:
+
+- The [Cart Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/cart/index.html.md)'s `LineItem` data model and the `Product` data model. Because the link is read-only from the `LineItem`'s side, you can only retrieve the product of a line item, and not the other way around.
+- The `ProductVariant` data model and the [Cart Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/cart/index.html.md)'s `LineItem` data model. Because the link is read-only from the `LineItem`'s side, you can only retrieve the variant of a line item, and not the other way around.
+
+### Retrieve with Query
+
+To retrieve the variant of a line item with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `variant.*` in `fields`:
+
+To retrieve the product, pass `product.*` in `fields`.
+
+### query.graph
+
+```ts
+const { data: lineItems } = await query.graph({
+  entity: "line_item",
+  fields: [
+    "variant.*",
+  ],
+})
+
+// lineItems[0].variant
+```
+
+### useQueryGraphStep
+
+```ts
+import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
+
+// ...
+
+const { data: lineItems } = useQueryGraphStep({
+  entity: "line_item",
+  fields: [
+    "variant.*",
+  ],
+})
+
+// lineItems[0].variant
+```
+
+***
+
+## Fulfillment Module
+
+Medusa defines a link between the `Product` data model and the `ShippingProfile` data model of the Fulfillment Module. Each product must belong to a shipping profile.
+
+This link is introduced in [Medusa v2.5.0](https://github.com/medusajs/medusa/releases/tag/v2.5.0).
+
+### Retrieve with Query
+
+To retrieve the shipping profile of a product with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `shipping_profile.*` in `fields`:
+
+### query.graph
+
+```ts
+const { data: products } = await query.graph({
+  entity: "product",
+  fields: [
+    "shipping_profile.*",
+  ],
+})
+
+// products[0].shipping_profile
+```
+
+### useQueryGraphStep
+
+```ts
+import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
+
+// ...
+
+const { data: products } = useQueryGraphStep({
+  entity: "product",
+  fields: [
+    "shipping_profile.*",
+  ],
+})
+
+// products[0].shipping_profile
+```
+
+### Manage with Link
+
+To manage the shipping profile of a product, use [Link](https://docs.medusajs.com/docs/learn/fundamentals/module-links/link/index.html.md):
+
+### link.create
+
+```ts
+import { Modules } from "@medusajs/framework/utils"
+
+// ...
+
+await link.create({
+  [Modules.PRODUCT]: {
+    product_id: "prod_123",
+  },
+  [Modules.FULFILLMENT]: {
+    shipping_profile_id: "sp_123",
+  },
+})
+```
+
+### createRemoteLinkStep
+
+```ts
+import { Modules } from "@medusajs/framework/utils"
+import { createRemoteLinkStep } from "@medusajs/medusa/core-flows"
+
+// ...
+
+createRemoteLinkStep({
+  [Modules.PRODUCT]: {
+    product_id: "prod_123",
+  },
+  [Modules.FULFILLMENT]: {
+    shipping_profile_id: "sp_123",
+  },
+})
+```
+
+***
+
+## Inventory Module
+
+The Inventory Module provides inventory-management features for any stock-kept item.
+
+Medusa defines a link between the `ProductVariant` and `InventoryItem` data models. Each product variant has different inventory details.
+
+![A diagram showcasing an example of how data models from the Product and Inventory modules are linked.](https://res.cloudinary.com/dza7lstvk/image/upload/v1709652779/Medusa%20Resources/product-inventory_kmjnud.jpg)
+
+When the `manage_inventory` property of a product variant is enabled, you can manage the variant's inventory in different locations through this relation.
+
+Learn more about product variant's inventory management in [this guide](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/product/variant-inventory/index.html.md).
+
+### Retrieve with Query
+
+To retrieve the inventory items of a product variant with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `inventory_items.*` in `fields`:
+
+### query.graph
+
+```ts
+const { data: variants } = await query.graph({
+  entity: "variant",
+  fields: [
+    "inventory_items.*",
+  ],
+})
+
+// variants[0].inventory_items
+```
+
+### useQueryGraphStep
+
+```ts
+import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
+
+// ...
+
+const { data: variants } = useQueryGraphStep({
+  entity: "variant",
+  fields: [
+    "inventory_items.*",
+  ],
+})
+
+// variants[0].inventory_items
+```
+
+### Manage with Link
+
+To manage the inventory items of a variant, use [Link](https://docs.medusajs.com/docs/learn/fundamentals/module-links/link/index.html.md):
+
+### link.create
+
+```ts
+import { Modules } from "@medusajs/framework/utils"
+
+// ...
+
+await link.create({
+  [Modules.PRODUCT]: {
+    variant_id: "variant_123",
+  },
+  [Modules.INVENTORY]: {
+    inventory_item_id: "iitem_123",
+  },
+})
+```
+
+### createRemoteLinkStep
+
+```ts
+import { Modules } from "@medusajs/framework/utils"
+import { createRemoteLinkStep } from "@medusajs/medusa/core-flows"
+
+// ...
+
+createRemoteLinkStep({
+  [Modules.PRODUCT]: {
+    variant_id: "variant_123",
+  },
+  [Modules.INVENTORY]: {
+    inventory_item_id: "iitem_123",
+  },
+})
+```
+
+***
+
+## Order Module
+
+Medusa defines read-only links between:
+
+- the [Order Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/order/index.html.md)'s `OrderLineItem` data model and the `Product` data model. Because the link is read-only from the `OrderLineItem`'s side, you can only retrieve the product of an order line item, and not the other way around.
+- the [Order Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/order/index.html.md)'s `OrderLineItem` data model and the `ProductVariant` data model. Because the link is read-only from the `OrderLineItem`'s side, you can only retrieve the variant of an order line item, and not the other way around.
+
+### Retrieve with Query
+
+To retrieve the variant of a line item with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `variant.*` in `fields`:
+
+To retrieve the product, pass `product.*` in `fields`.
+
+### query.graph
+
+```ts
+const { data: lineItems } = await query.graph({
+  entity: "order_line_item",
+  fields: [
+    "variant.*",
+  ],
+})
+
+// lineItems[0].variant
+```
+
+### useQueryGraphStep
+
+```ts
+import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
+
+// ...
+
+const { data: lineItems } = useQueryGraphStep({
+  entity: "order_line_item",
+  fields: [
+    "variant.*",
+  ],
+})
+
+// lineItems[0].variant
+```
+
+***
+
+## Pricing Module
+
+The Product Module doesn't provide pricing-related features.
+
+Instead, Medusa defines a link between the `ProductVariant` and the `PriceSet` data models. A product variant’s prices are stored belonging to a price set.
+
+![A diagram showcasing an example of how data models from the Pricing and Product Module are linked.](https://res.cloudinary.com/dza7lstvk/image/upload/v1709651464/Medusa%20Resources/product-pricing_vlxsiq.jpg)
+
+So, to add prices for a product variant, create a price set and add the prices to it.
+
+### Retrieve with Query
+
+To retrieve the price set of a variant with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `price_set.*` in `fields`:
+
+### query.graph
+
+```ts
+const { data: variants } = await query.graph({
+  entity: "variant",
+  fields: [
+    "price_set.*",
+  ],
+})
+
+// variants[0].price_set
+```
+
+### useQueryGraphStep
+
+```ts
+import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
+
+// ...
+
+const { data: variants } = useQueryGraphStep({
+  entity: "variant",
+  fields: [
+    "price_set.*",
+  ],
+})
+
+// variants[0].price_set
+```
+
+### Manage with Link
+
+To manage the price set of a variant, use [Link](https://docs.medusajs.com/docs/learn/fundamentals/module-links/link/index.html.md):
+
+### link.create
+
+```ts
+import { Modules } from "@medusajs/framework/utils"
+
+// ...
+
+await link.create({
+  [Modules.PRODUCT]: {
+    variant_id: "variant_123",
+  },
+  [Modules.PRICING]: {
+    price_set_id: "pset_123",
+  },
+})
+```
+
+### createRemoteLinkStep
+
+```ts
+import { Modules } from "@medusajs/framework/utils"
+import { createRemoteLinkStep } from "@medusajs/medusa/core-flows"
+
+// ...
+
+createRemoteLinkStep({
+  [Modules.PRODUCT]: {
+    variant_id: "variant_123",
+  },
+  [Modules.PRICING]: {
+    price_set_id: "pset_123",
+  },
+})
+```
+
+***
+
+## Sales Channel Module
+
+The Sales Channel Module provides functionalities to manage multiple selling channels in your store.
+
+Medusa defines a link between the `Product` and `SalesChannel` data models. A product can have different availability in different sales channels.
+
+![A diagram showcasing an example of how data models from the Product and Sales Channel modules are linked.](https://res.cloudinary.com/dza7lstvk/image/upload/v1709651840/Medusa%20Resources/product-sales-channel_t848ik.jpg)
+
+### Retrieve with Query
+
+To retrieve the sales channels of a product with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `sales_channels.*` in `fields`:
+
+### query.graph
+
+```ts
+const { data: products } = await query.graph({
+  entity: "product",
+  fields: [
+    "sales_channels.*",
+  ],
+})
+
+// products[0].sales_channels
+```
+
+### useQueryGraphStep
+
+```ts
+import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
+
+// ...
+
+const { data: products } = useQueryGraphStep({
+  entity: "product",
+  fields: [
+    "sales_channels.*",
+  ],
+})
+
+// products[0].sales_channels
+```
+
+### Manage with Link
+
+To manage the sales channels of a product, use [Link](https://docs.medusajs.com/docs/learn/fundamentals/module-links/link/index.html.md):
+
+### link.create
+
+```ts
+import { Modules } from "@medusajs/framework/utils"
+
+// ...
+
+await link.create({
+  [Modules.PRODUCT]: {
+    product_id: "prod_123",
+  },
+  [Modules.SALES_CHANNEL]: {
+    sales_channel_id: "sc_123",
+  },
+})
+```
+
+### createRemoteLinkStep
+
+```ts
+import { Modules } from "@medusajs/framework/utils"
+import { createRemoteLinkStep } from "@medusajs/medusa/core-flows"
+
+// ...
+
+createRemoteLinkStep({
+  [Modules.PRODUCT]: {
+    product_id: "prod_123",
+  },
+  [Modules.SALES_CHANNEL]: {
+    sales_channel_id: "sc_123",
+  },
+})
+```
+
+
+# Tax-Inclusive Pricing
+
+In this document, you’ll learn about tax-inclusive pricing and how it's used when calculating prices.
+
+## What is Tax-Inclusive Pricing?
+
+A tax-inclusive price is a price of a resource that includes taxes. Medusa calculates the tax amount from the price rather than adds the amount to it.
+
+For example, if a product’s price is $50, the tax rate is 2%, and tax-inclusive pricing is enabled, then the product's price is $49, and the applied tax amount is $1.
+
+***
+
+## How is Tax-Inclusive Pricing Set?
+
+The [PricePreference data model](https://docs.medusajs.com/references/pricing/models/PricePreference/index.html.md) holds the tax-inclusive setting for a context. It has two properties that indicate the context:
+
+- `attribute`: The name of the attribute to compare against. For example, `region_id` or `currency_code`.
+- `value`: The attribute’s value. For example, `reg_123` or `usd`.
+
+Only `region_id` and `currency_code` are supported as an `attribute` at the moment.
+
+The `is_tax_inclusive` property indicates whether tax-inclusivity is enabled in the specified context.
+
+For example:
+
+```json
+{
+  "attribute": "currency_code",
+  "value": "USD",
+  "is_tax_inclusive": true,
+}
+```
+
+In this example, tax-inclusivity is enabled for the `USD` currency code.
+
+***
+
+## Tax-Inclusive Pricing in Price Calculation
+
+### Tax Context
+
+As mentioned in the [Price Calculation documentation](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/pricing/price-calculation#calculation-context/index.html.md), The `calculatePrices` method accepts as a parameter a calculation context.
+
+To get accurate tax results, pass the `region_id` and / or `currency_code` in the calculation context.
+
+### Returned Tax Properties
+
+The `calculatePrices` method returns two properties related to tax-inclusivity:
+
+Learn more about the returned properties in [this guide](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/pricing/price-calculation#returned-price-object/index.html.md).
+
+- `is_calculated_price_tax_inclusive`: Whether the selected `calculated_price` is tax-inclusive.
+- `is_original_price_tax_inclusive` : Whether the selected `original_price` is tax-inclusive.
+
+A price is considered tax-inclusive if:
+
+1. It belongs to the region or currency code specified in the calculation context;
+2. and the region or currency code has a price preference with `is_tax_inclusive` enabled.
+
+### Tax Context Precedence
+
+A region’s price preference’s `is_tax_inclusive`'s value takes higher precedence in determining whether a price is tax-inclusive if:
+
+- both the `region_id` and `currency_code` are provided in the calculation context;
+- the selected price belongs to the region;
+- and the region has a price preference
+
+
+# Product Variant Inventory
+
+# Product Variant Inventory
+
+In this guide, you'll learn about the inventory management features related to product variants.
+
+Refer to this [Medusa Admin User Guide](https://docs.medusajs.com/user-guide/products/variants#manage-product-variant-inventory/index.html.md) to learn how to manage inventory of product variants.
+
+## Configure Inventory Management of Product Variants
+
+A product variant, represented by the [ProductVariant](https://docs.medusajs.com/references/product/models/ProductVariant/index.html.md) data model, has a `manage_inventory` field that's disabled by default. This field indicates whether you'll manage the inventory quantity of the product variant in the Medusa application. You can also keep `manage_inventory` disabled if you manage the product's inventory in an external system, such as an ERP.
+
+The Product Module doesn't provide inventory-management features. Instead, the Medusa application uses the [Inventory Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/inventory/index.html.md) to manage inventory for products and variants. When `manage_inventory` is disabled, the Medusa application always considers the product variant to be in stock. This is useful if your product's variants aren't items that can be stocked, such as digital products, or they don't have a limited stock quantity.
+
+When `manage_inventory` is enabled, the Medusa application tracks the inventory of the product variant using the [Inventory Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/inventory/index.html.md). For example, when a customer purchases a product variant, the Medusa application decrements the stocked quantity of the product variant.
+
+***
+
+## How the Medusa Application Manages Inventory
+
+When a product variant has `manage_inventory` enabled, the Medusa application creates an inventory item using the [Inventory Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/inventory/index.html.md) and links it to the product variant.
+
+![Diagram showcasing the link between a product variant and its inventory item](https://res.cloudinary.com/dza7lstvk/image/upload/v1709652779/Medusa%20Resources/product-inventory_kmjnud.jpg)
+
+The inventory item has one or more locations, called inventory levels, that represent the stock quantity of the product variant at a specific location. This allows you to manage inventory across multiple warehouses, such as a warehouse in the US and another in Europe.
+
+![Diagram showcasing the link between a variant and its inventory item, and the inventory item's level.](https://res.cloudinary.com/dza7lstvk/image/upload/v1738580390/Medusa%20Resources/variant-inventory-level_bbee2t.jpg)
+
+Learn more about inventory concepts in the [Inventory Module's documentation](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/inventory/concepts/index.html.md).
+
+The Medusa application represents and manages stock locations using the [Stock Location Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/stock-location/index.html.md). It creates a read-only link between the `InventoryLevel` and `StockLocation` data models so that it can retrieve the stock location of an inventory level.
+
+![Diagram showcasing the read-only link between an inventory level and a stock location](https://res.cloudinary.com/dza7lstvk/image/upload/v1738582163/Medusa%20Resources/inventory-level-stock_amxfg5.jpg)
+
+Learn more about the Stock Location Module in the [Stock Location Module's documentation](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/stock-location/concepts/index.html.md).
+
+### Product Inventory in Storefronts
+
+When a storefront sends a request to the Medusa application, it must always pass a [publishable API key](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/sales-channel/publishable-api-keys/index.html.md) in the request header. This API key specifies the sales channels, available through the [Sales Channel Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/sales-channel/index.html.md), of the storefront.
+
+The Medusa application links sales channels to stock locations, indicating the locations available for a specific sales channel. So, all inventory-related operations are scoped by the sales channel and its associated stock locations.
+
+For example, the availability of a product variant is determined by the `stocked_quantity` of its inventory level at the stock location linked to the storefront's sales channel.
+
+![Diagram showcasing the overall relations between inventory, stock location, and sales channel concepts](https://res.cloudinary.com/dza7lstvk/image/upload/v1738582163/Medusa%20Resources/inventory-stock-sales_fknoxw.jpg)
+
+***
+
+## Variant Back Orders
+
+Product variants have an `allow_backorder` field that's disabled by default. When enabled, the Medusa application allows customers to purchase the product variant even when it's out of stock. Use this when your product variant is available through on-demand or pre-order purchase.
+
+You can also allow customers to subscribe to restock notifications of a product variant as explained in [this guide](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/recipes/commerce-automation/restock-notification/index.html.md).
+
+***
+
+## Additional Resources
+
+The following guides provide more details on inventory management in the Medusa application:
+
+- [Inventory Kits in the Inventory Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/inventory/inventory-kit/index.html.md): Learn how you can implement bundled or multi-part products through the Inventory Module.
+- [Retrieve Product Variant Inventory Quantity](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/product/guides/variant-inventory/index.html.md): Learn how to retrieve the available inventory quantity of a product variant.
+- [Configure Selling Products](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/product/selling-products/index.html.md): Learn how to use inventory management to support different use cases when selling products.
+- [Inventory in Flows](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/inventory/inventory-in-flows/index.html.md): Learn how Medusa utilizes inventory management in different flows.
+- [Storefront guide: how to retrieve a product variant's inventory details](https://docs.medusajs.com/resources/storefront-development/products/inventory/index.html.md).
+
+
+# Promotion Actions
+
+In this document, you’ll learn about promotion actions and how they’re computed using the [computeActions method](https://docs.medusajs.com/references/promotion/computeActions/index.html.md).
+
+## computeActions Method
+
+The Promotion Module's main service has a [computeActions method](https://docs.medusajs.com/references/promotion/computeActions/index.html.md) that returns an array of actions to perform on a cart when one or more promotions are applied.
+
+Actions inform you what adjustment must be made to a cart item or shipping method. Each action is an object having the `action` property indicating the type of action.
+
+***
+
+## Action Types
+
+### `addItemAdjustment` Action
+
+The `addItemAdjustment` action indicates that an adjustment must be made to an item. For example, removing $5 off its amount.
+
+This action has the following format:
+
+```ts
+export interface AddItemAdjustmentAction {
+  action: "addItemAdjustment"
+  item_id: string
+  amount: number
+  code: string
+  description?: string
+}
+```
+
+This action means that a new record should be created of the `LineItemAdjustment` data model in the Cart Module, or `OrderLineItemAdjustment` data model in the Order Module.
+
+Refer to [this reference](https://docs.medusajs.com/references/promotion/interfaces/promotion.AddItemAdjustmentAction/index.html.md) for details on the object’s properties.
+
+### `removeItemAdjustment` Action
+
+The `removeItemAdjustment` action indicates that an adjustment must be removed from a line item. For example, remove the $5 discount.
+
+The `computeActions` method accepts any previous item adjustments in the `items` property of the second parameter.
+
+This action has the following format:
+
+```ts
+export interface RemoveItemAdjustmentAction {
+  action: "removeItemAdjustment"
+  adjustment_id: string
+  description?: string
+  code: string
+}
+```
+
+This action means that a new record should be removed of the `LineItemAdjustment` (or `OrderLineItemAdjustment`) with the specified ID in the `adjustment_id` property.
+
+Refer to [this reference](https://docs.medusajs.com/references/promotion/interfaces/promotion.RemoveItemAdjustmentAction/index.html.md) for details on the object’s properties.
+
+### `addShippingMethodAdjustment` Action
+
+The `addShippingMethodAdjustment` action indicates that an adjustment must be made on a shipping method. For example, make the shipping method free.
+
+This action has the following format:
+
+```ts
+export interface AddShippingMethodAdjustment {
+  action: "addShippingMethodAdjustment"
+  shipping_method_id: string
+  amount: number
+  code: string
+  description?: string
+}
+```
+
+This action means that a new record should be created of the `ShippingMethodAdjustment` data model in the Cart Module, or `OrderShippingMethodAdjustment` data model in the Order Module.
+
+Refer to [this reference](https://docs.medusajs.com/references/promotion/interfaces/promotion.AddShippingMethodAdjustment/index.html.md) for details on the object’s properties.
+
+### `removeShippingMethodAdjustment` Action
+
+The `removeShippingMethodAdjustment` action indicates that an adjustment must be removed from a shipping method. For example, remove the free shipping discount.
+
+The `computeActions` method accepts any previous shipping method adjustments in the `shipping_methods` property of the second parameter.
+
+This action has the following format:
+
+```ts
+export interface RemoveShippingMethodAdjustment {
+  action: "removeShippingMethodAdjustment"
+  adjustment_id: string
+  code: string
+}
+```
+
+When the Medusa application receives this action type, it removes the `ShippingMethodAdjustment` (or `OrderShippingMethodAdjustment`) with the specified ID in the `adjustment_id` property.
+
+Refer to [this reference](https://docs.medusajs.com/references/promotion/interfaces/promotion.RemoveShippingMethodAdjustment/index.html.md) for details on the object’s properties.
+
+### `campaignBudgetExceeded` Action
+
+When the `campaignBudgetExceeded` action is returned, the promotions within a campaign can no longer be used as the campaign budget has been exceeded.
+
+This action has the following format:
+
+```ts
+export interface CampaignBudgetExceededAction {
+  action: "campaignBudgetExceeded"
+  code: string
+}
+```
+
+Refer to [this reference](https://docs.medusajs.com/references/promotion/interfaces/promotion.CampaignBudgetExceededAction/index.html.md) for details on the object’s properties.
+
+
+# Application Method
+
+In this document, you'll learn what an application method is.
+
+## What is an Application Method?
+
+The [ApplicationMethod data model](https://docs.medusajs.com/references/promotion/models/ApplicationMethod/index.html.md) defines how a promotion is applied:
+
+|Property|Purpose|
+|---|---|
+|\`type\`|Does the promotion discount a fixed amount or a percentage?|
+|\`target\_type\`|Is the promotion applied on a cart item, shipping method, or the entire order?|
+|\`allocation\`|Is the discounted amount applied on each item or split between the applicable items?|
+
+## Target Promotion Rules
+
+When the promotion is applied to a cart item or a shipping method, you can restrict which items/shipping methods the promotion is applied to.
+
+The `ApplicationMethod` data model has a collection of `PromotionRule` records to restrict which items or shipping methods the promotion applies to. The `target_rules` property represents this relation.
+
+![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.
+
+
+# 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.
+
+## Summary
+
+The Promotion Module has the following links to other modules:
+
+Read-only links are used to query data across modules, but the relations aren't stored in a pivot table in the database.
+
+|First Data Model|Second Data Model|Type|Description|
+|---|---|---|---|
+|Cart|Promotion|Stored - many-to-many|Learn more|
+|LineItemAdjustment|Promotion|Read-only - has one|Learn more|
+|Order|Promotion|Stored - many-to-many|Learn more|
+
+***
+
+## Cart Module
+
+A promotion can be applied on line items and shipping methods of a cart. Medusa defines a link between the `Cart` and `Promotion` data models.
+
+![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",
+  },
+})
+```
+
+
+# Links between Region Module and Other Modules
+
+This document showcases the module links defined between the Region Module and other Commerce Modules.
+
+## Summary
+
+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|
+|---|---|---|---|
+|Cart|Region|Read-only - has one|Learn more|
+|Order|Region|Read-only - has one|Learn more|
+|Region|PaymentProvider|Stored - many-to-many|Learn more|
+
+***
+
+## 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.
+
+### 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`:
+
+### query.graph
+
+```ts
+const { data: carts } = await query.graph({
+  entity: "cart",
+  fields: [
+    "region.*",
+  ],
+})
+
+// carts[0].region
+```
+
+### useQueryGraphStep
+
+```ts
+import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
+
+// ...
+
+const { data: carts } = useQueryGraphStep({
+  entity: "cart",
+  fields: [
+    "region.*",
+  ],
+})
+
+// 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
+```
+
+### Manage with Link
+
+To manage the payment providers in a region, use [Link](https://docs.medusajs.com/docs/learn/fundamentals/module-links/link/index.html.md):
+
+### link.create
+
+```ts
+import { Modules } from "@medusajs/framework/utils"
+
+// ...
+
+await link.create({
+  [Modules.REGION]: {
+    region_id: "reg_123",
+  },
+  [Modules.PAYMENT]: {
+    payment_provider_id: "pp_stripe_stripe",
+  },
+})
+```
+
+### createRemoteLinkStep
+
+```ts
+import { Modules } from "@medusajs/framework/utils"
+import { createRemoteLinkStep } from "@medusajs/medusa/core-flows"
+
+// ...
+
+createRemoteLinkStep({
+  [Modules.REGION]: {
+    region_id: "reg_123",
+  },
+  [Modules.PAYMENT]: {
+    payment_provider_id: "pp_stripe_stripe",
+  },
+})
+```
 
 
 # Order Concepts
@@ -25568,59 +28439,6 @@ const { data: orders } = useQueryGraphStep({
 ```
 
 
-# Order Exchange
-
-In this document, you’ll learn about order exchanges.
-
-Refer to this [Medusa Admin User Guide](https://docs.medusajs.com/user-guide/orders/exchanges/index.html.md) to learn how to manage an order's exchanges using the dashboard.
-
-## What is an Exchange?
-
-An exchange is the replacement of an item that the customer ordered with another.
-
-A merchant creates the exchange, specifying the items to be replaced and the new items to be sent.
-
-The [OrderExchange data model](https://docs.medusajs.com/references/order/models/OrderExchange/index.html.md) represents an exchange.
-
-***
-
-## Returned and New Items
-
-When the exchange is created, a return, represented by the [Return data model](https://docs.medusajs.com/references/order/models/Return/index.html.md), is created to handle receiving the items back from the customer.
-
-Learn more about returns in [this guide](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/order/return/index.html.md).
-
-The [OrderExchangeItem data model](https://docs.medusajs.com/references/order/models/OrderExchangeItem/index.html.md) represents the new items to be sent to the customer.
-
-***
-
-## Exchange Shipping Methods
-
-An exchange has shipping methods used to send the new items to the customer. They’re represented by the [OrderShippingMethod data model](https://docs.medusajs.com/references/order/models/OrderShippingMethod/index.html.md).
-
-The shipping methods for the returned items are associated with the exchange's return, as explained in [this guide](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/order/return#return-shipping-methods/index.html.md).
-
-***
-
-## Exchange Payment
-
-The `Exchange` data model has a `difference_due` property that stores the outstanding amount.
-
-|Condition|Result|
-|---|---|---|
-|\`difference\_due \< 0\`|Merchant owes the customer a refund of the |
-|\`difference\_due > 0\`|Merchant requires additional payment from the customer of the |
-|\`difference\_due = 0\`|No payment processing is required.|
-
-Any payment or refund made is stored in the [Transaction data model](https://docs.medusajs.com/references/order/models/OrderTransaction/index.html.md).
-
-***
-
-## How Exchanges Impact an Order’s Version
-
-When an exchange is confirmed, the order’s version is incremented.
-
-
 # Order Change
 
 In this document, you'll learn about the Order Change data model and possible actions in it.
@@ -25660,67 +28478,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 Return
-
-In this document, you’ll learn about order returns.
-
-Refer to this [Medusa Admin User Guide](https://docs.medusajs.com/user-guide/orders/returns/index.html.md) to learn how to manage an order's returns using the dashboard.
-
-## What is a Return?
-
-A return is the return of items delivered from the customer back to the merchant. It is represented by the [Return data model](https://docs.medusajs.com/references/order/models/Return/index.html.md).
-
-A return is requested either by the customer from the storefront, or the merchant from the admin. Medusa supports an automated Return Merchandise Authorization (RMA) flow.
-
-![Diagram showcasing the automated RMA flow.](https://res.cloudinary.com/dza7lstvk/image/upload/v1719578128/Medusa%20Resources/return-rma_pzprwq.jpg)
-
-Once the merchant receives the returned items, they mark the return as received.
-
-***
-
-## Returned Items
-
-The items to be returned are represented by the [ReturnItem data model](references/order/models/ReturnItem).
-
-The `ReturnItem` model has two properties storing the item's quantity:
-
-1. `received_quantity`: The quantity of the item that's received and can be added to the item's inventory quantity.
-2. `damaged_quantity`: The quantity of the item that's damaged, meaning it can't be sold again or added to the item's inventory quantity.
-
-***
-
-## Return Shipping Methods
-
-A return has shipping methods used to return the items to the merchant. The shipping methods are represented by the [OrderShippingMethod data model](references/order/models/OrderShippingMethod).
-
-In the Medusa application, the shipping method for a return is created only from a shipping option, provided by the Fulfillment Module, that has the rule `is_return` enabled.
-
-***
-
-## Refund Payment
-
-The `refund_amount` property of the `Return` data model holds the amount a merchant must refund the customer.
-
-The [OrderTransaction data model](references/order/models/OrderTransaction) represents the refunds made for the return.
-
-***
-
-## Returns in Exchanges and Claims
-
-When a merchant creates an exchange or a claim, it includes returning items from the customer.
-
-The `Return` data model also represents the return of these items. In this case, the return is associated with the exchange or claim it was created for.
-
-***
-
-## How Returns Impact an Order’s Version
-
-The order’s version is incremented when:
-
-1. A return is requested.
-2. A return is marked as received.
-
-
 # Order Versioning
 
 In this document, you’ll learn how an order and its details are versioned.
@@ -25950,846 +28707,183 @@ The `OrderTransaction` data model has two properties that determine which data m
 - `reference_id`: indicates the ID of the record in the table. For example, `pay_123`.
 
 
-# Pricing Concepts
+# Order Return
 
-In this document, you’ll learn about the main concepts in the Pricing Module.
+In this document, you’ll learn about order returns.
 
-## Price Set
+Refer to this [Medusa Admin User Guide](https://docs.medusajs.com/user-guide/orders/returns/index.html.md) to learn how to manage an order's returns using the dashboard.
 
-A [PriceSet](https://docs.medusajs.com/references/pricing/models/PriceSet/index.html.md) represents a collection of prices that are linked to a resource (for example, a product or a shipping option).
+## What is a Return?
 
-Each of these prices are represented by the [Price data module](https://docs.medusajs.com/references/pricing/models/Price/index.html.md).
+A return is the return of items delivered from the customer back to the merchant. It is represented by the [Return data model](https://docs.medusajs.com/references/order/models/Return/index.html.md).
 
-![A diagram showcasing the relation between the price set and price](https://res.cloudinary.com/dza7lstvk/image/upload/v1709648650/Medusa%20Resources/price-set-money-amount_xeees0.jpg)
+A return is requested either by the customer from the storefront, or the merchant from the admin. Medusa supports an automated Return Merchandise Authorization (RMA) flow.
+
+![Diagram showcasing the automated RMA flow.](https://res.cloudinary.com/dza7lstvk/image/upload/v1719578128/Medusa%20Resources/return-rma_pzprwq.jpg)
+
+Once the merchant receives the returned items, they mark the return as received.
 
 ***
 
-## Price List
+## Returned Items
 
-A [PriceList](https://docs.medusajs.com/references/pricing/models/PriceList/index.html.md) is a group of prices only enabled if their conditions and rules are satisfied.
+The items to be returned are represented by the [ReturnItem data model](references/order/models/ReturnItem).
 
-A price list has optional `start_date` and `end_date` properties that indicate the date range in which a price list can be applied.
+The `ReturnItem` model has two properties storing the item's quantity:
 
-Its associated prices are represented by the `Price` data model.
-
-
-# Links between Pricing Module and Other Modules
-
-This document showcases the module links defined between the Pricing Module and other Commerce Modules.
-
-## Summary
-
-The Pricing Module has the following links to other modules:
-
-|First Data Model|Second Data Model|Type|Description|
-|---|---|---|---|
-|ShippingOption|PriceSet|Stored - one-to-one|Learn more|
-|ProductVariant|PriceSet|Stored - one-to-one|Learn more|
+1. `received_quantity`: The quantity of the item that's received and can be added to the item's inventory quantity.
+2. `damaged_quantity`: The quantity of the item that's damaged, meaning it can't be sold again or added to the item's inventory quantity.
 
 ***
 
-## Fulfillment Module
+## Return Shipping Methods
 
-The Fulfillment Module provides fulfillment-related functionalities, including shipping options that the customer chooses from when they place their order. However, it doesn't provide pricing-related functionalities for these options.
+A return has shipping methods used to return the items to the merchant. The shipping methods are represented by the [OrderShippingMethod data model](references/order/models/OrderShippingMethod).
 
-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 shipping option of a price set with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `shipping_option.*` in `fields`:
-
-### query.graph
-
-```ts
-const { data: priceSets } = await query.graph({
-  entity: "price_set",
-  fields: [
-    "shipping_option.*",
-  ],
-})
-
-// priceSets[0].shipping_option
-```
-
-### useQueryGraphStep
-
-```ts
-import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
-
-// ...
-
-const { data: priceSets } = useQueryGraphStep({
-  entity: "price_set",
-  fields: [
-    "shipping_option.*",
-  ],
-})
-
-// priceSets[0].shipping_option
-```
-
-### Manage with Link
-
-To manage the price set of a shipping option, use [Link](https://docs.medusajs.com/docs/learn/fundamentals/module-links/link/index.html.md):
-
-### link.create
-
-```ts
-import { Modules } from "@medusajs/framework/utils"
-
-// ...
-
-await link.create({
-  [Modules.FULFILLMENT]: {
-    shipping_option_id: "so_123",
-  },
-  [Modules.PRICING]: {
-    price_set_id: "pset_123",
-  },
-})
-```
-
-### createRemoteLinkStep
-
-```ts
-import { Modules } from "@medusajs/framework/utils"
-import { createRemoteLinkStep } from "@medusajs/medusa/core-flows"
-
-// ...
-
-createRemoteLinkStep({
-  [Modules.FULFILLMENT]: {
-    shipping_option_id: "so_123",
-  },
-  [Modules.PRICING]: {
-    price_set_id: "pset_123",
-  },
-})
-```
+In the Medusa application, the shipping method for a return is created only from a shipping option, provided by the Fulfillment Module, that has the rule `is_return` enabled.
 
 ***
 
-## Product Module
+## Refund Payment
 
-The Product Module doesn't store or manage the prices of product variants.
+The `refund_amount` property of the `Return` data model holds the amount a merchant must refund the customer.
 
-Medusa defines a link between the `ProductVariant` and the `PriceSet`. A product variant’s prices are stored as prices belonging to a price set.
-
-![A diagram showcasing an example of how data models from the Pricing and Product Module are linked. The PriceSet is linked to the ProductVariant of the Product Module.](https://res.cloudinary.com/dza7lstvk/image/upload/v1709651039/Medusa%20Resources/pricing-product_m4xaut.jpg)
-
-So, when you want to add prices for a product variant, you create a price set and add the prices to it.
-
-You can then benefit from adding rules to prices or using the `calculatePrices` method to retrieve the price of a product variant within a specified context.
-
-### Retrieve with Query
-
-To retrieve the variant of a price set with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `variant.*` in `fields`:
-
-### query.graph
-
-```ts
-const { data: priceSets } = await query.graph({
-  entity: "price_set",
-  fields: [
-    "variant.*",
-  ],
-})
-
-// priceSets[0].variant
-```
-
-### useQueryGraphStep
-
-```ts
-import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
-
-// ...
-
-const { data: priceSets } = useQueryGraphStep({
-  entity: "price_set",
-  fields: [
-    "variant.*",
-  ],
-})
-
-// priceSets[0].variant
-```
-
-### Manage with Link
-
-To manage the price set of a variant, use [Link](https://docs.medusajs.com/docs/learn/fundamentals/module-links/link/index.html.md):
-
-### link.create
-
-```ts
-import { Modules } from "@medusajs/framework/utils"
-
-// ...
-
-await link.create({
-  [Modules.PRODUCT]: {
-    variant_id: "variant_123",
-  },
-  [Modules.PRICING]: {
-    price_set_id: "pset_123",
-  },
-})
-```
-
-### createRemoteLinkStep
-
-```ts
-import { Modules } from "@medusajs/framework/utils"
-import { createRemoteLinkStep } from "@medusajs/medusa/core-flows"
-
-// ...
-
-createRemoteLinkStep({
-  [Modules.PRODUCT]: {
-    variant_id: "variant_123",
-  },
-  [Modules.PRICING]: {
-    price_set_id: "pset_123",
-  },
-})
-```
-
-
-# Prices Calculation
-
-In this document, you'll learn how prices are calculated when you use the [calculatePrices method](https://docs.medusajs.com/references/pricing/calculatePrices/index.html.md) of the Pricing Module's main service.
-
-## calculatePrices Method
-
-The [calculatePrices method](https://docs.medusajs.com/references/pricing/calculatePrices/index.html.md) accepts as parameters the ID of one or more price sets and a context.
-
-It returns a price object with the best matching price for each price set.
-
-### Calculation Context
-
-The calculation context is an optional object passed as a second parameter to the `calculatePrices` method. It accepts rules to restrict the selected prices in the price set.
-
-For example:
-
-```ts
-const price = await pricingModuleService.calculatePrices(
-  { id: [priceSetId] },
-  {
-    context: {
-      currency_code: currencyCode,
-      region_id: "reg_123",
-    },
-  }
-)
-```
-
-In this example, you retrieve the prices in a price set for the specified currency code and region ID.
-
-### Returned Price Object
-
-For each price set, the `calculatePrices` method selects two prices:
-
-- A calculated price: Either a price that belongs to a price list and best matches the specified context, or the same as the original price.
-- An original price, which is either:
-  - The same price as the calculated price if the price list it belongs to is of type `override`;
-  - Or a price that doesn't belong to a price list and best matches the specified context.
-
-Both prices are returned in an object that has the following properties:
-
-- id: (\`string\`) The ID of the price set from which the price was selected.
-- is\_calculated\_price\_price\_list: (\`boolean\`) Whether the calculated price belongs to a price list.
-- calculated\_amount: (\`number\`) The amount of the calculated price, or \`null\` if there isn't a calculated price. This is the amount shown to the customer.
-- is\_original\_price\_price\_list: (\`boolean\`) Whether the original price belongs to a price list.
-- original\_amount: (\`number\`) The amount of the original price, or \`null\` if there isn't an original price. This amount is useful to compare with the \`calculated\_amount\`, such as to check for discounted value.
-- currency\_code: (\`string\`) The currency code of the calculated price, or \`null\` if there isn't a calculated price.
-- is\_calculated\_price\_tax\_inclusive: (\`boolean\`) Whether the calculated price is tax inclusive. Learn more about tax-inclusivity in \[this document]\(../tax-inclusive-pricing/page.mdx)
-- is\_original\_price\_tax\_inclusive: (\`boolean\`) Whether the original price is tax inclusive. Learn more about tax-inclusivity in \[this document]\(../tax-inclusive-pricing/page.mdx)
-- calculated\_price: (\`object\`) The calculated price's price details.
-
-  - id: (\`string\`) The ID of the price.
-
-  - price\_list\_id: (\`string\`) The ID of the associated price list.
-
-  - price\_list\_type: (\`string\`) The price list's type. For example, \`sale\`.
-
-  - min\_quantity: (\`number\`) The price's min quantity condition.
-
-  - max\_quantity: (\`number\`) The price's max quantity condition.
-- original\_price: (\`object\`) The original price's price details.
-
-  - id: (\`string\`) The ID of the price.
-
-  - price\_list\_id: (\`string\`) The ID of the associated price list.
-
-  - price\_list\_type: (\`string\`) The price list's type. For example, \`sale\`.
-
-  - min\_quantity: (\`number\`) The price's min quantity condition.
-
-  - max\_quantity: (\`number\`) The price's max quantity condition.
+The [OrderTransaction data model](references/order/models/OrderTransaction) represents the refunds made for the return.
 
 ***
 
-## Examples
+## Returns in Exchanges and Claims
 
-Consider the following price set:
+When a merchant creates an exchange or a claim, it includes returning items from the customer.
 
-```ts
-const priceSet = await pricingModuleService.createPriceSets({
-  prices: [
-    // default price
-    {
-      amount: 500,
-      currency_code: "EUR",
-      rules: {},
-    },
-    // prices with rules
-    {
-      amount: 400,
-      currency_code: "EUR",
-      rules: {
-        region_id: "reg_123",
-      },
-    },
-    {
-      amount: 450,
-      currency_code: "EUR",
-      rules: {
-        city: "krakow",
-      },
-    },
-    {
-      amount: 500,
-      currency_code: "EUR",
-      rules: {
-        city: "warsaw",
-        region_id: "reg_123",
-      },
-    },
-    {
-      amount: 200,
-      currency_code: "EUR",
-      min_quantity: 100,
-    },
-  ],
-})
-```
-
-### Default Price Selection
-
-### Code
-
-```ts
-const price = await pricingModuleService.calculatePrices(
-  { id: [priceSet.id] },
-  {
-    context: {
-      currency_code: "EUR"
-    }
-  }
-)
-```
-
-### Result
-
-### Calculate Prices with Rules
-
-### Code
-
-```ts
-const price = await pricingModuleService.calculatePrices(
-  { id: [priceSet.id] },
-  {
-    context: {
-      currency_code: "EUR",
-      region_id: "reg_123",
-      city: "krakow"
-    }
-  }
-)
-```
-
-### Result
-
-### Tiered Pricing Selection
-
-### Code
-
-```ts
-const price = await pricingModuleService.calculatePrices(
-  { id: [priceSet.id] },
-  {
-    context: {
-      cart: {
-        items: [
-          {
-            id: "item_1",
-            quantity: 200,
-            // assuming the price set belongs to this variant
-            variant_id: "variant_1",
-            // ...
-          }
-        ],
-        // ...
-      }
-    }
-  }
-)
-```
-
-### Result
-
-### Price Selection with Price List
-
-### Code
-
-```ts
-const priceList = pricingModuleService.createPriceLists([{
-  title: "Summer Price List",
-  description: "Price list for summer sale",
-  starts_at: Date.parse("01/10/2023").toString(),
-  ends_at: Date.parse("31/10/2023").toString(),
-  rules: {
-    region_id: ['PL']
-  },
-  type: "sale",
-  prices: [
-    {
-      amount: 400,
-      currency_code: "EUR",
-      price_set_id: priceSet.id,
-    },
-    {
-      amount: 450,
-      currency_code: "EUR",
-      price_set_id: priceSet.id,
-    },
-  ],
-}]);
-
-const price = await pricingModuleService.calculatePrices(
-  { id: [priceSet.id] },
-  {
-    context: {
-      currency_code: "EUR",
-      region_id: "PL",
-      city: "krakow"
-    }
-  }
-)
-```
-
-### Result
-
-
-# Price Tiers and Rules
-
-In this Pricing Module guide, you'll learn about tired prices, price rules for price sets and price lists, and how to add rules to a price.
-
-## Tiered Pricing
-
-Each price, represented by the [Price data model](https://docs.medusajs.com/references/pricing/models/Price/index.html.md), has two optional properties that can be used to create tiered prices:
-
-- `min_quantity`: The minimum quantity that must be in the cart for the price to be applied.
-- `max_quantity`: The maximum quantity that can be in the cart for the price to be applied.
-
-This is useful to set tiered pricing for resources like product variants and shipping options.
-
-For example, you can set a variant's price to:
-
-- `$10` by default.
-- `$8` when the customer adds `10` or more of the variant to the cart.
-- `$6` when the customer adds `20` or more of the variant to the cart.
-
-These price definitions would look like this:
-
-```json title="Example Prices"
-[
-  // default price
-  {
-    "amount": 10,
-    "currency_code": "usd",
-  },
-  {
-    "amount": 8,
-    "currency_code": "usd",
-    "min_quantity": 10,
-    "max_quantity": 19,
-  },
-  {
-    "amount": 6,
-    "currency_code": "usd",
-    "min_quantity": 20,
-  },
-],
-```
-
-### How to Create Tiered Prices?
-
-When you create prices, you can specify a `min_quantity` and `max_quantity` for each price. This allows you to create tiered pricing, where the price changes based on the quantity of items in the cart.
-
-For example:
-
-For most use cases where you're building customizations in the Medusa application, it's highly recommended to use [Medusa's workflows](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/medusa-workflows-reference/index.html.md) rather than using the Pricing Module directly. Medusa's workflows already implement extensive functionalities that you can re-use in your custom flows, with reliable roll-back mechanism.
-
-### Using Medusa Workflows
-
-```ts highlights={tieredPricingHighlights}
-const { result } = await createProductsWorkflow(container)
-  .run({
-    input: {
-      products: [{
-        variants: [{
-          id: "variant_1",
-          prices: [
-            // default price
-            {
-              amount: 10,
-              currency_code: "usd",
-            },
-            {
-              amount: 8,
-              currency_code: "usd",
-              min_quantity: 10,
-              max_quantity: 19,
-            },
-            {
-              amount: 6,
-              currency_code: "usd",
-              min_quantity: 20,
-            },
-          ],
-          // ...
-        }],
-      }],
-      // ...
-    },
-  })
-```
-
-### Using the Pricing Module
-
-```ts
-const priceSet = await pricingModule.addPrices({
-  priceSetId: "pset_1",
-  prices: [
-    // default price
-    {
-      amount: 10,
-      currency_code: "usd",
-    },
-    // tiered prices
-    {
-      amount: 8,
-      currency_code: "usd",
-      min_quantity: 10,
-      max_quantity: 19,
-    },
-    {
-      amount: 6,
-      currency_code: "usd",
-      min_quantity: 20,
-    },
-  ],
-})
-```
-
-In this example, you create a product with a variant whose default price is `$10`. You also add two tiered prices that set the price to `$8` when the quantity is between `10` and `19`, and to `$6` when the quantity is `20` or more.
-
-### How are Tiered Prices 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 the cart's items as a context when choosing the best price to apply.
-
-For example, consider the customer added the `variant_1` product variant (created in the workflow snippet of the [above section](#how-to-create-tiered-prices)) to their cart with a quantity of `15`.
-
-The price calculation mechanism will choose the second price, which is `$8`, because the quantity of `15` is between `10` and `19`.
-
-If there are other rules applied to the price, they may affect the price calculation. Keep reading to learn about other price rules, and refer to the [Price Calculation](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/pricing/price-calculation/index.html.md) guide for more details on the calculation mechanism.
+The `Return` data model also represents the return of these items. In this case, the return is associated with the exchange or claim it was created for.
 
 ***
 
-## Price Rule
+## How Returns Impact an Order’s Version
 
-You can also restrict prices by advanced rules, such as a customer's group, zip code, or a cart's total.
+The order’s version is incremented when:
 
-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 Create Prices with Rules?
-
-When you create prices, you can specify rules for each price. This allows you to create complex pricing strategies based on different contexts.
-
-For example:
-
-For most use cases where you're building customizations in the Medusa application, it's highly recommended to use [Medusa's workflows](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/medusa-workflows-reference/index.html.md) rather than using the Pricing Module directly. Medusa's workflows already implement extensive functionalities that you can re-use in your custom flows, with reliable roll-back mechanism.
-
-### Using Medusa Workflows
-
-```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,
-            },
-          },
-        },
-      ],
-    }],
-  })
-```
-
-### Using the Pricing Module
-
-```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 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.
-
-### 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.
+1. A return is requested.
+2. A return is marked as received.
 
 
-# Tax-Inclusive Pricing
+# Order Claim
 
-In this document, you’ll learn about tax-inclusive pricing and how it's used when calculating prices.
+In this document, you’ll learn about order claims.
 
-## What is Tax-Inclusive Pricing?
+Refer to this [Medusa Admin User Guide](https://docs.medusajs.com/user-guide/orders/claims/index.html.md) to learn how to manage an order's claims using the dashboard.
 
-A tax-inclusive price is a price of a resource that includes taxes. Medusa calculates the tax amount from the price rather than adds the amount to it.
+## What is a Claim?
 
-For example, if a product’s price is $50, the tax rate is 2%, and tax-inclusive pricing is enabled, then the product's price is $49, and the applied tax amount is $1.
+When a customer receives a defective or incorrect item, the merchant can create a claim to refund or replace the item.
+
+The [OrderClaim data model](https://docs.medusajs.com/references/order/models/OrderClaim/index.html.md) represents a claim.
 
 ***
 
-## How is Tax-Inclusive Pricing Set?
+## Claim Type
 
-The [PricePreference data model](https://docs.medusajs.com/references/pricing/models/PricePreference/index.html.md) holds the tax-inclusive setting for a context. It has two properties that indicate the context:
+The `Claim` data model has a `type` property whose value indicates the type of the claim:
 
-- `attribute`: The name of the attribute to compare against. For example, `region_id` or `currency_code`.
-- `value`: The attribute’s value. For example, `reg_123` or `usd`.
-
-Only `region_id` and `currency_code` are supported as an `attribute` at the moment.
-
-The `is_tax_inclusive` property indicates whether tax-inclusivity is enabled in the specified context.
-
-For example:
-
-```json
-{
-  "attribute": "currency_code",
-  "value": "USD",
-  "is_tax_inclusive": true,
-}
-```
-
-In this example, tax-inclusivity is enabled for the `USD` currency code.
+- `refund`: the items are returned, and the customer is refunded.
+- `replace`: the items are returned, and the customer receives new items.
 
 ***
 
-## Tax-Inclusive Pricing in Price Calculation
+## Old and Replacement Items
 
-### Tax Context
+When the claim is created, a return, represented by the [Return data model](https://docs.medusajs.com/references/order/models/Return/index.html.md), is also created to handle receiving the old items from the customer.
 
-As mentioned in the [Price Calculation documentation](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/pricing/price-calculation#calculation-context/index.html.md), The `calculatePrices` method accepts as a parameter a calculation context.
+Learn more about returns in [this guide](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/order/return/index.html.md).
 
-To get accurate tax results, pass the `region_id` and / or `currency_code` in the calculation context.
-
-### Returned Tax Properties
-
-The `calculatePrices` method returns two properties related to tax-inclusivity:
-
-Learn more about the returned properties in [this guide](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/pricing/price-calculation#returned-price-object/index.html.md).
-
-- `is_calculated_price_tax_inclusive`: Whether the selected `calculated_price` is tax-inclusive.
-- `is_original_price_tax_inclusive` : Whether the selected `original_price` is tax-inclusive.
-
-A price is considered tax-inclusive if:
-
-1. It belongs to the region or currency code specified in the calculation context;
-2. and the region or currency code has a price preference with `is_tax_inclusive` enabled.
-
-### Tax Context Precedence
-
-A region’s price preference’s `is_tax_inclusive`'s value takes higher precedence in determining whether a price is tax-inclusive if:
-
-- both the `region_id` and `currency_code` are provided in the calculation context;
-- the selected price belongs to the region;
-- 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.
+If the claim’s type is `replace`, replacement items are represented by the [ClaimItem data model](https://docs.medusajs.com/references/order/models/OrderClaimItem/index.html.md).
 
 ***
 
-## Save Payment Methods
+## Claim Shipping Methods
 
-If a payment provider supports saving payment methods for a customer, they must implement the following methods:
+A claim uses shipping methods to send the replacement items to the customer. These methods are represented by the [OrderShippingMethod data model](https://docs.medusajs.com/references/order/models/OrderShippingMethod/index.html.md).
 
-- `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).
+The shipping methods for the returned items are associated with the claim's return, as explained in [this guide](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/order/return#return-shipping-methods/index.html.md).
 
 ***
 
-## Account Holder in Medusa Payment Flows
+## Claim Refund
 
-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.
+If the claim’s type is `refund`, the amount to be refunded is stored in the `refund_amount` property.
 
-Consequently, the Payment Module uses the payment provider to create an account holder in the third-party service, then creates the account holder in Medusa.
-
-This flow is only supported if the chosen payment provider has implemented the necessary [save payment methods](#save-payment-methods).
-
-
-# Payment Module Options
-
-In this document, you'll learn about the options of the Payment Module.
-
-## All Module Options
-
-|Option|Description|Required|Default|
-|---|---|---|---|---|---|---|
-|\`webhook\_delay\`|A number indicating the delay in milliseconds before processing a webhook event.|No|\`5000\`|
-|\`webhook\_retries\`|The number of times to retry the webhook event processing in case of an error.|No|\`3\`|
-|\`providers\`|An array of payment providers to install and register. Learn more |No|-|
+The [Transaction data model](https://docs.medusajs.com/references/order/models/OrderTransaction/index.html.md) represents the refunds made for the claim.
 
 ***
 
-## providers Option
+## How Claims Impact an Order’s Version
 
-The `providers` option is an array of payment module providers.
+When a claim is confirmed, the order’s version is incremented.
 
-When the Medusa application starts, these providers are registered and can be used to process payments.
 
-For example:
+# Order Exchange
+
+In this document, you’ll learn about order exchanges.
+
+Refer to this [Medusa Admin User Guide](https://docs.medusajs.com/user-guide/orders/exchanges/index.html.md) to learn how to manage an order's exchanges using the dashboard.
+
+## What is an Exchange?
+
+An exchange is the replacement of an item that the customer ordered with another.
+
+A merchant creates the exchange, specifying the items to be replaced and the new items to be sent.
+
+The [OrderExchange data model](https://docs.medusajs.com/references/order/models/OrderExchange/index.html.md) represents an exchange.
+
+***
+
+## Returned and New Items
+
+When the exchange is created, a return, represented by the [Return data model](https://docs.medusajs.com/references/order/models/Return/index.html.md), is created to handle receiving the items back from the customer.
+
+Learn more about returns in [this guide](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/order/return/index.html.md).
+
+The [OrderExchangeItem data model](https://docs.medusajs.com/references/order/models/OrderExchangeItem/index.html.md) represents the new items to be sent to the customer.
+
+***
+
+## Exchange Shipping Methods
+
+An exchange has shipping methods used to send the new items to the customer. They’re represented by the [OrderShippingMethod data model](https://docs.medusajs.com/references/order/models/OrderShippingMethod/index.html.md).
+
+The shipping methods for the returned items are associated with the exchange's return, as explained in [this guide](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/order/return#return-shipping-methods/index.html.md).
+
+***
+
+## Exchange Payment
+
+The `Exchange` data model has a `difference_due` property that stores the outstanding amount.
+
+|Condition|Result|
+|---|---|---|
+|\`difference\_due \< 0\`|Merchant owes the customer a refund of the |
+|\`difference\_due > 0\`|Merchant requires additional payment from the customer of the |
+|\`difference\_due = 0\`|No payment processing is required.|
+
+Any payment or refund made is stored in the [Transaction data model](https://docs.medusajs.com/references/order/models/OrderTransaction/index.html.md).
+
+***
+
+## How Exchanges Impact an Order’s Version
+
+When an exchange is confirmed, the order’s version is incremented.
+
+
+# Tax Module Options
+
+In this guide, you'll learn about the options of the Tax Module.
+
+## providers
+
+The `providers` option is an array of either [tax module providers](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/tax/tax-provider/index.html.md) or path to a file that defines a tax provider.
+
+When the Medusa application starts, these providers are registered and can be used to retrieve tax lines.
 
 ```ts title="medusa-config.ts"
 import { Modules } from "@medusajs/framework/utils"
@@ -26800,12 +28894,12 @@ module.exports = defineConfig({
   // ...
   modules: [
     {
-      resolve: "@medusajs/medusa/payment",
+      resolve: "@medusajs/tax",
       options: {
         providers: [
           {
-            resolve: "@medusajs/medusa/payment-stripe",
-            id: "stripe",
+            resolve: "./path/to/my-provider",
+            id: "my-provider",
             options: {
               // ...
             },
@@ -26817,2227 +28911,345 @@ module.exports = defineConfig({
 })
 ```
 
-The `providers` option is an array of objects that accept the following properties:
+The objects in the array accept the following properties:
 
-- `resolve`: A string indicating the package name of the module provider or the path to it relative to the `src` directory.
+- `resolve`: A string indicating the package name of the module provider or the path to it.
 - `id`: A string indicating the provider's unique name or ID.
 - `options`: An optional object of the module provider's options.
 
 
-# Links between Payment Module and Other Modules
+# Tax Calculation with the Tax Provider
 
-This document showcases the module links defined between the Payment Module and other Commerce Modules.
+In this guide, you’ll learn how tax lines are calculated using the tax provider.
 
-## Summary
+## Tax Lines Calculation
 
-The Payment Module has the following links to other modules:
-
-|First Data Model|Second Data Model|Type|Description|
-|---|---|---|---|
-|Cart|PaymentCollection|Stored - one-to-one|Learn more|
-|Customer|AccountHolder|Stored - many-to-many|Learn more|
-|Order|PaymentCollection|Stored - one-to-many|Learn more|
-|OrderClaim|PaymentCollection|Stored - one-to-many|Learn more|
-|OrderExchange|PaymentCollection|Stored - one-to-many|Learn more|
-|Region|PaymentProvider|Stored - many-to-many|Learn more|
-
-***
-
-## Cart Module
-
-The Cart Module provides cart-related features, but not payment processing.
-
-Medusa defines a link between the `Cart` and `PaymentCollection` data models. A cart has a payment collection which holds all the authorized payment sessions and payments made related to the cart.
-
-Learn more about this relation in [this documentation](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/payment/payment-collection#usage-with-the-cart-module/index.html.md).
-
-### Retrieve with Query
-
-To retrieve the cart associated with the payment collection with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `cart.*` in `fields`:
-
-### query.graph
-
-```ts
-const { data: paymentCollections } = await query.graph({
-  entity: "payment_collection",
-  fields: [
-    "cart.*",
-  ],
-})
-
-// paymentCollections[0].cart
-```
-
-### useQueryGraphStep
-
-```ts
-import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
-
-// ...
-
-const { data: paymentCollections } = useQueryGraphStep({
-  entity: "payment_collection",
-  fields: [
-    "cart.*",
-  ],
-})
-
-// paymentCollections[0].cart
-```
-
-### Manage with Link
-
-To manage the payment collection of a cart, use [Link](https://docs.medusajs.com/docs/learn/fundamentals/module-links/link/index.html.md):
-
-### link.create
-
-```ts
-import { Modules } from "@medusajs/framework/utils"
-
-// ...
-
-await link.create({
-  [Modules.CART]: {
-    cart_id: "cart_123",
-  },
-  [Modules.PAYMENT]: {
-    payment_collection_id: "paycol_123",
-  },
-})
-```
-
-### createRemoteLinkStep
-
-```ts
-import { createRemoteLinkStep } from "@medusajs/medusa/core-flows"
-
-// ...
-
-createRemoteLinkStep({
-  [Modules.CART]: {
-    cart_id: "cart_123",
-  },
-  [Modules.PAYMENT]: {
-    payment_collection_id: "paycol_123",
-  },
-})
-```
-
-***
-
-## Customer Module
-
-Medusa defines a link between the `Customer` and `AccountHolder` data models, allowing payment providers to save payment methods for a customer, if the payment provider supports it.
-
-This link is available starting from Medusa `v2.5.0`.
-
-### Retrieve with Query
-
-To retrieve the customer associated with an account holder with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `customer.*` in `fields`:
-
-### query.graph
-
-```ts
-const { data: accountHolders } = await query.graph({
-  entity: "account_holder",
-  fields: [
-    "customer.*",
-  ],
-})
-
-// accountHolders[0].customer
-```
-
-### useQueryGraphStep
-
-```ts
-import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
-
-// ...
-
-const { data: accountHolders } = useQueryGraphStep({
-  entity: "account_holder",
-  fields: [
-    "customer.*",
-  ],
-})
-
-// accountHolders[0].customer
-```
-
-### Manage with Link
-
-To manage the account holders of a customer, use [Link](https://docs.medusajs.com/docs/learn/fundamentals/module-links/link/index.html.md):
-
-### link.create
-
-```ts
-import { Modules } from "@medusajs/framework/utils"
-
-// ...
-
-await link.create({
-  [Modules.CUSTOMER]: {
-    customer_id: "cus_123",
-  },
-  [Modules.PAYMENT]: {
-    account_holder_id: "acchld_123",
-  },
-})
-```
-
-### createRemoteLinkStep
-
-```ts
-import { createRemoteLinkStep } from "@medusajs/medusa/core-flows"
-
-// ...
-
-createRemoteLinkStep({
-  [Modules.CUSTOMER]: {
-    customer_id: "cus_123",
-  },
-  [Modules.PAYMENT]: {
-    account_holder_id: "acchld_123",
-  },
-})
-```
-
-***
-
-## Order Module
-
-An order's payment details are stored in a payment collection. This also applies for claims and exchanges.
-
-So, Medusa defines links between the `PaymentCollection` data model and the `Order`, `OrderClaim`, and `OrderExchange` data models.
-
-![A diagram showcasing an example of how data models from the Order and Payment modules are linked](https://res.cloudinary.com/dza7lstvk/image/upload/v1716554726/Medusa%20Resources/order-payment_ubdwok.jpg)
-
-### Retrieve with Query
-
-To retrieve the order of a payment collection with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `order.*` in `fields`:
-
-### query.graph
-
-```ts
-const { data: paymentCollections } = await query.graph({
-  entity: "payment_collection",
-  fields: [
-    "order.*",
-  ],
-})
-
-// paymentCollections[0].order
-```
-
-### useQueryGraphStep
-
-```ts
-import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
-
-// ...
-
-const { data: paymentCollections } = useQueryGraphStep({
-  entity: "payment_collection",
-  fields: [
-    "order.*",
-  ],
-})
-
-// paymentCollections[0].order
-```
-
-### Manage with Link
-
-To manage the payment collections of an order, use [Link](https://docs.medusajs.com/docs/learn/fundamentals/module-links/link/index.html.md):
-
-### link.create
-
-```ts
-import { Modules } from "@medusajs/framework/utils"
-
-// ...
-
-await link.create({
-  [Modules.ORDER]: {
-    order_id: "order_123",
-  },
-  [Modules.PAYMENT]: {
-    payment_collection_id: "paycol_123",
-  },
-})
-```
-
-### createRemoteLinkStep
-
-```ts
-import { Modules } from "@medusajs/framework/utils"
-import { createRemoteLinkStep } from "@medusajs/medusa/core-flows"
-
-// ...
-
-createRemoteLinkStep({
-  [Modules.ORDER]: {
-    order_id: "order_123",
-  },
-  [Modules.PAYMENT]: {
-    payment_collection_id: "paycol_123",
-  },
-})
-```
-
-***
-
-## Region Module
-
-You can specify for each region which payment providers are available. The Medusa application defines a link between the `PaymentProvider` and the `Region` data models.
-
-![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)
-
-This increases the flexibility of your store. For example, you only show during checkout the payment providers associated with the cart's region.
-
-### Retrieve with Query
-
-To retrieve the regions of a payment provider with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `regions.*` in `fields`:
-
-### query.graph
-
-```ts
-const { data: paymentProviders } = await query.graph({
-  entity: "payment_provider",
-  fields: [
-    "regions.*",
-  ],
-})
-
-// paymentProviders[0].regions
-```
-
-### useQueryGraphStep
-
-```ts
-import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
-
-// ...
-
-const { data: paymentProviders } = useQueryGraphStep({
-  entity: "payment_provider",
-  fields: [
-    "regions.*",
-  ],
-})
-
-// paymentProviders[0].regions
-```
-
-### Manage with Link
-
-To manage the payment providers in a region, use [Link](https://docs.medusajs.com/docs/learn/fundamentals/module-links/link/index.html.md):
-
-### link.create
-
-```ts
-import { Modules } from "@medusajs/framework/utils"
-
-// ...
-
-await link.create({
-  [Modules.REGION]: {
-    region_id: "reg_123",
-  },
-  [Modules.PAYMENT]: {
-    payment_provider_id: "pp_stripe_stripe",
-  },
-})
-```
-
-### createRemoteLinkStep
-
-```ts
-import { Modules } from "@medusajs/framework/utils"
-import { createRemoteLinkStep } from "@medusajs/medusa/core-flows"
-
-// ...
-
-createRemoteLinkStep({
-  [Modules.REGION]: {
-    region_id: "reg_123",
-  },
-  [Modules.PAYMENT]: {
-    payment_provider_id: "pp_stripe_stripe",
-  },
-})
-```
-
-
-# Payment
-
-In this document, you’ll learn what a payment is and how it's created, captured, and refunded.
-
-## What's a Payment?
-
-When a payment session is authorized, a payment, represented by the [Payment data model](https://docs.medusajs.com/references/payment/models/Payment/index.html.md), is created. This payment can later be captured or refunded.
-
-A payment carries many of the data and relations of a payment session:
-
-- It belongs to the same payment collection.
-- It’s associated with the same payment provider, which handles further payment processing.
-- It stores the payment session’s `data` property in its `data` property, as it’s still useful for the payment provider’s processing.
-
-***
-
-## Capture Payments
-
-When a payment is captured, a capture, represented by the [Capture data model](https://docs.medusajs.com/references/payment/models/Capture/index.html.md), is created. It holds details related to the capture, such as the amount, the capture date, and more.
-
-The payment can also be captured incrementally, each time a capture record is created for that amount.
-
-![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 Collection
-
-In this document, you’ll learn what a payment collection is and how the Medusa application uses it with the Cart Module.
-
-## What's a Payment Collection?
-
-A payment collection stores payment details related to a resource, such as a cart or an order. It’s represented by the [PaymentCollection data model](https://docs.medusajs.com/references/payment/models/PaymentCollection/index.html.md).
-
-Every purchase or request for payment starts with a payment collection. The collection holds details necessary to complete the payment, including:
-
-- The [payment sessions](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/payment/payment-session/index.html.md) that represents the payment amount to authorize.
-- The [payments](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/payment/payment/index.html.md) that are created when a payment session is authorized. They can be captured and refunded.
-- The [payment providers](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/payment/payment-provider/index.html.md) that handle the processing of each payment session, including the authorization, capture, and refund.
-
-***
-
-## Multiple Payments
-
-The payment collection supports multiple payment sessions and payments.
-
-You can use this to accept payments in increments or split payments across payment providers.
-
-![Diagram showcasing how a payment collection can have multiple payment sessions and payments](https://res.cloudinary.com/dza7lstvk/image/upload/v1711554695/Medusa%20Resources/payment-collection-multiple-payments_oi3z3n.jpg)
-
-***
-
-## Usage with the Cart Module
-
-The Cart Module provides cart management features. However, it doesn’t provide any features related to accepting payment.
-
-During checkout, the Medusa application links a cart to a payment collection, which will be used for further payment processing.
-
-It also implements the payment flow during checkout as explained in [this documentation](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/payment/payment-flow/index.html.md).
-
-![Diagram showcasing the relation between the Payment and Cart modules](https://res.cloudinary.com/dza7lstvk/image/upload/v1711537849/Medusa%20Resources/cart-payment_ixziqm.jpg)
-
-
-# Accept Payment Flow
-
-In this document, you’ll learn how to implement an accept-payment flow using workflows or the Payment Module's main service.
-
-It's highly recommended to use Medusa's workflows to implement this flow. Use the Payment Module's main service for more complex cases.
-
-For a guide on how to implement this flow in the storefront, check out [this guide](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/storefront-development/checkout/payment/index.html.md).
-
-## Flow Overview
-
-![A diagram showcasing the payment flow's steps](https://res.cloudinary.com/dza7lstvk/image/upload/v1711566781/Medusa%20Resources/payment-flow_jblrvw.jpg)
-
-***
-
-## 1. Create a Payment Collection
-
-A payment collection holds all details related to a resource’s payment operations. So, you start off by creating a payment collection.
+Tax lines are calculated and retrieved using the [getTaxLines method of the Tax Module’s main service](https://docs.medusajs.com/references/tax/getTaxLines/index.html.md). It accepts an array of line items and shipping methods, and the context of the calculation.
 
 For example:
 
-### Using Workflow
-
 ```ts
-import { createPaymentCollectionForCartWorkflow } from "@medusajs/medusa/core-flows"
-
-// ...
-
-await createPaymentCollectionForCartWorkflow(req.scope)
-  .run({
-    input: {
-      cart_id: "cart_123",
-    },
-  })
-```
-
-### Using Service
-
-```ts
-const paymentCollection =
-  await paymentModuleService.createPaymentCollections({
-    currency_code: "usd",
-    amount: 5000,
-  })
-```
-
-***
-
-## 2. Create Payment Sessions
-
-The payment collection has one or more payment sessions, each being a payment amount to be authorized by a payment provider.
-
-So, after creating the payment collection, create at least one payment session for a provider.
-
-For example:
-
-### Using Workflow
-
-```ts
-import { createPaymentSessionsWorkflow } from "@medusajs/medusa/core-flows"
-
-// ...
-
-const { result: paymentSesion } = await createPaymentSessionsWorkflow(req.scope)
-  .run({
-    input: {
-      payment_collection_id: "paycol_123",
-      provider_id: "stripe",
-    },
-  })
-```
-
-### Using Service
-
-```ts
-const paymentSession =
-  await paymentModuleService.createPaymentSession(
-    paymentCollection.id,
+const taxLines = await taxModuleService.getTaxLines(
+  [
     {
-      provider_id: "stripe",
-      currency_code: "usd",
-      amount: 5000,
-      data: {
-        // any necessary data for the
-        // payment provider
-      },
-    }
-  )
-```
-
-***
-
-## 3. Authorize Payment Session
-
-Once the customer chooses a payment session, start the authorization process. This may involve some action performed by the third-party payment provider, such as entering a 3DS code.
-
-For example:
-
-### Using Step
-
-```ts
-import { authorizePaymentSessionStep } from "@medusajs/medusa/core-flows"
-
-// ...
-
-authorizePaymentSessionStep({
-  id: "payses_123",
-  context: {},
-})
-```
-
-### Using Service
-
-```ts
-const payment = authorizePaymentSessionStep({
-  id: "payses_123",
-  context: {},
-})
-```
-
-When the payment authorization is successful, a payment is created and returned.
-
-### Handling Additional Action
-
-If you used the `authorizePaymentSessionStep`, you don't need to implement this logic as it's implemented in the step.
-
-If the payment authorization isn’t successful, whether because it requires additional action or for another reason, the method updates the payment session with the new status and throws an error.
-
-In that case, you can catch that error and, if the session's `status` property is `requires_more`, handle the additional action, then retry the authorization.
-
-For example:
-
-```ts
-try {
-  const payment =
-    await paymentModuleService.authorizePaymentSession(
-      paymentSession.id,
-      {}
-    )
-} catch (e) {
-  // retrieve the payment session again
-  const updatedPaymentSession = (
-    await paymentModuleService.listPaymentSessions({
-      id: [paymentSession.id],
-    })
-  )[0]
-
-  if (updatedPaymentSession.status === "requires_more") {
-    // TODO perform required action
-    // TODO authorize payment again.
-  }
-}
-```
-
-***
-
-## 4. Payment Flow Complete
-
-The payment flow is complete once the payment session is authorized and the payment is created.
-
-You can then:
-
-- Capture the payment either using the [capturePaymentWorkflow](https://docs.medusajs.com/references/medusa-workflows/capturePaymentWorkflow/index.html.md) or [capturePayment method](https://docs.medusajs.com/references/payment/capturePayment/index.html.md).
-- Refund captured amounts using the [refundPaymentWorkflow](https://docs.medusajs.com/references/medusa-workflows/refundPaymentWorkflow/index.html.md) or [refundPayment method](https://docs.medusajs.com/references/payment/refundPayment/index.html.md).
-
-Some payment providers allow capturing the payment automatically once it’s authorized. In that case, you don’t need to do it manually.
-
-
-# Payment Module Provider
-
-In this document, you’ll learn what a payment module provider is.
-
-Refer to this [Medusa Admin User Guide](https://docs.medusajs.com/user-guide/settings/regions/index.html.md) to learn how to manage the payment providers available in a region using the dashboard.
-
-## What's a Payment Module Provider?
-
-A payment module provider registers a payment provider that handles payment processing in the Medusa application. It integrates third-party payment providers, such as Stripe.
-
-To authorize a payment amount with a payment provider, a payment session is created and associated with that payment provider. The payment provider is then used to handle the authorization.
-
-After the payment session is authorized, the payment provider is associated with the resulting payment and handles its payment processing, such as to capture or refund payment.
-
-### List of Payment Module Providers
-
-- [Stripe](https://docs.medusajs.com/commerce-modules/payment/payment-provider/stripe/index.html.md)
-
-***
-
-## System Payment Provider
-
-The Payment Module provides a `system` payment provider that acts as a placeholder payment provider.
-
-It doesn’t handle payment processing and delegates that to the merchant. It acts similarly to a cash-on-delivery (COD) payment method.
-
-***
-
-## How are Payment Providers Created?
-
-A payment provider is a module whose main service extends the `AbstractPaymentProvider` imported from `@medusajs/framework/utils`.
-
-Refer to [this guide](https://docs.medusajs.com/references/payment/provider/index.html.md) on how to create a payment provider for the Payment Module.
-
-***
-
-## Configure Payment Providers
-
-The Payment Module accepts a `providers` option that allows you to register providers in your application.
-
-Learn more about this option in [this documentation](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/payment/module-options#providers/index.html.md).
-
-***
-
-## PaymentProvider Data Model
-
-When the Medusa application starts and registers the payment providers, it also creates a record of the `PaymentProvider` data model if none exists.
-
-This data model is used to reference a payment provider and determine whether it’s installed in the application.
-
-
-# Payment Session
-
-In this document, you’ll learn what a payment session is.
-
-## What's a Payment Session?
-
-A payment session, represented by the [PaymentSession data model](https://docs.medusajs.com/references/payment/models/PaymentSession/index.html.md), is a payment amount to be authorized. It’s associated with a payment provider that handles authorizing it.
-
-A payment collection can have multiple payment sessions. Using this feature, you can implement payment in installments or payments using multiple providers.
-
-![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.
-
-## What's a Webhook Event?
-
-A webhook event is sent from a third-party payment provider to your application. It indicates a change in a payment’s status.
-
-This is useful in many cases such as when a payment is being processed asynchronously or when a request is interrupted and the payment provider is sending details on the process later.
-
-***
-
-## getWebhookActionAndData Method
-
-The Payment Module’s main service has a [getWebhookActionAndData method](https://docs.medusajs.com/references/payment/getWebhookActionAndData/index.html.md) used to handle incoming webhook events from third-party payment services. The method delegates the handling to the associated payment provider, which returns the event's details.
-
-Medusa implements a webhook listener route at the `/hooks/payment/[identifier]_[provider]` API route, where:
-
-- `[identifier]` is the `identifier` static property defined in the payment provider. For example, `stripe`.
-- `[provider]` is the ID of the provider. For example, `stripe`.
-
-For example, when integrating basic Stripe payments with the [Stripe Module Provider](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/payment/payment-provider/stripe/index.html.md), the webhook listener route is `/hooks/payment/stripe_stripe`. If you're integrating Stripe's Bancontact payments, the webhook listener route is `/hooks/payment/stripe-bancontact_stripe`.
-
-Use that webhook listener in your third-party payment provider's configurations.
-
-![A diagram showcasing the steps of how the getWebhookActionAndData method words](https://res.cloudinary.com/dza7lstvk/image/upload/v1711567415/Medusa%20Resources/payment-webhook_seaocg.jpg)
-
-If the event's details indicate that the payment should be authorized, then the [authorizePaymentSession method of the main service](https://docs.medusajs.com/references/payment/authorizePaymentSession/index.html.md) is executed on the specified payment session.
-
-If the event's details indicate that the payment should be captured, then the [capturePayment method of the main service](https://docs.medusajs.com/references/payment/capturePayment/index.html.md) is executed on the payment of the specified payment session.
-
-### Actions After Webhook Payment Processing
-
-After the payment webhook actions are processed and the payment is authorized or captured, the Medusa application completes the cart associated with the payment's collection if it's not completed yet.
-
-
-# Links between Product Module and Other Modules
-
-This document showcases the module links defined between the Product Module and other Commerce Modules.
-
-## Summary
-
-The Product Module has the following links to other modules:
-
-Read-only links are used to query data across modules, but the relations aren't stored in a pivot table in the database.
-
-|First Data Model|Second Data Model|Type|Description|
-|---|---|---|---|
-|LineItem|Product|Read-only - has one|Learn more|
-|Product|ShippingProfile|Stored - many-to-one|Learn more|
-|ProductVariant|InventoryItem|Stored - many-to-many|Learn more|
-|OrderLineItem|Product|Read-only - has one|Learn more|
-|ProductVariant|PriceSet|Stored - one-to-one|Learn more|
-|Product|SalesChannel|Stored - many-to-many|Learn more|
-
-***
-
-## Cart Module
-
-Medusa defines read-only links between:
-
-- The [Cart Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/cart/index.html.md)'s `LineItem` data model and the `Product` data model. Because the link is read-only from the `LineItem`'s side, you can only retrieve the product of a line item, and not the other way around.
-- The `ProductVariant` data model and the [Cart Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/cart/index.html.md)'s `LineItem` data model. Because the link is read-only from the `LineItem`'s side, you can only retrieve the variant of a line item, and not the other way around.
-
-### Retrieve with Query
-
-To retrieve the variant of a line item with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `variant.*` in `fields`:
-
-To retrieve the product, pass `product.*` in `fields`.
-
-### query.graph
-
-```ts
-const { data: lineItems } = await query.graph({
-  entity: "line_item",
-  fields: [
-    "variant.*",
-  ],
-})
-
-// lineItems[0].variant
-```
-
-### useQueryGraphStep
-
-```ts
-import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
-
-// ...
-
-const { data: lineItems } = useQueryGraphStep({
-  entity: "line_item",
-  fields: [
-    "variant.*",
-  ],
-})
-
-// lineItems[0].variant
-```
-
-***
-
-## Fulfillment Module
-
-Medusa defines a link between the `Product` data model and the `ShippingProfile` data model of the Fulfillment Module. Each product must belong to a shipping profile.
-
-This link is introduced in [Medusa v2.5.0](https://github.com/medusajs/medusa/releases/tag/v2.5.0).
-
-### Retrieve with Query
-
-To retrieve the shipping profile of a product with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `shipping_profile.*` in `fields`:
-
-### query.graph
-
-```ts
-const { data: products } = await query.graph({
-  entity: "product",
-  fields: [
-    "shipping_profile.*",
-  ],
-})
-
-// products[0].shipping_profile
-```
-
-### useQueryGraphStep
-
-```ts
-import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
-
-// ...
-
-const { data: products } = useQueryGraphStep({
-  entity: "product",
-  fields: [
-    "shipping_profile.*",
-  ],
-})
-
-// products[0].shipping_profile
-```
-
-### Manage with Link
-
-To manage the shipping profile of a product, use [Link](https://docs.medusajs.com/docs/learn/fundamentals/module-links/link/index.html.md):
-
-### link.create
-
-```ts
-import { Modules } from "@medusajs/framework/utils"
-
-// ...
-
-await link.create({
-  [Modules.PRODUCT]: {
-    product_id: "prod_123",
-  },
-  [Modules.FULFILLMENT]: {
-    shipping_profile_id: "sp_123",
-  },
-})
-```
-
-### createRemoteLinkStep
-
-```ts
-import { Modules } from "@medusajs/framework/utils"
-import { createRemoteLinkStep } from "@medusajs/medusa/core-flows"
-
-// ...
-
-createRemoteLinkStep({
-  [Modules.PRODUCT]: {
-    product_id: "prod_123",
-  },
-  [Modules.FULFILLMENT]: {
-    shipping_profile_id: "sp_123",
-  },
-})
-```
-
-***
-
-## Inventory Module
-
-The Inventory Module provides inventory-management features for any stock-kept item.
-
-Medusa defines a link between the `ProductVariant` and `InventoryItem` data models. Each product variant has different inventory details.
-
-![A diagram showcasing an example of how data models from the Product and Inventory modules are linked.](https://res.cloudinary.com/dza7lstvk/image/upload/v1709652779/Medusa%20Resources/product-inventory_kmjnud.jpg)
-
-When the `manage_inventory` property of a product variant is enabled, you can manage the variant's inventory in different locations through this relation.
-
-Learn more about product variant's inventory management in [this guide](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/product/variant-inventory/index.html.md).
-
-### Retrieve with Query
-
-To retrieve the inventory items of a product variant with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `inventory_items.*` in `fields`:
-
-### query.graph
-
-```ts
-const { data: variants } = await query.graph({
-  entity: "variant",
-  fields: [
-    "inventory_items.*",
-  ],
-})
-
-// variants[0].inventory_items
-```
-
-### useQueryGraphStep
-
-```ts
-import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
-
-// ...
-
-const { data: variants } = useQueryGraphStep({
-  entity: "variant",
-  fields: [
-    "inventory_items.*",
-  ],
-})
-
-// variants[0].inventory_items
-```
-
-### Manage with Link
-
-To manage the inventory items of a variant, use [Link](https://docs.medusajs.com/docs/learn/fundamentals/module-links/link/index.html.md):
-
-### link.create
-
-```ts
-import { Modules } from "@medusajs/framework/utils"
-
-// ...
-
-await link.create({
-  [Modules.PRODUCT]: {
-    variant_id: "variant_123",
-  },
-  [Modules.INVENTORY]: {
-    inventory_item_id: "iitem_123",
-  },
-})
-```
-
-### createRemoteLinkStep
-
-```ts
-import { Modules } from "@medusajs/framework/utils"
-import { createRemoteLinkStep } from "@medusajs/medusa/core-flows"
-
-// ...
-
-createRemoteLinkStep({
-  [Modules.PRODUCT]: {
-    variant_id: "variant_123",
-  },
-  [Modules.INVENTORY]: {
-    inventory_item_id: "iitem_123",
-  },
-})
-```
-
-***
-
-## Order Module
-
-Medusa defines read-only links between:
-
-- the [Order Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/order/index.html.md)'s `OrderLineItem` data model and the `Product` data model. Because the link is read-only from the `OrderLineItem`'s side, you can only retrieve the product of an order line item, and not the other way around.
-- the [Order Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/order/index.html.md)'s `OrderLineItem` data model and the `ProductVariant` data model. Because the link is read-only from the `OrderLineItem`'s side, you can only retrieve the variant of an order line item, and not the other way around.
-
-### Retrieve with Query
-
-To retrieve the variant of a line item with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `variant.*` in `fields`:
-
-To retrieve the product, pass `product.*` in `fields`.
-
-### query.graph
-
-```ts
-const { data: lineItems } = await query.graph({
-  entity: "order_line_item",
-  fields: [
-    "variant.*",
-  ],
-})
-
-// lineItems[0].variant
-```
-
-### useQueryGraphStep
-
-```ts
-import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
-
-// ...
-
-const { data: lineItems } = useQueryGraphStep({
-  entity: "order_line_item",
-  fields: [
-    "variant.*",
-  ],
-})
-
-// lineItems[0].variant
-```
-
-***
-
-## Pricing Module
-
-The Product Module doesn't provide pricing-related features.
-
-Instead, Medusa defines a link between the `ProductVariant` and the `PriceSet` data models. A product variant’s prices are stored belonging to a price set.
-
-![A diagram showcasing an example of how data models from the Pricing and Product Module are linked.](https://res.cloudinary.com/dza7lstvk/image/upload/v1709651464/Medusa%20Resources/product-pricing_vlxsiq.jpg)
-
-So, to add prices for a product variant, create a price set and add the prices to it.
-
-### Retrieve with Query
-
-To retrieve the price set of a variant with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `price_set.*` in `fields`:
-
-### query.graph
-
-```ts
-const { data: variants } = await query.graph({
-  entity: "variant",
-  fields: [
-    "price_set.*",
-  ],
-})
-
-// variants[0].price_set
-```
-
-### useQueryGraphStep
-
-```ts
-import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
-
-// ...
-
-const { data: variants } = useQueryGraphStep({
-  entity: "variant",
-  fields: [
-    "price_set.*",
-  ],
-})
-
-// variants[0].price_set
-```
-
-### Manage with Link
-
-To manage the price set of a variant, use [Link](https://docs.medusajs.com/docs/learn/fundamentals/module-links/link/index.html.md):
-
-### link.create
-
-```ts
-import { Modules } from "@medusajs/framework/utils"
-
-// ...
-
-await link.create({
-  [Modules.PRODUCT]: {
-    variant_id: "variant_123",
-  },
-  [Modules.PRICING]: {
-    price_set_id: "pset_123",
-  },
-})
-```
-
-### createRemoteLinkStep
-
-```ts
-import { Modules } from "@medusajs/framework/utils"
-import { createRemoteLinkStep } from "@medusajs/medusa/core-flows"
-
-// ...
-
-createRemoteLinkStep({
-  [Modules.PRODUCT]: {
-    variant_id: "variant_123",
-  },
-  [Modules.PRICING]: {
-    price_set_id: "pset_123",
-  },
-})
-```
-
-***
-
-## Sales Channel Module
-
-The Sales Channel Module provides functionalities to manage multiple selling channels in your store.
-
-Medusa defines a link between the `Product` and `SalesChannel` data models. A product can have different availability in different sales channels.
-
-![A diagram showcasing an example of how data models from the Product and Sales Channel modules are linked.](https://res.cloudinary.com/dza7lstvk/image/upload/v1709651840/Medusa%20Resources/product-sales-channel_t848ik.jpg)
-
-### Retrieve with Query
-
-To retrieve the sales channels of a product with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `sales_channels.*` in `fields`:
-
-### query.graph
-
-```ts
-const { data: products } = await query.graph({
-  entity: "product",
-  fields: [
-    "sales_channels.*",
-  ],
-})
-
-// products[0].sales_channels
-```
-
-### useQueryGraphStep
-
-```ts
-import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
-
-// ...
-
-const { data: products } = useQueryGraphStep({
-  entity: "product",
-  fields: [
-    "sales_channels.*",
-  ],
-})
-
-// products[0].sales_channels
-```
-
-### Manage with Link
-
-To manage the sales channels of a product, use [Link](https://docs.medusajs.com/docs/learn/fundamentals/module-links/link/index.html.md):
-
-### link.create
-
-```ts
-import { Modules } from "@medusajs/framework/utils"
-
-// ...
-
-await link.create({
-  [Modules.PRODUCT]: {
-    product_id: "prod_123",
-  },
-  [Modules.SALES_CHANNEL]: {
-    sales_channel_id: "sc_123",
-  },
-})
-```
-
-### createRemoteLinkStep
-
-```ts
-import { Modules } from "@medusajs/framework/utils"
-import { createRemoteLinkStep } from "@medusajs/medusa/core-flows"
-
-// ...
-
-createRemoteLinkStep({
-  [Modules.PRODUCT]: {
-    product_id: "prod_123",
-  },
-  [Modules.SALES_CHANNEL]: {
-    sales_channel_id: "sc_123",
-  },
-})
-```
-
-
-# Configure Selling Products
-
-In this guide, you'll learn how to set up and configure your products based on their shipping and inventory requirements, the product type, how you want to sell them, or your commerce ecosystem.
-
-The concepts in this guide are applicable starting from Medusa v2.5.1.
-
-## Scenario
-
-Businesses can have different selling requirements:
-
-1. They may sell physical or digital items.
-2. They may sell items that don't require shipping or inventory management, such as selling digital products, services, or booking appointments.
-3. They may sell items whose inventory is managed by an external system, such as an ERP.
-
-Medusa supports these different selling requirements by allowing you to configure shipping and inventory requirements for products and their variants. This guide explains how these configurations work, then provides examples of setting up different use cases.
-
-***
-
-## Configuring Shipping Requirements
-
-The Medusa application defines a link between the `Product` data model and a [ShippingProfile](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/fulfillment/concepts#shipping-profile/index.html.md) in the [Fulfillment Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/fulfillment/index.html.md), allowing you to associate a product with a shipping profile.
-
-When a product is associated with a shipping profile, its variants require shipping and fulfillment when purchased. This is useful for physical products or digital products that require custom fulfillment.
-
-If a product doesn't have an associated shipping profile, its variants don't require shipping and fulfillment when purchased. This is useful for digital products, for example, that don't require shipping.
-
-### Overriding Shipping Requirements for Variants
-
-A product variant whose inventory is managed by Medusa (its `manage_inventory` property is enabled) has an [inventory item](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/inventory/concepts#inventoryitem/index.html.md). The inventory item has a `requires_shipping` property that can be used to override its shipping requirement. This is useful if the product has an associated shipping profile but you want to disable shipping for a specific variant, or vice versa.
-
-Learn more about product variant's inventory in [this guide](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/product/variant-inventory/index.html.md).
-
-When a product variant is purchased, the Medusa application decides whether the purchased item requires shipping in the following order:
-
-1. The product variant has an inventory item. In this case, the Medusa application uses the inventory item's `requires_shipping` property to determine if the item requires shipping.
-2. If the product variant doesn't have an inventory item, the Medusa application checks whether the product has an associated shipping profile to determine if the item requires shipping.
-
-***
-
-## Use Case Examples
-
-By combining configurations of shipment requirements and inventory management, you can set up your products to support your use case:
-
-|Use Case|Configurations|Example|
-|---|---|---|---|---|
-|Item that's shipped on purchase, and its variant inventory is managed by the Medusa application.||Any stock-kept item (clothing, for example), whose inventory is managed in the Medusa application.|
-|Item that's shipped on purchase, but its variant inventory is managed externally (not by Medusa) or it has infinite stock.||Any stock-kept item (clothing, for example), whose inventory is managed in an ERP or has infinite stock.|
-|Item that's not shipped on purchase, but its variant inventory is managed by Medusa.||Digital products, such as licenses, that don't require shipping but have a limited quantity.|
-|Item that doesn't require shipping and its variant inventory isn't managed by Medusa.|||
-
-
-# Product Variant Inventory
-
-# Product Variant Inventory
-
-In this guide, you'll learn about the inventory management features related to product variants.
-
-Refer to this [Medusa Admin User Guide](https://docs.medusajs.com/user-guide/products/variants#manage-product-variant-inventory/index.html.md) to learn how to manage inventory of product variants.
-
-## Configure Inventory Management of Product Variants
-
-A product variant, represented by the [ProductVariant](https://docs.medusajs.com/references/product/models/ProductVariant/index.html.md) data model, has a `manage_inventory` field that's disabled by default. This field indicates whether you'll manage the inventory quantity of the product variant in the Medusa application. You can also keep `manage_inventory` disabled if you manage the product's inventory in an external system, such as an ERP.
-
-The Product Module doesn't provide inventory-management features. Instead, the Medusa application uses the [Inventory Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/inventory/index.html.md) to manage inventory for products and variants. When `manage_inventory` is disabled, the Medusa application always considers the product variant to be in stock. This is useful if your product's variants aren't items that can be stocked, such as digital products, or they don't have a limited stock quantity.
-
-When `manage_inventory` is enabled, the Medusa application tracks the inventory of the product variant using the [Inventory Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/inventory/index.html.md). For example, when a customer purchases a product variant, the Medusa application decrements the stocked quantity of the product variant.
-
-***
-
-## How the Medusa Application Manages Inventory
-
-When a product variant has `manage_inventory` enabled, the Medusa application creates an inventory item using the [Inventory Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/inventory/index.html.md) and links it to the product variant.
-
-![Diagram showcasing the link between a product variant and its inventory item](https://res.cloudinary.com/dza7lstvk/image/upload/v1709652779/Medusa%20Resources/product-inventory_kmjnud.jpg)
-
-The inventory item has one or more locations, called inventory levels, that represent the stock quantity of the product variant at a specific location. This allows you to manage inventory across multiple warehouses, such as a warehouse in the US and another in Europe.
-
-![Diagram showcasing the link between a variant and its inventory item, and the inventory item's level.](https://res.cloudinary.com/dza7lstvk/image/upload/v1738580390/Medusa%20Resources/variant-inventory-level_bbee2t.jpg)
-
-Learn more about inventory concepts in the [Inventory Module's documentation](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/inventory/concepts/index.html.md).
-
-The Medusa application represents and manages stock locations using the [Stock Location Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/stock-location/index.html.md). It creates a read-only link between the `InventoryLevel` and `StockLocation` data models so that it can retrieve the stock location of an inventory level.
-
-![Diagram showcasing the read-only link between an inventory level and a stock location](https://res.cloudinary.com/dza7lstvk/image/upload/v1738582163/Medusa%20Resources/inventory-level-stock_amxfg5.jpg)
-
-Learn more about the Stock Location Module in the [Stock Location Module's documentation](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/stock-location/concepts/index.html.md).
-
-### Product Inventory in Storefronts
-
-When a storefront sends a request to the Medusa application, it must always pass a [publishable API key](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/sales-channel/publishable-api-keys/index.html.md) in the request header. This API key specifies the sales channels, available through the [Sales Channel Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/sales-channel/index.html.md), of the storefront.
-
-The Medusa application links sales channels to stock locations, indicating the locations available for a specific sales channel. So, all inventory-related operations are scoped by the sales channel and its associated stock locations.
-
-For example, the availability of a product variant is determined by the `stocked_quantity` of its inventory level at the stock location linked to the storefront's sales channel.
-
-![Diagram showcasing the overall relations between inventory, stock location, and sales channel concepts](https://res.cloudinary.com/dza7lstvk/image/upload/v1738582163/Medusa%20Resources/inventory-stock-sales_fknoxw.jpg)
-
-***
-
-## Variant Back Orders
-
-Product variants have an `allow_backorder` field that's disabled by default. When enabled, the Medusa application allows customers to purchase the product variant even when it's out of stock. Use this when your product variant is available through on-demand or pre-order purchase.
-
-You can also allow customers to subscribe to restock notifications of a product variant as explained in [this guide](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/recipes/commerce-automation/restock-notification/index.html.md).
-
-***
-
-## Additional Resources
-
-The following guides provide more details on inventory management in the Medusa application:
-
-- [Inventory Kits in the Inventory Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/inventory/inventory-kit/index.html.md): Learn how you can implement bundled or multi-part products through the Inventory Module.
-- [Retrieve Product Variant Inventory Quantity](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/product/guides/variant-inventory/index.html.md): Learn how to retrieve the available inventory quantity of a product variant.
-- [Configure Selling Products](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/product/selling-products/index.html.md): Learn how to use inventory management to support different use cases when selling products.
-- [Inventory in Flows](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/inventory/inventory-in-flows/index.html.md): Learn how Medusa utilizes inventory management in different flows.
-- [Storefront guide: how to retrieve a product variant's inventory details](https://docs.medusajs.com/resources/storefront-development/products/inventory/index.html.md).
-
-
-# Promotion Actions
-
-In this document, you’ll learn about promotion actions and how they’re computed using the [computeActions method](https://docs.medusajs.com/references/promotion/computeActions/index.html.md).
-
-## computeActions Method
-
-The Promotion Module's main service has a [computeActions method](https://docs.medusajs.com/references/promotion/computeActions/index.html.md) that returns an array of actions to perform on a cart when one or more promotions are applied.
-
-Actions inform you what adjustment must be made to a cart item or shipping method. Each action is an object having the `action` property indicating the type of action.
-
-***
-
-## Action Types
-
-### `addItemAdjustment` Action
-
-The `addItemAdjustment` action indicates that an adjustment must be made to an item. For example, removing $5 off its amount.
-
-This action has the following format:
-
-```ts
-export interface AddItemAdjustmentAction {
-  action: "addItemAdjustment"
-  item_id: string
-  amount: number
-  code: string
-  description?: string
-}
-```
-
-This action means that a new record should be created of the `LineItemAdjustment` data model in the Cart Module, or `OrderLineItemAdjustment` data model in the Order Module.
-
-Refer to [this reference](https://docs.medusajs.com/references/promotion/interfaces/promotion.AddItemAdjustmentAction/index.html.md) for details on the object’s properties.
-
-### `removeItemAdjustment` Action
-
-The `removeItemAdjustment` action indicates that an adjustment must be removed from a line item. For example, remove the $5 discount.
-
-The `computeActions` method accepts any previous item adjustments in the `items` property of the second parameter.
-
-This action has the following format:
-
-```ts
-export interface RemoveItemAdjustmentAction {
-  action: "removeItemAdjustment"
-  adjustment_id: string
-  description?: string
-  code: string
-}
-```
-
-This action means that a new record should be removed of the `LineItemAdjustment` (or `OrderLineItemAdjustment`) with the specified ID in the `adjustment_id` property.
-
-Refer to [this reference](https://docs.medusajs.com/references/promotion/interfaces/promotion.RemoveItemAdjustmentAction/index.html.md) for details on the object’s properties.
-
-### `addShippingMethodAdjustment` Action
-
-The `addShippingMethodAdjustment` action indicates that an adjustment must be made on a shipping method. For example, make the shipping method free.
-
-This action has the following format:
-
-```ts
-export interface AddShippingMethodAdjustment {
-  action: "addShippingMethodAdjustment"
-  shipping_method_id: string
-  amount: number
-  code: string
-  description?: string
-}
-```
-
-This action means that a new record should be created of the `ShippingMethodAdjustment` data model in the Cart Module, or `OrderShippingMethodAdjustment` data model in the Order Module.
-
-Refer to [this reference](https://docs.medusajs.com/references/promotion/interfaces/promotion.AddShippingMethodAdjustment/index.html.md) for details on the object’s properties.
-
-### `removeShippingMethodAdjustment` Action
-
-The `removeShippingMethodAdjustment` action indicates that an adjustment must be removed from a shipping method. For example, remove the free shipping discount.
-
-The `computeActions` method accepts any previous shipping method adjustments in the `shipping_methods` property of the second parameter.
-
-This action has the following format:
-
-```ts
-export interface RemoveShippingMethodAdjustment {
-  action: "removeShippingMethodAdjustment"
-  adjustment_id: string
-  code: string
-}
-```
-
-When the Medusa application receives this action type, it removes the `ShippingMethodAdjustment` (or `OrderShippingMethodAdjustment`) with the specified ID in the `adjustment_id` property.
-
-Refer to [this reference](https://docs.medusajs.com/references/promotion/interfaces/promotion.RemoveShippingMethodAdjustment/index.html.md) for details on the object’s properties.
-
-### `campaignBudgetExceeded` Action
-
-When the `campaignBudgetExceeded` action is returned, the promotions within a campaign can no longer be used as the campaign budget has been exceeded.
-
-This action has the following format:
-
-```ts
-export interface CampaignBudgetExceededAction {
-  action: "campaignBudgetExceeded"
-  code: string
-}
-```
-
-Refer to [this reference](https://docs.medusajs.com/references/promotion/interfaces/promotion.CampaignBudgetExceededAction/index.html.md) for details on the object’s properties.
-
-
-# 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",
-            ],
-          },
-        ],
-      }],
+      id: "cali_123",
+      product_id: "prod_123",
+      unit_price: 1000,
+      quantity: 1,
     },
-  })
-```
-
-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([
+    {
+      id: "casm_123",
+      shipping_option_id: "so_123",
+      unit_price: 2000,
+    },
+  ],
   {
-    code: "50OFF",
-    type: "standard",
-    status: "active",
-    application_method: {
-      type: "percentage",
-      target_type: "items",
-      value: 50,
+    address: {
+      country_code: "us",
     },
-    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.
+The context object is used to determine which tax regions and rates to use in the calculation. It includes properties related to the address and customer.
 
-### How is the Promotion Rule Applied?
+The example above retrieves the tax lines based on the tax region for the United States.
 
-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:
+The method returns tax lines for the line item and shipping methods. For example:
 
 ```json
-{
-  "code": "10OFF",
-  "type": "standard",
-  "status": "active",
-  "application_method": {
-    "type": "percentage",
-    "target_type": "items",
-    "allocation": "across",
-    "value": 10,
-    "currency_code": "usd"
+[
+  {
+    "line_item_id": "cali_123",
+    "rate_id": "txr_1",
+    "rate": 10,
+    "code": "XXX",
+    "name": "Tax Rate 1"
   },
-  "rules": [
+  {
+    "shipping_line_id": "casm_123",
+    "rate_id": "txr_2",
+    "rate": 5,
+    "code": "YYY",
+    "name": "Tax Rate 2"
+  }
+]
+```
+
+***
+
+## Using the Tax Provider in the Calculation
+
+The tax lines retrieved by the `getTaxLines` method are actually retrieved from the tax region’s [Tax Module Provider](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/tax/tax-provider/index.html.md).
+
+A tax module implements the logic to shape tax lines. Each tax region uses a tax provider.
+
+Learn more about tax providers, configuring, and creating them in the [Tax Module Provider](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/tax/tax-provider/index.html.md) guide.
+
+
+# Tax Module Provider
+
+In this guide, you’ll learn about the Tax Module Provider and how it's used.
+
+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 provider of a tax region using the dashboard.
+
+## What is a Tax Module Provider?
+
+The Tax Module Provider handles tax line calculations in the Medusa application. It integrates third-party tax services, such as TaxJar, or implements custom tax calculation logic.
+
+The Medusa application uses the Tax Module Provider whenever it needs to calculate tax lines for a cart or order, or when you [calculate the tax lines using the Tax Module's service](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/tax/tax-calculation-with-provider/index.html.md).
+
+![Diagram showcasing the communication between Medusa the Tax Module Provider, and the third-party tax provider.](https://res.cloudinary.com/dza7lstvk/image/upload/v1746790996/Medusa%20Resources/tax-provider-service_kcgpne.jpg)
+
+***
+
+## Default Tax Provider
+
+The Tax Module provides a `system` tax provider that acts as a placeholder tax provider. It performs basic tax calculation, as you can see in the [Create Tax Module Provider](https://docs.medusajs.com/references/tax/provider#gettaxlines/index.html.md) guide.
+
+This provider is installed by default in your application and you can use it with tax regions.
+
+The identifier of the system tax provider is `tp_system`.
+
+***
+
+## How to Create a Custom Tax Provider?
+
+A Tax Module Provider is a module whose service implements the `ITaxProvider` imported from `@medusajs/framework/types`.
+
+The module can have multiple tax provider services, where each are registered as separate tax providers.
+
+Refer to the [Create Tax Module Provider](https://docs.medusajs.com/references/tax/provider/index.html.md) guide to learn how to create a Tax Module Provider.
+
+After you create a tax provider, you can choose it as the default Tax Module Provider for a region in the [Medusa Admin dashboard](https://docs.medusajs.com/user-guide/settings/tax-regions/index.html.md).
+
+***
+
+## How are Tax Providers Registered?
+
+### Configure Tax Module's Providers
+
+The Tax Module accepts a `providers` option that allows you to configure the providers registered in your application.
+
+Learn more about this option in the [Module Options](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/tax/module-options/index.html.md) guide.
+
+### Registration on Application Start
+
+When the Medusa application starts, it registers the Tax Module Providers defined in the `providers` option of the Tax Module.
+
+For each Tax Module Provider, the Medusa application finds all tax provider services defined in them to register.
+
+### TaxProvider Data Model
+
+A registered tax provider is represented by the [TaxProvider data model](https://docs.medusajs.com/references/tax/models/TaxProvider/index.html.md) in the Medusa application.
+
+This data model is used to reference a service in the Tax Module Provider and determine whether it's installed in the application.
+
+![Diagram showcasing the TaxProvider data model](https://res.cloudinary.com/dza7lstvk/image/upload/v1746791254/Medusa%20Resources/tax-provider-model_r6ktjw.jpg)
+
+The `TaxProvider` data model has the following properties:
+
+- `id`: The unique identifier of the tax provider. The ID's format is `tp_{identifier}_{id}`, where:
+  - `identifier` is the value of the `identifier` property in the Tax Module Provider's service.
+  - `id` is the value of the `id` property of the Tax Module Provider in `medusa-config.ts`.
+- `is_enabled`: A boolean indicating whether the tax provider is enabled.
+
+### How to Remove a Tax Provider?
+
+You can remove a registered tax provider from the Medusa application by removing it from the `providers` option in the Tax Module's configuration.
+
+Then, the next time the Medusa application starts, it will set the `is_enabled` property of the `TaxProvider`'s record to `false`. This allows you to re-enable the tax provider later if needed by adding it back to the `providers` option.
+
+
+# Tax Rates and Rules
+
+In this document, you’ll learn about tax rates and rules.
+
+Refer to this [Medusa Admin User Guide](https://docs.medusajs.com/user-guide/settings/tax-regions#manage-tax-rate-overrides/index.html.md) to learn how to manage tax rates using the dashboard.
+
+## What are Tax Rates?
+
+A tax rate is a percentage amount used to calculate the tax amount for each taxable item’s price, such as line items or shipping methods, in a cart. The sum of all calculated tax amounts are then added to the cart’s total as a tax total.
+
+Each tax region has a default tax rate. This tax rate is applied to all taxable items of a cart in that region.
+
+### Combinable Tax Rates
+
+Tax regions can have parent tax regions. To inherit the tax rates of the parent tax region, set the `is_combinable` of the child’s tax rates to `true`.
+
+Then, when tax rates are retrieved for a taxable item in the child region, both the child and the parent tax regions’ applicable rates are returned.
+
+***
+
+## Override Tax Rates with Rules
+
+You can create tax rates that override the default for specific conditions or rules.
+
+For example, you can have a default tax rate is 10%, but for products of type “Shirt” is %15.
+
+A tax region can have multiple tax rates, and each tax rate can have multiple tax rules. The [TaxRateRule data model](https://docs.medusajs.com/references/tax/models/TaxRateRule/index.html.md) represents a tax rate’s rule.
+
+![A diagram showcasing the relation between TaxRegion, TaxRate, and TaxRateRule](https://res.cloudinary.com/dza7lstvk/image/upload/v1711462167/Medusa%20Resources/tax-rate-rule_enzbp2.jpg)
+
+These two properties of the data model identify the rule’s target:
+
+- `reference`: the name of the table in the database that this rule points to. For example, `product_type`.
+- `reference_id`: the ID of the data model’s record that this points to. For example, a product type’s ID.
+
+So, to override the default tax rate for product types “Shirt”, you create a tax rate and associate with it a tax rule whose `reference` is `product_type` and `reference_id` the ID of the “Shirt” product type.
+
+
+# Tax Region
+
+In this document, you’ll learn about tax regions and how to use them with the Region Module.
+
+Refer to this [Medusa Admin User Guide](https://docs.medusajs.com/user-guide/settings/tax-regions/index.html.md) to learn how to manage tax regions using the dashboard.
+
+## What is a Tax Region?
+
+A tax region, represented by the [TaxRegion data model](https://docs.medusajs.com/references/tax/models/TaxRegion/index.html.md), stores tax settings related to a region that your store serves.
+
+Tax regions can inherit settings and rules from a parent tax region.
+
+***
+
+## Tax Rules in a Tax Region
+
+Tax rules define the tax rates and behavior within a tax region. They specify:
+
+- The tax rate percentage.
+- Which products the tax applies to.
+- Other custom rules to determine tax applicability.
+
+Learn more about tax rules in the [Tax Rates and Rules](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/tax/tax-rates-and-rules/index.html.md) guide.
+
+***
+
+## Tax Provider
+
+Each tax region can have a default tax provider. The tax provider is responsible for calculating the tax lines for carts and orders in that region.
+
+You can use Medusa's default tax provider or create a custom one, allowing you to integrate with third-party tax services or implement your own tax calculation logic.
+
+Learn more about tax providers in the [Tax Provider](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/tax/tax-provider/index.html.md) guide.
+
+
+# User Module Options
+
+In this document, you'll learn about the options of the User Module.
+
+## Module Options
+
+```ts title="medusa-config.ts"
+import { Modules } from "@medusajs/framework/utils"
+
+// ...
+
+module.exports = defineConfig({
+  // ...
+  modules: [
     {
-      "attribute": "customer_id",
-      "operator": "eq",
-      "values": [
-        "cus_123"
-      ]
-    }
-  ]
+      resolve: "@medusajs/user",
+      options: {
+        jwt_secret: process.env.JWT_SECRET,
+      },
+    },
+  ],
+})
+```
+
+|Option|Description|Required|
+|---|---|---|---|---|
+|\`jwt\_secret\`|A string indicating the secret used to sign the invite tokens.|Yes|
+
+### Environment Variables
+
+Make sure to add the necessary environment variables for the above options in `.env`:
+
+```bash
+JWT_SECRET=supersecret
+```
+
+
+# User Creation Flows
+
+In this document, learn the different ways to create a user using the User Module.
+
+Refer to this [Medusa Admin User Guide](https://docs.medusajs.com/user-guide/settings/users/index.html.md) to learn how to manage users using the dashboard.
+
+## Straightforward User Creation
+
+To create a user, use the [create method of the User Module’s main service](https://docs.medusajs.com/references/user/create/index.html.md):
+
+```ts
+const user = await userModuleService.createUsers({
+  email: "user@example.com",
+})
+```
+
+You can pair this with the Auth Module to allow the user to authenticate, as explained in a [later section](#create-identity-with-the-auth-module).
+
+***
+
+## Invite Users
+
+To create a user, you can create an invite for them using the [createInvites method](https://docs.medusajs.com/references/user/createInvites/index.html.md) of the User Module's main service:
+
+```ts
+const invite = await userModuleService.createInvites({
+  email: "user@example.com",
+})
+```
+
+Later, you can accept the invite and create a new user for them:
+
+```ts
+const invite =
+  await userModuleService.validateInviteToken("secret_123")
+
+await userModuleService.updateInvites({
+  id: invite.id,
+  accepted: true,
+})
+
+const user = await userModuleService.createUsers({
+  email: invite.email,
+})
+```
+
+### Invite Expiry
+
+An invite has an expiry date. You can renew the expiry date and refresh the token using the [refreshInviteTokens method](https://docs.medusajs.com/references/user/refreshInviteTokens/index.html.md):
+
+```ts
+await userModuleService.refreshInviteTokens(["invite_123"])
+```
+
+***
+
+## Create Identity with the Auth Module
+
+By combining the User and Auth Modules, you can use the Auth Module for authenticating users, and the User Module to manage those users.
+
+So, when a user is authenticated, and you receive the `AuthIdentity` object, you can use it to create a user if it doesn’t exist:
+
+```ts
+const { success, authIdentity } =
+  await authModuleService.authenticate("emailpass", {
+    // ...
+  })
+
+const [, count] = await userModuleService.listAndCountUsers({
+  email: authIdentity.entity_id,
+})
+
+if (!count) {
+  const user = await userModuleService.createUsers({
+    email: authIdentity.entity_id,
+  })
 }
 ```
 
-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`.
-
-
-# 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`.
-
-***
-
-## 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.
-
-
-# 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)
-
-
-# Links between Promotion Module and Other Modules
-
-This document showcases the module links defined between the Promotion Module and other Commerce Modules.
-
-## Summary
-
-The Promotion Module has the following links to other modules:
-
-Read-only links are used to query data across modules, but the relations aren't stored in a pivot table in the database.
-
-|First Data Model|Second Data Model|Type|Description|
-|---|---|---|---|
-|Cart|Promotion|Stored - many-to-many|Learn more|
-|LineItemAdjustment|Promotion|Read-only - has one|Learn more|
-|Order|Promotion|Stored - many-to-many|Learn more|
-
-***
-
-## Cart Module
-
-A promotion can be applied on line items and shipping methods of a cart. Medusa defines a link between the `Cart` and `Promotion` data models.
-
-![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",
-  },
-})
-```
-
-
-# Links between Region Module and Other Modules
-
-This document showcases the module links defined between the Region Module and other Commerce Modules.
-
-## Summary
-
-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|
-|---|---|---|---|
-|Cart|Region|Read-only - has one|Learn more|
-|Order|Region|Read-only - has one|Learn more|
-|Region|PaymentProvider|Stored - many-to-many|Learn more|
-
-***
-
-## 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.
-
-### 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`:
-
-### query.graph
-
-```ts
-const { data: carts } = await query.graph({
-  entity: "cart",
-  fields: [
-    "region.*",
-  ],
-})
-
-// carts[0].region
-```
-
-### useQueryGraphStep
-
-```ts
-import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
-
-// ...
-
-const { data: carts } = useQueryGraphStep({
-  entity: "cart",
-  fields: [
-    "region.*",
-  ],
-})
-
-// 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
-```
-
-### Manage with Link
-
-To manage the payment providers in a region, use [Link](https://docs.medusajs.com/docs/learn/fundamentals/module-links/link/index.html.md):
-
-### link.create
-
-```ts
-import { Modules } from "@medusajs/framework/utils"
-
-// ...
-
-await link.create({
-  [Modules.REGION]: {
-    region_id: "reg_123",
-  },
-  [Modules.PAYMENT]: {
-    payment_provider_id: "pp_stripe_stripe",
-  },
-})
-```
-
-### createRemoteLinkStep
-
-```ts
-import { Modules } from "@medusajs/framework/utils"
-import { createRemoteLinkStep } from "@medusajs/medusa/core-flows"
-
-// ...
-
-createRemoteLinkStep({
-  [Modules.REGION]: {
-    region_id: "reg_123",
-  },
-  [Modules.PAYMENT]: {
-    payment_provider_id: "pp_stripe_stripe",
-  },
-})
-```
-
-
-# Stock Location Concepts
-
-In this document, you’ll learn about the main concepts in the Stock Location Module.
-
-## Stock Location
-
-A stock location, represented by the `StockLocation` data model, represents a location where stock items are kept. For example, a warehouse.
-
-Medusa uses stock locations to provide inventory details, from the Inventory Module, per location.
-
-***
-
-## StockLocationAddress
-
-The `StockLocationAddress` data model belongs to the `StockLocation` data model. It provides more detailed information of the location, such as country code or street address.
-
-
-# Links between Stock Location Module and Other Modules
-
-This document showcases the module links defined between the Stock Location Module and other Commerce Modules.
-
-## Summary
-
-The Stock Location Module has the following links to other modules:
-
-Read-only links are used to query data across modules, but the relations aren't stored in a pivot table in the database.
-
-|First Data Model|Second Data Model|Type|Description|
-|---|---|---|---|
-|FulfillmentSet|StockLocation|Stored - many-to-one|Learn more|
-|FulfillmentProvider|StockLocation|Stored - many-to-many|Learn more|
-|InventoryLevel|StockLocation|Read-only - has many|Learn more|
-|SalesChannel|StockLocation|Stored - many-to-many|Learn more|
-
-***
-
-## Fulfillment Module
-
-A fulfillment set can be conditioned to a specific stock location.
-
-Medusa defines a link between the `FulfillmentSet` and `StockLocation` data models.
-
-![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 fulfillment sets of a stock location with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `fulfillment_sets.*` in `fields`:
-
-To retrieve the fulfillment providers, pass `fulfillment_providers.*` in `fields`.
-
-### query.graph
-
-```ts
-const { data: stockLocations } = await query.graph({
-  entity: "stock_location",
-  fields: [
-    "fulfillment_sets.*",
-  ],
-})
-
-// stockLocations[0].fulfillment_sets
-```
-
-### useQueryGraphStep
-
-```ts
-import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
-
-// ...
-
-const { data: stockLocations } = useQueryGraphStep({
-  entity: "stock_location",
-  fields: [
-    "fulfillment_sets.*",
-  ],
-})
-
-// stockLocations[0].fulfillment_sets
-```
-
-### Manage with Link
-
-To manage the stock location of a fulfillment set, use [Link](https://docs.medusajs.com/docs/learn/fundamentals/module-links/link/index.html.md):
-
-### link.create
-
-```ts
-import { Modules } from "@medusajs/framework/utils"
-
-// ...
-
-await link.create({
-  [Modules.STOCK_LOCATION]: {
-    stock_location_id: "sloc_123",
-  },
-  [Modules.FULFILLMENT]: {
-    fulfillment_set_id: "fset_123",
-  },
-})
-```
-
-### createRemoteLinkStep
-
-```ts
-import { Modules } from "@medusajs/framework/utils"
-import { createRemoteLinkStep } from "@medusajs/medusa/core-flows"
-
-// ...
-
-createRemoteLinkStep({
-  [Modules.STOCK_LOCATION]: {
-    stock_location_id: "sloc_123",
-  },
-  [Modules.FULFILLMENT]: {
-    fulfillment_set_id: "fset_123",
-  },
-})
-```
-
-***
-
-## Inventory Module
-
-Medusa defines a read-only link between the [Inventory Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/inventory/index.html.md)'s `InventoryLevel` data model and the `StockLocation` data model. Because the link is read-only from the `InventoryLevel`'s side, you can only retrieve the stock location of an inventory level, and not the other way around.
-
-### Retrieve with Query
-
-To retrieve the stock locations of an inventory level with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `stock_locations.*` in `fields`:
-
-### query.graph
-
-```ts
-const { data: inventoryLevels } = await query.graph({
-  entity: "inventory_level",
-  fields: [
-    "stock_locations.*",
-  ],
-})
-
-// inventoryLevels[0].stock_locations
-```
-
-### useQueryGraphStep
-
-```ts
-import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
-
-// ...
-
-const { data: inventoryLevels } = useQueryGraphStep({
-  entity: "inventory_level",
-  fields: [
-    "stock_locations.*",
-  ],
-})
-
-// inventoryLevels[0].stock_locations
-```
-
-***
-
-## Sales Channel Module
-
-A stock location is associated with a sales channel. This scopes inventory quantities in a stock location by the associated sales channel.
-
-Medusa defines a link between the `SalesChannel` and `StockLocation` data models.
-
-![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 sales channels of a stock location with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `sales_channels.*` in `fields`:
-
-### query.graph
-
-```ts
-const { data: stockLocations } = await query.graph({
-  entity: "stock_location",
-  fields: [
-    "sales_channels.*",
-  ],
-})
-
-// stockLocations[0].sales_channels
-```
-
-### useQueryGraphStep
-
-```ts
-import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
-
-// ...
-
-const { data: stockLocations } = useQueryGraphStep({
-  entity: "stock_location",
-  fields: [
-    "sales_channels.*",
-  ],
-})
-
-// stockLocations[0].sales_channels
-```
-
-### Manage with Link
-
-To manage the stock locations of a sales channel, use [Link](https://docs.medusajs.com/docs/learn/fundamentals/module-links/link/index.html.md):
-
-### link.create
-
-```ts
-import { Modules } from "@medusajs/framework/utils"
-
-// ...
-
-await link.create({
-  [Modules.SALES_CHANNEL]: {
-    sales_channel_id: "sc_123",
-  },
-  [Modules.STOCK_LOCATION]: {
-    sales_channel_id: "sloc_123",
-  },
-})
-```
-
-### createRemoteLinkStep
-
-```ts
-import { Modules } from "@medusajs/framework/utils"
-import { createRemoteLinkStep } from "@medusajs/medusa/core-flows"
-
-// ...
-
-createRemoteLinkStep({
-  [Modules.SALES_CHANNEL]: {
-    sales_channel_id: "sc_123",
-  },
-  [Modules.STOCK_LOCATION]: {
-    sales_channel_id: "sloc_123",
-  },
-})
-```
-
 
 # Publishable API Keys with Sales Channels
 
@@ -29442,177 +29654,251 @@ createRemoteLinkStep({
 ```
 
 
-# Tax Module Options
+# Stock Location Concepts
 
-In this document, you'll learn about the options of the Tax Module.
+In this document, you’ll learn about the main concepts in the Stock Location Module.
 
-## providers
+## Stock Location
 
-The `providers` option is an array of either tax module providers or path to a file that defines a tax provider.
+A stock location, represented by the `StockLocation` data model, represents a location where stock items are kept. For example, a warehouse.
 
-When the Medusa application starts, these providers are registered and can be used to retrieve tax lines.
+Medusa uses stock locations to provide inventory details, from the Inventory Module, per location.
 
-```ts title="medusa-config.ts"
+***
+
+## StockLocationAddress
+
+The `StockLocationAddress` data model belongs to the `StockLocation` data model. It provides more detailed information of the location, such as country code or street address.
+
+
+# Links between Stock Location Module and Other Modules
+
+This document showcases the module links defined between the Stock Location Module and other Commerce Modules.
+
+## Summary
+
+The Stock Location Module has the following links to other modules:
+
+Read-only links are used to query data across modules, but the relations aren't stored in a pivot table in the database.
+
+|First Data Model|Second Data Model|Type|Description|
+|---|---|---|---|
+|FulfillmentSet|StockLocation|Stored - many-to-one|Learn more|
+|FulfillmentProvider|StockLocation|Stored - many-to-many|Learn more|
+|InventoryLevel|StockLocation|Read-only - has many|Learn more|
+|SalesChannel|StockLocation|Stored - many-to-many|Learn more|
+
+***
+
+## Fulfillment Module
+
+A fulfillment set can be conditioned to a specific stock location.
+
+Medusa defines a link between the `FulfillmentSet` and `StockLocation` data models.
+
+![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 fulfillment sets of a stock location with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `fulfillment_sets.*` in `fields`:
+
+To retrieve the fulfillment providers, pass `fulfillment_providers.*` in `fields`.
+
+### query.graph
+
+```ts
+const { data: stockLocations } = await query.graph({
+  entity: "stock_location",
+  fields: [
+    "fulfillment_sets.*",
+  ],
+})
+
+// stockLocations[0].fulfillment_sets
+```
+
+### useQueryGraphStep
+
+```ts
+import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
+
+// ...
+
+const { data: stockLocations } = useQueryGraphStep({
+  entity: "stock_location",
+  fields: [
+    "fulfillment_sets.*",
+  ],
+})
+
+// stockLocations[0].fulfillment_sets
+```
+
+### Manage with Link
+
+To manage the stock location of a fulfillment set, use [Link](https://docs.medusajs.com/docs/learn/fundamentals/module-links/link/index.html.md):
+
+### link.create
+
+```ts
 import { Modules } from "@medusajs/framework/utils"
 
 // ...
 
-module.exports = defineConfig({
-  // ...
-  modules: [
-    {
-      resolve: "@medusajs/tax",
-      options: {
-        providers: [
-          {
-            resolve: "./path/to/my-provider",
-            id: "my-provider",
-            options: {
-              // ...
-            },
-          },
-        ],
-      },
-    },
-  ],
+await link.create({
+  [Modules.STOCK_LOCATION]: {
+    stock_location_id: "sloc_123",
+  },
+  [Modules.FULFILLMENT]: {
+    fulfillment_set_id: "fset_123",
+  },
 })
 ```
 
-The objects in the array accept the following properties:
-
-- `resolve`: A string indicating the package name of the module provider or the path to it.
-- `id`: A string indicating the provider's unique name or ID.
-- `options`: An optional object of the module provider's options.
-
-
-# Tax Rates and Rules
-
-In this document, you’ll learn about tax rates and rules.
-
-Refer to this [Medusa Admin User Guide](https://docs.medusajs.com/user-guide/settings/tax-regions#manage-tax-rate-overrides/index.html.md) to learn how to manage tax rates using the dashboard.
-
-## What are Tax Rates?
-
-A tax rate is a percentage amount used to calculate the tax amount for each taxable item’s price, such as line items or shipping methods, in a cart. The sum of all calculated tax amounts are then added to the cart’s total as a tax total.
-
-Each tax region has a default tax rate. This tax rate is applied to all taxable items of a cart in that region.
-
-### Combinable Tax Rates
-
-Tax regions can have parent tax regions. To inherit the tax rates of the parent tax region, set the `is_combinable` of the child’s tax rates to `true`.
-
-Then, when tax rates are retrieved for a taxable item in the child region, both the child and the parent tax regions’ applicable rates are returned.
-
-***
-
-## Override Tax Rates with Rules
-
-You can create tax rates that override the default for specific conditions or rules.
-
-For example, you can have a default tax rate is 10%, but for products of type “Shirt” is %15.
-
-A tax region can have multiple tax rates, and each tax rate can have multiple tax rules. The [TaxRateRule data model](https://docs.medusajs.com/references/tax/models/TaxRateRule/index.html.md) represents a tax rate’s rule.
-
-![A diagram showcasing the relation between TaxRegion, TaxRate, and TaxRateRule](https://res.cloudinary.com/dza7lstvk/image/upload/v1711462167/Medusa%20Resources/tax-rate-rule_enzbp2.jpg)
-
-These two properties of the data model identify the rule’s target:
-
-- `reference`: the name of the table in the database that this rule points to. For example, `product_type`.
-- `reference_id`: the ID of the data model’s record that this points to. For example, a product type’s ID.
-
-So, to override the default tax rate for product types “Shirt”, you create a tax rate and associate with it a tax rule whose `reference` is `product_type` and `reference_id` the ID of the “Shirt” product type.
-
-
-# Tax Calculation with the Tax Provider
-
-In this document, you’ll learn how tax lines are calculated and what a tax provider is.
-
-## Tax Lines Calculation
-
-Tax lines are calculated and retrieved using the [getTaxLines method of the Tax Module’s main service](https://docs.medusajs.com/references/tax/getTaxLines/index.html.md). It accepts an array of line items and shipping methods, and the context of the calculation.
-
-For example:
+### createRemoteLinkStep
 
 ```ts
-const taxLines = await taxModuleService.getTaxLines(
-  [
-    {
-      id: "cali_123",
-      product_id: "prod_123",
-      unit_price: 1000,
-      quantity: 1,
-    },
-    {
-      id: "casm_123",
-      shipping_option_id: "so_123",
-      unit_price: 2000,
-    },
-  ],
-  {
-    address: {
-      country_code: "us",
-    },
-  }
-)
-```
+import { Modules } from "@medusajs/framework/utils"
+import { createRemoteLinkStep } from "@medusajs/medusa/core-flows"
 
-The context object is used to determine which tax regions and rates to use in the calculation. It includes properties related to the address and customer.
+// ...
 
-The example above retrieves the tax lines based on the tax region for the United States.
-
-The method returns tax lines for the line item and shipping methods. For example:
-
-```json
-[
-  {
-    "line_item_id": "cali_123",
-    "rate_id": "txr_1",
-    "rate": 10,
-    "code": "XXX",
-    "name": "Tax Rate 1"
+createRemoteLinkStep({
+  [Modules.STOCK_LOCATION]: {
+    stock_location_id: "sloc_123",
   },
-  {
-    "shipping_line_id": "casm_123",
-    "rate_id": "txr_2",
-    "rate": 5,
-    "code": "YYY",
-    "name": "Tax Rate 2"
-  }
-]
+  [Modules.FULFILLMENT]: {
+    fulfillment_set_id: "fset_123",
+  },
+})
 ```
 
 ***
 
-## Using the Tax Provider in the Calculation
+## Inventory Module
 
-The tax lines retrieved by the `getTaxLines` method are actually retrieved from the tax region’s provider.
+Medusa defines a read-only link between the [Inventory Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/inventory/index.html.md)'s `InventoryLevel` data model and the `StockLocation` data model. Because the link is read-only from the `InventoryLevel`'s side, you can only retrieve the stock location of an inventory level, and not the other way around.
 
-A tax module provider whose main service implements the logic to shape tax lines. Each tax region has a tax provider.
+### Retrieve with Query
 
-The Tax Module provides a `system` tax provider that only transforms calculated item and shipping tax rates into the required return type.
+To retrieve the stock locations of an inventory level with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `stock_locations.*` in `fields`:
 
-{/* ---
+### query.graph
 
-TODO add once tax provider guide is updated + add module providers match other modules.
+```ts
+const { data: inventoryLevels } = await query.graph({
+  entity: "inventory_level",
+  fields: [
+    "stock_locations.*",
+  ],
+})
 
-## Create Tax Provider
+// inventoryLevels[0].stock_locations
+```
 
-Refer to [this guide](/modules/tax/provider) to learn more about creating a tax provider. */}
+### useQueryGraphStep
 
+```ts
+import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
 
-# Tax Region
+// ...
 
-In this document, you’ll learn about tax regions and how to use them with the Region Module.
+const { data: inventoryLevels } = useQueryGraphStep({
+  entity: "inventory_level",
+  fields: [
+    "stock_locations.*",
+  ],
+})
 
-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.
+// inventoryLevels[0].stock_locations
+```
 
-## 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.
+## Sales Channel Module
 
-Tax regions can inherit settings and rules from a parent tax region.
+A stock location is associated with a sales channel. This scopes inventory quantities in a stock location by the associated sales channel.
 
-Each tax region has tax rules and a tax provider.
+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 sales channels of a stock location with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `sales_channels.*` in `fields`:
+
+### query.graph
+
+```ts
+const { data: stockLocations } = await query.graph({
+  entity: "stock_location",
+  fields: [
+    "sales_channels.*",
+  ],
+})
+
+// stockLocations[0].sales_channels
+```
+
+### useQueryGraphStep
+
+```ts
+import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
+
+// ...
+
+const { data: stockLocations } = useQueryGraphStep({
+  entity: "stock_location",
+  fields: [
+    "sales_channels.*",
+  ],
+})
+
+// stockLocations[0].sales_channels
+```
+
+### Manage with Link
+
+To manage the stock locations of a sales channel, use [Link](https://docs.medusajs.com/docs/learn/fundamentals/module-links/link/index.html.md):
+
+### link.create
+
+```ts
+import { Modules } from "@medusajs/framework/utils"
+
+// ...
+
+await link.create({
+  [Modules.SALES_CHANNEL]: {
+    sales_channel_id: "sc_123",
+  },
+  [Modules.STOCK_LOCATION]: {
+    sales_channel_id: "sloc_123",
+  },
+})
+```
+
+### createRemoteLinkStep
+
+```ts
+import { Modules } from "@medusajs/framework/utils"
+import { createRemoteLinkStep } from "@medusajs/medusa/core-flows"
+
+// ...
+
+createRemoteLinkStep({
+  [Modules.SALES_CHANNEL]: {
+    sales_channel_id: "sc_123",
+  },
+  [Modules.STOCK_LOCATION]: {
+    sales_channel_id: "sloc_123",
+  },
+})
+```
 
 
 # Links between Store Module and Other Modules
@@ -29672,123 +29958,6 @@ const { data: stores } = useQueryGraphStep({
 ```
 
 
-# User Module Options
-
-In this document, you'll learn about the options of the User Module.
-
-## Module Options
-
-```ts title="medusa-config.ts"
-import { Modules } from "@medusajs/framework/utils"
-
-// ...
-
-module.exports = defineConfig({
-  // ...
-  modules: [
-    {
-      resolve: "@medusajs/user",
-      options: {
-        jwt_secret: process.env.JWT_SECRET,
-      },
-    },
-  ],
-})
-```
-
-|Option|Description|Required|
-|---|---|---|---|---|
-|\`jwt\_secret\`|A string indicating the secret used to sign the invite tokens.|Yes|
-
-### Environment Variables
-
-Make sure to add the necessary environment variables for the above options in `.env`:
-
-```bash
-JWT_SECRET=supersecret
-```
-
-
-# User Creation Flows
-
-In this document, learn the different ways to create a user using the User Module.
-
-Refer to this [Medusa Admin User Guide](https://docs.medusajs.com/user-guide/settings/users/index.html.md) to learn how to manage users using the dashboard.
-
-## Straightforward User Creation
-
-To create a user, use the [create method of the User Module’s main service](https://docs.medusajs.com/references/user/create/index.html.md):
-
-```ts
-const user = await userModuleService.createUsers({
-  email: "user@example.com",
-})
-```
-
-You can pair this with the Auth Module to allow the user to authenticate, as explained in a [later section](#create-identity-with-the-auth-module).
-
-***
-
-## Invite Users
-
-To create a user, you can create an invite for them using the [createInvites method](https://docs.medusajs.com/references/user/createInvites/index.html.md) of the User Module's main service:
-
-```ts
-const invite = await userModuleService.createInvites({
-  email: "user@example.com",
-})
-```
-
-Later, you can accept the invite and create a new user for them:
-
-```ts
-const invite =
-  await userModuleService.validateInviteToken("secret_123")
-
-await userModuleService.updateInvites({
-  id: invite.id,
-  accepted: true,
-})
-
-const user = await userModuleService.createUsers({
-  email: invite.email,
-})
-```
-
-### Invite Expiry
-
-An invite has an expiry date. You can renew the expiry date and refresh the token using the [refreshInviteTokens method](https://docs.medusajs.com/references/user/refreshInviteTokens/index.html.md):
-
-```ts
-await userModuleService.refreshInviteTokens(["invite_123"])
-```
-
-***
-
-## Create Identity with the Auth Module
-
-By combining the User and Auth Modules, you can use the Auth Module for authenticating users, and the User Module to manage those users.
-
-So, when a user is authenticated, and you receive the `AuthIdentity` object, you can use it to create a user if it doesn’t exist:
-
-```ts
-const { success, authIdentity } =
-  await authModuleService.authenticate("emailpass", {
-    // ...
-  })
-
-const [, count] = await userModuleService.listAndCountUsers({
-  email: authIdentity.entity_id,
-})
-
-if (!count) {
-  const user = await userModuleService.createUsers({
-    email: authIdentity.entity_id,
-  })
-}
-```
-
-
 # Emailpass Auth Module Provider
 
 In this document, you’ll learn about the Emailpass auth module provider and how to install and use it in the Auth Module.
@@ -29851,175 +30020,6 @@ const hashConfig = \{
 - [How to register a customer using email and password](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/storefront-development/customers/register/index.html.md)
 
 
-# GitHub Auth Module Provider
-
-In this document, you’ll learn about the GitHub Auth Module Provider and how to install and use it in the Auth Module.
-
-The Github Auth Module Provider authenticates users with their GitHub account.
-
-Learn about the authentication flow in [this guide](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/auth/authentication-route/index.html.md).
-
-***
-
-## Register the Github Auth Module Provider
-
-### Prerequisites
-
-- [Register GitHub App. When setting the Callback URL, set it to a URL in your frontend that later uses Medusa's callback route to validate the authentication.](https://docs.github.com/en/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app)
-- [Retrieve the client ID and client secret of your GitHub App](https://docs.github.com/en/rest/authentication/authenticating-to-the-rest-api?apiVersion=2022-11-28#using-basic-authentication)
-
-Add the module to the array of providers passed to the Auth Module:
-
-```ts title="medusa-config.ts"
-import { Modules, ContainerRegistrationKeys } from "@medusajs/framework/utils"
-
-// ...
-
-module.exports = defineConfig({
-  // ...
-  modules: [
-    {
-      resolve: "@medusajs/medusa/auth",
-      dependencies: [Modules.CACHE, ContainerRegistrationKeys.LOGGER],
-      options: {
-        providers: [
-          // other providers...
-          {
-            resolve: "@medusajs/medusa/auth-github",
-            id: "github",
-            options: {
-              clientId: process.env.GITHUB_CLIENT_ID,
-              clientSecret: process.env.GITHUB_CLIENT_SECRET,
-              callbackUrl: process.env.GITHUB_CALLBACK_URL,
-            },
-          },
-        ],
-      },
-    },
-  ],
-})
-```
-
-### Environment Variables
-
-Make sure to add the necessary environment variables for the above options in `.env`:
-
-```plain
-GITHUB_CLIENT_ID=<YOUR_GITHUB_CLIENT_ID>
-GITHUB_CLIENT_SECRET=<YOUR_GITHUB_CLIENT_SECRET>
-GITHUB_CALLBACK_URL=<YOUR_GITHUB_CALLBACK_URL>
-```
-
-### Module Options
-
-|Configuration|Description|Required|
-|---|---|---|---|---|
-|\`clientId\`|A string indicating the client ID of your GitHub app.|Yes|
-|\`clientSecret\`|A string indicating the client secret of your GitHub app.|Yes|
-|\`callbackUrl\`|A string indicating the URL to redirect to in your frontend after the user completes their authentication in GitHub.|Yes|
-
-***
-
-## Override Callback URL During Authentication
-
-In many cases, you may have different callback URL for actor types. For example, you may redirect admin users to a different URL than customers after authentication.
-
-The [Authenticate or Login API Route](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/auth/authentication-route#login-route/index.html.md) can accept a `callback_url` body parameter to override the provider's `callbackUrl` option. Learn more in [this documentation](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/auth/authentication-route#login-route/index.html.md).
-
-***
-
-## Examples
-
-- [How to implement third-party / social login in the storefront.](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/storefront-development/customers/third-party-login/index.html.md).
-
-
-# Google Auth Module Provider
-
-In this document, you’ll learn about the Google Auth Module Provider and how to install and use it in the Auth Module.
-
-The Google Auth Module Provider authenticates users with their Google account.
-
-Learn about the authentication flow for third-party providers in [this guide](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).
-
-***
-
-## Register the Google Auth Module Provider
-
-### Prerequisites
-
-- [Create a project in Google Cloud.](https://cloud.google.com/resource-manager/docs/creating-managing-projects)
-- [Create authorization credentials. When setting the Redirect Uri, set it to a URL in your frontend that later uses Medusa's callback route to validate the authentication.](https://developers.google.com/identity/protocols/oauth2/web-server#creatingcred)
-
-Add the module to the array of providers passed to the Auth Module:
-
-```ts title="medusa-config.ts"
-import { Modules, ContainerRegistrationKeys } from "@medusajs/framework/utils"
-
-// ...
-
-module.exports = defineConfig({
-  // ...
-  modules: [
-    {
-      // ...
-      [Modules.AUTH]: {
-        resolve: "@medusajs/medusa/auth",
-        dependencies: [Modules.CACHE, ContainerRegistrationKeys.LOGGER],
-        options: {
-          providers: [
-            // other providers...
-            {
-              resolve: "@medusajs/medusa/auth-google",
-              id: "google",
-              options: {
-                clientId: process.env.GOOGLE_CLIENT_ID,
-                clientSecret: process.env.GOOGLE_CLIENT_SECRET,
-                callbackUrl: process.env.GOOGLE_CALLBACK_URL,
-              },
-            },
-          ],
-        },
-      },
-    },
-  ],
-})
-```
-
-### Environment Variables
-
-Make sure to add the necessary environment variables for the above options in `.env`:
-
-```plain
-GOOGLE_CLIENT_ID=<YOUR_GOOGLE_CLIENT_ID>
-GOOGLE_CLIENT_SECRET=<YOUR_GOOGLE_CLIENT_SECRET>
-GOOGLE_CALLBACK_URL=<YOUR_GOOGLE_CALLBACK_URL>
-```
-
-### Module Options
-
-|Configuration|Description|Required|
-|---|---|---|---|---|
-|\`clientId\`|A string indicating the |Yes|
-|\`clientSecret\`|A string indicating the |Yes|
-|\`callbackUrl\`|A string indicating the URL to redirect to in your frontend after the user completes their authentication in Google.|Yes|
-
-***
-
-***
-
-## Override Callback URL During Authentication
-
-In many cases, you may have different callback URL for actor types. For example, you may redirect admin users to a different URL than customers after authentication.
-
-The [Authenticate or Login API Route](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/auth/authentication-route#login-route/index.html.md) can accept a `callback_url` body parameter to override the provider's `callbackUrl` option. Learn more in [this documentation](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/auth/authentication-route#login-route/index.html.md).
-
-***
-
-## Examples
-
-- [How to implement Google social login in the storefront](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/storefront-development/customers/third-party-login/index.html.md).
-
-
 # Stripe Module Provider
 
 In this document, you’ll learn about the Stripe Module Provider and how to configure it in the Payment Module.
@@ -30150,6 +30150,175 @@ When you set up the webhook in Stripe, choose the following events to listen to:
 - [Add Saved Payment Methods with Stripe](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/how-to-tutorials/tutorials/saved-payment-methods/index.html.md).
 
 
+# Google Auth Module Provider
+
+In this document, you’ll learn about the Google Auth Module Provider and how to install and use it in the Auth Module.
+
+The Google Auth Module Provider authenticates users with their Google account.
+
+Learn about the authentication flow for third-party providers in [this guide](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).
+
+***
+
+## Register the Google Auth Module Provider
+
+### Prerequisites
+
+- [Create a project in Google Cloud.](https://cloud.google.com/resource-manager/docs/creating-managing-projects)
+- [Create authorization credentials. When setting the Redirect Uri, set it to a URL in your frontend that later uses Medusa's callback route to validate the authentication.](https://developers.google.com/identity/protocols/oauth2/web-server#creatingcred)
+
+Add the module to the array of providers passed to the Auth Module:
+
+```ts title="medusa-config.ts"
+import { Modules, ContainerRegistrationKeys } from "@medusajs/framework/utils"
+
+// ...
+
+module.exports = defineConfig({
+  // ...
+  modules: [
+    {
+      // ...
+      [Modules.AUTH]: {
+        resolve: "@medusajs/medusa/auth",
+        dependencies: [Modules.CACHE, ContainerRegistrationKeys.LOGGER],
+        options: {
+          providers: [
+            // other providers...
+            {
+              resolve: "@medusajs/medusa/auth-google",
+              id: "google",
+              options: {
+                clientId: process.env.GOOGLE_CLIENT_ID,
+                clientSecret: process.env.GOOGLE_CLIENT_SECRET,
+                callbackUrl: process.env.GOOGLE_CALLBACK_URL,
+              },
+            },
+          ],
+        },
+      },
+    },
+  ],
+})
+```
+
+### Environment Variables
+
+Make sure to add the necessary environment variables for the above options in `.env`:
+
+```plain
+GOOGLE_CLIENT_ID=<YOUR_GOOGLE_CLIENT_ID>
+GOOGLE_CLIENT_SECRET=<YOUR_GOOGLE_CLIENT_SECRET>
+GOOGLE_CALLBACK_URL=<YOUR_GOOGLE_CALLBACK_URL>
+```
+
+### Module Options
+
+|Configuration|Description|Required|
+|---|---|---|---|---|
+|\`clientId\`|A string indicating the |Yes|
+|\`clientSecret\`|A string indicating the |Yes|
+|\`callbackUrl\`|A string indicating the URL to redirect to in your frontend after the user completes their authentication in Google.|Yes|
+
+***
+
+***
+
+## Override Callback URL During Authentication
+
+In many cases, you may have different callback URL for actor types. For example, you may redirect admin users to a different URL than customers after authentication.
+
+The [Authenticate or Login API Route](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/auth/authentication-route#login-route/index.html.md) can accept a `callback_url` body parameter to override the provider's `callbackUrl` option. Learn more in [this documentation](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/auth/authentication-route#login-route/index.html.md).
+
+***
+
+## Examples
+
+- [How to implement Google social login in the storefront](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/storefront-development/customers/third-party-login/index.html.md).
+
+
+# GitHub Auth Module Provider
+
+In this document, you’ll learn about the GitHub Auth Module Provider and how to install and use it in the Auth Module.
+
+The Github Auth Module Provider authenticates users with their GitHub account.
+
+Learn about the authentication flow in [this guide](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/auth/authentication-route/index.html.md).
+
+***
+
+## Register the Github Auth Module Provider
+
+### Prerequisites
+
+- [Register GitHub App. When setting the Callback URL, set it to a URL in your frontend that later uses Medusa's callback route to validate the authentication.](https://docs.github.com/en/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app)
+- [Retrieve the client ID and client secret of your GitHub App](https://docs.github.com/en/rest/authentication/authenticating-to-the-rest-api?apiVersion=2022-11-28#using-basic-authentication)
+
+Add the module to the array of providers passed to the Auth Module:
+
+```ts title="medusa-config.ts"
+import { Modules, ContainerRegistrationKeys } from "@medusajs/framework/utils"
+
+// ...
+
+module.exports = defineConfig({
+  // ...
+  modules: [
+    {
+      resolve: "@medusajs/medusa/auth",
+      dependencies: [Modules.CACHE, ContainerRegistrationKeys.LOGGER],
+      options: {
+        providers: [
+          // other providers...
+          {
+            resolve: "@medusajs/medusa/auth-github",
+            id: "github",
+            options: {
+              clientId: process.env.GITHUB_CLIENT_ID,
+              clientSecret: process.env.GITHUB_CLIENT_SECRET,
+              callbackUrl: process.env.GITHUB_CALLBACK_URL,
+            },
+          },
+        ],
+      },
+    },
+  ],
+})
+```
+
+### Environment Variables
+
+Make sure to add the necessary environment variables for the above options in `.env`:
+
+```plain
+GITHUB_CLIENT_ID=<YOUR_GITHUB_CLIENT_ID>
+GITHUB_CLIENT_SECRET=<YOUR_GITHUB_CLIENT_SECRET>
+GITHUB_CALLBACK_URL=<YOUR_GITHUB_CALLBACK_URL>
+```
+
+### Module Options
+
+|Configuration|Description|Required|
+|---|---|---|---|---|
+|\`clientId\`|A string indicating the client ID of your GitHub app.|Yes|
+|\`clientSecret\`|A string indicating the client secret of your GitHub app.|Yes|
+|\`callbackUrl\`|A string indicating the URL to redirect to in your frontend after the user completes their authentication in GitHub.|Yes|
+
+***
+
+## Override Callback URL During Authentication
+
+In many cases, you may have different callback URL for actor types. For example, you may redirect admin users to a different URL than customers after authentication.
+
+The [Authenticate or Login API Route](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/auth/authentication-route#login-route/index.html.md) can accept a `callback_url` body parameter to override the provider's `callbackUrl` option. Learn more in [this documentation](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/auth/authentication-route#login-route/index.html.md).
+
+***
+
+## Examples
+
+- [How to implement third-party / social login in the storefront.](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/storefront-development/customers/third-party-login/index.html.md).
+
+
 # Get Product Variant Prices using Query
 
 In this document, you'll learn how to retrieve product variant prices in the Medusa application using [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md).
@@ -30570,357 +30739,357 @@ Then, you pass the first sales channel ID to the `getVariantAvailability` functi
 
 ## Workflows
 
-- [batchLinksWorkflow](https://docs.medusajs.com/references/medusa-workflows/batchLinksWorkflow/index.html.md)
-- [createLinksWorkflow](https://docs.medusajs.com/references/medusa-workflows/createLinksWorkflow/index.html.md)
-- [updateLinksWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateLinksWorkflow/index.html.md)
-- [dismissLinksWorkflow](https://docs.medusajs.com/references/medusa-workflows/dismissLinksWorkflow/index.html.md)
+- [createApiKeysWorkflow](https://docs.medusajs.com/references/medusa-workflows/createApiKeysWorkflow/index.html.md)
 - [deleteApiKeysWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteApiKeysWorkflow/index.html.md)
 - [linkSalesChannelsToApiKeyWorkflow](https://docs.medusajs.com/references/medusa-workflows/linkSalesChannelsToApiKeyWorkflow/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)
 - [updateApiKeysWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateApiKeysWorkflow/index.html.md)
-- [createCustomerAddressesWorkflow](https://docs.medusajs.com/references/medusa-workflows/createCustomerAddressesWorkflow/index.html.md)
+- [revokeApiKeysWorkflow](https://docs.medusajs.com/references/medusa-workflows/revokeApiKeysWorkflow/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)
 - [createCustomersWorkflow](https://docs.medusajs.com/references/medusa-workflows/createCustomersWorkflow/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)
 - [updateCustomerAddressesWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateCustomerAddressesWorkflow/index.html.md)
-- [deleteCustomersWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteCustomersWorkflow/index.html.md)
 - [updateCustomersWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateCustomersWorkflow/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)
-- [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)
-- [cancelDraftOrderEditWorkflow](https://docs.medusajs.com/references/medusa-workflows/cancelDraftOrderEditWorkflow/index.html.md)
-- [removeDraftOrderActionItemWorkflow](https://docs.medusajs.com/references/medusa-workflows/removeDraftOrderActionItemWorkflow/index.html.md)
-- [convertDraftOrderWorkflow](https://docs.medusajs.com/references/medusa-workflows/convertDraftOrderWorkflow/index.html.md)
-- [removeDraftOrderActionShippingMethodWorkflow](https://docs.medusajs.com/references/medusa-workflows/removeDraftOrderActionShippingMethodWorkflow/index.html.md)
-- [removeDraftOrderPromotionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/removeDraftOrderPromotionsWorkflow/index.html.md)
-- [requestDraftOrderEditWorkflow](https://docs.medusajs.com/references/medusa-workflows/requestDraftOrderEditWorkflow/index.html.md)
-- [removeDraftOrderShippingMethodWorkflow](https://docs.medusajs.com/references/medusa-workflows/removeDraftOrderShippingMethodWorkflow/index.html.md)
-- [updateDraftOrderActionItemWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateDraftOrderActionItemWorkflow/index.html.md)
-- [convertDraftOrderStep](https://docs.medusajs.com/references/medusa-workflows/convertDraftOrderStep/index.html.md)
-- [updateDraftOrderActionShippingMethodWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateDraftOrderActionShippingMethodWorkflow/index.html.md)
-- [updateDraftOrderShippingMethodWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateDraftOrderShippingMethodWorkflow/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)
-- [updateDraftOrderStep](https://docs.medusajs.com/references/medusa-workflows/updateDraftOrderStep/index.html.md)
-- [createDefaultsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createDefaultsWorkflow/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)
-- [confirmVariantInventoryWorkflow](https://docs.medusajs.com/references/medusa-workflows/confirmVariantInventoryWorkflow/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)
-- [createPaymentCollectionForCartWorkflow](https://docs.medusajs.com/references/medusa-workflows/createPaymentCollectionForCartWorkflow/index.html.md)
-- [createCartWorkflow](https://docs.medusajs.com/references/medusa-workflows/createCartWorkflow/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)
-- [refreshCartItemsWorkflow](https://docs.medusajs.com/references/medusa-workflows/refreshCartItemsWorkflow/index.html.md)
-- [refreshCartShippingMethodsWorkflow](https://docs.medusajs.com/references/medusa-workflows/refreshCartShippingMethodsWorkflow/index.html.md)
-- [listShippingOptionsForCartWorkflow](https://docs.medusajs.com/references/medusa-workflows/listShippingOptionsForCartWorkflow/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)
-- [updateCartPromotionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateCartPromotionsWorkflow/index.html.md)
-- [updateCartWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateCartWorkflow/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)
-- [updateLineItemInCartWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateLineItemInCartWorkflow/index.html.md)
-- [generateResetPasswordTokenWorkflow](https://docs.medusajs.com/references/medusa-workflows/generateResetPasswordTokenWorkflow/index.html.md)
-- [batchShippingOptionRulesWorkflow](https://docs.medusajs.com/references/medusa-workflows/batchShippingOptionRulesWorkflow/index.html.md)
-- [calculateShippingOptionsPricesWorkflow](https://docs.medusajs.com/references/medusa-workflows/calculateShippingOptionsPricesWorkflow/index.html.md)
-- [createFulfillmentWorkflow](https://docs.medusajs.com/references/medusa-workflows/createFulfillmentWorkflow/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)
-- [createServiceZonesWorkflow](https://docs.medusajs.com/references/medusa-workflows/createServiceZonesWorkflow/index.html.md)
-- [createShipmentWorkflow](https://docs.medusajs.com/references/medusa-workflows/createShipmentWorkflow/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)
-- [createShippingOptionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createShippingOptionsWorkflow/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)
-- [updateServiceZonesWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateServiceZonesWorkflow/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)
-- [updateShippingOptionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateShippingOptionsWorkflow/index.html.md)
-- [updateShippingProfilesWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateShippingProfilesWorkflow/index.html.md)
-- [validateFulfillmentDeliverabilityStep](https://docs.medusajs.com/references/medusa-workflows/validateFulfillmentDeliverabilityStep/index.html.md)
-- [uploadFilesWorkflow](https://docs.medusajs.com/references/medusa-workflows/uploadFilesWorkflow/index.html.md)
-- [deleteFilesWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteFilesWorkflow/index.html.md)
 - [createCustomerGroupsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createCustomerGroupsWorkflow/index.html.md)
 - [deleteCustomerGroupsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteCustomerGroupsWorkflow/index.html.md)
 - [linkCustomerGroupsToCustomerWorkflow](https://docs.medusajs.com/references/medusa-workflows/linkCustomerGroupsToCustomerWorkflow/index.html.md)
 - [linkCustomersToCustomerGroupWorkflow](https://docs.medusajs.com/references/medusa-workflows/linkCustomersToCustomerGroupWorkflow/index.html.md)
 - [updateCustomerGroupsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateCustomerGroupsWorkflow/index.html.md)
+- [createLinksWorkflow](https://docs.medusajs.com/references/medusa-workflows/createLinksWorkflow/index.html.md)
+- [batchLinksWorkflow](https://docs.medusajs.com/references/medusa-workflows/batchLinksWorkflow/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)
+- [listShippingOptionsForCartWithPricingWorkflow](https://docs.medusajs.com/references/medusa-workflows/listShippingOptionsForCartWithPricingWorkflow/index.html.md)
+- [deleteCartCreditLinesWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteCartCreditLinesWorkflow/index.html.md)
+- [refreshCartItemsWorkflow](https://docs.medusajs.com/references/medusa-workflows/refreshCartItemsWorkflow/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)
+- [refreshPaymentCollectionForCartWorkflow](https://docs.medusajs.com/references/medusa-workflows/refreshPaymentCollectionForCartWorkflow/index.html.md)
+- [updateCartPromotionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateCartPromotionsWorkflow/index.html.md)
+- [updateCartWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateCartWorkflow/index.html.md)
+- [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)
+- [addDraftOrderItemsWorkflow](https://docs.medusajs.com/references/medusa-workflows/addDraftOrderItemsWorkflow/index.html.md)
+- [beginDraftOrderEditWorkflow](https://docs.medusajs.com/references/medusa-workflows/beginDraftOrderEditWorkflow/index.html.md)
+- [addDraftOrderPromotionWorkflow](https://docs.medusajs.com/references/medusa-workflows/addDraftOrderPromotionWorkflow/index.html.md)
+- [addDraftOrderShippingMethodsWorkflow](https://docs.medusajs.com/references/medusa-workflows/addDraftOrderShippingMethodsWorkflow/index.html.md)
+- [cancelDraftOrderEditWorkflow](https://docs.medusajs.com/references/medusa-workflows/cancelDraftOrderEditWorkflow/index.html.md)
+- [convertDraftOrderStep](https://docs.medusajs.com/references/medusa-workflows/convertDraftOrderStep/index.html.md)
+- [convertDraftOrderWorkflow](https://docs.medusajs.com/references/medusa-workflows/convertDraftOrderWorkflow/index.html.md)
+- [confirmDraftOrderEditWorkflow](https://docs.medusajs.com/references/medusa-workflows/confirmDraftOrderEditWorkflow/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)
+- [removeDraftOrderPromotionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/removeDraftOrderPromotionsWorkflow/index.html.md)
+- [removeDraftOrderShippingMethodWorkflow](https://docs.medusajs.com/references/medusa-workflows/removeDraftOrderShippingMethodWorkflow/index.html.md)
+- [requestDraftOrderEditWorkflow](https://docs.medusajs.com/references/medusa-workflows/requestDraftOrderEditWorkflow/index.html.md)
+- [updateDraftOrderItemWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateDraftOrderItemWorkflow/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)
+- [updateDraftOrderShippingMethodWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateDraftOrderShippingMethodWorkflow/index.html.md)
+- [updateDraftOrderStep](https://docs.medusajs.com/references/medusa-workflows/updateDraftOrderStep/index.html.md)
+- [updateDraftOrderWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateDraftOrderWorkflow/index.html.md)
+- [createDefaultsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createDefaultsWorkflow/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)
+- [batchShippingOptionRulesWorkflow](https://docs.medusajs.com/references/medusa-workflows/batchShippingOptionRulesWorkflow/index.html.md)
+- [calculateShippingOptionsPricesWorkflow](https://docs.medusajs.com/references/medusa-workflows/calculateShippingOptionsPricesWorkflow/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)
+- [createServiceZonesWorkflow](https://docs.medusajs.com/references/medusa-workflows/createServiceZonesWorkflow/index.html.md)
+- [createShipmentWorkflow](https://docs.medusajs.com/references/medusa-workflows/createShipmentWorkflow/index.html.md)
+- [createShippingOptionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createShippingOptionsWorkflow/index.html.md)
+- [createShippingProfilesWorkflow](https://docs.medusajs.com/references/medusa-workflows/createShippingProfilesWorkflow/index.html.md)
+- [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)
+- [updateFulfillmentWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateFulfillmentWorkflow/index.html.md)
+- [markFulfillmentAsDeliveredWorkflow](https://docs.medusajs.com/references/medusa-workflows/markFulfillmentAsDeliveredWorkflow/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)
+- [validateFulfillmentDeliverabilityStep](https://docs.medusajs.com/references/medusa-workflows/validateFulfillmentDeliverabilityStep/index.html.md)
+- [updateShippingProfilesWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateShippingProfilesWorkflow/index.html.md)
+- [acceptInviteWorkflow](https://docs.medusajs.com/references/medusa-workflows/acceptInviteWorkflow/index.html.md)
+- [refreshInviteTokensWorkflow](https://docs.medusajs.com/references/medusa-workflows/refreshInviteTokensWorkflow/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)
 - [batchInventoryItemLevelsWorkflow](https://docs.medusajs.com/references/medusa-workflows/batchInventoryItemLevelsWorkflow/index.html.md)
 - [bulkCreateDeleteLevelsWorkflow](https://docs.medusajs.com/references/medusa-workflows/bulkCreateDeleteLevelsWorkflow/index.html.md)
 - [createInventoryItemsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createInventoryItemsWorkflow/index.html.md)
-- [deleteInventoryItemWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteInventoryItemWorkflow/index.html.md)
 - [createInventoryLevelsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createInventoryLevelsWorkflow/index.html.md)
 - [deleteInventoryLevelsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteInventoryLevelsWorkflow/index.html.md)
 - [updateInventoryItemsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateInventoryItemsWorkflow/index.html.md)
+- [deleteInventoryItemWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteInventoryItemWorkflow/index.html.md)
 - [updateInventoryLevelsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateInventoryLevelsWorkflow/index.html.md)
 - [validateInventoryLevelsDelete](https://docs.medusajs.com/references/medusa-workflows/validateInventoryLevelsDelete/index.html.md)
-- [deleteInvitesWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteInvitesWorkflow/index.html.md)
-- [createInvitesWorkflow](https://docs.medusajs.com/references/medusa-workflows/createInvitesWorkflow/index.html.md)
-- [acceptInviteWorkflow](https://docs.medusajs.com/references/medusa-workflows/acceptInviteWorkflow/index.html.md)
-- [refreshInviteTokensWorkflow](https://docs.medusajs.com/references/medusa-workflows/refreshInviteTokensWorkflow/index.html.md)
-- [deleteLineItemsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteLineItemsWorkflow/index.html.md)
 - [capturePaymentWorkflow](https://docs.medusajs.com/references/medusa-workflows/capturePaymentWorkflow/index.html.md)
 - [processPaymentWorkflow](https://docs.medusajs.com/references/medusa-workflows/processPaymentWorkflow/index.html.md)
-- [refundPaymentWorkflow](https://docs.medusajs.com/references/medusa-workflows/refundPaymentWorkflow/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)
+- [refundPaymentWorkflow](https://docs.medusajs.com/references/medusa-workflows/refundPaymentWorkflow/index.html.md)
 - [validatePaymentsRefundStep](https://docs.medusajs.com/references/medusa-workflows/validatePaymentsRefundStep/index.html.md)
+- [validateRefundStep](https://docs.medusajs.com/references/medusa-workflows/validateRefundStep/index.html.md)
+- [deleteLineItemsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteLineItemsWorkflow/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)
 - [deleteRefundReasonsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteRefundReasonsWorkflow/index.html.md)
 - [updateRefundReasonsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateRefundReasonsWorkflow/index.html.md)
-- [deletePaymentSessionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deletePaymentSessionsWorkflow/index.html.md)
-- [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)
 - [acceptOrderTransferValidationStep](https://docs.medusajs.com/references/medusa-workflows/acceptOrderTransferValidationStep/index.html.md)
+- [addOrderLineItemsWorkflow](https://docs.medusajs.com/references/medusa-workflows/addOrderLineItemsWorkflow/index.html.md)
+- [acceptOrderTransferWorkflow](https://docs.medusajs.com/references/medusa-workflows/acceptOrderTransferWorkflow/index.html.md)
+- [beginClaimOrderValidationStep](https://docs.medusajs.com/references/medusa-workflows/beginClaimOrderValidationStep/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)
 - [beginClaimOrderWorkflow](https://docs.medusajs.com/references/medusa-workflows/beginClaimOrderWorkflow/index.html.md)
-- [beginOrderEditValidationStep](https://docs.medusajs.com/references/medusa-workflows/beginOrderEditValidationStep/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)
-- [beginReceiveReturnValidationStep](https://docs.medusajs.com/references/medusa-workflows/beginReceiveReturnValidationStep/index.html.md)
+- [beginOrderEditValidationStep](https://docs.medusajs.com/references/medusa-workflows/beginOrderEditValidationStep/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)
 - [beginReturnOrderValidationStep](https://docs.medusajs.com/references/medusa-workflows/beginReturnOrderValidationStep/index.html.md)
+- [beginOrderExchangeValidationStep](https://docs.medusajs.com/references/medusa-workflows/beginOrderExchangeValidationStep/index.html.md)
+- [beginReturnOrderWorkflow](https://docs.medusajs.com/references/medusa-workflows/beginReturnOrderWorkflow/index.html.md)
+- [cancelBeginOrderClaimValidationStep](https://docs.medusajs.com/references/medusa-workflows/cancelBeginOrderClaimValidationStep/index.html.md)
+- [cancelBeginOrderClaimWorkflow](https://docs.medusajs.com/references/medusa-workflows/cancelBeginOrderClaimWorkflow/index.html.md)
 - [cancelBeginOrderEditValidationStep](https://docs.medusajs.com/references/medusa-workflows/cancelBeginOrderEditValidationStep/index.html.md)
 - [cancelBeginOrderEditWorkflow](https://docs.medusajs.com/references/medusa-workflows/cancelBeginOrderEditWorkflow/index.html.md)
-- [cancelBeginOrderExchangeWorkflow](https://docs.medusajs.com/references/medusa-workflows/cancelBeginOrderExchangeWorkflow/index.html.md)
 - [cancelBeginOrderExchangeValidationStep](https://docs.medusajs.com/references/medusa-workflows/cancelBeginOrderExchangeValidationStep/index.html.md)
-- [cancelClaimValidateOrderStep](https://docs.medusajs.com/references/medusa-workflows/cancelClaimValidateOrderStep/index.html.md)
+- [cancelBeginOrderExchangeWorkflow](https://docs.medusajs.com/references/medusa-workflows/cancelBeginOrderExchangeWorkflow/index.html.md)
 - [cancelExchangeValidateOrder](https://docs.medusajs.com/references/medusa-workflows/cancelExchangeValidateOrder/index.html.md)
-- [cancelOrderClaimWorkflow](https://docs.medusajs.com/references/medusa-workflows/cancelOrderClaimWorkflow/index.html.md)
+- [cancelClaimValidateOrderStep](https://docs.medusajs.com/references/medusa-workflows/cancelClaimValidateOrderStep/index.html.md)
+- [beginReceiveReturnValidationStep](https://docs.medusajs.com/references/medusa-workflows/beginReceiveReturnValidationStep/index.html.md)
 - [cancelOrderChangeWorkflow](https://docs.medusajs.com/references/medusa-workflows/cancelOrderChangeWorkflow/index.html.md)
-- [cancelOrderFulfillmentValidateOrder](https://docs.medusajs.com/references/medusa-workflows/cancelOrderFulfillmentValidateOrder/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)
+- [cancelOrderClaimWorkflow](https://docs.medusajs.com/references/medusa-workflows/cancelOrderClaimWorkflow/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)
 - [cancelOrderWorkflow](https://docs.medusajs.com/references/medusa-workflows/cancelOrderWorkflow/index.html.md)
-- [cancelOrderFulfillmentWorkflow](https://docs.medusajs.com/references/medusa-workflows/cancelOrderFulfillmentWorkflow/index.html.md)
-- [cancelReceiveReturnValidationStep](https://docs.medusajs.com/references/medusa-workflows/cancelReceiveReturnValidationStep/index.html.md)
 - [cancelRequestReturnValidationStep](https://docs.medusajs.com/references/medusa-workflows/cancelRequestReturnValidationStep/index.html.md)
 - [cancelReturnReceiveWorkflow](https://docs.medusajs.com/references/medusa-workflows/cancelReturnReceiveWorkflow/index.html.md)
 - [cancelReturnValidateOrder](https://docs.medusajs.com/references/medusa-workflows/cancelReturnValidateOrder/index.html.md)
-- [cancelReturnWorkflow](https://docs.medusajs.com/references/medusa-workflows/cancelReturnWorkflow/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)
+- [cancelReturnWorkflow](https://docs.medusajs.com/references/medusa-workflows/cancelReturnWorkflow/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)
+- [confirmClaimRequestValidationStep](https://docs.medusajs.com/references/medusa-workflows/confirmClaimRequestValidationStep/index.html.md)
+- [confirmExchangeRequestValidationStep](https://docs.medusajs.com/references/medusa-workflows/confirmExchangeRequestValidationStep/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)
-- [confirmExchangeRequestValidationStep](https://docs.medusajs.com/references/medusa-workflows/confirmExchangeRequestValidationStep/index.html.md)
 - [confirmExchangeRequestWorkflow](https://docs.medusajs.com/references/medusa-workflows/confirmExchangeRequestWorkflow/index.html.md)
+- [confirmOrderEditRequestWorkflow](https://docs.medusajs.com/references/medusa-workflows/confirmOrderEditRequestWorkflow/index.html.md)
 - [confirmOrderEditRequestValidationStep](https://docs.medusajs.com/references/medusa-workflows/confirmOrderEditRequestValidationStep/index.html.md)
 - [confirmReceiveReturnValidationStep](https://docs.medusajs.com/references/medusa-workflows/confirmReceiveReturnValidationStep/index.html.md)
-- [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)
 - [confirmReturnRequestWorkflow](https://docs.medusajs.com/references/medusa-workflows/confirmReturnRequestWorkflow/index.html.md)
 - [createAndCompleteReturnOrderWorkflow](https://docs.medusajs.com/references/medusa-workflows/createAndCompleteReturnOrderWorkflow/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)
-- [createExchangeShippingMethodWorkflow](https://docs.medusajs.com/references/medusa-workflows/createExchangeShippingMethodWorkflow/index.html.md)
 - [createExchangeShippingMethodValidationStep](https://docs.medusajs.com/references/medusa-workflows/createExchangeShippingMethodValidationStep/index.html.md)
 - [createFulfillmentValidateOrder](https://docs.medusajs.com/references/medusa-workflows/createFulfillmentValidateOrder/index.html.md)
+- [createExchangeShippingMethodWorkflow](https://docs.medusajs.com/references/medusa-workflows/createExchangeShippingMethodWorkflow/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)
-- [confirmClaimRequestValidationStep](https://docs.medusajs.com/references/medusa-workflows/confirmClaimRequestValidationStep/index.html.md)
+- [createOrderCreditLinesWorkflow](https://docs.medusajs.com/references/medusa-workflows/createOrderCreditLinesWorkflow/index.html.md)
 - [createOrderChangeWorkflow](https://docs.medusajs.com/references/medusa-workflows/createOrderChangeWorkflow/index.html.md)
 - [createOrderEditShippingMethodValidationStep](https://docs.medusajs.com/references/medusa-workflows/createOrderEditShippingMethodValidationStep/index.html.md)
-- [createOrderFulfillmentWorkflow](https://docs.medusajs.com/references/medusa-workflows/createOrderFulfillmentWorkflow/index.html.md)
 - [createOrderEditShippingMethodWorkflow](https://docs.medusajs.com/references/medusa-workflows/createOrderEditShippingMethodWorkflow/index.html.md)
 - [createOrderPaymentCollectionWorkflow](https://docs.medusajs.com/references/medusa-workflows/createOrderPaymentCollectionWorkflow/index.html.md)
+- [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)
-- [createOrdersWorkflow](https://docs.medusajs.com/references/medusa-workflows/createOrdersWorkflow/index.html.md)
 - [createReturnShippingMethodValidationStep](https://docs.medusajs.com/references/medusa-workflows/createReturnShippingMethodValidationStep/index.html.md)
-- [createShipmentValidateOrder](https://docs.medusajs.com/references/medusa-workflows/createShipmentValidateOrder/index.html.md)
+- [createOrdersWorkflow](https://docs.medusajs.com/references/medusa-workflows/createOrdersWorkflow/index.html.md)
 - [createReturnShippingMethodWorkflow](https://docs.medusajs.com/references/medusa-workflows/createReturnShippingMethodWorkflow/index.html.md)
-- [createOrderCreditLinesWorkflow](https://docs.medusajs.com/references/medusa-workflows/createOrderCreditLinesWorkflow/index.html.md)
+- [createShipmentValidateOrder](https://docs.medusajs.com/references/medusa-workflows/createShipmentValidateOrder/index.html.md)
 - [declineOrderChangeWorkflow](https://docs.medusajs.com/references/medusa-workflows/declineOrderChangeWorkflow/index.html.md)
 - [declineOrderTransferRequestWorkflow](https://docs.medusajs.com/references/medusa-workflows/declineOrderTransferRequestWorkflow/index.html.md)
 - [declineTransferOrderRequestValidationStep](https://docs.medusajs.com/references/medusa-workflows/declineTransferOrderRequestValidationStep/index.html.md)
 - [deleteOrderChangeActionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteOrderChangeActionsWorkflow/index.html.md)
 - [deleteOrderChangeWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteOrderChangeWorkflow/index.html.md)
-- [dismissItemReturnRequestWorkflow](https://docs.medusajs.com/references/medusa-workflows/dismissItemReturnRequestWorkflow/index.html.md)
-- [dismissItemReturnRequestValidationStep](https://docs.medusajs.com/references/medusa-workflows/dismissItemReturnRequestValidationStep/index.html.md)
 - [deleteOrderPaymentCollections](https://docs.medusajs.com/references/medusa-workflows/deleteOrderPaymentCollections/index.html.md)
+- [dismissItemReturnRequestValidationStep](https://docs.medusajs.com/references/medusa-workflows/dismissItemReturnRequestValidationStep/index.html.md)
 - [exchangeAddNewItemValidationStep](https://docs.medusajs.com/references/medusa-workflows/exchangeAddNewItemValidationStep/index.html.md)
 - [exchangeRequestItemReturnValidationStep](https://docs.medusajs.com/references/medusa-workflows/exchangeRequestItemReturnValidationStep/index.html.md)
-- [getOrderDetailWorkflow](https://docs.medusajs.com/references/medusa-workflows/getOrderDetailWorkflow/index.html.md)
+- [dismissItemReturnRequestWorkflow](https://docs.medusajs.com/references/medusa-workflows/dismissItemReturnRequestWorkflow/index.html.md)
 - [getOrdersListWorkflow](https://docs.medusajs.com/references/medusa-workflows/getOrdersListWorkflow/index.html.md)
-- [markOrderFulfillmentAsDeliveredWorkflow](https://docs.medusajs.com/references/medusa-workflows/markOrderFulfillmentAsDeliveredWorkflow/index.html.md)
+- [getOrderDetailWorkflow](https://docs.medusajs.com/references/medusa-workflows/getOrderDetailWorkflow/index.html.md)
 - [markPaymentCollectionAsPaid](https://docs.medusajs.com/references/medusa-workflows/markPaymentCollectionAsPaid/index.html.md)
-- [orderClaimAddNewItemWorkflow](https://docs.medusajs.com/references/medusa-workflows/orderClaimAddNewItemWorkflow/index.html.md)
+- [markOrderFulfillmentAsDeliveredWorkflow](https://docs.medusajs.com/references/medusa-workflows/markOrderFulfillmentAsDeliveredWorkflow/index.html.md)
 - [orderClaimAddNewItemValidationStep](https://docs.medusajs.com/references/medusa-workflows/orderClaimAddNewItemValidationStep/index.html.md)
-- [orderClaimItemWorkflow](https://docs.medusajs.com/references/medusa-workflows/orderClaimItemWorkflow/index.html.md)
-- [orderClaimRequestItemReturnWorkflow](https://docs.medusajs.com/references/medusa-workflows/orderClaimRequestItemReturnWorkflow/index.html.md)
+- [orderClaimAddNewItemWorkflow](https://docs.medusajs.com/references/medusa-workflows/orderClaimAddNewItemWorkflow/index.html.md)
 - [orderClaimItemValidationStep](https://docs.medusajs.com/references/medusa-workflows/orderClaimItemValidationStep/index.html.md)
+- [orderClaimItemWorkflow](https://docs.medusajs.com/references/medusa-workflows/orderClaimItemWorkflow/index.html.md)
 - [orderClaimRequestItemReturnValidationStep](https://docs.medusajs.com/references/medusa-workflows/orderClaimRequestItemReturnValidationStep/index.html.md)
-- [orderEditAddNewItemWorkflow](https://docs.medusajs.com/references/medusa-workflows/orderEditAddNewItemWorkflow/index.html.md)
 - [orderEditAddNewItemValidationStep](https://docs.medusajs.com/references/medusa-workflows/orderEditAddNewItemValidationStep/index.html.md)
+- [orderClaimRequestItemReturnWorkflow](https://docs.medusajs.com/references/medusa-workflows/orderClaimRequestItemReturnWorkflow/index.html.md)
+- [orderEditAddNewItemWorkflow](https://docs.medusajs.com/references/medusa-workflows/orderEditAddNewItemWorkflow/index.html.md)
 - [orderEditUpdateItemQuantityValidationStep](https://docs.medusajs.com/references/medusa-workflows/orderEditUpdateItemQuantityValidationStep/index.html.md)
 - [orderEditUpdateItemQuantityWorkflow](https://docs.medusajs.com/references/medusa-workflows/orderEditUpdateItemQuantityWorkflow/index.html.md)
 - [orderExchangeAddNewItemWorkflow](https://docs.medusajs.com/references/medusa-workflows/orderExchangeAddNewItemWorkflow/index.html.md)
-- [orderFulfillmentDeliverablilityValidationStep](https://docs.medusajs.com/references/medusa-workflows/orderFulfillmentDeliverablilityValidationStep/index.html.md)
 - [orderExchangeRequestItemReturnWorkflow](https://docs.medusajs.com/references/medusa-workflows/orderExchangeRequestItemReturnWorkflow/index.html.md)
-- [receiveItemReturnRequestValidationStep](https://docs.medusajs.com/references/medusa-workflows/receiveItemReturnRequestValidationStep/index.html.md)
+- [orderFulfillmentDeliverablilityValidationStep](https://docs.medusajs.com/references/medusa-workflows/orderFulfillmentDeliverablilityValidationStep/index.html.md)
 - [receiveAndCompleteReturnOrderWorkflow](https://docs.medusajs.com/references/medusa-workflows/receiveAndCompleteReturnOrderWorkflow/index.html.md)
+- [receiveItemReturnRequestValidationStep](https://docs.medusajs.com/references/medusa-workflows/receiveItemReturnRequestValidationStep/index.html.md)
+- [receiveItemReturnRequestWorkflow](https://docs.medusajs.com/references/medusa-workflows/receiveItemReturnRequestWorkflow/index.html.md)
 - [receiveCompleteReturnValidationStep](https://docs.medusajs.com/references/medusa-workflows/receiveCompleteReturnValidationStep/index.html.md)
 - [removeAddItemClaimActionWorkflow](https://docs.medusajs.com/references/medusa-workflows/removeAddItemClaimActionWorkflow/index.html.md)
 - [removeClaimAddItemActionValidationStep](https://docs.medusajs.com/references/medusa-workflows/removeClaimAddItemActionValidationStep/index.html.md)
-- [receiveItemReturnRequestWorkflow](https://docs.medusajs.com/references/medusa-workflows/receiveItemReturnRequestWorkflow/index.html.md)
 - [removeClaimItemActionValidationStep](https://docs.medusajs.com/references/medusa-workflows/removeClaimItemActionValidationStep/index.html.md)
-- [removeClaimShippingMethodWorkflow](https://docs.medusajs.com/references/medusa-workflows/removeClaimShippingMethodWorkflow/index.html.md)
 - [removeClaimShippingMethodValidationStep](https://docs.medusajs.com/references/medusa-workflows/removeClaimShippingMethodValidationStep/index.html.md)
-- [removeExchangeShippingMethodValidationStep](https://docs.medusajs.com/references/medusa-workflows/removeExchangeShippingMethodValidationStep/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)
 - [removeItemOrderEditActionWorkflow](https://docs.medusajs.com/references/medusa-workflows/removeItemOrderEditActionWorkflow/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)
-- [removeItemReturnActionWorkflow](https://docs.medusajs.com/references/medusa-workflows/removeItemReturnActionWorkflow/index.html.md)
-- [removeOrderEditItemActionValidationStep](https://docs.medusajs.com/references/medusa-workflows/removeOrderEditItemActionValidationStep/index.html.md)
-- [removeOrderEditShippingMethodWorkflow](https://docs.medusajs.com/references/medusa-workflows/removeOrderEditShippingMethodWorkflow/index.html.md)
 - [removeOrderEditShippingMethodValidationStep](https://docs.medusajs.com/references/medusa-workflows/removeOrderEditShippingMethodValidationStep/index.html.md)
+- [removeOrderEditItemActionValidationStep](https://docs.medusajs.com/references/medusa-workflows/removeOrderEditItemActionValidationStep/index.html.md)
+- [removeItemReturnActionWorkflow](https://docs.medusajs.com/references/medusa-workflows/removeItemReturnActionWorkflow/index.html.md)
+- [removeOrderEditShippingMethodWorkflow](https://docs.medusajs.com/references/medusa-workflows/removeOrderEditShippingMethodWorkflow/index.html.md)
 - [removeReturnShippingMethodValidationStep](https://docs.medusajs.com/references/medusa-workflows/removeReturnShippingMethodValidationStep/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)
-- [requestItemReturnWorkflow](https://docs.medusajs.com/references/medusa-workflows/requestItemReturnWorkflow/index.html.md)
 - [requestItemReturnValidationStep](https://docs.medusajs.com/references/medusa-workflows/requestItemReturnValidationStep/index.html.md)
-- [requestOrderTransferValidationStep](https://docs.medusajs.com/references/medusa-workflows/requestOrderTransferValidationStep/index.html.md)
 - [requestOrderEditRequestValidationStep](https://docs.medusajs.com/references/medusa-workflows/requestOrderEditRequestValidationStep/index.html.md)
+- [requestItemReturnWorkflow](https://docs.medusajs.com/references/medusa-workflows/requestItemReturnWorkflow/index.html.md)
 - [requestOrderEditRequestWorkflow](https://docs.medusajs.com/references/medusa-workflows/requestOrderEditRequestWorkflow/index.html.md)
+- [requestOrderTransferValidationStep](https://docs.medusajs.com/references/medusa-workflows/requestOrderTransferValidationStep/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)
 - [throwUnlessStatusIsNotPaid](https://docs.medusajs.com/references/medusa-workflows/throwUnlessStatusIsNotPaid/index.html.md)
 - [throwUnlessPaymentCollectionNotPaid](https://docs.medusajs.com/references/medusa-workflows/throwUnlessPaymentCollectionNotPaid/index.html.md)
+- [updateClaimAddItemValidationStep](https://docs.medusajs.com/references/medusa-workflows/updateClaimAddItemValidationStep/index.html.md)
 - [updateClaimAddItemWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateClaimAddItemWorkflow/index.html.md)
-- [updateClaimItemWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateClaimItemWorkflow/index.html.md)
 - [updateClaimItemValidationStep](https://docs.medusajs.com/references/medusa-workflows/updateClaimItemValidationStep/index.html.md)
 - [updateClaimShippingMethodValidationStep](https://docs.medusajs.com/references/medusa-workflows/updateClaimShippingMethodValidationStep/index.html.md)
+- [updateClaimItemWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateClaimItemWorkflow/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)
 - [updateExchangeAddItemWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateExchangeAddItemWorkflow/index.html.md)
-- [updateExchangeAddItemValidationStep](https://docs.medusajs.com/references/medusa-workflows/updateExchangeAddItemValidationStep/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)
+- [updateExchangeShippingMethodValidationStep](https://docs.medusajs.com/references/medusa-workflows/updateExchangeShippingMethodValidationStep/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)
-- [updateOrderEditItemQuantityWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateOrderEditItemQuantityWorkflow/index.html.md)
 - [updateOrderEditItemQuantityValidationStep](https://docs.medusajs.com/references/medusa-workflows/updateOrderEditItemQuantityValidationStep/index.html.md)
-- [updateOrderEditShippingMethodWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateOrderEditShippingMethodWorkflow/index.html.md)
-- [updateOrderValidationStep](https://docs.medusajs.com/references/medusa-workflows/updateOrderValidationStep/index.html.md)
-- [updateOrderTaxLinesWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateOrderTaxLinesWorkflow/index.html.md)
+- [updateOrderEditItemQuantityWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateOrderEditItemQuantityWorkflow/index.html.md)
 - [updateOrderEditShippingMethodValidationStep](https://docs.medusajs.com/references/medusa-workflows/updateOrderEditShippingMethodValidationStep/index.html.md)
+- [updateOrderEditShippingMethodWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateOrderEditShippingMethodWorkflow/index.html.md)
+- [updateOrderTaxLinesWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateOrderTaxLinesWorkflow/index.html.md)
+- [updateOrderValidationStep](https://docs.medusajs.com/references/medusa-workflows/updateOrderValidationStep/index.html.md)
+- [updateReceiveItemReturnRequestValidationStep](https://docs.medusajs.com/references/medusa-workflows/updateReceiveItemReturnRequestValidationStep/index.html.md)
 - [updateOrderWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateOrderWorkflow/index.html.md)
 - [updateReceiveItemReturnRequestWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateReceiveItemReturnRequestWorkflow/index.html.md)
-- [updateReceiveItemReturnRequestValidationStep](https://docs.medusajs.com/references/medusa-workflows/updateReceiveItemReturnRequestValidationStep/index.html.md)
 - [updateRequestItemReturnValidationStep](https://docs.medusajs.com/references/medusa-workflows/updateRequestItemReturnValidationStep/index.html.md)
 - [updateRequestItemReturnWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateRequestItemReturnWorkflow/index.html.md)
+- [updateReturnShippingMethodValidationStep](https://docs.medusajs.com/references/medusa-workflows/updateReturnShippingMethodValidationStep/index.html.md)
 - [updateReturnShippingMethodWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateReturnShippingMethodWorkflow/index.html.md)
 - [updateReturnValidationStep](https://docs.medusajs.com/references/medusa-workflows/updateReturnValidationStep/index.html.md)
-- [updateReturnShippingMethodValidationStep](https://docs.medusajs.com/references/medusa-workflows/updateReturnShippingMethodValidationStep/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)
-- [batchPromotionRulesWorkflow](https://docs.medusajs.com/references/medusa-workflows/batchPromotionRulesWorkflow/index.html.md)
-- [createCampaignsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createCampaignsWorkflow/index.html.md)
-- [addOrRemoveCampaignPromotionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/addOrRemoveCampaignPromotionsWorkflow/index.html.md)
-- [createPromotionRulesWorkflow](https://docs.medusajs.com/references/medusa-workflows/createPromotionRulesWorkflow/index.html.md)
-- [createPromotionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createPromotionsWorkflow/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)
-- [updateCampaignsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateCampaignsWorkflow/index.html.md)
-- [deletePromotionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deletePromotionsWorkflow/index.html.md)
-- [updatePromotionRulesWorkflow](https://docs.medusajs.com/references/medusa-workflows/updatePromotionRulesWorkflow/index.html.md)
-- [updatePromotionsStatusWorkflow](https://docs.medusajs.com/references/medusa-workflows/updatePromotionsStatusWorkflow/index.html.md)
-- [updatePromotionsValidationStep](https://docs.medusajs.com/references/medusa-workflows/updatePromotionsValidationStep/index.html.md)
-- [updatePromotionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updatePromotionsWorkflow/index.html.md)
+- [updateReturnWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateReturnWorkflow/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)
 - [batchLinkProductsToCollectionWorkflow](https://docs.medusajs.com/references/medusa-workflows/batchLinkProductsToCollectionWorkflow/index.html.md)
 - [batchProductVariantsWorkflow](https://docs.medusajs.com/references/medusa-workflows/batchProductVariantsWorkflow/index.html.md)
 - [createCollectionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createCollectionsWorkflow/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)
-- [createProductTagsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createProductTagsWorkflow/index.html.md)
 - [createProductTypesWorkflow](https://docs.medusajs.com/references/medusa-workflows/createProductTypesWorkflow/index.html.md)
+- [createProductTagsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createProductTagsWorkflow/index.html.md)
 - [createProductVariantsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createProductVariantsWorkflow/index.html.md)
-- [deleteCollectionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteCollectionsWorkflow/index.html.md)
 - [createProductsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createProductsWorkflow/index.html.md)
-- [deleteProductTagsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteProductTagsWorkflow/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)
 - [deleteProductTypesWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteProductTypesWorkflow/index.html.md)
+- [deleteProductTagsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteProductTagsWorkflow/index.html.md)
 - [deleteProductVariantsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteProductVariantsWorkflow/index.html.md)
+- [deleteProductsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteProductsWorkflow/index.html.md)
 - [exportProductsWorkflow](https://docs.medusajs.com/references/medusa-workflows/exportProductsWorkflow/index.html.md)
 - [importProductsWorkflow](https://docs.medusajs.com/references/medusa-workflows/importProductsWorkflow/index.html.md)
-- [updateCollectionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateCollectionsWorkflow/index.html.md)
-- [deleteProductsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteProductsWorkflow/index.html.md)
 - [updateProductOptionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateProductOptionsWorkflow/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)
 - [updateProductTagsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateProductTagsWorkflow/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)
-- [validateProductInputStep](https://docs.medusajs.com/references/medusa-workflows/validateProductInputStep/index.html.md)
+- [updateProductVariantsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateProductVariantsWorkflow/index.html.md)
+- [updateProductTypesWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateProductTypesWorkflow/index.html.md)
 - [upsertVariantPricesWorkflow](https://docs.medusajs.com/references/medusa-workflows/upsertVariantPricesWorkflow/index.html.md)
+- [validateProductInputStep](https://docs.medusajs.com/references/medusa-workflows/validateProductInputStep/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)
 - [createPriceListsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createPriceListsWorkflow/index.html.md)
-- [removePriceListPricesWorkflow](https://docs.medusajs.com/references/medusa-workflows/removePriceListPricesWorkflow/index.html.md)
 - [deletePriceListsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deletePriceListsWorkflow/index.html.md)
+- [removePriceListPricesWorkflow](https://docs.medusajs.com/references/medusa-workflows/removePriceListPricesWorkflow/index.html.md)
 - [updatePriceListPricesWorkflow](https://docs.medusajs.com/references/medusa-workflows/updatePriceListPricesWorkflow/index.html.md)
 - [updatePriceListsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updatePriceListsWorkflow/index.html.md)
-- [updatePricePreferencesWorkflow](https://docs.medusajs.com/references/medusa-workflows/updatePricePreferencesWorkflow/index.html.md)
-- [createPricePreferencesWorkflow](https://docs.medusajs.com/references/medusa-workflows/createPricePreferencesWorkflow/index.html.md)
 - [deletePricePreferencesWorkflow](https://docs.medusajs.com/references/medusa-workflows/deletePricePreferencesWorkflow/index.html.md)
-- [createRegionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createRegionsWorkflow/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)
+- [deleteProductCategoriesWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteProductCategoriesWorkflow/index.html.md)
+- [updateProductCategoriesWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateProductCategoriesWorkflow/index.html.md)
+- [createProductCategoriesWorkflow](https://docs.medusajs.com/references/medusa-workflows/createProductCategoriesWorkflow/index.html.md)
 - [deleteRegionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteRegionsWorkflow/index.html.md)
+- [createRegionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createRegionsWorkflow/index.html.md)
 - [updateRegionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateRegionsWorkflow/index.html.md)
 - [createReservationsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createReservationsWorkflow/index.html.md)
-- [deleteReservationsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteReservationsWorkflow/index.html.md)
 - [deleteReservationsByLineItemsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteReservationsByLineItemsWorkflow/index.html.md)
+- [deleteReservationsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteReservationsWorkflow/index.html.md)
 - [updateReservationsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateReservationsWorkflow/index.html.md)
-- [validateStepShippingProfileDelete](https://docs.medusajs.com/references/medusa-workflows/validateStepShippingProfileDelete/index.html.md)
-- [deleteShippingProfileWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteShippingProfileWorkflow/index.html.md)
-- [createProductCategoriesWorkflow](https://docs.medusajs.com/references/medusa-workflows/createProductCategoriesWorkflow/index.html.md)
-- [updateProductCategoriesWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateProductCategoriesWorkflow/index.html.md)
-- [deleteProductCategoriesWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteProductCategoriesWorkflow/index.html.md)
-- [createLocationFulfillmentSetWorkflow](https://docs.medusajs.com/references/medusa-workflows/createLocationFulfillmentSetWorkflow/index.html.md)
-- [deleteStockLocationsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteStockLocationsWorkflow/index.html.md)
-- [createStockLocationsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createStockLocationsWorkflow/index.html.md)
-- [updateStockLocationsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateStockLocationsWorkflow/index.html.md)
-- [linkSalesChannelsToStockLocationWorkflow](https://docs.medusajs.com/references/medusa-workflows/linkSalesChannelsToStockLocationWorkflow/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)
+- [deleteReturnReasonsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteReturnReasonsWorkflow/index.html.md)
+- [addOrRemoveCampaignPromotionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/addOrRemoveCampaignPromotionsWorkflow/index.html.md)
+- [batchPromotionRulesWorkflow](https://docs.medusajs.com/references/medusa-workflows/batchPromotionRulesWorkflow/index.html.md)
+- [createPromotionRulesWorkflow](https://docs.medusajs.com/references/medusa-workflows/createPromotionRulesWorkflow/index.html.md)
+- [createCampaignsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createCampaignsWorkflow/index.html.md)
+- [createPromotionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createPromotionsWorkflow/index.html.md)
+- [deleteCampaignsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteCampaignsWorkflow/index.html.md)
+- [deletePromotionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deletePromotionsWorkflow/index.html.md)
+- [deletePromotionRulesWorkflow](https://docs.medusajs.com/references/medusa-workflows/deletePromotionRulesWorkflow/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)
+- [updatePromotionRulesWorkflow](https://docs.medusajs.com/references/medusa-workflows/updatePromotionRulesWorkflow/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)
 - [createSalesChannelsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createSalesChannelsWorkflow/index.html.md)
+- [linkProductsToSalesChannelWorkflow](https://docs.medusajs.com/references/medusa-workflows/linkProductsToSalesChannelWorkflow/index.html.md)
 - [updateSalesChannelsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateSalesChannelsWorkflow/index.html.md)
 - [deleteSalesChannelsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteSalesChannelsWorkflow/index.html.md)
-- [linkProductsToSalesChannelWorkflow](https://docs.medusajs.com/references/medusa-workflows/linkProductsToSalesChannelWorkflow/index.html.md)
-- [createStoresWorkflow](https://docs.medusajs.com/references/medusa-workflows/createStoresWorkflow/index.html.md)
-- [updateStoresWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateStoresWorkflow/index.html.md)
-- [deleteStoresWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteStoresWorkflow/index.html.md)
+- [deleteStockLocationsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteStockLocationsWorkflow/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)
 - [createTaxRateRulesWorkflow](https://docs.medusajs.com/references/medusa-workflows/createTaxRateRulesWorkflow/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)
 - [createTaxRatesWorkflow](https://docs.medusajs.com/references/medusa-workflows/createTaxRatesWorkflow/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)
-- [deleteTaxRegionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteTaxRegionsWorkflow/index.html.md)
 - [deleteTaxRateRulesWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteTaxRateRulesWorkflow/index.html.md)
+- [deleteTaxRegionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteTaxRegionsWorkflow/index.html.md)
 - [maybeListTaxRateRuleIdsStep](https://docs.medusajs.com/references/medusa-workflows/maybeListTaxRateRuleIdsStep/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)
+- [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)
 - [createUsersWorkflow](https://docs.medusajs.com/references/medusa-workflows/createUsersWorkflow/index.html.md)
 - [deleteUsersWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteUsersWorkflow/index.html.md)
 - [createUserAccountWorkflow](https://docs.medusajs.com/references/medusa-workflows/createUserAccountWorkflow/index.html.md)
@@ -30930,100 +31099,98 @@ Then, you pass the first sales channel ID to the `getVariantAvailability` functi
 
 ## 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)
+- [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)
 - [setAuthAppMetadataStep](https://docs.medusajs.com/references/medusa-workflows/steps/setAuthAppMetadataStep/index.html.md)
+- [deleteCustomerAddressesStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteCustomerAddressesStep/index.html.md)
+- [deleteCustomersStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteCustomersStep/index.html.md)
+- [maybeUnsetDefaultShippingAddressesStep](https://docs.medusajs.com/references/medusa-workflows/steps/maybeUnsetDefaultShippingAddressesStep/index.html.md)
+- [maybeUnsetDefaultBillingAddressesStep](https://docs.medusajs.com/references/medusa-workflows/steps/maybeUnsetDefaultBillingAddressesStep/index.html.md)
+- [createCustomersStep](https://docs.medusajs.com/references/medusa-workflows/steps/createCustomersStep/index.html.md)
+- [createCustomerAddressesStep](https://docs.medusajs.com/references/medusa-workflows/steps/createCustomerAddressesStep/index.html.md)
+- [updateCustomersStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateCustomersStep/index.html.md)
+- [updateCustomerAddressesStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateCustomerAddressesStep/index.html.md)
+- [validateCustomerAccountCreation](https://docs.medusajs.com/references/medusa-workflows/steps/validateCustomerAccountCreation/index.html.md)
 - [addShippingMethodToCartStep](https://docs.medusajs.com/references/medusa-workflows/steps/addShippingMethodToCartStep/index.html.md)
-- [createCartsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createCartsStep/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)
-- [createLineItemsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createLineItemsStep/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)
+- [createLineItemAdjustmentsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createLineItemAdjustmentsStep/index.html.md)
 - [createShippingMethodAdjustmentsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createShippingMethodAdjustmentsStep/index.html.md)
 - [findOneOrAnyRegionStep](https://docs.medusajs.com/references/medusa-workflows/steps/findOneOrAnyRegionStep/index.html.md)
 - [findOrCreateCustomerStep](https://docs.medusajs.com/references/medusa-workflows/steps/findOrCreateCustomerStep/index.html.md)
-- [findSalesChannelStep](https://docs.medusajs.com/references/medusa-workflows/steps/findSalesChannelStep/index.html.md)
-- [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)
+- [getActionsToComputeFromPromotionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/getActionsToComputeFromPromotionsStep/index.html.md)
+- [findSalesChannelStep](https://docs.medusajs.com/references/medusa-workflows/steps/findSalesChannelStep/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)
-- [removeLineItemAdjustmentsStep](https://docs.medusajs.com/references/medusa-workflows/steps/removeLineItemAdjustmentsStep/index.html.md)
-- [removeShippingMethodAdjustmentsStep](https://docs.medusajs.com/references/medusa-workflows/steps/removeShippingMethodAdjustmentsStep/index.html.md)
+- [getVariantPriceSetsStep](https://docs.medusajs.com/references/medusa-workflows/steps/getVariantPriceSetsStep/index.html.md)
 - [removeShippingMethodFromCartStep](https://docs.medusajs.com/references/medusa-workflows/steps/removeShippingMethodFromCartStep/index.html.md)
+- [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)
+- [removeLineItemAdjustmentsStep](https://docs.medusajs.com/references/medusa-workflows/steps/removeLineItemAdjustmentsStep/index.html.md)
+- [prepareAdjustmentsFromPromotionActionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/prepareAdjustmentsFromPromotionActionsStep/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)
-- [updateCartPromotionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateCartPromotionsStep/index.html.md)
 - [updateShippingMethodsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateShippingMethodsStep/index.html.md)
-- [updateCartsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateCartsStep/index.html.md)
 - [updateLineItemsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateLineItemsStep/index.html.md)
+- [updateCartPromotionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateCartPromotionsStep/index.html.md)
 - [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)
 - [validateCartShippingOptionsPriceStep](https://docs.medusajs.com/references/medusa-workflows/steps/validateCartShippingOptionsPriceStep/index.html.md)
-- [validateCartShippingOptionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/validateCartShippingOptionsStep/index.html.md)
-- [validateCartStep](https://docs.medusajs.com/references/medusa-workflows/steps/validateCartStep/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)
-- [validateVariantPricesStep](https://docs.medusajs.com/references/medusa-workflows/steps/validateVariantPricesStep/index.html.md)
 - [validateCartPaymentsStep](https://docs.medusajs.com/references/medusa-workflows/steps/validateCartPaymentsStep/index.html.md)
-- [createRemoteLinkStep](https://docs.medusajs.com/references/medusa-workflows/steps/createRemoteLinkStep/index.html.md)
-- [dismissRemoteLinkStep](https://docs.medusajs.com/references/medusa-workflows/steps/dismissRemoteLinkStep/index.html.md)
-- [emitEventStep](https://docs.medusajs.com/references/medusa-workflows/steps/emitEventStep/index.html.md)
-- [removeRemoteLinkStep](https://docs.medusajs.com/references/medusa-workflows/steps/removeRemoteLinkStep/index.html.md)
-- [useQueryGraphStep](https://docs.medusajs.com/references/medusa-workflows/steps/useQueryGraphStep/index.html.md)
-- [updateRemoteLinksStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateRemoteLinksStep/index.html.md)
-- [useRemoteQueryStep](https://docs.medusajs.com/references/medusa-workflows/steps/useRemoteQueryStep/index.html.md)
-- [validatePresenceOfStep](https://docs.medusajs.com/references/medusa-workflows/steps/validatePresenceOfStep/index.html.md)
-- [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)
-- [deleteCustomerAddressesStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteCustomerAddressesStep/index.html.md)
-- [deleteCustomersStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteCustomersStep/index.html.md)
-- [maybeUnsetDefaultBillingAddressesStep](https://docs.medusajs.com/references/medusa-workflows/steps/maybeUnsetDefaultBillingAddressesStep/index.html.md)
-- [maybeUnsetDefaultShippingAddressesStep](https://docs.medusajs.com/references/medusa-workflows/steps/maybeUnsetDefaultShippingAddressesStep/index.html.md)
-- [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)
+- [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)
+- [validateVariantPricesStep](https://docs.medusajs.com/references/medusa-workflows/steps/validateVariantPricesStep/index.html.md)
+- [validateCartStep](https://docs.medusajs.com/references/medusa-workflows/steps/validateCartStep/index.html.md)
+- [validateShippingStep](https://docs.medusajs.com/references/medusa-workflows/steps/validateShippingStep/index.html.md)
+- [createDefaultStoreStep](https://docs.medusajs.com/references/medusa-workflows/steps/createDefaultStoreStep/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)
-- [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)
+- [linkCustomerGroupsToCustomerStep](https://docs.medusajs.com/references/medusa-workflows/steps/linkCustomerGroupsToCustomerStep/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)
+- [attachInventoryItemToVariants](https://docs.medusajs.com/references/medusa-workflows/steps/attachInventoryItemToVariants/index.html.md)
+- [adjustInventoryLevelsStep](https://docs.medusajs.com/references/medusa-workflows/steps/adjustInventoryLevelsStep/index.html.md)
+- [createInventoryItemsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createInventoryItemsStep/index.html.md)
+- [createInventoryLevelsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createInventoryLevelsStep/index.html.md)
+- [deleteInventoryItemStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteInventoryItemStep/index.html.md)
+- [updateInventoryLevelsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateInventoryLevelsStep/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)
+- [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)
 - [buildPriceSet](https://docs.medusajs.com/references/medusa-workflows/steps/buildPriceSet/index.html.md)
 - [cancelFulfillmentStep](https://docs.medusajs.com/references/medusa-workflows/steps/cancelFulfillmentStep/index.html.md)
 - [calculateShippingOptionsPricesStep](https://docs.medusajs.com/references/medusa-workflows/steps/calculateShippingOptionsPricesStep/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)
-- [createServiceZonesStep](https://docs.medusajs.com/references/medusa-workflows/steps/createServiceZonesStep/index.html.md)
-- [createShippingOptionRulesStep](https://docs.medusajs.com/references/medusa-workflows/steps/createShippingOptionRulesStep/index.html.md)
 - [createReturnFulfillmentStep](https://docs.medusajs.com/references/medusa-workflows/steps/createReturnFulfillmentStep/index.html.md)
-- [createShippingOptionsPriceSetsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createShippingOptionsPriceSetsStep/index.html.md)
+- [createFulfillmentStep](https://docs.medusajs.com/references/medusa-workflows/steps/createFulfillmentStep/index.html.md)
+- [createShippingOptionRulesStep](https://docs.medusajs.com/references/medusa-workflows/steps/createShippingOptionRulesStep/index.html.md)
+- [createServiceZonesStep](https://docs.medusajs.com/references/medusa-workflows/steps/createServiceZonesStep/index.html.md)
 - [createShippingProfilesStep](https://docs.medusajs.com/references/medusa-workflows/steps/createShippingProfilesStep/index.html.md)
-- [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)
+- [createShippingOptionsPriceSetsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createShippingOptionsPriceSetsStep/index.html.md)
 - [deleteFulfillmentSetsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteFulfillmentSetsStep/index.html.md)
+- [deleteShippingOptionRulesStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteShippingOptionRulesStep/index.html.md)
+- [deleteServiceZonesStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteServiceZonesStep/index.html.md)
 - [deleteShippingOptionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteShippingOptionsStep/index.html.md)
 - [setShippingOptionsPricesStep](https://docs.medusajs.com/references/medusa-workflows/steps/setShippingOptionsPricesStep/index.html.md)
-- [updateServiceZonesStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateServiceZonesStep/index.html.md)
 - [updateFulfillmentStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateFulfillmentStep/index.html.md)
 - [updateShippingOptionRulesStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateShippingOptionRulesStep/index.html.md)
+- [updateServiceZonesStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateServiceZonesStep/index.html.md)
 - [updateShippingProfilesStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateShippingProfilesStep/index.html.md)
-- [validateShipmentStep](https://docs.medusajs.com/references/medusa-workflows/steps/validateShipmentStep/index.html.md)
 - [upsertShippingOptionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/upsertShippingOptionsStep/index.html.md)
 - [validateShippingOptionPricesStep](https://docs.medusajs.com/references/medusa-workflows/steps/validateShippingOptionPricesStep/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)
-- [deleteInventoryLevelsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteInventoryLevelsStep/index.html.md)
-- [updateInventoryItemsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateInventoryItemsStep/index.html.md)
-- [validateInventoryDeleteStep](https://docs.medusajs.com/references/medusa-workflows/steps/validateInventoryDeleteStep/index.html.md)
-- [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)
-- [updateInventoryLevelsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateInventoryLevelsStep/index.html.md)
+- [validateShipmentStep](https://docs.medusajs.com/references/medusa-workflows/steps/validateShipmentStep/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)
@@ -31031,164 +31198,166 @@ Then, you pass the first sales channel ID to the `getVariantAvailability` functi
 - [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)
-- [addOrderTransactionStep](https://docs.medusajs.com/references/medusa-workflows/steps/addOrderTransactionStep/index.html.md)
-- [cancelOrderClaimStep](https://docs.medusajs.com/references/medusa-workflows/steps/cancelOrderClaimStep/index.html.md)
-- [archiveOrdersStep](https://docs.medusajs.com/references/medusa-workflows/steps/archiveOrdersStep/index.html.md)
-- [cancelOrderExchangeStep](https://docs.medusajs.com/references/medusa-workflows/steps/cancelOrderExchangeStep/index.html.md)
-- [cancelOrderChangeStep](https://docs.medusajs.com/references/medusa-workflows/steps/cancelOrderChangeStep/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)
-- [cancelOrdersStep](https://docs.medusajs.com/references/medusa-workflows/steps/cancelOrdersStep/index.html.md)
-- [completeOrdersStep](https://docs.medusajs.com/references/medusa-workflows/steps/completeOrdersStep/index.html.md)
-- [createOrderClaimItemsFromActionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createOrderClaimItemsFromActionsStep/index.html.md)
-- [createOrderChangeStep](https://docs.medusajs.com/references/medusa-workflows/steps/createOrderChangeStep/index.html.md)
-- [createOrderExchangesStep](https://docs.medusajs.com/references/medusa-workflows/steps/createOrderExchangesStep/index.html.md)
-- [createOrderClaimsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createOrderClaimsStep/index.html.md)
-- [createOrderExchangeItemsFromActionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createOrderExchangeItemsFromActionsStep/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)
-- [deleteClaimsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteClaimsStep/index.html.md)
-- [deleteExchangesStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteExchangesStep/index.html.md)
-- [deleteOrderChangeActionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteOrderChangeActionsStep/index.html.md)
-- [createReturnsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createReturnsStep/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)
-- [declineOrderChangeStep](https://docs.medusajs.com/references/medusa-workflows/steps/declineOrderChangeStep/index.html.md)
-- [deleteReturnsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteReturnsStep/index.html.md)
-- [previewOrderChangeStep](https://docs.medusajs.com/references/medusa-workflows/steps/previewOrderChangeStep/index.html.md)
-- [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)
-- [registerOrderFulfillmentStep](https://docs.medusajs.com/references/medusa-workflows/steps/registerOrderFulfillmentStep/index.html.md)
-- [setOrderTaxLinesForItemsStep](https://docs.medusajs.com/references/medusa-workflows/steps/setOrderTaxLinesForItemsStep/index.html.md)
-- [deleteOrderLineItems](https://docs.medusajs.com/references/medusa-workflows/steps/deleteOrderLineItems/index.html.md)
-- [registerOrderChangesStep](https://docs.medusajs.com/references/medusa-workflows/steps/registerOrderChangesStep/index.html.md)
-- [updateOrderChangesStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateOrderChangesStep/index.html.md)
-- [updateOrderChangeActionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateOrderChangeActionsStep/index.html.md)
-- [updateOrdersStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateOrdersStep/index.html.md)
-- [updateReturnItemsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateReturnItemsStep/index.html.md)
-- [updateOrderShippingMethodsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateOrderShippingMethodsStep/index.html.md)
-- [updateReturnsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateReturnsStep/index.html.md)
+- [notifyOnFailureStep](https://docs.medusajs.com/references/medusa-workflows/steps/notifyOnFailureStep/index.html.md)
+- [dismissRemoteLinkStep](https://docs.medusajs.com/references/medusa-workflows/steps/dismissRemoteLinkStep/index.html.md)
+- [createRemoteLinkStep](https://docs.medusajs.com/references/medusa-workflows/steps/createRemoteLinkStep/index.html.md)
+- [emitEventStep](https://docs.medusajs.com/references/medusa-workflows/steps/emitEventStep/index.html.md)
+- [removeRemoteLinkStep](https://docs.medusajs.com/references/medusa-workflows/steps/removeRemoteLinkStep/index.html.md)
+- [updateRemoteLinksStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateRemoteLinksStep/index.html.md)
+- [useQueryGraphStep](https://docs.medusajs.com/references/medusa-workflows/steps/useQueryGraphStep/index.html.md)
+- [validatePresenceOfStep](https://docs.medusajs.com/references/medusa-workflows/steps/validatePresenceOfStep/index.html.md)
+- [useRemoteQueryStep](https://docs.medusajs.com/references/medusa-workflows/steps/useRemoteQueryStep/index.html.md)
 - [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)
 - [authorizePaymentSessionStep](https://docs.medusajs.com/references/medusa-workflows/steps/authorizePaymentSessionStep/index.html.md)
-- [createPaymentSessionStep](https://docs.medusajs.com/references/medusa-workflows/steps/createPaymentSessionStep/index.html.md)
+- [refundPaymentsStep](https://docs.medusajs.com/references/medusa-workflows/steps/refundPaymentsStep/index.html.md)
+- [archiveOrdersStep](https://docs.medusajs.com/references/medusa-workflows/steps/archiveOrdersStep/index.html.md)
+- [addOrderTransactionStep](https://docs.medusajs.com/references/medusa-workflows/steps/addOrderTransactionStep/index.html.md)
+- [cancelOrderChangeStep](https://docs.medusajs.com/references/medusa-workflows/steps/cancelOrderChangeStep/index.html.md)
+- [cancelOrderClaimStep](https://docs.medusajs.com/references/medusa-workflows/steps/cancelOrderClaimStep/index.html.md)
+- [cancelOrderExchangeStep](https://docs.medusajs.com/references/medusa-workflows/steps/cancelOrderExchangeStep/index.html.md)
+- [cancelOrdersStep](https://docs.medusajs.com/references/medusa-workflows/steps/cancelOrdersStep/index.html.md)
+- [cancelOrderReturnStep](https://docs.medusajs.com/references/medusa-workflows/steps/cancelOrderReturnStep/index.html.md)
+- [cancelOrderFulfillmentStep](https://docs.medusajs.com/references/medusa-workflows/steps/cancelOrderFulfillmentStep/index.html.md)
+- [completeOrdersStep](https://docs.medusajs.com/references/medusa-workflows/steps/completeOrdersStep/index.html.md)
+- [createOrderChangeStep](https://docs.medusajs.com/references/medusa-workflows/steps/createOrderChangeStep/index.html.md)
+- [createCompleteReturnStep](https://docs.medusajs.com/references/medusa-workflows/steps/createCompleteReturnStep/index.html.md)
+- [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)
+- [createOrderExchangesStep](https://docs.medusajs.com/references/medusa-workflows/steps/createOrderExchangesStep/index.html.md)
+- [createOrderExchangeItemsFromActionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createOrderExchangeItemsFromActionsStep/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)
+- [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)
+- [deleteExchangesStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteExchangesStep/index.html.md)
+- [deleteOrderChangeActionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteOrderChangeActionsStep/index.html.md)
+- [declineOrderChangeStep](https://docs.medusajs.com/references/medusa-workflows/steps/declineOrderChangeStep/index.html.md)
+- [deleteOrderChangesStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteOrderChangesStep/index.html.md)
+- [deleteOrderLineItems](https://docs.medusajs.com/references/medusa-workflows/steps/deleteOrderLineItems/index.html.md)
+- [deleteOrderShippingMethods](https://docs.medusajs.com/references/medusa-workflows/steps/deleteOrderShippingMethods/index.html.md)
+- [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)
+- [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)
+- [registerOrderFulfillmentStep](https://docs.medusajs.com/references/medusa-workflows/steps/registerOrderFulfillmentStep/index.html.md)
+- [setOrderTaxLinesForItemsStep](https://docs.medusajs.com/references/medusa-workflows/steps/setOrderTaxLinesForItemsStep/index.html.md)
+- [registerOrderShipmentStep](https://docs.medusajs.com/references/medusa-workflows/steps/registerOrderShipmentStep/index.html.md)
+- [updateOrderChangesStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateOrderChangesStep/index.html.md)
+- [updateOrderChangeActionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateOrderChangeActionsStep/index.html.md)
+- [updateOrderShippingMethodsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateOrderShippingMethodsStep/index.html.md)
+- [updateOrdersStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateOrdersStep/index.html.md)
+- [updateReturnItemsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateReturnItemsStep/index.html.md)
+- [updateReturnsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateReturnsStep/index.html.md)
 - [createPaymentAccountHolderStep](https://docs.medusajs.com/references/medusa-workflows/steps/createPaymentAccountHolderStep/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)
 - [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)
+- [deleteRefundReasonsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteRefundReasonsStep/index.html.md)
+- [updatePaymentCollectionStep](https://docs.medusajs.com/references/medusa-workflows/steps/updatePaymentCollectionStep/index.html.md)
 - [updateRefundReasonsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateRefundReasonsStep/index.html.md)
 - [validateDeletedPaymentSessionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/validateDeletedPaymentSessionsStep/index.html.md)
-- [updatePaymentCollectionStep](https://docs.medusajs.com/references/medusa-workflows/steps/updatePaymentCollectionStep/index.html.md)
-- [deleteRefundReasonsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteRefundReasonsStep/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)
+- [updatePriceListsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updatePriceListsStep/index.html.md)
+- [updatePriceListPricesStep](https://docs.medusajs.com/references/medusa-workflows/steps/updatePriceListPricesStep/index.html.md)
+- [removePriceListPricesStep](https://docs.medusajs.com/references/medusa-workflows/steps/removePriceListPricesStep/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)
 - [createPricePreferencesStep](https://docs.medusajs.com/references/medusa-workflows/steps/createPricePreferencesStep/index.html.md)
 - [createPriceSetsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createPriceSetsStep/index.html.md)
 - [deletePricePreferencesStep](https://docs.medusajs.com/references/medusa-workflows/steps/deletePricePreferencesStep/index.html.md)
-- [updatePricePreferencesStep](https://docs.medusajs.com/references/medusa-workflows/steps/updatePricePreferencesStep/index.html.md)
 - [updatePriceSetsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updatePriceSetsStep/index.html.md)
+- [updatePricePreferencesStep](https://docs.medusajs.com/references/medusa-workflows/steps/updatePricePreferencesStep/index.html.md)
 - [updatePricePreferencesAsArrayStep](https://docs.medusajs.com/references/medusa-workflows/steps/updatePricePreferencesAsArrayStep/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)
-- [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)
-- [revokeApiKeysStep](https://docs.medusajs.com/references/medusa-workflows/steps/revokeApiKeysStep/index.html.md)
-- [linkSalesChannelsToApiKeyStep](https://docs.medusajs.com/references/medusa-workflows/steps/linkSalesChannelsToApiKeyStep/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)
-- [deletePriceListsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deletePriceListsStep/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)
-- [batchLinkProductsToCollectionStep](https://docs.medusajs.com/references/medusa-workflows/steps/batchLinkProductsToCollectionStep/index.html.md)
-- [createProductTagsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createProductTagsStep/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)
-- [createProductTypesStep](https://docs.medusajs.com/references/medusa-workflows/steps/createProductTypesStep/index.html.md)
-- [deleteCollectionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteCollectionsStep/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)
-- [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)
-- [deleteProductTypesStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteProductTypesStep/index.html.md)
-- [deleteProductTagsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteProductTagsStep/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)
-- [deleteProductsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteProductsStep/index.html.md)
-- [getVariantAvailabilityStep](https://docs.medusajs.com/references/medusa-workflows/steps/getVariantAvailabilityStep/index.html.md)
-- [parseProductCsvStep](https://docs.medusajs.com/references/medusa-workflows/steps/parseProductCsvStep/index.html.md)
-- [getProductsStep](https://docs.medusajs.com/references/medusa-workflows/steps/getProductsStep/index.html.md)
-- [updateCollectionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateCollectionsStep/index.html.md)
-- [groupProductsForBatchStep](https://docs.medusajs.com/references/medusa-workflows/steps/groupProductsForBatchStep/index.html.md)
-- [updateProductTagsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateProductTagsStep/index.html.md)
-- [updateProductOptionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateProductOptionsStep/index.html.md)
-- [updateProductsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateProductsStep/index.html.md)
-- [updateProductVariantsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateProductVariantsStep/index.html.md)
-- [updateProductTypesStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateProductTypesStep/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)
-- [updateProductCategoriesStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateProductCategoriesStep/index.html.md)
-- [deleteProductCategoriesStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteProductCategoriesStep/index.html.md)
 - [addCampaignPromotionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/addCampaignPromotionsStep/index.html.md)
 - [addRulesToPromotionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/addRulesToPromotionsStep/index.html.md)
 - [createCampaignsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createCampaignsStep/index.html.md)
 - [createPromotionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createPromotionsStep/index.html.md)
-- [deletePromotionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deletePromotionsStep/index.html.md)
 - [deleteCampaignsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteCampaignsStep/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)
 - [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)
-- [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)
-- [createRegionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createRegionsStep/index.html.md)
-- [setRegionsPaymentProvidersStep](https://docs.medusajs.com/references/medusa-workflows/steps/setRegionsPaymentProvidersStep/index.html.md)
-- [updateRegionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateRegionsStep/index.html.md)
-- [deleteRegionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteRegionsStep/index.html.md)
+- [createCollectionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createCollectionsStep/index.html.md)
+- [batchLinkProductsToCollectionStep](https://docs.medusajs.com/references/medusa-workflows/steps/batchLinkProductsToCollectionStep/index.html.md)
+- [batchLinkProductsToCategoryStep](https://docs.medusajs.com/references/medusa-workflows/steps/batchLinkProductsToCategoryStep/index.html.md)
+- [createProductOptionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createProductOptionsStep/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)
+- [createProductTagsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createProductTagsStep/index.html.md)
+- [createProductsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createProductsStep/index.html.md)
+- [deleteCollectionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteCollectionsStep/index.html.md)
+- [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)
+- [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)
+- [deleteProductsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteProductsStep/index.html.md)
+- [deleteProductTypesStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteProductTypesStep/index.html.md)
+- [generateProductCsvStep](https://docs.medusajs.com/references/medusa-workflows/steps/generateProductCsvStep/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)
+- [groupProductsForBatchStep](https://docs.medusajs.com/references/medusa-workflows/steps/groupProductsForBatchStep/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)
+- [parseProductCsvStep](https://docs.medusajs.com/references/medusa-workflows/steps/parseProductCsvStep/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)
+- [deleteProductCategoriesStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteProductCategoriesStep/index.html.md)
+- [updateProductCategoriesStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateProductCategoriesStep/index.html.md)
 - [createReservationsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createReservationsStep/index.html.md)
-- [updateReservationsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateReservationsStep/index.html.md)
 - [deleteReservationsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteReservationsStep/index.html.md)
 - [deleteReservationsByLineItemsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteReservationsByLineItemsStep/index.html.md)
-- [createReturnReasonsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createReturnReasonsStep/index.html.md)
-- [updateReturnReasonsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateReturnReasonsStep/index.html.md)
-- [deleteReturnReasonStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteReturnReasonStep/index.html.md)
-- [associateLocationsWithSalesChannelsStep](https://docs.medusajs.com/references/medusa-workflows/steps/associateLocationsWithSalesChannelsStep/index.html.md)
-- [associateProductsWithSalesChannelsStep](https://docs.medusajs.com/references/medusa-workflows/steps/associateProductsWithSalesChannelsStep/index.html.md)
-- [createDefaultSalesChannelStep](https://docs.medusajs.com/references/medusa-workflows/steps/createDefaultSalesChannelStep/index.html.md)
-- [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)
-- [canDeleteSalesChannelsOrThrowStep](https://docs.medusajs.com/references/medusa-workflows/steps/canDeleteSalesChannelsOrThrowStep/index.html.md)
-- [updateSalesChannelsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateSalesChannelsStep/index.html.md)
-- [deleteSalesChannelsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteSalesChannelsStep/index.html.md)
+- [updateReservationsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateReservationsStep/index.html.md)
+- [createRegionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createRegionsStep/index.html.md)
+- [deleteRegionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteRegionsStep/index.html.md)
+- [setRegionsPaymentProvidersStep](https://docs.medusajs.com/references/medusa-workflows/steps/setRegionsPaymentProvidersStep/index.html.md)
+- [updateRegionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateRegionsStep/index.html.md)
 - [listShippingOptionsForContextStep](https://docs.medusajs.com/references/medusa-workflows/steps/listShippingOptionsForContextStep/index.html.md)
 - [deleteShippingProfilesStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteShippingProfilesStep/index.html.md)
-- [deleteStockLocationsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteStockLocationsStep/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)
 - [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)
 - [createStoresStep](https://docs.medusajs.com/references/medusa-workflows/steps/createStoresStep/index.html.md)
-- [updateStoresStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateStoresStep/index.html.md)
 - [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)
 - [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)
 - [createTaxRateRulesStep](https://docs.medusajs.com/references/medusa-workflows/steps/createTaxRateRulesStep/index.html.md)
 - [updateUsersStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateUsersStep/index.html.md)
 - [createTaxRatesStep](https://docs.medusajs.com/references/medusa-workflows/steps/createTaxRatesStep/index.html.md)
 - [deleteTaxRatesStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteTaxRatesStep/index.html.md)
+- [deleteTaxRateRulesStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteTaxRateRulesStep/index.html.md)
 - [createTaxRegionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createTaxRegionsStep/index.html.md)
 - [deleteTaxRegionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteTaxRegionsStep/index.html.md)
-- [deleteTaxRateRulesStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteTaxRateRulesStep/index.html.md)
 - [getItemTaxLinesStep](https://docs.medusajs.com/references/medusa-workflows/steps/getItemTaxLinesStep/index.html.md)
-- [listTaxRateIdsStep](https://docs.medusajs.com/references/medusa-workflows/steps/listTaxRateIdsStep/index.html.md)
 - [listTaxRateRuleIdsStep](https://docs.medusajs.com/references/medusa-workflows/steps/listTaxRateRuleIdsStep/index.html.md)
-- [updateTaxRegionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateTaxRegionsStep/index.html.md)
+- [listTaxRateIdsStep](https://docs.medusajs.com/references/medusa-workflows/steps/listTaxRateIdsStep/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)
+- [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)
+- [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)
+- [createDefaultSalesChannelStep](https://docs.medusajs.com/references/medusa-workflows/steps/createDefaultSalesChannelStep/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)
+- [updateSalesChannelsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateSalesChannelsStep/index.html.md)
 
 
 # Events Reference
@@ -32537,22 +32706,6 @@ npx medusa --help
 ***
 
 
-# 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).
@@ -32598,68 +32751,6 @@ medusa new [<dir_name> [<starter_url>]]
 |\`--db-host \<host>\`|The database host to use for database setup.|
 
 
-# build Command - Medusa CLI Reference
-
-Create a standalone build of the Medusa application.
-
-This creates a build that:
-
-- Doesn't rely on the source TypeScript files.
-- Can be copied to a production server reliably.
-
-The build is outputted to a new `.medusa/server` directory.
-
-```bash
-npx medusa build
-```
-
-Refer to [this section](#run-built-medusa-application) for next steps.
-
-## Options
-
-|Option|Description|
-|---|---|---|
-|\`--admin-only\`|Whether to only build the admin to host it separately. If this option is not passed, the admin is built to the |
-
-***
-
-## Run Built Medusa Application
-
-After running the `build` command, use the following step to run the built Medusa application:
-
-- Change to the `.medusa/server` directory and install the dependencies:
-
-```bash npm2yarn
-cd .medusa/server && npm install
-```
-
-- When running the application locally, make sure to copy the `.env` file from the root project's directory. In production, use system environment variables instead.
-
-```bash npm2yarn
-cp .env .medusa/server/.env.production
-```
-
-- In the system environment variables, set `NODE_ENV` to `production`:
-
-```bash
-NODE_ENV=production
-```
-
-- Use the `start` command to run the application:
-
-```bash npm2yarn
-cd .medusa/server && npm run start
-```
-
-***
-
-## Build Medusa Admin
-
-By default, the Medusa Admin is built to the `.medusa/server/public/admin` directory.
-
-If you want a separate build to host the admin standalone, such as on Vercel, pass the `--admin-only` option as explained in the [Options](#options) section. This outputs the admin to the `.medusa/admin` directory instead.
-
-
 # db Commands - Medusa CLI Reference
 
 Commands starting with `db:` perform actions on the database.
@@ -32780,6 +32871,22 @@ npx medusa db:sync-links
 |\`--execute-all\`|Skip prompts when syncing links and execute all (including unsafe) actions.|No|Prompts are shown for unsafe actions, by default.|
 
 
+# develop Command - Medusa CLI Reference
+
+Start Medusa application in development. This command watches files for any changes, then rebuilds the files and restarts the Medusa application.
+
+```bash
+npx medusa develop
+```
+
+## Options
+
+|Option|Description|Default|
+|---|---|---|---|---|
+|\`-H \<host>\`|Set host of the Medusa server.|\`localhost\`|
+|\`-p \<port>\`|Set port of the Medusa server.|\`9000\`|
+
+
 # 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.
@@ -32858,6 +32965,84 @@ npx medusa start
 |\`--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.|
 
 
+# build Command - Medusa CLI Reference
+
+Create a standalone build of the Medusa application.
+
+This creates a build that:
+
+- Doesn't rely on the source TypeScript files.
+- Can be copied to a production server reliably.
+
+The build is outputted to a new `.medusa/server` directory.
+
+```bash
+npx medusa build
+```
+
+Refer to [this section](#run-built-medusa-application) for next steps.
+
+## Options
+
+|Option|Description|
+|---|---|---|
+|\`--admin-only\`|Whether to only build the admin to host it separately. If this option is not passed, the admin is built to the |
+
+***
+
+## Run Built Medusa Application
+
+After running the `build` command, use the following step to run the built Medusa application:
+
+- Change to the `.medusa/server` directory and install the dependencies:
+
+```bash npm2yarn
+cd .medusa/server && npm install
+```
+
+- When running the application locally, make sure to copy the `.env` file from the root project's directory. In production, use system environment variables instead.
+
+```bash npm2yarn
+cp .env .medusa/server/.env.production
+```
+
+- In the system environment variables, set `NODE_ENV` to `production`:
+
+```bash
+NODE_ENV=production
+```
+
+- Use the `start` command to run the application:
+
+```bash npm2yarn
+cd .medusa/server && npm run start
+```
+
+***
+
+## Build Medusa Admin
+
+By default, the Medusa Admin is built to the `.medusa/server/public/admin` directory.
+
+If you want a separate build to host the admin standalone, such as on Vercel, pass the `--admin-only` option as explained in the [Options](#options) section. This outputs the admin to the `.medusa/admin` directory instead.
+
+
+# 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.
@@ -32877,22 +33062,6 @@ npx medusa user --email <email> [--password <password>]
 If ran successfully, you'll receive the invite token in the output.|No|\`false\`|
 
 
-# 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.|
-
-
 # Medusa CLI Reference
 
 The Medusa CLI tool provides commands that facilitate your development.
@@ -32978,67 +33147,6 @@ By default, the Medusa Admin is built to the `.medusa/server/public/admin` direc
 If you want a separate build to host the admin standalone, such as on Vercel, pass the `--admin-only` option as explained in the [Options](#options) section. This outputs the admin to the `.medusa/admin` directory instead.
 
 
-# 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|
-
-
-# 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.|
-
-
 # db Commands - Medusa CLI Reference
 
 Commands starting with `db:` perform actions on the database.
@@ -33159,6 +33267,22 @@ npx medusa db:sync-links
 |\`--execute-all\`|Skip prompts when syncing links and execute all (including unsafe) actions.|No|Prompts are shown for unsafe actions, by default.|
 
 
+# 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|
+
+
 # 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.
@@ -33220,6 +33344,22 @@ npx medusa plugin:build
 ```
 
 
+# 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.|
+
+
 # start Command - Medusa CLI Reference
 
 Start the Medusa application in production.
@@ -33237,6 +33377,22 @@ npx medusa start
 |\`--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.|
 
 
+# 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\`|
+
+
 # user Command - Medusa CLI Reference
 
 Create a new admin user.
@@ -33256,20 +33412,33 @@ npx medusa user --email <email> [--password <password>]
 If ran successfully, you'll receive the invite token in the output.|No|\`false\`|
 
 
-# telemetry Command - Medusa CLI Reference
+# new 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.
+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 telemetry
+medusa new [<dir_name> [<starter_url>]]
 ```
 
-#### Options
+## 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|
 |---|---|---|
-|\`--enable\`|Enable telemetry (default).|
-|\`--disable\`|Disable telemetry.|
+|\`-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.|
 
 
 # Medusa JS SDK
@@ -42411,6 +42580,637 @@ 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.
 
 
+# Send Abandoned Cart Notifications in Medusa
+
+In this tutorial, you will learn how to send notifications to customers who have abandoned their carts.
+
+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. These features include cart-management capabilities.
+
+Medusa's [Notification Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/infrastructure-modules/notification/index.html.md) allows you to send notifications to users or customers, such as password reset emails, order confirmation SMS, or other types of notifications.
+
+In this tutorial, you will use the Notification Module to send an email to customers who have abandoned their carts. The email will contain a link to recover the customer's cart, encouraging them to complete their purchase. You will use SendGrid to send the emails, but you can also use other email providers.
+
+## Summary
+
+By following this tutorial, you will:
+
+- Install and set up Medusa.
+- Create the logic to send an email to customers who have abandoned their carts.
+- Run the above logic once a day.
+- Add a route to the storefront to recover the cart.
+
+![Diagram illustrating the flow of the abandoned-cart functionalities](https://res.cloudinary.com/dza7lstvk/image/upload/v1742460588/Medusa%20Resources/abandoned-cart-summary_fcf2tn.jpg)
+
+[View on Github](https://github.com/medusajs/examples/tree/main/abandoned-cart): Find the full code for this tutorial.
+
+***
+
+## 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 will 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: Set up SendGrid
+
+### Prerequisites
+
+- [SendGrid account](https://sendgrid.com)
+- [Verified Sender Identity](https://mc.sendgrid.com/senders)
+- [SendGrid API Key](https://app.sendgrid.com/settings/api_keys)
+
+Medusa's Notification Module provides the general functionality to send notifications, but the sending logic is implemented in a module provider. This allows you to integrate the email provider of your choice.
+
+To send the cart-abandonment emails, you will use SendGrid. Medusa provides a [SendGrid Notification Module Provider](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/infrastructure-modules/notification/sendgrid/index.html.md) that you can use to send emails.
+
+Alternatively, you can use [other Notification Module Providers](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/infrastructure-modules/notification#what-is-a-notification-module-provider/index.html.md) or [create a custom provider](https://docs.medusajs.com/references/notification-provider-module/index.html.md).
+
+To set up SendGrid, add the SendGrid Notification Module Provider to `medusa-config.ts`:
+
+```ts title="medusa-config.ts"
+module.exports = defineConfig({
+  // ...
+  modules: [
+    {
+      resolve: "@medusajs/medusa/notification",
+      options: {
+        providers: [
+          {
+            resolve: "@medusajs/medusa/notification-sendgrid",
+            id: "sendgrid",
+            options: {
+              channels: ["email"],
+              api_key: process.env.SENDGRID_API_KEY,
+              from: process.env.SENDGRID_FROM,
+            },
+          },
+        ],
+      },
+    },
+  ],
+})
+```
+
+In the `modules` configuration, you pass the Notification Provider and add SendGrid as a provider. You also pass to the SendGrid Module Provider the following options:
+
+- `channels`: The channels that the provider supports. In this case, it is only email.
+- `api_key`: Your SendGrid API key.
+- `from`: The email address that the emails will be sent from.
+
+Then, set the SendGrid API key and "from" email as environment variables, such as in the `.env` file at the root of your project:
+
+```plain
+SENDGRID_API_KEY=your-sendgrid-api-key
+SENDGRID_FROM=test@gmail.com
+```
+
+You can now use SendGrid to send emails in Medusa.
+
+***
+
+## Step 3: Send Abandoned Cart Notification Flow
+
+You will now implement the sending logic for the abandoned cart notifications.
+
+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 is 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 scheduled job.
+
+In this step, you will create the workflow that sends the abandoned cart notifications. Later, you will learn how to execute it once a day.
+
+The workflow will receive the list of abandoned carts as an input. The workflow has the following steps:
+
+- [sendAbandonedNotificationsStep](#sendAbandonedNotificationsStep): Send the abandoned cart notifications.
+- [updateCartsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateCartsStep/index.html.md): Update the cart to store the last notification date.
+
+Medusa provides the second step in its `@medusajs/medusa/core-flows` package. So, you only need to implement the first one.
+
+### sendAbandonedNotificationsStep
+
+The first step of the workflow sends a notification to the owners of the abandoned carts that are passed as an input.
+
+To implement the step, create the file `src/workflows/steps/send-abandoned-notifications.ts` with the following content:
+
+```ts title="src/workflows/steps/send-abandoned-notifications.ts"
+import { 
+  createStep,
+  StepResponse, 
+} from "@medusajs/framework/workflows-sdk"
+import { Modules } from "@medusajs/framework/utils"
+import { CartDTO, CustomerDTO } from "@medusajs/framework/types"
+
+type SendAbandonedNotificationsStepInput = {
+  carts: (CartDTO & {
+    customer: CustomerDTO
+  })[]
+}
+
+export const sendAbandonedNotificationsStep = createStep(
+  "send-abandoned-notifications",
+  async (input: SendAbandonedNotificationsStepInput, { container }) => {
+    const notificationModuleService = container.resolve(
+      Modules.NOTIFICATION
+    )
+
+    const notificationData = input.carts.map((cart) => ({
+      to: cart.email!,
+      channel: "email", 
+      template: process.env.ABANDONED_CART_TEMPLATE_ID || "",
+      data: {
+        customer: {
+          first_name: cart.customer?.first_name || cart.shipping_address?.first_name,
+          last_name: cart.customer?.last_name || cart.shipping_address?.last_name,
+        },
+        cart_id: cart.id,
+        items: cart.items?.map((item) => ({
+          product_title: item.title,
+          quantity: item.quantity,
+          unit_price: item.unit_price,
+          thumbnail: item.thumbnail,
+        })),
+      },
+    }))
+
+    const notifications = await notificationModuleService.createNotifications(
+      notificationData
+    )
+
+    return new StepResponse({
+      notifications,
+    })
+  }
+)
+```
+
+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 first resolve the Notification Module's service, which has methods to manage notifications. Then, you prepare the data of each notification, and create the notifications with the `createNotifications` method.
+
+Notice that each notification is an object with the following properties:
+
+- `to`: The email address of the customer.
+- `channel`: The channel that the notification will be sent through. The Notification Module uses the provider registered for the channel.
+- `template`: The ID or name of the email template in the third-party provider. Make sure to set it as an environment variable once you have it.
+- `data`: The data to pass to the template to render the email's dynamic content.
+
+Based on the dynamic template you create in SendGrid or another provider, you can pass different data in the `data` object.
+
+A step function must return a `StepResponse` instance. The `StepResponse` constructor accepts the step's output as a parameter, which is the created notifications.
+
+### Create Workflow
+
+You can now create the workflow that uses the step you just created to send the abandoned cart notifications.
+
+Create the file `src/workflows/send-abandoned-carts.ts` with the following content:
+
+```ts title="src/workflows/send-abandoned-carts.ts"
+import {
+  createWorkflow,
+  WorkflowResponse,
+  transform,
+} from "@medusajs/framework/workflows-sdk"
+import { 
+  sendAbandonedNotificationsStep,
+} from "./steps/send-abandoned-notifications"
+import { updateCartsStep } from "@medusajs/medusa/core-flows"
+import { CartDTO } from "@medusajs/framework/types"
+import { CustomerDTO } from "@medusajs/framework/types"
+
+export type SendAbandonedCartsWorkflowInput = {
+  carts: (CartDTO & {
+    customer: CustomerDTO
+  })[]
+}
+
+export const sendAbandonedCartsWorkflow = createWorkflow(
+  "send-abandoned-carts",
+  function (input: SendAbandonedCartsWorkflowInput) {
+    sendAbandonedNotificationsStep(input)
+
+    const updateCartsData = transform(
+      input,
+      (data) => {
+        return data.carts.map((cart) => ({
+          id: cart.id,
+          metadata: {
+            ...cart.metadata,
+            abandoned_notification: new Date().toISOString(),
+          },
+        }))
+      }
+    )
+
+    const updatedCarts = updateCartsStep(updateCartsData)
+
+    return new WorkflowResponse(updatedCarts)
+  }
+)
+```
+
+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 arra of carts.
+
+In the workflow's constructor function, you:
+
+- Use the `sendAbandonedNotificationsStep` to send the notifications to the carts' customers.
+- Use the `updateCartsStep` from Medusa's core flows to update the carts' metadata with the last notification date.
+
+Notice that you use the `transform` function to prepare the `updateCartsStep`'s input. Medusa does not support direct data manipulation in a workflow's constructor function. You can learn more about it in the [Data Manipulation in Workflows documentation](https://docs.medusajs.com/docs/learn/fundamentals/workflows/variable-manipulation/index.html.md).
+
+Your workflow is now ready for use. You will learn how to execute it in the next section.
+
+### Setup Email Template
+
+Before you can test the workflow, you need to set up an email template in SendGrid. The template should contain the dynamic content that you pass in the workflow's step.
+
+To create an email template in SendGrid:
+
+- Go to [Dynamic Templates](https://mc.sendgrid.com/dynamic-templates) in the SendGrid dashboard.
+- Click on the "Create Dynamic Template" button.
+
+![Button is at the top right of the page](https://res.cloudinary.com/dza7lstvk/image/upload/v1742457153/Medusa%20Resources/Screenshot_2025-03-20_at_9.51.38_AM_g5nk80.png)
+
+- In the side window that opens, enter a name for the template, then click on the Create button.
+- The template will be added to the middle of the page. When you click on it, a new section will show with an "Add Version" button. Click on it.
+
+![The template is a collapsible in the middle of the page,with the "Add Version" button shown in the middle](https://res.cloudinary.com/dza7lstvk/image/upload/v1742458096/Medusa%20Resources/Screenshot_2025-03-20_at_10.07.54_AM_y2dys7.png)
+
+In the form that opens, you can either choose to start with a blank template or from an existing design. You can then use the drag-and-drop or code editor to design the email template.
+
+You can also use the following template as an example:
+
+```html title="Abandoned Cart Email Template"
+<!DOCTYPE html>
+<html>
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <title>Complete Your Purchase</title>
+    <style>
+        body {
+            font-family: Arial, sans-serif;
+            background-color: #f8f9fa;
+            margin: 0;
+            padding: 20px;
+        }
+        .container {
+            max-width: 600px;
+            background: #ffffff;
+            padding: 20px;
+            border-radius: 10px;
+            box-shadow: 0px 4px 10px rgba(0, 0, 0, 0.1);
+            text-align: center;
+        }
+        .header {
+            font-size: 26px;
+            font-weight: bold;
+            color: #333;
+            margin-bottom: 20px;
+        }
+        .message {
+            font-size: 16px;
+            color: #555;
+            margin-bottom: 20px;
+        }
+        .item {
+            display: flex;
+            align-items: center;
+            background: #f9f9f9;
+            padding: 10px;
+            border-radius: 8px;
+            margin-bottom: 15px;
+        }
+        .item img {
+            width: 80px;
+            height: auto;
+            margin-right: 15px;
+            border-radius: 5px;
+        }
+        .item-details {
+            text-align: left;
+            flex-grow: 1;
+        }
+        .item-details strong {
+            font-size: 18px;
+            color: #333;
+        }
+        .item-details p {
+            font-size: 14px;
+            color: #777;
+            margin: 5px 0;
+        }
+        .button {
+            display: inline-block;
+            background-color: #007bff;
+            color: #ffffff;
+            text-decoration: none;
+            font-size: 18px;
+            padding: 12px 20px;
+            border-radius: 5px;
+            margin-top: 20px;
+            transition: background 0.3s ease;
+        }
+        .button:hover {
+            background-color: #0056b3;
+        }
+        .footer {
+            font-size: 12px;
+            color: #888;
+            margin-top: 20px;
+        }
+    </style>
+</head>
+<body>
+    <div class="container">
+        <div class="header">Hi {{customer.first_name}}, your cart is waiting! 🛍️</div>
+        <p class="message">You left some great items in your cart. Complete your purchase before they're gone!</p>
+        
+        {{#each items}}
+        <div class="item">
+            <img src="{{thumbnail}}" alt="{{product_title}}">
+            <div class="item-details">
+                <strong>{{product_title}}</strong>
+                <p>{{subtitle}}</p>
+                <p>Quantity: <strong>{{quantity}}</strong></p>
+                <p>Price: <strong>$ {{unit_price}}</strong></p>
+            </div>
+        </div>
+        {{/each}}
+        
+        <a href="https://yourstore.com/cart/recover/{{cart_id}}" class="button">Return to Cart & Checkout</a>
+        <p class="footer">Need help? <a href="mailto:support@yourstore.com">Contact us</a></p>
+    </div>
+</body>
+</html>
+```
+
+This template will show each item's image, title, quantity, and price in the cart. It will also show a button to return to the cart and checkout.
+
+You can replace `https://yourstore.com` with your storefront's URL. You'll later implement the `/cart/recover/:cart_id` route in the storefront to recover the cart.
+
+Once you are done, copy the template ID from SendGrid and set it as an environment variable in your Medusa project:
+
+```plain
+ABANDONED_CART_TEMPLATE_ID=your-sendgrid-template-id
+```
+
+***
+
+## Step 4: Schedule Cart Abandonment Notifications
+
+The next step is to automate sending the abandoned cart notifications. You need a task that runs once a day to find the carts that have been abandoned for a certain period and send the notifications to the customers.
+
+To run a task at a scheduled interval, you can use a [scheduled job](https://docs.medusajs.com/docs/learn/fundamentals/scheduled-jobs/index.html.md). A scheduled job is an asynchronous function that the Medusa application runs at the interval you specify during the Medusa application's runtime.
+
+You can create a scheduled job in a TypeScript or JavaScript file under the `src/jobs` directory. So, to create the scheduled job that sends the abandoned cart notifications, create the file `src/jobs/send-abandoned-cart-notification.ts` with the following content:
+
+```ts title="src/jobs/send-abandoned-cart-notification.ts"
+import { MedusaContainer } from "@medusajs/framework/types"
+import { 
+  sendAbandonedCartsWorkflow, 
+  SendAbandonedCartsWorkflowInput,
+} from "../workflows/send-abandoned-carts"
+
+export default async function abandonedCartJob(
+  container: MedusaContainer
+) {
+  const logger = container.resolve("logger")
+  const query = container.resolve("query")
+
+  const oneDayAgo = new Date()
+  oneDayAgo.setDate(oneDayAgo.getDate() - 1)
+  const limit = 100
+  const offset = 0
+  const totalCount = 0
+  const abandonedCartsCount = 0
+
+  do {
+    // TODO retrieve paginated abandoned carts
+  } while (offset < totalCount)
+
+  logger.info(`Sent ${abandonedCartsCount} abandoned cart notifications`)
+}
+
+export const config = {
+  name: "abandoned-cart-notification",
+  schedule: "0 0 * * *", // Run at midnight every day
+}
+```
+
+In a scheduled job's file, you must export:
+
+1. An asynchronous function that holds 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.
+2. A `config` object that specifies the job's name and schedule. The schedule is a [cron expression](https://crontab.guru/) that defines the interval at which the job runs.
+
+In the scheduled job function, so far you resolve the [Logger](https://docs.medusajs.com/docs/learn/debugging-and-testing/logging/index.html.md) to log messages, and [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md) to retrieve data across modules.
+
+You also define a `oneDayAgo` date, which is the date that you will use as the condition of an abandoned cart. In addition, you define variables to paginate the carts.
+
+Next, you will retrieve the abandoned carts using Query. Replace the `TODO` with the following:
+
+```ts title="src/jobs/send-abandoned-cart-notification.ts"
+const { 
+  data: abandonedCarts, 
+  metadata,
+} = await query.graph({
+  entity: "cart",
+  fields: [
+    "id",
+    "email",
+    "items.*",
+    "metadata",
+    "customer.*",
+  ],
+  filters: {
+    updated_at: {
+      $lt: oneDayAgo,
+    },
+    // @ts-ignore
+    email: {
+      $ne: null,
+    },
+    // @ts-ignore
+    completed_at: null,
+  },
+  pagination: {
+    skip: offset,
+    take: limit,
+  },
+})
+
+totalCount = metadata?.count ?? 0
+const cartsWithItems = abandonedCarts.filter((cart) => 
+  cart.items?.length > 0 && !cart.metadata?.abandoned_notification
+)
+
+try {
+  await sendAbandonedCartsWorkflow(container).run({
+    input: {
+      carts: cartsWithItems,
+    } as unknown as SendAbandonedCartsWorkflowInput,
+  })
+  abandonedCartsCount += cartsWithItems.length
+
+} catch (error) {
+  logger.error(
+    `Failed to send abandoned cart notification: ${error.message}`
+  )
+}
+
+offset += limit
+```
+
+In the do-while loop, you use Query to retrieve carts matching the following criteria:
+
+- The cart was last updated more than a day ago.
+- The cart has an email address.
+- The cart has not been completed.
+
+You also filter the retrieved carts to only include carts with items and customers that have not received an abandoned cart notification.
+
+Finally, you execute the `sendAbandonedCartsWorkflow` passing it the abandoned carts as an input. You will execute the workflow for each paginated batch of carts.
+
+### Test it Out
+
+To test out the scheduled job and workflow, it is recommended to change the `oneDayAgo` date to a minute before now for easy testing:
+
+```ts title="src/jobs/send-abandoned-cart-notification.ts"
+oneDayAgo.setMinutes(oneDayAgo.getMinutes() - 1) // For testing
+```
+
+And to change the job's schedule in `config` to run every minute:
+
+```ts title="src/jobs/send-abandoned-cart-notification.ts"
+export const config = {
+  // ...
+  schedule: "* * * * *", // Run every minute for testing
+}
+```
+
+Finally, start the Medusa application with the following command:
+
+```bash npm2yarn
+npm run dev
+```
+
+And in the [Next.js Starter Storefront](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/nextjs-starter/index.html.md)'s directory (that you installed in the first step), start the storefront with the following command:
+
+```bash npm2yarn
+npm run dev
+```
+
+Open the storefront at `localhost:8000`. You can either:
+
+- Create an account and add items to the cart, then leave the cart for a minute.
+- Add an item to the cart as a guest. Then, start the checkout process, but only enter the shipping and email addresses, and leave the cart for a minute.
+
+Afterwards, wait for the job to execute. Once it is executed, you will see the following message in the terminal:
+
+```bash
+info:    Sent 1 abandoned cart notifications
+```
+
+Once you're done testing, make sure to revert the changes to the `oneDayAgo` date and the job's schedule.
+
+***
+
+## Step 5: Recover Cart in Storefront
+
+In the storefront, you need to add a route that recovers the cart when the customer clicks on the link in the email. The route should receive the cart ID, set the cart ID in the cookie, and redirect the customer to the cart page.
+
+To implement the route, in the Next.js Starter Storefront create the file `src/app/[countryCode]/(main)/cart/recover/[id]/route.tsx` with the following content:
+
+```tsx title="src/app/[countryCode]/(main)/cart/recover/[id]/route.tsx" badgeLabel="Storefront" badgeColor="blue"
+import { NextRequest } from "next/server"
+import { retrieveCart } from "../../../../../../lib/data/cart"
+import { setCartId } from "../../../../../../lib/data/cookies"
+import { notFound, redirect } from "next/navigation"
+type Params = Promise<{
+  id: string
+}>
+
+export async function GET(req: NextRequest, { params }: { params: Params }) {
+  const { id } = await params
+  const cart = await retrieveCart(id)
+
+  if (!cart) {
+    return notFound()
+  }
+
+  setCartId(id)
+
+  const countryCode = cart.shipping_address?.country_code || 
+    cart.region?.countries?.[0]?.iso_2
+
+  redirect(
+    `/${countryCode ? `${countryCode}/` : ""}cart`
+  )
+}
+```
+
+You add a `GET` route handler that receives the cart ID as a path parameter. In the route handler, you:
+
+- Try to retrieve the cart from the Medusa application. The `retrieveCart` function is already available in the Next.js storefront. If the cart is not found, you return a 404 response.
+- Set the cart ID in a cookie using the `setCartId` function. This is also a function that is already available in the storefront.
+- Redirect the customer to the cart page. You set the country code in the URL based on the cart's shipping address or region.
+
+### Test it Out
+
+To test it out, start the Medusa application:
+
+```bash npm2yarn
+npm run dev
+```
+
+And in the Next.js Starter Storefront's directory, start the storefront:
+
+```bash npm2yarn
+npm run dev
+```
+
+Then, either open the link in an abandoned cart email or navigate to `localhost:8000/cart/recover/:cart_id` in your browser. You will be redirected to the cart page with the recovered cart.
+
+![Cart page in the storefront](https://res.cloudinary.com/dza7lstvk/image/upload/v1742459552/Medusa%20Resources/Screenshot_2025-03-20_at_10.32.17_AM_frmbup.png)
+
+***
+
+## Next Steps
+
+You have now implemented the logic to send abandoned cart notifications in Medusa. You can implement other customizations with Medusa, such as:
+
+- [Implement Product Reviews](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/how-to-tutorials/tutorials/product-reviews/index.html.md).
+- [Implement Wishlist](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/plugins/guides/wishlist/index.html.md).
+- [Allow Custom-Item Pricing](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/examples/guides/custom-item-price/index.html.md).
+
+If you are new to Medusa, check out the [main documentation](https://docs.medusajs.com/docs/learn/index.html.md), where you will get a more in-depth learning of all the concepts you have 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).
+
+
 # Implement Loyalty Points System in Medusa
 
 In this tutorial, you'll learn how to implement a loyalty points system in Medusa.
@@ -44202,1481 +45002,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).
 
 
-# Send Abandoned Cart Notifications in Medusa
-
-In this tutorial, you will learn how to send notifications to customers who have abandoned their carts.
-
-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. These features include cart-management capabilities.
-
-Medusa's [Notification Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/infrastructure-modules/notification/index.html.md) allows you to send notifications to users or customers, such as password reset emails, order confirmation SMS, or other types of notifications.
-
-In this tutorial, you will use the Notification Module to send an email to customers who have abandoned their carts. The email will contain a link to recover the customer's cart, encouraging them to complete their purchase. You will use SendGrid to send the emails, but you can also use other email providers.
-
-## Summary
-
-By following this tutorial, you will:
-
-- Install and set up Medusa.
-- Create the logic to send an email to customers who have abandoned their carts.
-- Run the above logic once a day.
-- Add a route to the storefront to recover the cart.
-
-![Diagram illustrating the flow of the abandoned-cart functionalities](https://res.cloudinary.com/dza7lstvk/image/upload/v1742460588/Medusa%20Resources/abandoned-cart-summary_fcf2tn.jpg)
-
-[View on Github](https://github.com/medusajs/examples/tree/main/abandoned-cart): Find the full code for this tutorial.
-
-***
-
-## 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 will 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: Set up SendGrid
-
-### Prerequisites
-
-- [SendGrid account](https://sendgrid.com)
-- [Verified Sender Identity](https://mc.sendgrid.com/senders)
-- [SendGrid API Key](https://app.sendgrid.com/settings/api_keys)
-
-Medusa's Notification Module provides the general functionality to send notifications, but the sending logic is implemented in a module provider. This allows you to integrate the email provider of your choice.
-
-To send the cart-abandonment emails, you will use SendGrid. Medusa provides a [SendGrid Notification Module Provider](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/infrastructure-modules/notification/sendgrid/index.html.md) that you can use to send emails.
-
-Alternatively, you can use [other Notification Module Providers](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/infrastructure-modules/notification#what-is-a-notification-module-provider/index.html.md) or [create a custom provider](https://docs.medusajs.com/references/notification-provider-module/index.html.md).
-
-To set up SendGrid, add the SendGrid Notification Module Provider to `medusa-config.ts`:
-
-```ts title="medusa-config.ts"
-module.exports = defineConfig({
-  // ...
-  modules: [
-    {
-      resolve: "@medusajs/medusa/notification",
-      options: {
-        providers: [
-          {
-            resolve: "@medusajs/medusa/notification-sendgrid",
-            id: "sendgrid",
-            options: {
-              channels: ["email"],
-              api_key: process.env.SENDGRID_API_KEY,
-              from: process.env.SENDGRID_FROM,
-            },
-          },
-        ],
-      },
-    },
-  ],
-})
-```
-
-In the `modules` configuration, you pass the Notification Provider and add SendGrid as a provider. You also pass to the SendGrid Module Provider the following options:
-
-- `channels`: The channels that the provider supports. In this case, it is only email.
-- `api_key`: Your SendGrid API key.
-- `from`: The email address that the emails will be sent from.
-
-Then, set the SendGrid API key and "from" email as environment variables, such as in the `.env` file at the root of your project:
-
-```plain
-SENDGRID_API_KEY=your-sendgrid-api-key
-SENDGRID_FROM=test@gmail.com
-```
-
-You can now use SendGrid to send emails in Medusa.
-
-***
-
-## Step 3: Send Abandoned Cart Notification Flow
-
-You will now implement the sending logic for the abandoned cart notifications.
-
-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 is 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 scheduled job.
-
-In this step, you will create the workflow that sends the abandoned cart notifications. Later, you will learn how to execute it once a day.
-
-The workflow will receive the list of abandoned carts as an input. The workflow has the following steps:
-
-- [sendAbandonedNotificationsStep](#sendAbandonedNotificationsStep): Send the abandoned cart notifications.
-- [updateCartsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateCartsStep/index.html.md): Update the cart to store the last notification date.
-
-Medusa provides the second step in its `@medusajs/medusa/core-flows` package. So, you only need to implement the first one.
-
-### sendAbandonedNotificationsStep
-
-The first step of the workflow sends a notification to the owners of the abandoned carts that are passed as an input.
-
-To implement the step, create the file `src/workflows/steps/send-abandoned-notifications.ts` with the following content:
-
-```ts title="src/workflows/steps/send-abandoned-notifications.ts"
-import { 
-  createStep,
-  StepResponse, 
-} from "@medusajs/framework/workflows-sdk"
-import { Modules } from "@medusajs/framework/utils"
-import { CartDTO, CustomerDTO } from "@medusajs/framework/types"
-
-type SendAbandonedNotificationsStepInput = {
-  carts: (CartDTO & {
-    customer: CustomerDTO
-  })[]
-}
-
-export const sendAbandonedNotificationsStep = createStep(
-  "send-abandoned-notifications",
-  async (input: SendAbandonedNotificationsStepInput, { container }) => {
-    const notificationModuleService = container.resolve(
-      Modules.NOTIFICATION
-    )
-
-    const notificationData = input.carts.map((cart) => ({
-      to: cart.email!,
-      channel: "email", 
-      template: process.env.ABANDONED_CART_TEMPLATE_ID || "",
-      data: {
-        customer: {
-          first_name: cart.customer?.first_name || cart.shipping_address?.first_name,
-          last_name: cart.customer?.last_name || cart.shipping_address?.last_name,
-        },
-        cart_id: cart.id,
-        items: cart.items?.map((item) => ({
-          product_title: item.title,
-          quantity: item.quantity,
-          unit_price: item.unit_price,
-          thumbnail: item.thumbnail,
-        })),
-      },
-    }))
-
-    const notifications = await notificationModuleService.createNotifications(
-      notificationData
-    )
-
-    return new StepResponse({
-      notifications,
-    })
-  }
-)
-```
-
-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 first resolve the Notification Module's service, which has methods to manage notifications. Then, you prepare the data of each notification, and create the notifications with the `createNotifications` method.
-
-Notice that each notification is an object with the following properties:
-
-- `to`: The email address of the customer.
-- `channel`: The channel that the notification will be sent through. The Notification Module uses the provider registered for the channel.
-- `template`: The ID or name of the email template in the third-party provider. Make sure to set it as an environment variable once you have it.
-- `data`: The data to pass to the template to render the email's dynamic content.
-
-Based on the dynamic template you create in SendGrid or another provider, you can pass different data in the `data` object.
-
-A step function must return a `StepResponse` instance. The `StepResponse` constructor accepts the step's output as a parameter, which is the created notifications.
-
-### Create Workflow
-
-You can now create the workflow that uses the step you just created to send the abandoned cart notifications.
-
-Create the file `src/workflows/send-abandoned-carts.ts` with the following content:
-
-```ts title="src/workflows/send-abandoned-carts.ts"
-import {
-  createWorkflow,
-  WorkflowResponse,
-  transform,
-} from "@medusajs/framework/workflows-sdk"
-import { 
-  sendAbandonedNotificationsStep,
-} from "./steps/send-abandoned-notifications"
-import { updateCartsStep } from "@medusajs/medusa/core-flows"
-import { CartDTO } from "@medusajs/framework/types"
-import { CustomerDTO } from "@medusajs/framework/types"
-
-export type SendAbandonedCartsWorkflowInput = {
-  carts: (CartDTO & {
-    customer: CustomerDTO
-  })[]
-}
-
-export const sendAbandonedCartsWorkflow = createWorkflow(
-  "send-abandoned-carts",
-  function (input: SendAbandonedCartsWorkflowInput) {
-    sendAbandonedNotificationsStep(input)
-
-    const updateCartsData = transform(
-      input,
-      (data) => {
-        return data.carts.map((cart) => ({
-          id: cart.id,
-          metadata: {
-            ...cart.metadata,
-            abandoned_notification: new Date().toISOString(),
-          },
-        }))
-      }
-    )
-
-    const updatedCarts = updateCartsStep(updateCartsData)
-
-    return new WorkflowResponse(updatedCarts)
-  }
-)
-```
-
-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 arra of carts.
-
-In the workflow's constructor function, you:
-
-- Use the `sendAbandonedNotificationsStep` to send the notifications to the carts' customers.
-- Use the `updateCartsStep` from Medusa's core flows to update the carts' metadata with the last notification date.
-
-Notice that you use the `transform` function to prepare the `updateCartsStep`'s input. Medusa does not support direct data manipulation in a workflow's constructor function. You can learn more about it in the [Data Manipulation in Workflows documentation](https://docs.medusajs.com/docs/learn/fundamentals/workflows/variable-manipulation/index.html.md).
-
-Your workflow is now ready for use. You will learn how to execute it in the next section.
-
-### Setup Email Template
-
-Before you can test the workflow, you need to set up an email template in SendGrid. The template should contain the dynamic content that you pass in the workflow's step.
-
-To create an email template in SendGrid:
-
-- Go to [Dynamic Templates](https://mc.sendgrid.com/dynamic-templates) in the SendGrid dashboard.
-- Click on the "Create Dynamic Template" button.
-
-![Button is at the top right of the page](https://res.cloudinary.com/dza7lstvk/image/upload/v1742457153/Medusa%20Resources/Screenshot_2025-03-20_at_9.51.38_AM_g5nk80.png)
-
-- In the side window that opens, enter a name for the template, then click on the Create button.
-- The template will be added to the middle of the page. When you click on it, a new section will show with an "Add Version" button. Click on it.
-
-![The template is a collapsible in the middle of the page,with the "Add Version" button shown in the middle](https://res.cloudinary.com/dza7lstvk/image/upload/v1742458096/Medusa%20Resources/Screenshot_2025-03-20_at_10.07.54_AM_y2dys7.png)
-
-In the form that opens, you can either choose to start with a blank template or from an existing design. You can then use the drag-and-drop or code editor to design the email template.
-
-You can also use the following template as an example:
-
-```html title="Abandoned Cart Email Template"
-<!DOCTYPE html>
-<html>
-<head>
-    <meta charset="UTF-8">
-    <meta name="viewport" content="width=device-width, initial-scale=1">
-    <title>Complete Your Purchase</title>
-    <style>
-        body {
-            font-family: Arial, sans-serif;
-            background-color: #f8f9fa;
-            margin: 0;
-            padding: 20px;
-        }
-        .container {
-            max-width: 600px;
-            background: #ffffff;
-            padding: 20px;
-            border-radius: 10px;
-            box-shadow: 0px 4px 10px rgba(0, 0, 0, 0.1);
-            text-align: center;
-        }
-        .header {
-            font-size: 26px;
-            font-weight: bold;
-            color: #333;
-            margin-bottom: 20px;
-        }
-        .message {
-            font-size: 16px;
-            color: #555;
-            margin-bottom: 20px;
-        }
-        .item {
-            display: flex;
-            align-items: center;
-            background: #f9f9f9;
-            padding: 10px;
-            border-radius: 8px;
-            margin-bottom: 15px;
-        }
-        .item img {
-            width: 80px;
-            height: auto;
-            margin-right: 15px;
-            border-radius: 5px;
-        }
-        .item-details {
-            text-align: left;
-            flex-grow: 1;
-        }
-        .item-details strong {
-            font-size: 18px;
-            color: #333;
-        }
-        .item-details p {
-            font-size: 14px;
-            color: #777;
-            margin: 5px 0;
-        }
-        .button {
-            display: inline-block;
-            background-color: #007bff;
-            color: #ffffff;
-            text-decoration: none;
-            font-size: 18px;
-            padding: 12px 20px;
-            border-radius: 5px;
-            margin-top: 20px;
-            transition: background 0.3s ease;
-        }
-        .button:hover {
-            background-color: #0056b3;
-        }
-        .footer {
-            font-size: 12px;
-            color: #888;
-            margin-top: 20px;
-        }
-    </style>
-</head>
-<body>
-    <div class="container">
-        <div class="header">Hi {{customer.first_name}}, your cart is waiting! 🛍️</div>
-        <p class="message">You left some great items in your cart. Complete your purchase before they're gone!</p>
-        
-        {{#each items}}
-        <div class="item">
-            <img src="{{thumbnail}}" alt="{{product_title}}">
-            <div class="item-details">
-                <strong>{{product_title}}</strong>
-                <p>{{subtitle}}</p>
-                <p>Quantity: <strong>{{quantity}}</strong></p>
-                <p>Price: <strong>$ {{unit_price}}</strong></p>
-            </div>
-        </div>
-        {{/each}}
-        
-        <a href="https://yourstore.com/cart/recover/{{cart_id}}" class="button">Return to Cart & Checkout</a>
-        <p class="footer">Need help? <a href="mailto:support@yourstore.com">Contact us</a></p>
-    </div>
-</body>
-</html>
-```
-
-This template will show each item's image, title, quantity, and price in the cart. It will also show a button to return to the cart and checkout.
-
-You can replace `https://yourstore.com` with your storefront's URL. You'll later implement the `/cart/recover/:cart_id` route in the storefront to recover the cart.
-
-Once you are done, copy the template ID from SendGrid and set it as an environment variable in your Medusa project:
-
-```plain
-ABANDONED_CART_TEMPLATE_ID=your-sendgrid-template-id
-```
-
-***
-
-## Step 4: Schedule Cart Abandonment Notifications
-
-The next step is to automate sending the abandoned cart notifications. You need a task that runs once a day to find the carts that have been abandoned for a certain period and send the notifications to the customers.
-
-To run a task at a scheduled interval, you can use a [scheduled job](https://docs.medusajs.com/docs/learn/fundamentals/scheduled-jobs/index.html.md). A scheduled job is an asynchronous function that the Medusa application runs at the interval you specify during the Medusa application's runtime.
-
-You can create a scheduled job in a TypeScript or JavaScript file under the `src/jobs` directory. So, to create the scheduled job that sends the abandoned cart notifications, create the file `src/jobs/send-abandoned-cart-notification.ts` with the following content:
-
-```ts title="src/jobs/send-abandoned-cart-notification.ts"
-import { MedusaContainer } from "@medusajs/framework/types"
-import { 
-  sendAbandonedCartsWorkflow, 
-  SendAbandonedCartsWorkflowInput,
-} from "../workflows/send-abandoned-carts"
-
-export default async function abandonedCartJob(
-  container: MedusaContainer
-) {
-  const logger = container.resolve("logger")
-  const query = container.resolve("query")
-
-  const oneDayAgo = new Date()
-  oneDayAgo.setDate(oneDayAgo.getDate() - 1)
-  const limit = 100
-  const offset = 0
-  const totalCount = 0
-  const abandonedCartsCount = 0
-
-  do {
-    // TODO retrieve paginated abandoned carts
-  } while (offset < totalCount)
-
-  logger.info(`Sent ${abandonedCartsCount} abandoned cart notifications`)
-}
-
-export const config = {
-  name: "abandoned-cart-notification",
-  schedule: "0 0 * * *", // Run at midnight every day
-}
-```
-
-In a scheduled job's file, you must export:
-
-1. An asynchronous function that holds 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.
-2. A `config` object that specifies the job's name and schedule. The schedule is a [cron expression](https://crontab.guru/) that defines the interval at which the job runs.
-
-In the scheduled job function, so far you resolve the [Logger](https://docs.medusajs.com/docs/learn/debugging-and-testing/logging/index.html.md) to log messages, and [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md) to retrieve data across modules.
-
-You also define a `oneDayAgo` date, which is the date that you will use as the condition of an abandoned cart. In addition, you define variables to paginate the carts.
-
-Next, you will retrieve the abandoned carts using Query. Replace the `TODO` with the following:
-
-```ts title="src/jobs/send-abandoned-cart-notification.ts"
-const { 
-  data: abandonedCarts, 
-  metadata,
-} = await query.graph({
-  entity: "cart",
-  fields: [
-    "id",
-    "email",
-    "items.*",
-    "metadata",
-    "customer.*",
-  ],
-  filters: {
-    updated_at: {
-      $lt: oneDayAgo,
-    },
-    // @ts-ignore
-    email: {
-      $ne: null,
-    },
-    // @ts-ignore
-    completed_at: null,
-  },
-  pagination: {
-    skip: offset,
-    take: limit,
-  },
-})
-
-totalCount = metadata?.count ?? 0
-const cartsWithItems = abandonedCarts.filter((cart) => 
-  cart.items?.length > 0 && !cart.metadata?.abandoned_notification
-)
-
-try {
-  await sendAbandonedCartsWorkflow(container).run({
-    input: {
-      carts: cartsWithItems,
-    } as unknown as SendAbandonedCartsWorkflowInput,
-  })
-  abandonedCartsCount += cartsWithItems.length
-
-} catch (error) {
-  logger.error(
-    `Failed to send abandoned cart notification: ${error.message}`
-  )
-}
-
-offset += limit
-```
-
-In the do-while loop, you use Query to retrieve carts matching the following criteria:
-
-- The cart was last updated more than a day ago.
-- The cart has an email address.
-- The cart has not been completed.
-
-You also filter the retrieved carts to only include carts with items and customers that have not received an abandoned cart notification.
-
-Finally, you execute the `sendAbandonedCartsWorkflow` passing it the abandoned carts as an input. You will execute the workflow for each paginated batch of carts.
-
-### Test it Out
-
-To test out the scheduled job and workflow, it is recommended to change the `oneDayAgo` date to a minute before now for easy testing:
-
-```ts title="src/jobs/send-abandoned-cart-notification.ts"
-oneDayAgo.setMinutes(oneDayAgo.getMinutes() - 1) // For testing
-```
-
-And to change the job's schedule in `config` to run every minute:
-
-```ts title="src/jobs/send-abandoned-cart-notification.ts"
-export const config = {
-  // ...
-  schedule: "* * * * *", // Run every minute for testing
-}
-```
-
-Finally, start the Medusa application with the following command:
-
-```bash npm2yarn
-npm run dev
-```
-
-And in the [Next.js Starter Storefront](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/nextjs-starter/index.html.md)'s directory (that you installed in the first step), start the storefront with the following command:
-
-```bash npm2yarn
-npm run dev
-```
-
-Open the storefront at `localhost:8000`. You can either:
-
-- Create an account and add items to the cart, then leave the cart for a minute.
-- Add an item to the cart as a guest. Then, start the checkout process, but only enter the shipping and email addresses, and leave the cart for a minute.
-
-Afterwards, wait for the job to execute. Once it is executed, you will see the following message in the terminal:
-
-```bash
-info:    Sent 1 abandoned cart notifications
-```
-
-Once you're done testing, make sure to revert the changes to the `oneDayAgo` date and the job's schedule.
-
-***
-
-## Step 5: Recover Cart in Storefront
-
-In the storefront, you need to add a route that recovers the cart when the customer clicks on the link in the email. The route should receive the cart ID, set the cart ID in the cookie, and redirect the customer to the cart page.
-
-To implement the route, in the Next.js Starter Storefront create the file `src/app/[countryCode]/(main)/cart/recover/[id]/route.tsx` with the following content:
-
-```tsx title="src/app/[countryCode]/(main)/cart/recover/[id]/route.tsx" badgeLabel="Storefront" badgeColor="blue"
-import { NextRequest } from "next/server"
-import { retrieveCart } from "../../../../../../lib/data/cart"
-import { setCartId } from "../../../../../../lib/data/cookies"
-import { notFound, redirect } from "next/navigation"
-type Params = Promise<{
-  id: string
-}>
-
-export async function GET(req: NextRequest, { params }: { params: Params }) {
-  const { id } = await params
-  const cart = await retrieveCart(id)
-
-  if (!cart) {
-    return notFound()
-  }
-
-  setCartId(id)
-
-  const countryCode = cart.shipping_address?.country_code || 
-    cart.region?.countries?.[0]?.iso_2
-
-  redirect(
-    `/${countryCode ? `${countryCode}/` : ""}cart`
-  )
-}
-```
-
-You add a `GET` route handler that receives the cart ID as a path parameter. In the route handler, you:
-
-- Try to retrieve the cart from the Medusa application. The `retrieveCart` function is already available in the Next.js storefront. If the cart is not found, you return a 404 response.
-- Set the cart ID in a cookie using the `setCartId` function. This is also a function that is already available in the storefront.
-- Redirect the customer to the cart page. You set the country code in the URL based on the cart's shipping address or region.
-
-### Test it Out
-
-To test it out, start the Medusa application:
-
-```bash npm2yarn
-npm run dev
-```
-
-And in the Next.js Starter Storefront's directory, start the storefront:
-
-```bash npm2yarn
-npm run dev
-```
-
-Then, either open the link in an abandoned cart email or navigate to `localhost:8000/cart/recover/:cart_id` in your browser. You will be redirected to the cart page with the recovered cart.
-
-![Cart page in the storefront](https://res.cloudinary.com/dza7lstvk/image/upload/v1742459552/Medusa%20Resources/Screenshot_2025-03-20_at_10.32.17_AM_frmbup.png)
-
-***
-
-## Next Steps
-
-You have now implemented the logic to send abandoned cart notifications in Medusa. You can implement other customizations with Medusa, such as:
-
-- [Implement Product Reviews](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/how-to-tutorials/tutorials/product-reviews/index.html.md).
-- [Implement Wishlist](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/plugins/guides/wishlist/index.html.md).
-- [Allow Custom-Item Pricing](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/examples/guides/custom-item-price/index.html.md).
-
-If you are new to Medusa, check out the [main documentation](https://docs.medusajs.com/docs/learn/index.html.md), where you will get a more in-depth learning of all the concepts you have 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).
-
-
-# Use Saved Payment Methods During Checkout
-
-In this tutorial, you'll learn how to allow customers to save their payment methods and use them for future purchases.
-
-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.
-
-Medusa's architecture facilitates integrating third-party services, such as payment providers. These payment providers can process payments and securely store customers' payment methods for future use.
-
-In this tutorial, you'll expand on Medusa's [Stripe Module Provider](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/payment/payment-provider/stripe/index.html.md) to allow customers to re-use their saved payment methods during checkout.
-
-You can follow this guide whether you're new to Medusa or an advanced Medusa developer.
-
-While this tutorial uses Stripe as an example, you can follow the same steps to implement saved payment methods with other payment providers.
-
-## Summary
-
-By following this tutorial, you'll learn how to:
-
-- Install and set up Medusa and the Next.js Starter Storefront.
-- Set up the Stripe Module Provider in Medusa.
-- Customize the checkout flow to save customers' payment methods.
-- Allow customers to select saved payment methods during checkout.
-
-![Diagram illustrating the features of this guide](https://res.cloudinary.com/dza7lstvk/image/upload/v1745309355/Medusa%20Resources/saved-payment-methods_orjnix.jpg)
-
-[Saved Payment Methods Repository](https://github.com/medusajs/examples/tree/main/stripe-saved-payment): Find the full code for this 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 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: Set Up the Stripe Module Provider
-
-Medusa's [Payment Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/payment/index.html.md) provides payment-related models and the interface to manage and process payments. However, it delegates the actual payment processing to module providers that integrate third-party payment services.
-
-The [Stripe Module Provider](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/payment/payment-provider/stripe/index.html.md) is a Payment Module Provider that integrates Stripe into your Medusa application to process payments. It can also save payment methods securely.
-
-In this section, you'll set up the Stripe Module Provider in your Medusa application.
-
-### Prerequisites
-
-- [Stripe account](https://stripe.com/)
-- [Stripe Secret and Public API Keys](https://support.stripe.com/questions/locate-api-keys-in-the-dashboard)
-
-### Register the Stripe Module Provider
-
-To register the Stripe Module Provider in your Medusa application, add it to the array of providers passed to the Payment Module in `medusa-config.ts`:
-
-```ts title="medusa-config.ts"
-module.exports = defineConfig({
-  // ...
-  modules: [
-    {
-      resolve: "@medusajs/medusa/payment",
-      options: {
-        providers: [
-          {
-            resolve: "@medusajs/medusa/payment-stripe",
-            id: "stripe",
-            options: {
-              apiKey: process.env.STRIPE_API_KEY,
-            },
-          },
-        ],
-      },
-    },
-  ],
-})
-```
-
-The Medusa configuration accepts a `modules` array, which contains the modules to be loaded. While the Payment Module is loaded by default, you need to add it again when registering a new provider.
-
-You register provides in the `providers` option of the Payment Module. Each provider is an object with the following properties:
-
-- `resolve`: The package name of the provider.
-- `id`: The ID of the provider. This is used to identify the provider in the Medusa application.
-- `options`: The options to be passed to the provider. In this case, the `apiKey` option is required for the Stripe Module Provider.
-
-Learn about other options in the [Stripe Module Provider](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/payment/payment-provider/stripe#module-options/index.html.md) documentation.
-
-### Add Environment Variables
-
-Next, add the following environment variables to your `.env` file:
-
-```plain
-STRIPE_API_KEY=sk_...
-```
-
-Where `STRIPE_API_KEY` is your Stripe Secret API Key. You can find it in the Stripe dashboard under Developers > API keys.
-
-![Secret API Key in the Stripe dashboard](https://res.cloudinary.com/dza7lstvk/image/upload/v1745313823/Medusa%20Resources/Screenshot_2025-04-22_at_12.20.08_PM_w6rxxo.png)
-
-### Enable Stripe in a Region
-
-In Medusa, each [region](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/region/index.html.md) (which is a geographical area where your store operates) can have different payment methods enabled. So, after registering the Stripe Module Provider, you need to enable it in a region.
-
-To enable it in a region, start the Medusa application with the following command:
-
-```bash npm2yarn
-npm run dev
-```
-
-Then, go to `localhost:9000/app` and log in with the user you created earlier.
-
-Once you're logged in:
-
-1. Go to Settings -> Regions.
-2. Click on the region where you want to enable the payment provider.
-3. Click the <InlineIcon Icon={EllipsisHorizontal} alt="three-dots" /> icon at the top right of the first section
-4. Choose "Edit" from the dropdown menu
-5. In the side window that opens, find the "Payment Providers" field and select Stripe from the dropdown.
-6. Once you're done, click the "Save" button.
-
-Stripe will now be available as a payment option during checkout.
-
-The Stripe Module Provider supports different payment methods in Stripe, such as Bancontact or iDEAL. This guide focuses only on the card payment method, but you can enable other payment methods as well.
-
-![Stripe in the dropdown](https://res.cloudinary.com/dza7lstvk/image/upload/v1745245433/Medusa%20Resources/Screenshot_2025-04-21_at_5.23.07_PM_yd7xji.png)
-
-### Add Evnironement Variable to Storefront
-
-The [Next.js Starter Storefront](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/nextjs-starter/index.html.md) supports payment with Stripe during checkout if it's enabled in the region.
-
-The Next.js Starter Storefront was installed in a separate directory from Medusa. The directory's name is `{your-project}-storefront`.
-
-So, if your Medusa application's directory is `medusa-payment`, you can find the storefront by going back to the parent directory and changing to the `medusa-payment-storefront` directory:
-
-```bash
-cd ../medusa-payment-storefront # change based on your project name
-```
-
-In the Next.js Starter Storefront project, add the Stripe public API key as an environment variable in `.env.local`:
-
-```plain badgeLabel="Storefront" badgeColor="blue"
-NEXT_PUBLIC_STRIPE_KEY=pk_123...
-```
-
-Where `NEXT_PUBLIC_STRIPE_KEY` is your Stripe public API key. You can find it in the Stripe dashboard under Developers > API keys.
-
-***
-
-## Step 3: List Payment Methods API Route
-
-The Payment Module uses [account holders](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/payment/account-holder/index.html.md) to represent a customer's details that are stored in a third-party payment provider. Medusa creates an account holder for each customer, allowing you later to retrieve the customer's saved payment methods in the third-party provider.
-
-![Diagram illustrating the relation between customers and account holders in Medusa, and customers in Stripe](https://res.cloudinary.com/dza7lstvk/image/upload/v1745314344/Medusa%20Resources/customer-account-stripe_in5ei6.jpg)
-
-While this feature is available out-of-the-box, you need to expose it to clients, like storefronts, 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.
-
-In this step, you'll create an API route that lists the saved payment methods for an authenticated customer.
-
-Refer to the [API routes](https://docs.medusajs.com/docs/learn/fundamentals/api-routes/index.html.md) documentation to learn more.
-
-### Create 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`, and it can include path parameters using square brackets.
-
-So, to create an API route at the path `/store/payment-methods/:account-holder-id`, create the file `src/api/store/payment-methods/[account_holder_id]/route.ts` with the following content:
-
-```ts title="src/api/store/payment-methods/[account_holder_id]/route.ts" highlights={apiRouteHighlights}
-import { MedusaError } from "@medusajs/framework/utils"
-import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
-
-export async function GET(
-  req: MedusaRequest,
-  res: MedusaResponse
-) {
-  const { account_holder_id } = req.params
-  const query = req.scope.resolve("query")
-  const paymentModuleService = req.scope.resolve("payment")
-
-  const { data: [accountHolder] } = await query.graph({
-    entity: "account_holder",
-    fields: [
-      "data",
-      "provider_id",
-    ],
-    filters: {
-      id: account_holder_id,
-    },
-  })
-
-  if (!accountHolder) {
-    throw new MedusaError(
-      MedusaError.Types.NOT_FOUND, 
-      "Account holder not found"
-    )
-  }
-
-  const paymentMethods = await paymentModuleService.listPaymentMethods(
-    {
-      provider_id: accountHolder.provider_id,
-      context: {
-        account_holder: {
-          data: {
-            id: accountHolder.data.id,
-          },
-        },
-      },
-    }
-  )
-
-  res.json({
-    payment_methods: paymentMethods,
-  })
-}
-```
-
-Since you export a route handler function named `GET`, you expose a `GET` API route at `/store/payment-methods/:account-holder-id`. 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.
-
-The request object has a `scope` property, which is an instance of the [Medusa container](https://docs.medusajs.com/docs/learn/fundamentals/medusa-container/index.html.md). The Medusa container is a registry of Framework and commerce tools that you can access in the API route.
-
-You use the Medusa container to resolve:
-
-- [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), which is a tool that retrieves data across modules in the Medusa application.
-- The [Payment Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/payment/index.html.md)'s service, which provides an interface to manage and process payments with third-party providers.
-
-You use Query to retrieve the account holder with the ID passed as a path parameter. If the account holder is not found, you throw an error.
-
-Then, you use the [listPaymentMethods](https://docs.medusajs.com/references/payment/listPaymentMethods/index.html.md) method of the Payment Module's service to retrieve the payment providers saved in the third-party provider. The method accepts an object with the following properties:
-
-- `provider_id`: The ID of the provider, such as Stripe's ID. The account holder stores the ID its associated provider.
-- `context`: The context of the request. In this case, you pass the account holder's ID to retrieve the payment methods associated with it in the third-party provider.
-
-Finally, you return the payment methods in the response.
-
-### Protect API Route
-
-Only authenticated customers can access and use saved payment methods. So, you need to protect the API route to ensure that only authenticated customers can access it.
-
-To protect an API route, you can add a [middleware](https://docs.medusajs.com/docs/learn/fundamentals/api-routes/middlewares/index.html.md). A middleware is a function executed when a request is sent to an API Route. You can add an authentication middleware that ensures that the request is authenticated before executing the route handler function.
-
-Refer to the [Middlewares](https://docs.medusajs.com/docs/learn/fundamentals/api-routes/middlewares/index.html.md) documentation to learn more.
-
-Middlewares are added in the `src/api/middlewares.ts` file. So, create the file with the following content:
-
-```ts title="src/api/middlewares.ts"
-import { authenticate, defineMiddlewares } from "@medusajs/framework/http"
-
-export default defineMiddlewares({
-  routes: [
-    {
-      matcher: "/store/payment-methods/:provider_id/:account_holder_id",
-      method: "GET",
-      middlewares: [
-        authenticate("customer", ["bearer", "session"]),
-      ],
-    },
-  ],
-})
-```
-
-The `src/api/middlewares.ts` file must use the `defineMiddlewares` function and export its result. The `defineMiddlewares` function accepts a `routes` array that accepts objects with the following properties:
-
-- `matcher`: The path of the API route to apply the middleware to.
-- `method`: The HTTP method of the API route to apply the middleware to.
-- `middlewares`: An array of middlewares to apply to the API route.
-
-You apply the `authenticate` middleware to the API route you created earlier. The `authenticate` middleware ensures that only authenticated customers can access the API route.
-
-Refer to the [Protected Routes](https://docs.medusajs.com/docs/learn/fundamentals/api-routes/protected-routes/index.html.md) documentation to learn more about the `authenticate` middleware.
-
-Your API route can now only be accessed by authenticated customers. You'll test it out as you customize the Next.js Starter Storefront in the next steps.
-
-***
-
-## Step 4: Save Payment Methods During Checkout
-
-In this step, you'll customize the checkout flow in the [Next.js Starter Storefront](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/nextjs-starter/index.html.md) to save payment methods during checkout.
-
-The Next.js Starter Storefront was installed in a separate directory from Medusa. The directory's name is `{your-project}-storefront`.
-
-So, if your Medusa application's directory is `medusa-payment`, you can find the storefront by going back to the parent directory and changing to the `medusa-payment-storefront` directory:
-
-```bash
-cd ../medusa-payment-storefront # change based on your project name
-```
-
-During checkout, when the customer chooses a payment method, such as Stripe, the Next.js Starter Storefront creates a [payment session](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/payment/payment-session/index.html.md) in Medusa using the [Initialize Payment Session](https://docs.medusajs.com/api/store#payment-collections_postpaymentcollectionsidpaymentsessions) API route.
-
-Under the hood, Medusa uses the associated payment provider (Stripe) to initiate the payment process with the associated third-party payment provider. The [Initialize Payment Session](https://docs.medusajs.com/api/store#payment-collections_postpaymentcollectionsidpaymentsessions) API route accepts a `data` object parameter in the request body that allows you to pass data relevant to the third-party payment provider.
-
-So, to save the payment method that the customer uses during checkout with Stripe, you must pass the `setup_future_usage` property in the `data` object. The `setup_future_usage` property is a Stripe-specific property that allows you to save the payment method for future use.
-
-In `src/modules/checkout/components/payment/index.tsx` of the Next.js Starter Storefront, there are two uses of the `initiatePaymentSession` function. Update each of them to pass the `data` property:
-
-```ts title="src/modules/checkout/components/payment/index.tsx" badgeLabel="Storefront" badgeColor="blue"
-// update in two places
-await initiatePaymentSession(cart, {
-  // ...
-  data: {
-    setup_future_usage: "off_session",
-  },
-})
-```
-
-You customize the `initiatePaymentSession` function to pass the `data` object with the `setup_future_usage` property. You set the value to `off_session` to allow using the payment method outside of the checkout flow, such as for follow up payments. You can use `on_session` instead if you only want the payment method to be used by the customer during checkout.
-
-By making this change, you always save the payment method that the customer uses during checkout. You can alternatively show a checkbox to confirm saving the payment method, and only pass the `data` object if the customer checks it.
-
-### Test it Out
-
-To test it out, start the Medusa application by running the following command in the Medusa application's directory:
-
-```bash npm2yarn
-npm run dev
-```
-
-Then, start the Next.js Starter Storefront by running the following command in the storefront's directory:
-
-```bash npm2yarn
-npm run dev
-```
-
-You can open the storefront in your browser at `localhost:8000`. Then, create a new customer account by clicking on the "Account" link at the top right.
-
-After creating an account and logging in, add a product to the cart and go to the checkout page. Once you get to the payment step, choose Stripe and enter a [test card number](https://docs.stripe.com/testing#cards), such as `4242 4242 4242 4242`.
-
-Then, place the order. Once the order is placed, you can check on the Stripe dashboard that the payment method was saved by:
-
-1. Going to the "Customers" section in the Stripe dashboard.
-2. Clicking on the customer you just placed the order with.
-3. Scrolling down to the "Payment methods" section. You'll find the payment method you just used to place the order.
-
-![Saved payment method on the Stripe dashboard](https://res.cloudinary.com/dza7lstvk/image/upload/v1745249064/Medusa%20Resources/Screenshot_2025-04-21_at_6.24.00_PM_peotrd.png)
-
-In the next step, you'll show the saved payment methods to the customer during checkout and allow them to select one of them.
-
-***
-
-## Step 5: Use Saved Payment Methods During Checkout
-
-In this step, you'll customize the checkout flow in the Next.js Starter Storefront to show the saved payment methods to the customer and allow them to select one of them to place the order.
-
-### Retrieve Saved Payment Methods
-
-To retrieve the saved payment methods, you'll add a server function that retrieves the customer's saved payment methods from the API route you created earlier.
-
-Add the following in `src/lib/data/payment.ts`:
-
-```ts title="src/lib/data/payment.ts" badgeLabel="Storefront" badgeColor="blue" highlights={paymentHighlights}
-export type SavedPaymentMethod = {
-  id: string
-  provider_id: string
-  data: {
-    card: {
-      brand: string
-      last4: string
-      exp_month: number
-      exp_year: number
-    }
-  }
-}
-
-export const getSavedPaymentMethods = async (accountHolderId: string) => {
-  const headers = {
-    ...(await getAuthHeaders()),
-  }
-
-  return sdk.client.fetch<{
-    payment_methods: SavedPaymentMethod[]
-  }>(
-    `/store/payment-methods/${accountHolderId}`,
-    {
-      method: "GET",
-      headers,
-    }
-  ).catch(() => {
-    return {
-      payment_methods: [],
-    }
-  })
-}
-```
-
-You define a type for the retrieved payment methods. It contains the following properties:
-
-- `id`: The ID of the payment method in the third-party provider.
-- `provider_id`: The ID of the provider in the Medusa application, such as Stripe's ID.
-- `data`: Additional data retrieved from the third-party provider related to the saved payment method. The type is modeled after the data returned by Stripe, but you can change it to match other payment providers.
-
-You also create a `getSavedPaymentMethods` function that retrieves the saved payment methods from the API route you created earlier. The function accepts the account holder ID as a parameter and returns the saved payment methods.
-
-### Add Saved Payment Methods Component
-
-Next, you'll add the component that shows the saved payment methods and allows the customer to select one of them.
-
-The component that shows the Stripe card element is defined in `src/modules/checkout/components/payment-container/index.tsx`. So, you'll define the component for the saved payment methods in the same file.
-
-Start by adding the following import statements at the top of the file:
-
-```ts title="src/modules/checkout/components/payment-container/index.tsx" badgeLabel="Storefront" badgeColor="blue"
-import { Button } from "@medusajs/ui"
-import { useEffect, useState } from "react"
-import { HttpTypes } from "@medusajs/types"
-import { SavedPaymentMethod, getSavedPaymentMethods } from "@lib/data/payment"
-import { initiatePaymentSession } from "../../../../lib/data/cart"
-import { capitalize } from "lodash"
-```
-
-Then, update the `PaymentContainerProps` type to include the payment session and cart details:
-
-```ts title="src/modules/checkout/components/payment-container/index.tsx" badgeLabel="Storefront" badgeColor="blue"
-type PaymentContainerProps = {
-  // ...
-  paymentSession?: HttpTypes.StorePaymentSession
-  cart: HttpTypes.StoreCart
-}
-```
-
-You'll need these details to find which saved payment method the customer selected, and to initiate a new payment session for the cart when the customer chooses a saved payment method.
-
-Next, add the following component at the end of the file:
-
-```tsx title="src/modules/checkout/components/payment-container/index.tsx" badgeLabel="Storefront" badgeColor="blue" highlights={stripeSavedPaymentMethodsHighlights}
-const StripeSavedPaymentMethodsContainer = ({
-  paymentSession,
-  setCardComplete,
-  setCardBrand,
-  setError,
-  cart,
-}: {
-  paymentSession?: HttpTypes.StorePaymentSession
-  setCardComplete: (complete: boolean) => void
-  setCardBrand: (brand: string) => void
-  setError: (error: string | null) => void
-  cart: HttpTypes.StoreCart
-}) => {
-  const [savedPaymentMethods, setSavedPaymentMethods] = useState<
-    SavedPaymentMethod[]
-  >([])
-  const [selectedPaymentMethod, setSelectedPaymentMethod] = useState<
-    string | undefined
-  >(
-    paymentSession?.data?.payment_method_id as string | undefined
-  )
-
-  useEffect(() => {
-    const accountHolderId = (
-      paymentSession?.context?.account_holder as Record<string, string>
-    )
-      ?.id
-
-    if (!accountHolderId) {
-      return
-    }
-
-    getSavedPaymentMethods(accountHolderId)
-      .then(({ payment_methods }) => {
-        setSavedPaymentMethods(payment_methods)
-      })
-  }, [paymentSession])
-
-  useEffect(() => {
-    if (!selectedPaymentMethod || !savedPaymentMethods.length) {
-      setCardComplete(false)
-      setCardBrand("")
-      setError(null)
-      return
-    }
-    const selectedMethod = savedPaymentMethods.find(
-      (method) => method.id === selectedPaymentMethod
-    )
-
-    if (!selectedMethod) {
-      return
-    }
-
-    setCardBrand(capitalize(selectedMethod.data.card.brand))
-    setCardComplete(true)
-    setError(null)
-  }, [selectedPaymentMethod, savedPaymentMethods])
-
-  const handleSelect = async (method: SavedPaymentMethod) => {
-    // initiate a new payment session with the selected payment method
-    await initiatePaymentSession(cart, {
-      provider_id: method.provider_id,
-      data: {
-        payment_method_id: method.id,
-      },
-    }).catch((error) => {
-      setError(error.message)
-    })
-
-    setSelectedPaymentMethod(method.id)
-  }
-
-  if (!savedPaymentMethods.length) {
-    return <></>
-  }
-
-  // TODO add return statement
-}
-```
-
-You define a `StripeSavedPaymentMethodsContainer` component that accepts the following props:
-
-- `paymentSession`: The cart's current payment session.
-- `setCardComplete`: A function to tell parent components whether the cart or payment method selection is complete. This allows the customer to proceed to the next step in the checkout flow.
-- `setCardBrand`: A function to set the brand of the selected payment method. This is useful to show the brand of the selected payment method in review sections of the checkout flow.
-- `setError`: A function to set the error message in case of an error.
-- `cart`: The cart's details.
-
-In the component, you define a state variable to store the saved payment methods and another one to store the selected payment method.
-
-Then, you use the `useEffect` hook to retrieve the saved payment methods for the account holder set in the cart's payment session. You use the `getSavedPaymentMethods` function you created earlier to retrieve the saved payment methods.
-
-You also use another `useEffect` hook that is executed when the selected payment method changes. In this hook, you check if the selected payment method is valid and set the card brand and completion status accordingly.
-
-Finally, you define a `handleSelect` function that you'll execute when the customer selects a saved payment method. It creates a new payment session with the selected payment method.
-
-To show the saved payment methods, replace the `TODO` with the following `return` statement:
-
-```tsx title="src/modules/checkout/components/payment-container/index.tsx" badgeLabel="Storefront" badgeColor="blue"
-return (
-  <div className="flex flex-col gap-y-2">
-    <Text className="txt-medium-plus text-ui-fg-base">
-      Choose a saved payment method:
-    </Text>
-    {savedPaymentMethods.map((method) => (
-      <div 
-        key={method.id}
-        className={`flex items-center justify-between p-4 border rounded-lg cursor-pointer hover:border-ui-border-interactive ${
-          selectedPaymentMethod === method.id ? "border-ui-border-interactive" : ""
-        }`}
-        role="button"
-        onClick={() => handleSelect(method)}
-      >
-        <div className="flex items-center gap-x-4">
-          <input
-            type="radio"
-            name="saved-payment-method" 
-            value={method.id}
-            checked={selectedPaymentMethod === method.id}
-            className="h-4 w-4 text-ui-fg-interactive"
-            onChange={(e) => {
-              if (e.target.checked) {
-                handleSelect(method)
-              }
-            }}
-          />
-          <div className="flex flex-col">
-            <span className="text-sm font-medium text-ui-fg-base">
-              {capitalize(method.data.card.brand)} •••• {method.data.card.last4}
-            </span>
-            <span className="text-xs text-ui-fg-subtle">
-              Expires {method.data.card.exp_month}/{method.data.card.exp_year}
-            </span>
-          </div>
-        </div>
-      </div>
-    ))}
-  </div>
-)
-```
-
-You display the saved payment methods as radio buttons. When the customer selects one of them, you execute the `handleSelect` function to initiate a new payment session with the selected payment method.
-
-### Modify Existing Stripe Element
-
-Now that you have the component to show the saved payment methods, you need to modify the existing Stripe element to allow customers to select an existing payment method or enter a new one.
-
-In the same `src/modules/checkout/components/payment-container/index.tsx` file, expand the new `paymentSession` and `cart` props of the `StripeCardContainer` component:
-
-```ts title="src/modules/checkout/components/payment-container/index.tsx" badgeLabel="Storefront" badgeColor="blue"
-export const StripeCardContainer = ({
-  // ...
-  paymentSession,
-  cart,
-}: Omit<PaymentContainerProps, "children"> & {
-  // ...
-}) => {
-  // ...
-}
-```
-
-Then, add a new state variable that keeps track of whether the customer is using a saved payment method or entering a new one:
-
-```ts title="src/modules/checkout/components/payment-container/index.tsx" badgeLabel="Storefront" badgeColor="blue"
-const [isUsingSavedPaymentMethod, setIsUsingSavedPaymentMethod] = useState(
-  paymentSession?.data?.payment_method_id !== undefined
-)
-```
-
-Next, add a function that resets the payment session when the customer switches between saved and new payment methods:
-
-```ts title="src/modules/checkout/components/payment-container/index.tsx" badgeLabel="Storefront" badgeColor="blue"
-const handleRefreshSession = async () => {
-  await initiatePaymentSession(cart, {
-    provider_id: paymentProviderId,
-  })
-  setIsUsingSavedPaymentMethod(false)
-}
-```
-
-This function initiates a new payment session for the cart and disables the `isUsingSavedPaymentMethod` state variable.
-
-Finally, replace the `return` statement of the `StripeCardContainer` component with the following:
-
-```tsx title="src/modules/checkout/components/payment-container/index.tsx" badgeLabel="Storefront" badgeColor="blue" highlights={stripeCardReturnHighlights}
-return (
-  <PaymentContainer
-    paymentProviderId={paymentProviderId}
-    selectedPaymentOptionId={selectedPaymentOptionId}
-    paymentInfoMap={paymentInfoMap}
-    disabled={disabled}
-    paymentSession={paymentSession}
-    cart={cart}
-  >
-    {selectedPaymentOptionId === paymentProviderId &&
-      (stripeReady ? (
-        <div className="my-4 transition-all duration-150 ease-in-out">
-          <StripeSavedPaymentMethodsContainer
-            setCardComplete={setCardComplete}
-            setCardBrand={setCardBrand}
-            setError={setError}
-            paymentSession={paymentSession}
-            cart={cart}
-          />
-          {isUsingSavedPaymentMethod && (
-            <Button 
-              variant="secondary" 
-              size="small" 
-              className="mt-2" 
-              onClick={handleRefreshSession}
-            >
-              Use a new payment method
-            </Button>
-          )}
-          {!isUsingSavedPaymentMethod && (
-            <>
-              <Text className="txt-medium-plus text-ui-fg-base my-1">
-                Enter your card details:
-              </Text>
-              <CardElement
-                options={useOptions as StripeCardElementOptions}
-                onChange={(e) => {
-                  setCardBrand(
-                    e.brand && e.brand.charAt(0).toUpperCase() + e.brand.slice(1)
-                  )
-                  setError(e.error?.message || null)
-                  setCardComplete(e.complete)
-                  }}
-                />              
-            </>
-          )}
-        </div>
-      ) : (
-        <SkeletonCardDetails />
-      ))}
-  </PaymentContainer>
-)
-```
-
-You update the `return` statement to:
-
-- Pass the new `paymentSession` and `cart` props to the `PaymentContainer` component.
-- Show the `StripeSavedPaymentMethodsContainer` component before Stripe's card element.
-- Add a button that's shown when the customer selects a saved payment method. The button allows the customer to switch back to entering a new payment method.
-
-The existing Stripe element in checkout will now show the saved payment methods to the customer along with the component to enter a card's details.
-
-Since you added new props to the `StripeCardContainer` and `PaymentContainer` components, you need to update other components that use them to pass the props.
-
-In `src/modules/checkout/components/payment/index.tsx`, find usages of `StripeCardContainer` and `PaymentContainer` in the return statement and add the `paymentSession` and `cart` props:
-
-```tsx title="src/modules/checkout/components/payment/index.tsx" badgeLabel="Storefront" badgeColor="blue" highlights={[["5"], ["6"], ["11"], ["12"]]}
-<div key={paymentMethod.id}>
-  {isStripeFunc(paymentMethod.id) ? (
-    <StripeCardContainer
-      // ...
-      paymentSession={activeSession}
-      cart={cart}
-    />
-  ) : (
-    <PaymentContainer
-      // ...
-      paymentSession={activeSession}
-      cart={cart}
-    />
-  )}
-</div>
-```
-
-### Support Updating Stripe's Client Secret
-
-The Next.js Starter Storefront uses Stripe's `Elements` component to wrap the payment elements. The `Elements` component requires a `clientSecret` prop, which is available in the cart's payment session.
-
-With the recent changes, the client secret will be updated whenever a payment session is initiated, such as when the customer selects a saved payment method. However, the `options.clientSecret` prop of the `Elements` component is immutable, meaning that it cannot be changed after the component is mounted.
-
-To force the component to re-mount and update the `clientSecret` prop, you can add a `key` prop to the `Elements` component. The `key` prop ensures that the `Elements` component re-mounts whenever the client secret changes, allowing Stripe to process the updated payment session.
-
-In `src/modules/checkout/components/payment-wrapper/stripe-wrapper.tsx`, find the `Elements` component in the `return` statement and add the `key` prop:
-
-```tsx title="src/modules/checkout/components/payment-wrapper/stripe-wrapper.tsx" badgeLabel="Storefront" badgeColor="blue" highlights={[["4"]]}
-<Elements 
-  options={options} 
-  stripe={stripePromise} 
-  key={options.clientSecret}
->
-  {children}
-</Elements>
-```
-
-You set the `key` prop to the client secret, which forces the `Elements` component to re-mount whenever the client secret changes.
-
-### Support Payment with Saved Payment Method
-
-The last change you need to make ensures that the customer can place an order with a saved payment method.
-
-When the customer places the order, and they've chosen Stripe as a payment method, the Next.js Starter Storefront uses Stripe's `confirmCardPayment` method to confirm the payment. This method accepts either the ID of a saved payment method, or the details of a new card.
-
-So, you need to update the `confirmCardPayment` usage to support passing the ID of the selected payment method if the customer has selected one.
-
-In `src/modules/checkout/components/payment-button/index.tsx`, find the `handlePayment` method and update its first `if` condition:
-
-```ts title="src/modules/checkout/components/payment-button/index.tsx" badgeLabel="Storefront" badgeColor="blue"
-if (!stripe || !elements || (!card && !session?.data.payment_method_id) || !cart) {
-  setSubmitting(false)
-  return
-}
-```
-
-This allows the customer to place their order if they have selected a saved payment method but have not entered a new card.
-
-Then, find the usage of `confirmCardPayment` in the `handlePayment` function and change it to the following:
-
-```ts title="src/modules/checkout/components/payment-button/index.tsx" badgeLabel="Storefront" badgeColor="blue" highlights={confirmPaymentHighlights}
-await stripe
-.confirmCardPayment(session?.data.client_secret as string, {
-  payment_method: session?.data.payment_method_id as string || {
-    card: card!,
-    billing_details: {
-      name:
-        cart.billing_address?.first_name +
-        " " +
-        cart.billing_address?.last_name,
-      address: {
-        city: cart.billing_address?.city ?? undefined,
-        country: cart.billing_address?.country_code ?? undefined,
-        line1: cart.billing_address?.address_1 ?? undefined,
-        line2: cart.billing_address?.address_2 ?? undefined,
-        postal_code: cart.billing_address?.postal_code ?? undefined,
-        state: cart.billing_address?.province ?? undefined,
-      },
-      email: cart.email,
-      phone: cart.billing_address?.phone ?? undefined,
-    },
-  },
-})
-.then(({ error, paymentIntent }) => {
-  if (error) {
-    const pi = error.payment_intent
-
-    if (
-      (pi && pi.status === "requires_capture") ||
-      (pi && pi.status === "succeeded")
-    ) {
-      onPaymentCompleted()
-    }
-
-    setErrorMessage(error.message || null)
-    return
-  }
-
-  if (
-    (paymentIntent && paymentIntent.status === "requires_capture") ||
-    paymentIntent.status === "succeeded"
-  ) {
-    return onPaymentCompleted()
-  }
-
-  return
-})
-```
-
-In particular, you're changing the `payment_method` property to either be the ID of the selected payment method, or the details of a new card. This allows the customer to place an order with either a saved payment method or a new one.
-
-### Test it Out
-
-You can now test out placing orders with a saved payment method.
-
-To do that, start the Medusa application by running the following command in the Medusa application's directory:
-
-```bash npm2yarn
-npm run dev
-```
-
-Then, start the Next.js Starter Storefront by running the following command in the storefront's directory:
-
-```bash npm2yarn
-npm run dev
-```
-
-In the Next.js Starter Storefront, login with the customer account you created earlier and add a product to the cart.
-
-Then, proceed to the checkout flow. In the payment step, you should see the saved payment method you used earlier. You can select it and place the order.
-
-![Saved payment method in checkout](https://res.cloudinary.com/dza7lstvk/image/upload/v1745308047/Medusa%20Resources/Screenshot_2025-04-21_at_4.07.34_PM_krudjq.png)
-
-Once the order is placed successfully, you can check it in the Medusa Admin dashboard. You can view the order and capture the payment.
-
-![Order in the Medusa Admin dashboard](https://res.cloudinary.com/dza7lstvk/image/upload/v1745318042/Medusa%20Resources/Screenshot_2025-04-22_at_1.33.39_PM_uynlfp.png)
-
-***
-
-## Next Steps
-
-You've added support for saved payment methods in your Medusa application and Next.js Starter Storefront, allowing customers to save their payment methods during checkout and use them in future orders.
-
-You can add more features to the saved payment methods, such as allowing customers to delete saved payment methods. You can use [Stripe's APIs](https://docs.stripe.com/api/payment_methods/detach) in the storefront or add an [API route](https://docs.medusajs.com/docs/learn/fundamentals/api-routes/index.html.md) in Medusa to delete the saved payment method.
-
-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).
-
-
 # Implement Product Reviews in Medusa
 
 In this tutorial, you'll learn how to implement product reviews in Medusa.
@@ -47547,6 +46872,850 @@ 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).
 
 
+# Use Saved Payment Methods During Checkout
+
+In this tutorial, you'll learn how to allow customers to save their payment methods and use them for future purchases.
+
+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.
+
+Medusa's architecture facilitates integrating third-party services, such as payment providers. These payment providers can process payments and securely store customers' payment methods for future use.
+
+In this tutorial, you'll expand on Medusa's [Stripe Module Provider](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/payment/payment-provider/stripe/index.html.md) to allow customers to re-use their saved payment methods during checkout.
+
+You can follow this guide whether you're new to Medusa or an advanced Medusa developer.
+
+While this tutorial uses Stripe as an example, you can follow the same steps to implement saved payment methods with other payment providers.
+
+## Summary
+
+By following this tutorial, you'll learn how to:
+
+- Install and set up Medusa and the Next.js Starter Storefront.
+- Set up the Stripe Module Provider in Medusa.
+- Customize the checkout flow to save customers' payment methods.
+- Allow customers to select saved payment methods during checkout.
+
+![Diagram illustrating the features of this guide](https://res.cloudinary.com/dza7lstvk/image/upload/v1745309355/Medusa%20Resources/saved-payment-methods_orjnix.jpg)
+
+[Saved Payment Methods Repository](https://github.com/medusajs/examples/tree/main/stripe-saved-payment): Find the full code for this 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 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: Set Up the Stripe Module Provider
+
+Medusa's [Payment Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/payment/index.html.md) provides payment-related models and the interface to manage and process payments. However, it delegates the actual payment processing to module providers that integrate third-party payment services.
+
+The [Stripe Module Provider](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/payment/payment-provider/stripe/index.html.md) is a Payment Module Provider that integrates Stripe into your Medusa application to process payments. It can also save payment methods securely.
+
+In this section, you'll set up the Stripe Module Provider in your Medusa application.
+
+### Prerequisites
+
+- [Stripe account](https://stripe.com/)
+- [Stripe Secret and Public API Keys](https://support.stripe.com/questions/locate-api-keys-in-the-dashboard)
+
+### Register the Stripe Module Provider
+
+To register the Stripe Module Provider in your Medusa application, add it to the array of providers passed to the Payment Module in `medusa-config.ts`:
+
+```ts title="medusa-config.ts"
+module.exports = defineConfig({
+  // ...
+  modules: [
+    {
+      resolve: "@medusajs/medusa/payment",
+      options: {
+        providers: [
+          {
+            resolve: "@medusajs/medusa/payment-stripe",
+            id: "stripe",
+            options: {
+              apiKey: process.env.STRIPE_API_KEY,
+            },
+          },
+        ],
+      },
+    },
+  ],
+})
+```
+
+The Medusa configuration accepts a `modules` array, which contains the modules to be loaded. While the Payment Module is loaded by default, you need to add it again when registering a new provider.
+
+You register provides in the `providers` option of the Payment Module. Each provider is an object with the following properties:
+
+- `resolve`: The package name of the provider.
+- `id`: The ID of the provider. This is used to identify the provider in the Medusa application.
+- `options`: The options to be passed to the provider. In this case, the `apiKey` option is required for the Stripe Module Provider.
+
+Learn about other options in the [Stripe Module Provider](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/payment/payment-provider/stripe#module-options/index.html.md) documentation.
+
+### Add Environment Variables
+
+Next, add the following environment variables to your `.env` file:
+
+```plain
+STRIPE_API_KEY=sk_...
+```
+
+Where `STRIPE_API_KEY` is your Stripe Secret API Key. You can find it in the Stripe dashboard under Developers > API keys.
+
+![Secret API Key in the Stripe dashboard](https://res.cloudinary.com/dza7lstvk/image/upload/v1745313823/Medusa%20Resources/Screenshot_2025-04-22_at_12.20.08_PM_w6rxxo.png)
+
+### Enable Stripe in a Region
+
+In Medusa, each [region](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/region/index.html.md) (which is a geographical area where your store operates) can have different payment methods enabled. So, after registering the Stripe Module Provider, you need to enable it in a region.
+
+To enable it in a region, start the Medusa application with the following command:
+
+```bash npm2yarn
+npm run dev
+```
+
+Then, go to `localhost:9000/app` and log in with the user you created earlier.
+
+Once you're logged in:
+
+1. Go to Settings -> Regions.
+2. Click on the region where you want to enable the payment provider.
+3. Click the <InlineIcon Icon={EllipsisHorizontal} alt="three-dots" /> icon at the top right of the first section
+4. Choose "Edit" from the dropdown menu
+5. In the side window that opens, find the "Payment Providers" field and select Stripe from the dropdown.
+6. Once you're done, click the "Save" button.
+
+Stripe will now be available as a payment option during checkout.
+
+The Stripe Module Provider supports different payment methods in Stripe, such as Bancontact or iDEAL. This guide focuses only on the card payment method, but you can enable other payment methods as well.
+
+![Stripe in the dropdown](https://res.cloudinary.com/dza7lstvk/image/upload/v1745245433/Medusa%20Resources/Screenshot_2025-04-21_at_5.23.07_PM_yd7xji.png)
+
+### Add Evnironement Variable to Storefront
+
+The [Next.js Starter Storefront](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/nextjs-starter/index.html.md) supports payment with Stripe during checkout if it's enabled in the region.
+
+The Next.js Starter Storefront was installed in a separate directory from Medusa. The directory's name is `{your-project}-storefront`.
+
+So, if your Medusa application's directory is `medusa-payment`, you can find the storefront by going back to the parent directory and changing to the `medusa-payment-storefront` directory:
+
+```bash
+cd ../medusa-payment-storefront # change based on your project name
+```
+
+In the Next.js Starter Storefront project, add the Stripe public API key as an environment variable in `.env.local`:
+
+```plain badgeLabel="Storefront" badgeColor="blue"
+NEXT_PUBLIC_STRIPE_KEY=pk_123...
+```
+
+Where `NEXT_PUBLIC_STRIPE_KEY` is your Stripe public API key. You can find it in the Stripe dashboard under Developers > API keys.
+
+***
+
+## Step 3: List Payment Methods API Route
+
+The Payment Module uses [account holders](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/payment/account-holder/index.html.md) to represent a customer's details that are stored in a third-party payment provider. Medusa creates an account holder for each customer, allowing you later to retrieve the customer's saved payment methods in the third-party provider.
+
+![Diagram illustrating the relation between customers and account holders in Medusa, and customers in Stripe](https://res.cloudinary.com/dza7lstvk/image/upload/v1745314344/Medusa%20Resources/customer-account-stripe_in5ei6.jpg)
+
+While this feature is available out-of-the-box, you need to expose it to clients, like storefronts, 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.
+
+In this step, you'll create an API route that lists the saved payment methods for an authenticated customer.
+
+Refer to the [API routes](https://docs.medusajs.com/docs/learn/fundamentals/api-routes/index.html.md) documentation to learn more.
+
+### Create 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`, and it can include path parameters using square brackets.
+
+So, to create an API route at the path `/store/payment-methods/:account-holder-id`, create the file `src/api/store/payment-methods/[account_holder_id]/route.ts` with the following content:
+
+```ts title="src/api/store/payment-methods/[account_holder_id]/route.ts" highlights={apiRouteHighlights}
+import { MedusaError } from "@medusajs/framework/utils"
+import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
+
+export async function GET(
+  req: MedusaRequest,
+  res: MedusaResponse
+) {
+  const { account_holder_id } = req.params
+  const query = req.scope.resolve("query")
+  const paymentModuleService = req.scope.resolve("payment")
+
+  const { data: [accountHolder] } = await query.graph({
+    entity: "account_holder",
+    fields: [
+      "data",
+      "provider_id",
+    ],
+    filters: {
+      id: account_holder_id,
+    },
+  })
+
+  if (!accountHolder) {
+    throw new MedusaError(
+      MedusaError.Types.NOT_FOUND, 
+      "Account holder not found"
+    )
+  }
+
+  const paymentMethods = await paymentModuleService.listPaymentMethods(
+    {
+      provider_id: accountHolder.provider_id,
+      context: {
+        account_holder: {
+          data: {
+            id: accountHolder.data.id,
+          },
+        },
+      },
+    }
+  )
+
+  res.json({
+    payment_methods: paymentMethods,
+  })
+}
+```
+
+Since you export a route handler function named `GET`, you expose a `GET` API route at `/store/payment-methods/:account-holder-id`. 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.
+
+The request object has a `scope` property, which is an instance of the [Medusa container](https://docs.medusajs.com/docs/learn/fundamentals/medusa-container/index.html.md). The Medusa container is a registry of Framework and commerce tools that you can access in the API route.
+
+You use the Medusa container to resolve:
+
+- [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), which is a tool that retrieves data across modules in the Medusa application.
+- The [Payment Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/payment/index.html.md)'s service, which provides an interface to manage and process payments with third-party providers.
+
+You use Query to retrieve the account holder with the ID passed as a path parameter. If the account holder is not found, you throw an error.
+
+Then, you use the [listPaymentMethods](https://docs.medusajs.com/references/payment/listPaymentMethods/index.html.md) method of the Payment Module's service to retrieve the payment providers saved in the third-party provider. The method accepts an object with the following properties:
+
+- `provider_id`: The ID of the provider, such as Stripe's ID. The account holder stores the ID its associated provider.
+- `context`: The context of the request. In this case, you pass the account holder's ID to retrieve the payment methods associated with it in the third-party provider.
+
+Finally, you return the payment methods in the response.
+
+### Protect API Route
+
+Only authenticated customers can access and use saved payment methods. So, you need to protect the API route to ensure that only authenticated customers can access it.
+
+To protect an API route, you can add a [middleware](https://docs.medusajs.com/docs/learn/fundamentals/api-routes/middlewares/index.html.md). A middleware is a function executed when a request is sent to an API Route. You can add an authentication middleware that ensures that the request is authenticated before executing the route handler function.
+
+Refer to the [Middlewares](https://docs.medusajs.com/docs/learn/fundamentals/api-routes/middlewares/index.html.md) documentation to learn more.
+
+Middlewares are added in the `src/api/middlewares.ts` file. So, create the file with the following content:
+
+```ts title="src/api/middlewares.ts"
+import { authenticate, defineMiddlewares } from "@medusajs/framework/http"
+
+export default defineMiddlewares({
+  routes: [
+    {
+      matcher: "/store/payment-methods/:provider_id/:account_holder_id",
+      method: "GET",
+      middlewares: [
+        authenticate("customer", ["bearer", "session"]),
+      ],
+    },
+  ],
+})
+```
+
+The `src/api/middlewares.ts` file must use the `defineMiddlewares` function and export its result. The `defineMiddlewares` function accepts a `routes` array that accepts objects with the following properties:
+
+- `matcher`: The path of the API route to apply the middleware to.
+- `method`: The HTTP method of the API route to apply the middleware to.
+- `middlewares`: An array of middlewares to apply to the API route.
+
+You apply the `authenticate` middleware to the API route you created earlier. The `authenticate` middleware ensures that only authenticated customers can access the API route.
+
+Refer to the [Protected Routes](https://docs.medusajs.com/docs/learn/fundamentals/api-routes/protected-routes/index.html.md) documentation to learn more about the `authenticate` middleware.
+
+Your API route can now only be accessed by authenticated customers. You'll test it out as you customize the Next.js Starter Storefront in the next steps.
+
+***
+
+## Step 4: Save Payment Methods During Checkout
+
+In this step, you'll customize the checkout flow in the [Next.js Starter Storefront](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/nextjs-starter/index.html.md) to save payment methods during checkout.
+
+The Next.js Starter Storefront was installed in a separate directory from Medusa. The directory's name is `{your-project}-storefront`.
+
+So, if your Medusa application's directory is `medusa-payment`, you can find the storefront by going back to the parent directory and changing to the `medusa-payment-storefront` directory:
+
+```bash
+cd ../medusa-payment-storefront # change based on your project name
+```
+
+During checkout, when the customer chooses a payment method, such as Stripe, the Next.js Starter Storefront creates a [payment session](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/payment/payment-session/index.html.md) in Medusa using the [Initialize Payment Session](https://docs.medusajs.com/api/store#payment-collections_postpaymentcollectionsidpaymentsessions) API route.
+
+Under the hood, Medusa uses the associated payment provider (Stripe) to initiate the payment process with the associated third-party payment provider. The [Initialize Payment Session](https://docs.medusajs.com/api/store#payment-collections_postpaymentcollectionsidpaymentsessions) API route accepts a `data` object parameter in the request body that allows you to pass data relevant to the third-party payment provider.
+
+So, to save the payment method that the customer uses during checkout with Stripe, you must pass the `setup_future_usage` property in the `data` object. The `setup_future_usage` property is a Stripe-specific property that allows you to save the payment method for future use.
+
+In `src/modules/checkout/components/payment/index.tsx` of the Next.js Starter Storefront, there are two uses of the `initiatePaymentSession` function. Update each of them to pass the `data` property:
+
+```ts title="src/modules/checkout/components/payment/index.tsx" badgeLabel="Storefront" badgeColor="blue"
+// update in two places
+await initiatePaymentSession(cart, {
+  // ...
+  data: {
+    setup_future_usage: "off_session",
+  },
+})
+```
+
+You customize the `initiatePaymentSession` function to pass the `data` object with the `setup_future_usage` property. You set the value to `off_session` to allow using the payment method outside of the checkout flow, such as for follow up payments. You can use `on_session` instead if you only want the payment method to be used by the customer during checkout.
+
+By making this change, you always save the payment method that the customer uses during checkout. You can alternatively show a checkbox to confirm saving the payment method, and only pass the `data` object if the customer checks it.
+
+### Test it Out
+
+To test it out, start the Medusa application by running the following command in the Medusa application's directory:
+
+```bash npm2yarn
+npm run dev
+```
+
+Then, start the Next.js Starter Storefront by running the following command in the storefront's directory:
+
+```bash npm2yarn
+npm run dev
+```
+
+You can open the storefront in your browser at `localhost:8000`. Then, create a new customer account by clicking on the "Account" link at the top right.
+
+After creating an account and logging in, add a product to the cart and go to the checkout page. Once you get to the payment step, choose Stripe and enter a [test card number](https://docs.stripe.com/testing#cards), such as `4242 4242 4242 4242`.
+
+Then, place the order. Once the order is placed, you can check on the Stripe dashboard that the payment method was saved by:
+
+1. Going to the "Customers" section in the Stripe dashboard.
+2. Clicking on the customer you just placed the order with.
+3. Scrolling down to the "Payment methods" section. You'll find the payment method you just used to place the order.
+
+![Saved payment method on the Stripe dashboard](https://res.cloudinary.com/dza7lstvk/image/upload/v1745249064/Medusa%20Resources/Screenshot_2025-04-21_at_6.24.00_PM_peotrd.png)
+
+In the next step, you'll show the saved payment methods to the customer during checkout and allow them to select one of them.
+
+***
+
+## Step 5: Use Saved Payment Methods During Checkout
+
+In this step, you'll customize the checkout flow in the Next.js Starter Storefront to show the saved payment methods to the customer and allow them to select one of them to place the order.
+
+### Retrieve Saved Payment Methods
+
+To retrieve the saved payment methods, you'll add a server function that retrieves the customer's saved payment methods from the API route you created earlier.
+
+Add the following in `src/lib/data/payment.ts`:
+
+```ts title="src/lib/data/payment.ts" badgeLabel="Storefront" badgeColor="blue" highlights={paymentHighlights}
+export type SavedPaymentMethod = {
+  id: string
+  provider_id: string
+  data: {
+    card: {
+      brand: string
+      last4: string
+      exp_month: number
+      exp_year: number
+    }
+  }
+}
+
+export const getSavedPaymentMethods = async (accountHolderId: string) => {
+  const headers = {
+    ...(await getAuthHeaders()),
+  }
+
+  return sdk.client.fetch<{
+    payment_methods: SavedPaymentMethod[]
+  }>(
+    `/store/payment-methods/${accountHolderId}`,
+    {
+      method: "GET",
+      headers,
+    }
+  ).catch(() => {
+    return {
+      payment_methods: [],
+    }
+  })
+}
+```
+
+You define a type for the retrieved payment methods. It contains the following properties:
+
+- `id`: The ID of the payment method in the third-party provider.
+- `provider_id`: The ID of the provider in the Medusa application, such as Stripe's ID.
+- `data`: Additional data retrieved from the third-party provider related to the saved payment method. The type is modeled after the data returned by Stripe, but you can change it to match other payment providers.
+
+You also create a `getSavedPaymentMethods` function that retrieves the saved payment methods from the API route you created earlier. The function accepts the account holder ID as a parameter and returns the saved payment methods.
+
+### Add Saved Payment Methods Component
+
+Next, you'll add the component that shows the saved payment methods and allows the customer to select one of them.
+
+The component that shows the Stripe card element is defined in `src/modules/checkout/components/payment-container/index.tsx`. So, you'll define the component for the saved payment methods in the same file.
+
+Start by adding the following import statements at the top of the file:
+
+```ts title="src/modules/checkout/components/payment-container/index.tsx" badgeLabel="Storefront" badgeColor="blue"
+import { Button } from "@medusajs/ui"
+import { useEffect, useState } from "react"
+import { HttpTypes } from "@medusajs/types"
+import { SavedPaymentMethod, getSavedPaymentMethods } from "@lib/data/payment"
+import { initiatePaymentSession } from "../../../../lib/data/cart"
+import { capitalize } from "lodash"
+```
+
+Then, update the `PaymentContainerProps` type to include the payment session and cart details:
+
+```ts title="src/modules/checkout/components/payment-container/index.tsx" badgeLabel="Storefront" badgeColor="blue"
+type PaymentContainerProps = {
+  // ...
+  paymentSession?: HttpTypes.StorePaymentSession
+  cart: HttpTypes.StoreCart
+}
+```
+
+You'll need these details to find which saved payment method the customer selected, and to initiate a new payment session for the cart when the customer chooses a saved payment method.
+
+Next, add the following component at the end of the file:
+
+```tsx title="src/modules/checkout/components/payment-container/index.tsx" badgeLabel="Storefront" badgeColor="blue" highlights={stripeSavedPaymentMethodsHighlights}
+const StripeSavedPaymentMethodsContainer = ({
+  paymentSession,
+  setCardComplete,
+  setCardBrand,
+  setError,
+  cart,
+}: {
+  paymentSession?: HttpTypes.StorePaymentSession
+  setCardComplete: (complete: boolean) => void
+  setCardBrand: (brand: string) => void
+  setError: (error: string | null) => void
+  cart: HttpTypes.StoreCart
+}) => {
+  const [savedPaymentMethods, setSavedPaymentMethods] = useState<
+    SavedPaymentMethod[]
+  >([])
+  const [selectedPaymentMethod, setSelectedPaymentMethod] = useState<
+    string | undefined
+  >(
+    paymentSession?.data?.payment_method_id as string | undefined
+  )
+
+  useEffect(() => {
+    const accountHolderId = (
+      paymentSession?.context?.account_holder as Record<string, string>
+    )
+      ?.id
+
+    if (!accountHolderId) {
+      return
+    }
+
+    getSavedPaymentMethods(accountHolderId)
+      .then(({ payment_methods }) => {
+        setSavedPaymentMethods(payment_methods)
+      })
+  }, [paymentSession])
+
+  useEffect(() => {
+    if (!selectedPaymentMethod || !savedPaymentMethods.length) {
+      setCardComplete(false)
+      setCardBrand("")
+      setError(null)
+      return
+    }
+    const selectedMethod = savedPaymentMethods.find(
+      (method) => method.id === selectedPaymentMethod
+    )
+
+    if (!selectedMethod) {
+      return
+    }
+
+    setCardBrand(capitalize(selectedMethod.data.card.brand))
+    setCardComplete(true)
+    setError(null)
+  }, [selectedPaymentMethod, savedPaymentMethods])
+
+  const handleSelect = async (method: SavedPaymentMethod) => {
+    // initiate a new payment session with the selected payment method
+    await initiatePaymentSession(cart, {
+      provider_id: method.provider_id,
+      data: {
+        payment_method_id: method.id,
+      },
+    }).catch((error) => {
+      setError(error.message)
+    })
+
+    setSelectedPaymentMethod(method.id)
+  }
+
+  if (!savedPaymentMethods.length) {
+    return <></>
+  }
+
+  // TODO add return statement
+}
+```
+
+You define a `StripeSavedPaymentMethodsContainer` component that accepts the following props:
+
+- `paymentSession`: The cart's current payment session.
+- `setCardComplete`: A function to tell parent components whether the cart or payment method selection is complete. This allows the customer to proceed to the next step in the checkout flow.
+- `setCardBrand`: A function to set the brand of the selected payment method. This is useful to show the brand of the selected payment method in review sections of the checkout flow.
+- `setError`: A function to set the error message in case of an error.
+- `cart`: The cart's details.
+
+In the component, you define a state variable to store the saved payment methods and another one to store the selected payment method.
+
+Then, you use the `useEffect` hook to retrieve the saved payment methods for the account holder set in the cart's payment session. You use the `getSavedPaymentMethods` function you created earlier to retrieve the saved payment methods.
+
+You also use another `useEffect` hook that is executed when the selected payment method changes. In this hook, you check if the selected payment method is valid and set the card brand and completion status accordingly.
+
+Finally, you define a `handleSelect` function that you'll execute when the customer selects a saved payment method. It creates a new payment session with the selected payment method.
+
+To show the saved payment methods, replace the `TODO` with the following `return` statement:
+
+```tsx title="src/modules/checkout/components/payment-container/index.tsx" badgeLabel="Storefront" badgeColor="blue"
+return (
+  <div className="flex flex-col gap-y-2">
+    <Text className="txt-medium-plus text-ui-fg-base">
+      Choose a saved payment method:
+    </Text>
+    {savedPaymentMethods.map((method) => (
+      <div 
+        key={method.id}
+        className={`flex items-center justify-between p-4 border rounded-lg cursor-pointer hover:border-ui-border-interactive ${
+          selectedPaymentMethod === method.id ? "border-ui-border-interactive" : ""
+        }`}
+        role="button"
+        onClick={() => handleSelect(method)}
+      >
+        <div className="flex items-center gap-x-4">
+          <input
+            type="radio"
+            name="saved-payment-method" 
+            value={method.id}
+            checked={selectedPaymentMethod === method.id}
+            className="h-4 w-4 text-ui-fg-interactive"
+            onChange={(e) => {
+              if (e.target.checked) {
+                handleSelect(method)
+              }
+            }}
+          />
+          <div className="flex flex-col">
+            <span className="text-sm font-medium text-ui-fg-base">
+              {capitalize(method.data.card.brand)} •••• {method.data.card.last4}
+            </span>
+            <span className="text-xs text-ui-fg-subtle">
+              Expires {method.data.card.exp_month}/{method.data.card.exp_year}
+            </span>
+          </div>
+        </div>
+      </div>
+    ))}
+  </div>
+)
+```
+
+You display the saved payment methods as radio buttons. When the customer selects one of them, you execute the `handleSelect` function to initiate a new payment session with the selected payment method.
+
+### Modify Existing Stripe Element
+
+Now that you have the component to show the saved payment methods, you need to modify the existing Stripe element to allow customers to select an existing payment method or enter a new one.
+
+In the same `src/modules/checkout/components/payment-container/index.tsx` file, expand the new `paymentSession` and `cart` props of the `StripeCardContainer` component:
+
+```ts title="src/modules/checkout/components/payment-container/index.tsx" badgeLabel="Storefront" badgeColor="blue"
+export const StripeCardContainer = ({
+  // ...
+  paymentSession,
+  cart,
+}: Omit<PaymentContainerProps, "children"> & {
+  // ...
+}) => {
+  // ...
+}
+```
+
+Then, add a new state variable that keeps track of whether the customer is using a saved payment method or entering a new one:
+
+```ts title="src/modules/checkout/components/payment-container/index.tsx" badgeLabel="Storefront" badgeColor="blue"
+const [isUsingSavedPaymentMethod, setIsUsingSavedPaymentMethod] = useState(
+  paymentSession?.data?.payment_method_id !== undefined
+)
+```
+
+Next, add a function that resets the payment session when the customer switches between saved and new payment methods:
+
+```ts title="src/modules/checkout/components/payment-container/index.tsx" badgeLabel="Storefront" badgeColor="blue"
+const handleRefreshSession = async () => {
+  await initiatePaymentSession(cart, {
+    provider_id: paymentProviderId,
+  })
+  setIsUsingSavedPaymentMethod(false)
+}
+```
+
+This function initiates a new payment session for the cart and disables the `isUsingSavedPaymentMethod` state variable.
+
+Finally, replace the `return` statement of the `StripeCardContainer` component with the following:
+
+```tsx title="src/modules/checkout/components/payment-container/index.tsx" badgeLabel="Storefront" badgeColor="blue" highlights={stripeCardReturnHighlights}
+return (
+  <PaymentContainer
+    paymentProviderId={paymentProviderId}
+    selectedPaymentOptionId={selectedPaymentOptionId}
+    paymentInfoMap={paymentInfoMap}
+    disabled={disabled}
+    paymentSession={paymentSession}
+    cart={cart}
+  >
+    {selectedPaymentOptionId === paymentProviderId &&
+      (stripeReady ? (
+        <div className="my-4 transition-all duration-150 ease-in-out">
+          <StripeSavedPaymentMethodsContainer
+            setCardComplete={setCardComplete}
+            setCardBrand={setCardBrand}
+            setError={setError}
+            paymentSession={paymentSession}
+            cart={cart}
+          />
+          {isUsingSavedPaymentMethod && (
+            <Button 
+              variant="secondary" 
+              size="small" 
+              className="mt-2" 
+              onClick={handleRefreshSession}
+            >
+              Use a new payment method
+            </Button>
+          )}
+          {!isUsingSavedPaymentMethod && (
+            <>
+              <Text className="txt-medium-plus text-ui-fg-base my-1">
+                Enter your card details:
+              </Text>
+              <CardElement
+                options={useOptions as StripeCardElementOptions}
+                onChange={(e) => {
+                  setCardBrand(
+                    e.brand && e.brand.charAt(0).toUpperCase() + e.brand.slice(1)
+                  )
+                  setError(e.error?.message || null)
+                  setCardComplete(e.complete)
+                  }}
+                />              
+            </>
+          )}
+        </div>
+      ) : (
+        <SkeletonCardDetails />
+      ))}
+  </PaymentContainer>
+)
+```
+
+You update the `return` statement to:
+
+- Pass the new `paymentSession` and `cart` props to the `PaymentContainer` component.
+- Show the `StripeSavedPaymentMethodsContainer` component before Stripe's card element.
+- Add a button that's shown when the customer selects a saved payment method. The button allows the customer to switch back to entering a new payment method.
+
+The existing Stripe element in checkout will now show the saved payment methods to the customer along with the component to enter a card's details.
+
+Since you added new props to the `StripeCardContainer` and `PaymentContainer` components, you need to update other components that use them to pass the props.
+
+In `src/modules/checkout/components/payment/index.tsx`, find usages of `StripeCardContainer` and `PaymentContainer` in the return statement and add the `paymentSession` and `cart` props:
+
+```tsx title="src/modules/checkout/components/payment/index.tsx" badgeLabel="Storefront" badgeColor="blue" highlights={[["5"], ["6"], ["11"], ["12"]]}
+<div key={paymentMethod.id}>
+  {isStripeFunc(paymentMethod.id) ? (
+    <StripeCardContainer
+      // ...
+      paymentSession={activeSession}
+      cart={cart}
+    />
+  ) : (
+    <PaymentContainer
+      // ...
+      paymentSession={activeSession}
+      cart={cart}
+    />
+  )}
+</div>
+```
+
+### Support Updating Stripe's Client Secret
+
+The Next.js Starter Storefront uses Stripe's `Elements` component to wrap the payment elements. The `Elements` component requires a `clientSecret` prop, which is available in the cart's payment session.
+
+With the recent changes, the client secret will be updated whenever a payment session is initiated, such as when the customer selects a saved payment method. However, the `options.clientSecret` prop of the `Elements` component is immutable, meaning that it cannot be changed after the component is mounted.
+
+To force the component to re-mount and update the `clientSecret` prop, you can add a `key` prop to the `Elements` component. The `key` prop ensures that the `Elements` component re-mounts whenever the client secret changes, allowing Stripe to process the updated payment session.
+
+In `src/modules/checkout/components/payment-wrapper/stripe-wrapper.tsx`, find the `Elements` component in the `return` statement and add the `key` prop:
+
+```tsx title="src/modules/checkout/components/payment-wrapper/stripe-wrapper.tsx" badgeLabel="Storefront" badgeColor="blue" highlights={[["4"]]}
+<Elements 
+  options={options} 
+  stripe={stripePromise} 
+  key={options.clientSecret}
+>
+  {children}
+</Elements>
+```
+
+You set the `key` prop to the client secret, which forces the `Elements` component to re-mount whenever the client secret changes.
+
+### Support Payment with Saved Payment Method
+
+The last change you need to make ensures that the customer can place an order with a saved payment method.
+
+When the customer places the order, and they've chosen Stripe as a payment method, the Next.js Starter Storefront uses Stripe's `confirmCardPayment` method to confirm the payment. This method accepts either the ID of a saved payment method, or the details of a new card.
+
+So, you need to update the `confirmCardPayment` usage to support passing the ID of the selected payment method if the customer has selected one.
+
+In `src/modules/checkout/components/payment-button/index.tsx`, find the `handlePayment` method and update its first `if` condition:
+
+```ts title="src/modules/checkout/components/payment-button/index.tsx" badgeLabel="Storefront" badgeColor="blue"
+if (!stripe || !elements || (!card && !session?.data.payment_method_id) || !cart) {
+  setSubmitting(false)
+  return
+}
+```
+
+This allows the customer to place their order if they have selected a saved payment method but have not entered a new card.
+
+Then, find the usage of `confirmCardPayment` in the `handlePayment` function and change it to the following:
+
+```ts title="src/modules/checkout/components/payment-button/index.tsx" badgeLabel="Storefront" badgeColor="blue" highlights={confirmPaymentHighlights}
+await stripe
+.confirmCardPayment(session?.data.client_secret as string, {
+  payment_method: session?.data.payment_method_id as string || {
+    card: card!,
+    billing_details: {
+      name:
+        cart.billing_address?.first_name +
+        " " +
+        cart.billing_address?.last_name,
+      address: {
+        city: cart.billing_address?.city ?? undefined,
+        country: cart.billing_address?.country_code ?? undefined,
+        line1: cart.billing_address?.address_1 ?? undefined,
+        line2: cart.billing_address?.address_2 ?? undefined,
+        postal_code: cart.billing_address?.postal_code ?? undefined,
+        state: cart.billing_address?.province ?? undefined,
+      },
+      email: cart.email,
+      phone: cart.billing_address?.phone ?? undefined,
+    },
+  },
+})
+.then(({ error, paymentIntent }) => {
+  if (error) {
+    const pi = error.payment_intent
+
+    if (
+      (pi && pi.status === "requires_capture") ||
+      (pi && pi.status === "succeeded")
+    ) {
+      onPaymentCompleted()
+    }
+
+    setErrorMessage(error.message || null)
+    return
+  }
+
+  if (
+    (paymentIntent && paymentIntent.status === "requires_capture") ||
+    paymentIntent.status === "succeeded"
+  ) {
+    return onPaymentCompleted()
+  }
+
+  return
+})
+```
+
+In particular, you're changing the `payment_method` property to either be the ID of the selected payment method, or the details of a new card. This allows the customer to place an order with either a saved payment method or a new one.
+
+### Test it Out
+
+You can now test out placing orders with a saved payment method.
+
+To do that, start the Medusa application by running the following command in the Medusa application's directory:
+
+```bash npm2yarn
+npm run dev
+```
+
+Then, start the Next.js Starter Storefront by running the following command in the storefront's directory:
+
+```bash npm2yarn
+npm run dev
+```
+
+In the Next.js Starter Storefront, login with the customer account you created earlier and add a product to the cart.
+
+Then, proceed to the checkout flow. In the payment step, you should see the saved payment method you used earlier. You can select it and place the order.
+
+![Saved payment method in checkout](https://res.cloudinary.com/dza7lstvk/image/upload/v1745308047/Medusa%20Resources/Screenshot_2025-04-21_at_4.07.34_PM_krudjq.png)
+
+Once the order is placed successfully, you can check it in the Medusa Admin dashboard. You can view the order and capture the payment.
+
+![Order in the Medusa Admin dashboard](https://res.cloudinary.com/dza7lstvk/image/upload/v1745318042/Medusa%20Resources/Screenshot_2025-04-22_at_1.33.39_PM_uynlfp.png)
+
+***
+
+## Next Steps
+
+You've added support for saved payment methods in your Medusa application and Next.js Starter Storefront, allowing customers to save their payment methods during checkout and use them in future orders.
+
+You can add more features to the saved payment methods, such as allowing customers to delete saved payment methods. You can use [Stripe's APIs](https://docs.stripe.com/api/payment_methods/detach) in the storefront or add an [API route](https://docs.medusajs.com/docs/learn/fundamentals/api-routes/index.html.md) in Medusa to delete the saved payment method.
+
+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.
@@ -48849,6 +49018,2775 @@ 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 Localization in Medusa by Integrating Contentful
+
+In this tutorial, you'll learn how to localize your Medusa store's data with Contentful.
+
+When you install a Medusa application, you get a fully-fledged commerce platform with a Framework for customization. While Medusa provides features essential for internationalization, such as support for multiple [regions](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/region/index.html.md) and [currencies](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/currency/index.html.md), it doesn't provide content localization.
+
+However, Medusa's architecture supports the integration of third-party services to provide additional features, such as data localization. One service you can integrate is [Contentful](https://www.contentful.com/), a headless content management system (CMS) that allows you to manage and deliver content across multiple channels.
+
+## Summary
+
+By following this tutorial, you'll learn how to:
+
+- Install and set up Medusa.
+- Integrate Contentful with Medusa.
+- Create content types in Contentful for Medusa models.
+- Trigger syncing products and related data to Contentful when:
+  - A product is created.
+  - The admin user triggers syncing the products.
+- Customize the [Next.js Starter Storefront](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/nextjs-starter/index.html.md) to fetch localized data from Contentful through Medusa.
+- Listen to webhook events in Contentful to update Medusa's data accordingly.
+
+You can follow this tutorial whether you're new to Medusa or an advanced Medusa developer.
+
+![Diagram illustrating the integration of Contentful with Medusa](https://res.cloudinary.com/dza7lstvk/image/upload/v1744791908/Medusa%20Resources/contentful-summary_j5cpdx.jpg)
+
+- [Tutorial Repository](https://github.com/medusajs/examples/tree/main/localization-contentful): Find the full code for this guide in this repository.
+- [OpenApi Specs for Postman](https://res.cloudinary.com/dza7lstvk/raw/upload/v1744790686/OpenApi/Contentful_jysc07.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
+```
+
+First, you'll be asked for the project's name. Then, when prompted about installing 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 named `{project-name}-storefront`.
+
+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: Create Contentful Module
+
+To integrate third-party services into Medusa, you create a module. A [module](https://docs.medusajs.com/docs/learn/fundamentals/modules/index.html.md) is a reusable package that provides 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 module that provides the necessary functionalities to integrate Contentful with Medusa.
+
+Refer to the [Modules](https://docs.medusajs.com/docs/learn/fundamentals/modules/index.html.md) documentation to learn more about modules and their structure.
+
+### Install Contentful SDKs
+
+Before building the module, you need to install Contentful's management and delivery JS SDKs. So, run the following command in the Medusa application's directory:
+
+```bash npm2yarn
+npm install contentful contentful-management
+```
+
+Where `contentful` is the delivery SDK and `contentful-management` is the management SDK.
+
+### Create Module Directory
+
+A module is created under the `src/modules` directory of your Medusa application. So, create the directory `src/modules/contentful`.
+
+### Create Loader
+
+When the Medusa application starts, you want to establish a connection to Contentful, then create the necessary content types if they don't exist in Contentful.
+
+A module can specify a task to run on the Medusa application's startup using [loaders](https://docs.medusajs.com/docs/learn/fundamentals/modules/loaders/index.html.md). A loader is an asynchronous function that a module exports. Then, when the Medusa application starts, it runs the loader. The loader can be used to perform one-time tasks such as connecting to a database, creating content types, or initializing data.
+
+Refer to the [Loaders](https://docs.medusajs.com/docs/learn/fundamentals/modules/loaders/index.html.md) documentation to learn more about how loaders work and when to use them.
+
+Loaders are created in a TypeScript or JavaScript file under the `loaders` directory of a module. So, create the file `src/modules/contentful/loader/create-content-models.ts` with the following content:
+
+```ts title="src/modules/contentful/loader/create-content-models.ts" highlights={loaderHighlights}
+import { LoaderOptions } from "@medusajs/framework/types"
+import { asValue } from "awilix"
+import { createClient } from "contentful-management"
+import { MedusaError } from "@medusajs/framework/utils"
+
+const { createClient: createDeliveryClient } = require("contentful")
+
+export type ModuleOptions = {
+  management_access_token: string
+  delivery_token: string
+  space_id: string
+  environment: string
+  default_locale?: string
+}
+
+export default async function syncContentModelsLoader({
+  container,
+  options,
+}: LoaderOptions<ModuleOptions>) {
+  if (
+    !options?.management_access_token || !options?.delivery_token || 
+    !options?.space_id || !options?.environment
+  ) {
+    throw new MedusaError(
+      MedusaError.Types.INVALID_DATA,
+      "Contentful access token, space ID and environment are required"
+    )
+  }
+
+  const logger = container.resolve("logger")
+
+  try {
+    const managementClient = createClient({
+      accessToken: options.management_access_token,
+    }, {
+      type: "plain",
+      defaults: {
+        spaceId: options.space_id,
+        environmentId: options.environment,
+      },
+    })
+
+    const deliveryClient = createDeliveryClient({
+      accessToken: options.delivery_token,
+      space: options.space_id,
+      environment: options.environment,
+    })
+
+
+    // TODO try to create content types
+
+  } catch (error) {
+    logger.error(
+      `Failed to connect to Contentful: ${error}`
+    )
+    throw error
+  }
+}
+```
+
+The loader file exports an asynchronous function that accepts an object having the following properties:
+
+- `container`: The [Module container](https://docs.medusajs.com/docs/learn/fundamentals/modules/container/index.html.md), which is a registry of resources available to the module. You can use it to resolve or register resources in the module's container.
+- `options`: An object of options passed to the module. These options are useful to pass secrets or options that may change per environment. You'll learn how to pass these options later.
+  - The Contentful Module expects the options to include the Contentful tokens for the management and delivery APIs, the space ID, environment, and optionally the default locale to use.
+
+In the loader function, you validate the options passed to the module, and throw an error if they're invalid. Then, you resolve from the Module's container the [Logger](https://docs.medusajs.com/docs/learn/debugging-and-testing/logging/index.html.md) used to log messages in the terminal.
+
+Finally, you create clients for Contentful's management and delivery APIs, passing them the necessary module's options. If the connection fails, an error is thrown, which is handled in the `catch` block.
+
+#### Create Content Types
+
+In the loader, you need to create content types in Contentful if they don't already exist.
+
+In this tutorial, you'll only create content types for a product and its variants and options. However, you can create content types for other data models, such as categories or collections, by following the same approach.
+
+You can learn more about the product-related data models, which the content types are based on, in the [Product Module's Data Models](https://docs.medusajs.com/references/product/models/index.html.md) reference.
+
+To create the content type for products, replace the `TODO` in the loader with the following:
+
+```ts title="src/modules/contentful/loader/create-content-models.ts"
+// Try to create the product content type
+try {
+  await managementClient.contentType.get({
+    contentTypeId: "product",
+  })
+} catch (error) {
+  const productContentType = await managementClient.contentType.createWithId({
+    contentTypeId: "product",
+  }, {
+    name: "Product",
+    description: "Product content type synced from Medusa",
+    displayField: "title",
+    fields: [
+      {
+        id: "title", 
+        name: "Title",
+        type: "Symbol",
+        required: true,
+        localized: true,
+      },
+      {
+        id: "handle",
+        name: "Handle", 
+        type: "Symbol",
+        required: true,
+        localized: false,
+      },
+      {
+        id: "medusaId",
+        name: "Medusa ID",
+        type: "Symbol",
+        required: true,
+        localized: false,
+      },
+      {
+        type: "RichText",
+        name: "description", 
+        id: "description",
+        validations: [
+          {
+            enabledMarks: [
+              "bold",
+              "italic",
+              "underline", 
+              "code",
+              "superscript",
+              "subscript",
+              "strikethrough",
+            ],
+          },
+          {
+            enabledNodeTypes: [
+              "heading-1",
+              "heading-2", 
+              "heading-3",
+              "heading-4",
+              "heading-5",
+              "heading-6",
+              "ordered-list",
+              "unordered-list",
+              "hr",
+              "blockquote",
+              "embedded-entry-block",
+              "embedded-asset-block",
+              "table",
+              "asset-hyperlink",
+              "embedded-entry-inline",
+              "entry-hyperlink",
+              "hyperlink",
+            ],
+          },
+          {
+            nodes: {},
+          },
+        ],
+        localized: true,
+        required: true,
+      },
+      {
+        type: "Symbol",
+        name: "subtitle",
+        id: "subtitle",
+        localized: true,
+        required: false,
+        validations: [],
+      },
+      {
+        type: "Array",
+        items: {
+          type: "Link",
+          linkType: "Asset",
+          validations: [],
+        },
+        name: "images",
+        id: "images",
+        localized: true,
+        required: false,
+        validations: [],
+      },
+      {
+        id: "productVariants",
+        name: "Product Variants",
+        type: "Array",
+        localized: false,
+        required: false,
+        items: {
+          type: "Link",
+          validations: [
+            {
+              linkContentType: ["productVariant"],
+            },
+          ],
+          linkType: "Entry",
+        },
+        disabled: false,
+        omitted: false,
+      },
+      {
+        id: "productOptions",
+        name: "Product Options",
+        type: "Array",
+        localized: false,
+        required: false,
+        items: {
+          type: "Link",
+          validations: [
+            {
+              linkContentType: ["productOption"],
+            },
+          ],
+          linkType: "Entry",
+        },
+        disabled: false,
+        omitted: false,
+      },
+    ],
+  })
+
+  await managementClient.contentType.publish({
+    contentTypeId: "product",
+  }, productContentType)
+}
+
+// TODO create product variant content type
+```
+
+In the above snippet, you first try to retrieve the product content type using Contentful's Management APIs. If the content type doesn't exist, an error is thrown, which you handle in the `catch` block.
+
+In the `catch` block, you create the product content type with the following fields:
+
+- `title`: The product's title, which is a localized field.
+- `handle`: The product's handle, which is used to create a human-readable URL for the product in the storefront.
+- `medusaId`: The product's ID in Medusa, which is a non-localized field. You'll store in this field the ID of the product in Medusa.
+- `description`: The product's description, which is a localized rich-text field.
+- `subtitle`: The product's subtitle, which is a localized field.
+- `images`: The product's images, which is a localized array of assets in Contentful.
+- `productVariants`: The product's variants, which is an array that references content of the `productVariant` content type.
+- `productOptions`: The product's options, which is an array that references content of the `productOption` content type.
+
+Next, you'll create the `productVariant` content type that represents a product's variant. A variant is a combination of the product's options that customers can purchase. For example, a "red" shirt is a variant whose color option is `red`.
+
+To create the variant content type, replace the new `TODO` with the following:
+
+```ts title="src/modules/contentful/loader/create-content-models.ts"
+// Try to create the product variant content type
+try {
+  await managementClient.contentType.get({
+    contentTypeId: "productVariant",
+  })
+} catch (error) {
+  const productVariantContentType = await managementClient.contentType.createWithId({
+    contentTypeId: "productVariant",
+  }, {
+  name: "Product Variant",
+  description: "Product variant content type synced from Medusa",
+  displayField: "title",
+  fields: [
+    {
+      id: "title",
+      name: "Title",
+      type: "Symbol",
+      required: true,
+      localized: true,
+    },
+    {
+      id: "product",
+      name: "Product",
+      type: "Link",
+      required: true,
+      localized: false,
+      validations: [
+        {
+          linkContentType: ["product"],
+        },
+      ],
+      disabled: false,
+      omitted: false,
+      linkType: "Entry",
+    },
+    {
+      id: "medusaId",
+      name: "Medusa ID",
+      type: "Symbol",
+      required: true,
+      localized: false,
+    },
+    {
+      id: "productOptionValues",
+      name: "Product Option Values",
+      type: "Array",
+      localized: false,
+      required: false,
+      items: {
+        type: "Link",
+        validations: [
+          {
+            linkContentType: ["productOptionValue"],
+          },
+        ],
+        linkType: "Entry",
+      },
+      disabled: false,
+      omitted: false,
+      },
+    ],
+  })
+
+  await managementClient.contentType.publish({
+    contentTypeId: "productVariant",
+  }, productVariantContentType)
+}
+
+// TODO create product option content type
+```
+
+In the above snippet, you create the `productVariant` content type with the following fields:
+
+- `title`: The product variant's title, which is a localized field.
+- `product`: References the `product` content type, which is the product that the variant belongs to.
+- `medusaId`: The product variant's ID in Medusa, which is a non-localized field. You'll store in this field the ID of the variant in Medusa.
+- `productOptionValues`: The product variant's option values, which is an array that references content of the `productOptionValue` content type.
+
+Then, you'll create the `productOption` content type that represents a product's option, like size or color. Replace the new `TODO` with the following:
+
+```ts title="src/modules/contentful/loader/create-content-models.ts"
+// Try to create the product option content type
+try {
+  await managementClient.contentType.get({
+    contentTypeId: "productOption",
+  })
+} catch (error) {
+  const productOptionContentType = await managementClient.contentType.createWithId({
+    contentTypeId: "productOption",
+  }, {
+    name: "Product Option",
+    description: "Product option content type synced from Medusa",
+    displayField: "title",
+    fields: [
+    {
+      id: "title",
+      name: "Title",
+      type: "Symbol",
+      required: true,
+      localized: true,
+    },
+    {
+      id: "product",
+      name: "Product",
+      type: "Link",
+      required: true,
+      localized: false,
+      validations: [
+        {
+          linkContentType: ["product"],
+        },
+      ],
+      disabled: false,
+      omitted: false,
+      linkType: "Entry",
+    },
+    {
+      id: "medusaId",
+      name: "Medusa ID",
+      type: "Symbol",
+      required: true,
+      localized: false,
+    },
+    {
+      id: "values",
+      name: "Values",
+      type: "Array",
+      required: false,
+      localized: false,
+      items: {
+        type: "Link",
+        validations: [
+          {
+            linkContentType: ["productOptionValue"],
+          },
+        ],
+        linkType: "Entry",
+      },
+      disabled: false,
+      omitted: false,
+      },
+    ],
+  })
+
+  await managementClient.contentType.publish({
+    contentTypeId: "productOption",
+  }, productOptionContentType)
+}
+
+// TODO create product option value content type
+```
+
+In the above snippet, you create the `productOption` content type with the following fields:
+
+- `title`: The product option's title, which is a localized field.
+- `product`: References the `product` content type, which is the product that the option belongs to.
+- `medusaId`: The product option's ID in Medusa, which is a non-localized field. You'll store in this field the ID of the option in Medusa.
+- `values`: The product option's values, which is an array that references content of the `productOptionValue` content type.
+
+Finally, you'll create the `productOptionValue` content type that represents a product's option value, like "red" or "blue" for the color option. A variant references option values.
+
+To create the option value content type, replace the new `TODO` with the following:
+
+```ts title="src/modules/contentful/loader/create-content-models.ts"
+// Try to create the product option value content type
+try {
+  await managementClient.contentType.get({
+    contentTypeId: "productOptionValue",
+  })
+} catch (error) {
+  const productOptionValueContentType = await managementClient.contentType.createWithId({
+    contentTypeId: "productOptionValue",
+  }, {
+    name: "Product Option Value",
+    description: "Product option value content type synced from Medusa",
+    displayField: "value",
+    fields: [
+    {
+      id: "value",
+      name: "Value",
+      type: "Symbol",
+      required: true,
+      localized: true,
+    },
+    {
+      id: "medusaId",
+      name: "Medusa ID",
+      type: "Symbol",
+      required: true,
+      localized: false,
+    },
+  ],
+})
+
+await managementClient.contentType.publish({
+    contentTypeId: "productOptionValue",
+  }, productOptionValueContentType)
+}
+
+// TODO register clients in container
+```
+
+In the above snippet, you create the `productOptionValue` content type with the following fields:
+
+- `value`: The product option value, which is a localized field.
+- `medusaId`: The product option value's ID in Medusa, which is a non-localized field. You'll store in this field the ID of the option value in Medusa.
+
+You've now created all the necessary content types to localize products.
+
+### Register Clients in the Container
+
+The last step in the loader is to register the Contentful management and delivery clients in the module's container. This will allow you to resolve and use them in the module's service, which you'll create next.
+
+To register resources in the container, you can use its `register` method, which accepts an object containing key-value pairs. The keys are the names of the resources in the container, and the values are the resources themselves.
+
+To register the management and delivery clients, replace the last `TODO` in the loader with the following:
+
+```ts title="src/modules/contentful/loader/create-content-models.ts"
+container.register({
+  contentfulManagementClient: asValue(managementClient),
+  contentfulDeliveryClient: asValue(deliveryClient),
+})
+
+logger.info("Connected to Contentful")
+```
+
+Now, you can resolve the management and delivery clients from the module's container using the keys `contentfulManagementClient` and `contentfulDeliveryClient`, respectively.
+
+### Create Service
+
+You define a module's functionality 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 perform actions with a third-party service.
+
+In this section, you'll create the Contentful Module's service that can be used to retrieve content from Contentful, create content, and more.
+
+To create the service, create the file `src/modules/contenful/service.ts` with the following content:
+
+```ts title="src/modules/contentful/service.ts" highlights={serviceHighlights}
+import { ModuleOptions } from "./loader/create-content-models"
+import { PlainClientAPI } from "contentful-management"
+
+type InjectedDependencies = {
+  contentfulManagementClient: PlainClientAPI;
+  contentfulDeliveryClient: any;
+}
+
+export default class ContentfulModuleService {
+  private managementClient: PlainClientAPI
+  private deliveryClient: any
+  private options: ModuleOptions
+
+  constructor(
+    { 
+      contentfulManagementClient, 
+      contentfulDeliveryClient,
+    }: InjectedDependencies, 
+    options: ModuleOptions
+  ) {
+    this.managementClient = contentfulManagementClient
+    this.deliveryClient = contentfulDeliveryClient
+    this.options = {
+      ...options,
+      default_locale: options.default_locale || "en-US",
+    }
+  }
+
+  // TODO add methods
+}
+```
+
+You export a class that will be the Contentful Module's main service. In the class, you define properties for the Contentful clients and options passed to the module.
+
+You also add a constructor to the class. A service's constructor accepts the following params:
+
+1. The module's container, which you can use to resolve resources. You use it to resolve the Contentful clients you previously registered in the loader.
+2. The options passed to the module.
+
+In the constructor, you assign the clients and options to the class properties. You also set the default locale to `en-US` if it's not provided in the module's options.
+
+Since the loader is executed on application start-up, if an error occurs while connecting to Contentful, the module will not be registered and the service will not be executed. So, in the service, you're guaranteed that the clients are registered in the container and have successful connection to Contentful.
+
+As you implement the syncing and content retrieval features later, you'll add the necessary methods for them.
+
+### Export Module Definition
+
+The final piece to a module is its definition, which you export in an `index.ts` file at the module's root directory. This definition tells Medusa the name of the module, its service, and optionally its loaders.
+
+To create the module's definition, create the file `src/modules/contentful/index.ts` with the following content:
+
+```ts title="src/modules/contentful/index.ts" highlights={moduleHighlights}
+import { Module } from "@medusajs/framework/utils"
+import ContentfulModuleService from "./service"
+import createContentModelsLoader from "./loader/create-content-models"
+
+export const CONTENTFUL_MODULE = "contentful"
+
+export default Module(CONTENTFUL_MODULE, {
+  service: ContentfulModuleService,
+  loaders: [
+    createContentModelsLoader,
+  ],
+})
+```
+
+You use `Module` from the Modules SDK to create the module's definition. It accepts two parameters:
+
+1. The module's name, which is `contentful`.
+2. An object with a required property `service` indicating the module's service. You also pass the loader you created to ensure it's executed when the application starts.
+
+Aside from the module definition, you export the module's name as `CONTENTFUL_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/contentful",
+      options: {
+        management_access_token: process.env.CONTENTFUL_MANAGEMNT_ACCESS_TOKEN,
+        delivery_token: process.env.CONTENTFUL_DELIVERY_TOKEN,
+        space_id: process.env.CONTENTFUL_SPACE_ID,
+        environment: process.env.CONTENTFUL_ENVIRONMENT,
+        default_locale: "en-US",
+      },
+    },
+  ],
+})
+```
+
+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.
+
+You also pass an `options` property with the module's options, including the Contentful's tokens for the management and delivery APIs, the Contentful's space ID, environment, and default locale.
+
+### Note about Locales
+
+By default, your Contentful space will have one locale (for example, `en-US`). You can add locales as explained in the [Contentful documentation](https://www.contentful.com/help/localization/manage-locales/).
+
+When you add a locale, make sure to:
+
+- Set the fallback locale to the default locale (for example, `en-US`). This ensure that values are retrieved in the default locale if values for the requested locale are not available.
+- Allow the required fields to be empty for the locale. Otherwise, you'll have to specify the values for the localized fields in each locale when you create the products later.
+
+![Example of the locale's settings in the Contentful dashboard](https://res.cloudinary.com/dza7lstvk/image/upload/v1744716537/Medusa%20Resources/Screenshot_2025-04-15_at_2.28.46_PM_v50lrm.png)
+
+### Add Environment Variables
+
+Before you can start using the Contentful Module, you need to add the necessary environment variables used in the module's options.
+
+Add the following environment variables to your `.env` file:
+
+```plain
+CONTENTFUL_MANAGEMNT_ACCESS_TOKEN=CFPAT-...
+CONTENTFUL_DELIVERY_TOKEN=eij...
+CONTENTFUL_SPACE_ID=t2a...
+CONTENTFUL_ENVIRONMENT=master
+```
+
+Where:
+
+- `CONTENTFUL_MANAGEMNT_ACCESS_TOKEN`: The Contentful management API access token. To create it on the Contentful dashboard:
+  - Click on the cog icon at the top right, then choose "CMA tokens" from the dropdown.
+
+![The cog icon is at the top right next to the user avatar. If you click on it, a dropdown will show where you can click on "CMA tokens".](https://res.cloudinary.com/dza7lstvk/image/upload/v1744714244/Medusa%20Resources/Screenshot_2025-04-15_at_1.48.35_PM_ct2tfk.png)
+
+- In the CMA tokens page, click on the "Create personal access token" button.
+- In the window that pops up, enter a name for the token, and choose an expiry date. Once you're done, click the Generate button.
+- The token is generated and shown in the pop-up. Make sure to copy it and use it in the `.env` file, as you can't access it again.
+
+![Click on the copy button to copy the key](https://res.cloudinary.com/dza7lstvk/image/upload/v1744714749/Medusa%20Resources/Screenshot_2025-04-15_at_1.58.12_PM_tuugam.png)
+
+- `CONTENTFUL_DELIVERY_TOKEN`: An API token that you can use with the delivery API. To create it on the Contentful dashboard:
+  - Click on the cog icon at the top right, then choose "API keys" from the dropdown.
+
+![The cog icon is at the top right next to the user avatar. If you click on it, a dropdown will show where you can click on "API keys".](https://res.cloudinary.com/dza7lstvk/image/upload/v1744714971/Medusa%20Resources/Screenshot_2025-04-15_at_2.02.31_PM_qfsn1h.png)
+
+- In the APIs page, click on the "Add API key" button.
+- In the window that pops up, enter a name for the token, then click the Add API Key button.
+- This will create an API key and opens its page. On its page, copy the token for the "Content Delivery API" and use it as the value for `CONTENTFUL_DELIVERY_TOKEN`.
+
+![Copy the API key from the "Content Delivery API - access token" field](https://res.cloudinary.com/dza7lstvk/image/upload/v1744715228/Medusa%20Resources/Screenshot_2025-04-15_at_2.06.44_PM_ifu1mx.png)
+
+- `CONTENTFUL_SPACE_ID`: The ID of your Contentful space. You can copy this from the dashboard's URL which is of the format `https://app.contentful.com/spaces/{space_id}/...`.
+- `CONTENTFUL_ENVIRONMENT`: The environment to manage and retrieve the content in. By default, you have the `master` environment which you can use. However, you can use another Contentful environment that you've created.
+
+Your module is now ready for use.
+
+### Test the Module
+
+To test out the module, you'll start the Medusa application, which will run the module's loader.
+
+To start the Medusa application, run the following command:
+
+```bash npm2yarn
+npm run dev
+```
+
+If the loader ran successfully, you'll see the following message in the terminal:
+
+```bash
+info:    Connected to Contentful
+```
+
+You can also see on the Contentful dashboard that the content types were created. To view them, go to the Content Model page.
+
+![In the Contentful dashboard, go to the Content Model page](https://res.cloudinary.com/dza7lstvk/image/upload/v1744715783/Medusa%20Resources/Screenshot_2025-04-15_at_2.16.09_PM_w7oszm.png)
+
+***
+
+## Step 3: Create Products in Contentful
+
+Now that you have the Contentful Module ready for use, you can start creating products in Contentful.
+
+In this step, you'll implement the logic to create products in Contentful. Later, you'll execute it when:
+
+- A product is created in Medusa.
+- The admin user triggers a sync manually.
+
+### Add Methods to Contentful Module Service
+
+To create products in Contentful, you need to add the necessary methods in the Contentful Module's service. Then, you can use these methods later when building the creation flow.
+
+To create a product in Contentful, you'll need three methods: One to create the product's variants, another to create the product's options and values, and a third to create the product.
+
+In the service at `src/modules/contentful/service.ts`, start by adding the method to create the product's variants:
+
+```ts title="src/modules/contentful/service.ts"
+// imports...
+import { ProductVariantDTO } from "@medusajs/framework/types"
+import { EntryProps } from "contentful-management"
+
+export default class ContentfulModuleService {
+  // ...
+
+  private async createProductVariant(
+    variants: ProductVariantDTO[],
+    productEntry: EntryProps
+  ) {
+    for (const variant of variants) {
+      await this.managementClient.entry.createWithId(
+        {
+          contentTypeId: "productVariant",
+          entryId: variant.id,
+        },
+        {
+          fields: {
+            medusaId: {
+              [this.options.default_locale!]: variant.id,
+            },
+            title: {
+              [this.options.default_locale!]: variant.title,
+            },
+            product: {
+              [this.options.default_locale!]: {
+                sys: {
+                  type: "Link",
+                  linkType: "Entry",
+                  id: productEntry.sys.id,
+                },
+              },
+            },
+            productOptionValues: {
+              [this.options.default_locale!]: variant.options.map((option) => ({
+                sys: {
+                  type: "Link",
+                  linkType: "Entry",
+                  id: option.id,
+                },
+              })),
+            },
+          },
+        }
+      )
+    }
+  }
+}
+```
+
+You define a private method `createProductVariant` that accepts two parameters:
+
+1. The product's variants to create in Contentful.
+2. The product's entry in Contentful.
+
+In the method, you iterate over the product's variants and create a new entry in Contentful for each variant. You set the fields based on the product variant content type you created earlier.
+
+For each field, you specify the value for the default locale. In the Contentful dashboard, you can manage the values for other locales.
+
+Next, add the method to create the product's options and values:
+
+```ts title="src/modules/contentful/service.ts" highlights={createProductOptionHighlights}
+// other imports...
+import { ProductOptionDTO } from "@medusajs/framework/types"
+
+export default class ContentfulModuleService {
+  // ...
+  private async createProductOption(
+    options: ProductOptionDTO[],
+    productEntry: EntryProps
+  ) {
+    for (const option of options) {
+      const valueIds: {
+        sys: {
+          type: "Link",
+          linkType: "Entry",
+          id: string
+        }
+      }[] = []
+      for (const value of option.values) {
+        await this.managementClient.entry.createWithId(
+          {
+            contentTypeId: "productOptionValue",
+            entryId: value.id,
+          },
+          {
+            fields: {
+              value: {
+                [this.options.default_locale!]: value.value,
+              },
+              medusaId: {
+                [this.options.default_locale!]: value.id,
+              },
+            },
+          }
+        )
+        valueIds.push({
+          sys: {
+            type: "Link",
+            linkType: "Entry",
+            id: value.id,
+          },
+        })
+      }
+      await this.managementClient.entry.createWithId(
+        {
+          contentTypeId: "productOption",
+          entryId: option.id,
+        },
+        {
+          fields: {
+            medusaId: {
+              [this.options.default_locale!]: option.id,
+            },
+            title: {
+              [this.options.default_locale!]: option.title,
+            },
+            product: {
+              [this.options.default_locale!]: {
+                sys: {
+                  type: "Link",
+                  linkType: "Entry",
+                  id: productEntry.sys.id,
+                },
+              },
+            },
+            values: {
+              [this.options.default_locale!]: valueIds,
+            },
+          },
+        }
+      )
+    }
+  }
+}
+```
+
+You define a private method `createProductOption` that accepts two parameters:
+
+1. The product's options, which is an array of objects.
+2. The product's entry in Contentful, which is an object.
+
+In the method, you iterate over the product's options and create entries for each of its values. Then, you create an entry for the option, and reference the values you created in Contentful. You set the fields based on the option and value content types you created earlier.
+
+Finally, add the method to create the product:
+
+```ts title="src/modules/contentful/service.ts" highlights={createProductHighlights}
+// other imports...
+import { ProductDTO } from "@medusajs/framework/types"
+
+export default class ContentfulModuleService {
+  // ...
+  async createProduct(
+    product: ProductDTO
+  ) {
+    try {
+      // check if product already exists
+      const productEntry = await this.managementClient.entry.get({
+        environmentId: this.options.environment,
+        entryId: product.id,
+      })
+      
+      return productEntry
+    } catch(e) {}
+    
+    // Create product entry in Contentful
+    const productEntry = await this.managementClient.entry.createWithId(
+      {
+        contentTypeId: "product",
+        entryId: product.id,
+      },
+      {
+        fields: {
+          medusaId: {
+            [this.options.default_locale!]: product.id,
+          },
+          title: {
+            [this.options.default_locale!]: product.title,
+          },
+          description: product.description ? {
+            [this.options.default_locale!]: {
+              nodeType: "document",
+              data: {},
+              content: [
+                {
+                  nodeType: "paragraph",
+                  data: {},
+                  content: [
+                    {
+                      nodeType: "text",
+                      value: product.description,
+                      marks: [],
+                      data: {},
+                    },
+                  ],
+                },
+              ],
+            },
+          } : undefined,
+          subtitle: product.subtitle ? {
+            [this.options.default_locale!]: product.subtitle,
+          } : undefined,
+          handle: product.handle ? {
+            [this.options.default_locale!]: product.handle,
+          } : undefined,
+        },
+      }
+    )
+
+    // Create options if they exist
+    if (product.options?.length) {
+      await this.createProductOption(product.options, productEntry)
+    }
+
+    // Create variants if they exist
+    if (product.variants?.length) {
+      await this.createProductVariant(product.variants, productEntry)
+    }
+
+    // update product entry with variants and options
+    await this.managementClient.entry.update(
+      {
+        entryId: productEntry.sys.id,
+      },
+      {
+        sys: productEntry.sys,
+        fields: {
+          ...productEntry.fields,
+          productVariants: {
+            [this.options.default_locale!]: product.variants?.map((variant) => ({
+              sys: {
+                type: "Link",
+                linkType: "Entry",
+                id: variant.id,
+              },
+            })),
+          },
+          productOptions: {
+            [this.options.default_locale!]: product.options?.map((option) => ({
+              sys: {
+                type: "Link",
+                linkType: "Entry",
+                id: option.id,
+              },
+            })),
+          },
+        },
+      }
+    )
+
+    return productEntry
+  }
+}
+```
+
+You define a public method `createProduct` that accepts a product object as a parameter.
+
+In the method, you first check if the product already exists in Contentful. If it does, you return the existing product entry. Otherwise, you create a new product entry with the fields based on the product content type you created earlier.
+
+Next, you create entries for the product's options and variants using the methods you created earlier.
+
+Finally, you update the product entry to reference the variants and options you created.
+
+You now have all the methods to create products in Contentful. You'll also need one last method to delete a product in Contentful. This is useful when you implement the rollback mechanism in the flow that creates the products.
+
+Add the following method to the service:
+
+```ts title="src/modules/contentful/service.ts" highlights={deleteProductHighlights}
+// other imports...
+import { MedusaError } from "@medusajs/framework/utils"
+
+export default class ContentfulModuleService {
+  // ...
+  async deleteProduct(productId: string) {
+    try {
+      // Get the product entry
+      const productEntry = await this.managementClient.entry.get({
+        environmentId: this.options.environment,
+        entryId: productId,
+      })
+
+      if (!productEntry) {
+        return
+      }
+
+      // Delete the product entry
+      await this.managementClient.entry.unpublish({
+        environmentId: this.options.environment,
+        entryId: productId,
+      })
+
+      await this.managementClient.entry.delete({
+        environmentId: this.options.environment,
+        entryId: productId,
+      })
+
+      // Delete the product variant entries
+      for (const variant of productEntry.fields.productVariants[this.options.default_locale!]) {
+        await this.managementClient.entry.unpublish({
+          environmentId: this.options.environment,
+          entryId: variant.sys.id,
+        })
+
+        await this.managementClient.entry.delete({
+          environmentId: this.options.environment,
+          entryId: variant.sys.id,
+        })
+      }
+
+      // Delete the product options entries and values
+      for (const option of productEntry.fields.productOptions[this.options.default_locale!]) {
+        for (const value of option.fields.values[this.options.default_locale!]) {
+          await this.managementClient.entry.unpublish({
+            environmentId: this.options.environment,
+            entryId: value.sys.id,
+        })
+
+        await this.managementClient.entry.delete({
+          environmentId: this.options.environment,
+            entryId: value.sys.id,
+          })
+        }
+
+        await this.managementClient.entry.unpublish({
+          environmentId: this.options.environment,
+          entryId: option.sys.id,
+        })
+
+        await this.managementClient.entry.delete({
+          environmentId: this.options.environment,
+          entryId: option.sys.id,
+        })
+      }
+    } catch (error) {
+      throw new MedusaError(
+        MedusaError.Types.INVALID_DATA,
+        `Failed to delete product from Contentful: ${error.message}`
+      )
+    }
+  }
+}
+```
+
+You define a public method `deleteProduct` that accepts a product ID as a parameter.
+
+In the method, you retrieve the product entry from Contentful with its variants, options, and values. For each entry, you must unpublish and delete it.
+
+You now have all the methods necessary to build the creation flow.
+
+### Create Contentful Product Workflow
+
+To implement the logic that's triggered when a product is created in Medusa, or when the admin user triggers a sync manually, you need to create a workflow.
+
+A [workflow](https://docs.medusajs.com/docs/learn/fundamentals/workflows/index.html.md) is a series of 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.
+
+Learn more about workflows in the [Workflows documentation](https://docs.medusajs.com/docs/learn/fundamentals/workflows/index.html.md).
+
+In this section, you'll create a workflow that creates Medusa products in Contentful using the Contentful Module.
+
+The workflow has the following steps:
+
+- [useQueryGraphStep](https://docs.medusajs.com/references/helper-steps/useQueryGraphStep/index.html.md): Retrieve products to create in Contentful.
+- [createProductsContentfulStep](#createProductsContentfulStep): Create the products in Contentful.
+
+Medusa provides the `useQueryGraphStep` in its `@medusajs/medusa/core-flows` package. So, you only need to implement the second step.
+
+#### createProductsContentfulStep
+
+In the second step, you create the retrieved products in Contentful.
+
+To create the step, create the file `src/workflows/steps/create-products-contentful.ts` with the following content:
+
+```ts title="src/workflows/steps/create-products-contentful.ts" highlights={createProductsContentfulStepHighlights}
+import { ProductDTO } from "@medusajs/framework/types"
+import { CONTENTFUL_MODULE } from "../../modules/contentful"
+import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk"
+import ContentfulModuleService from "../../modules/contentful/service"
+import { EntryProps } from "contentful-management"
+
+type StepInput = {
+  products: ProductDTO[]
+}
+
+export const createProductsContentfulStep = createStep(
+  "create-products-contentful-step",
+  async (input: StepInput, { container }) => {
+    const contentfulModuleService: ContentfulModuleService = 
+      container.resolve(CONTENTFUL_MODULE)
+
+    const products: EntryProps[] = []
+
+    try {
+      for (const product of input.products) {
+        products.push(await contentfulModuleService.createProduct(product))
+      }
+    } catch(e) {
+      return StepResponse.permanentFailure(
+        `Error creating products in Contentful: ${e.message}`,
+        products
+      )
+    }
+
+    return new StepResponse(
+      products,
+      products
+    )
+  },
+  async (products, { container }) => {
+    if (!products) {
+      return
+    }
+
+    const contentfulModuleService: ContentfulModuleService = 
+      container.resolve(CONTENTFUL_MODULE)
+
+    for (const product of products) {
+      await contentfulModuleService.deleteProduct(product.sys.id)
+    }
+  }
+)
+```
+
+You create a step with `createStep` from the Workflows SDK. It accepts three parameters:
+
+1. The step's unique name, which is `create-products-contentful-step`.
+2. An async function that receives two parameters:
+   - The step's input, which is in this case an object holding an array of products to create in Contentful.
+   - 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.
+3. An optional compensation function that undoes the actions performed in the step if an error occurs in the workflow's execution. This mechanism ensures data consistency in your application, especially as you integrate external systems.
+
+The Medusa container is different from the module's container. Since modules are isolated, they each have a container with their resources. Refer to the [Module Container](https://docs.medusajs.com/docs/learn/fundamentals/modules/container/index.html.md) documentation for more information.
+
+In the step function, you resolve the Contentful Module's service from the Medusa container using the name you exported in the module definition's file.
+
+Then, you iterate over the products and create a new entry in Contentful for each product using the `createProduct` method you created earlier. If the creation of any product fails, you fail the step and pass the created products to the compensation function.
+
+A step function must return a `StepResponse` instance. The `StepResponse` constructor accepts two parameters:
+
+1. The step's output, which is the product entries created in Contentful.
+2. Data to pass to the step's compensation function.
+
+The compensation function accepts as a parameter the data passed from the step, and an object containing the Medusa container.
+
+In the compensation function, you iterate over the created product entries and delete them from Contentful using the `deleteProduct` method you created earlier.
+
+#### Create the Workflow
+
+Now that you have all the necessary steps, you can create the workflow.
+
+To create the workflow, create the file `src/workflows/create-products-contentful.ts` with the following content:
+
+```ts title="src/workflows/create-products-contentful.ts"
+import { createWorkflow, WorkflowResponse } from "@medusajs/framework/workflows-sdk"
+import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
+import { createProductsContentfulStep } from "./steps/create-products-contentful"
+import { ProductDTO } from "@medusajs/framework/types"
+
+type WorkflowInput = {
+  product_ids: string[]
+}
+
+export const createProductsContentfulWorkflow = createWorkflow(
+  { name: "create-products-contentful-workflow" },
+  (input: WorkflowInput) => {
+    // @ts-ignore
+    const { data } = useQueryGraphStep({
+      entity: "product",
+      fields: [
+        "id",
+        "title",
+        "description",
+        "subtitle",
+        "status",
+        "handle",
+        "variants.*",
+        "variants.options.*",
+        "options.*",
+        "options.values.*",
+      ],
+      filters: {
+        id: input.product_ids,
+      },
+    })
+    
+    const contentfulProducts = createProductsContentfulStep({
+      products: data as ProductDTO[],
+    })
+
+    return new WorkflowResponse(contentfulProducts)
+  }
+)
+```
+
+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 the product IDs to create in Contentful.
+
+In the workflow's constructor function, you:
+
+1. Retrieve the Medusa products using the `useQueryGraphStep` helper step. This step uses Medusa's [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md) tool to retrieve data across modules. You pass it the product IDs to retrieve.
+2. Create the product entries in Contentful using the `createProductsContentfulStep` step.
+
+A workflow must return an instance of `WorkflowResponse`. The `WorkflowResponse` constructor accepts the workflow's output as a parameter, which is an object of the product entries created in Contentful.
+
+You now have the workflow that you can execute when a product is created in Medusa, or when the admin user triggers a sync manually.
+
+***
+
+## Step 4: Trigger Sync on Product Creation
+
+Medusa has an event system that allows you to listen for events, such as `product.created`, and perform an asynchronous action when the event is emitted.
+
+You listen to events in a subscriber. A [subscriber](https://docs.medusajs.com/docs/learn/fundamentals/events-and-subscribers/index.html.md) is an asynchronous function that listens to one or more events and performs actions when these events are emitted. A subscriber is useful when syncing data across systems, as the operation can be time-consuming and should be performed in the background.
+
+In this step, you'll create a subscriber that listens to the `product.created` event and executes the `createProductsContentfulWorkflow` workflow.
+
+Learn more about subscribers in the [Events and Subscribers documentation](https://docs.medusajs.com/docs/learn/fundamentals/events-and-subscribers/index.html.md).
+
+To create a subscriber, create the file `src/subscribers/create-product.ts` with the following content:
+
+```ts title="src/subscribers/create-product.ts" highlights={createProductSubscriberHighlights}
+import {
+  type SubscriberConfig,
+  type SubscriberArgs,
+} from "@medusajs/framework"
+import { 
+  createProductsContentfulWorkflow,
+} from "../workflows/create-products-contentful"
+
+export default async function handleProductCreate({
+  event: { data },
+  container,
+}: SubscriberArgs<{ id: string }>) {
+  await createProductsContentfulWorkflow(container)
+    .run({
+      input: {
+        product_ids: [data.id],
+      },
+    })
+
+  console.log("Product created in Contentful")
+}
+
+export const config: SubscriberConfig = {
+  event: "product.created",
+}
+```
+
+A subscriber file must export:
+
+1. An asynchronous function, which is the subscriber that is executed when the event is emitted.
+2. A configuration object that holds the name of the event the subscriber listens to, which is `product.created` in this case.
+
+The subscriber function receives an object as a parameter that has the following properties:
+
+- `event`: An object that holds the event's data payload. The payload of the `product.created` event is an array of product IDs.
+- `container`: The Medusa container to access the Framework and commerce tools.
+
+In the subscriber function, you execute the `createProductsContentfulWorkflow` by invoking it, passing the Medusa container as a parameter. Then, you chain a `run` method, passing it the product ID from the event's data payload as input.
+
+Finally, you log a message to the console to indicate that the product was created in Contentful.
+
+### Test the Subscriber
+
+To test out the subscriber, start the Medusa application:
+
+```bash npm2yarn
+npm run dev
+```
+
+Then, open the Medusa Admin dashboard and login.
+
+Can't remember the credentials? Learn how to create a user in the [Medusa CLI reference](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/medusa-cli/commands/user/index.html.md).
+
+Next, open the Products page and create a new product.
+
+You should see the following message in the terminal:
+
+```bash
+info: Product created in Contentful
+```
+
+You can also see the product in the Contentful dashboard by going to the Content page.
+
+***
+
+## Step 5: Trigger Product Sync Manually
+
+The other way to sync products is when the admin user triggers a sync manually. This is useful when you already have products in Medusa and you want to sync them to Contentful.
+
+To allow admin users to trigger a sync manually, you need:
+
+1. A subscriber that listens to a custom event.
+2. An API route that emits the custom event when a request is sent to it.
+3. A UI route in the Medusa Admin that displays a button to trigger the sync.
+
+### Create Manual Sync Subscriber
+
+You'll start by creating the subscriber that listens to a custom event to sync the Medusa products to Contentful.
+
+To create the subscriber, create the file `src/subscribers/sync-products.ts` with the following content:
+
+```ts title="src/subscribers/sync-products.ts" highlights={syncProductsSubscriberHighlights}
+import type { 
+  SubscriberConfig,
+  SubscriberArgs,
+} from "@medusajs/framework"
+import { ContainerRegistrationKeys } from "@medusajs/framework/utils"
+import { 
+  createProductsContentfulWorkflow,
+} from "../workflows/create-products-contentful"
+
+export default async function syncProductsHandler({
+  container,
+}: SubscriberArgs<Record<string, unknown>>) {
+  const query = container.resolve(ContainerRegistrationKeys.QUERY)
+  
+  const batchSize = 100
+  let hasMore = true
+  let offset = 0
+  let totalCount = 0
+
+  while (hasMore) {
+    const {
+      data: products,
+      metadata: { count } = {},
+    } = await query.graph({
+      entity: "product",
+      fields: [
+        "id",
+      ],
+      pagination: {
+        skip: offset,
+        take: batchSize,
+      },
+    })
+
+    if (products.length) {
+      await createProductsContentfulWorkflow(container).run({
+        input: {
+          product_ids: products.map((product) => product.id),
+        },
+      })
+    }
+
+    hasMore = products.length === batchSize
+    offset += batchSize
+    totalCount = count ?? 0
+  }
+
+  console.log(`Synced ${totalCount} products to Contentful`)
+}
+
+export const config: SubscriberConfig = {
+  event: "products.sync",
+}
+```
+
+You create a subscriber that listens to the `products.sync` event.
+
+In the subscriber function, you use [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md) to retrieve all the products in Medusa with pagination. Then, for each batch of products, you execute the `createProductsContentfulWorkflow` workflow, passing the product IDs to the workflow.
+
+Finally, you log a message to the console to indicate that the products were synced to Contentful.
+
+### Create API Route to Trigger Sync
+
+Next, to allow the admin user to trigger the sync manually, you need to create an API route that emits the `products.sync` event.
+
+An API Route is an endpoint that exposes commerce features to external applications and clients, such as storefronts.
+
+Learn more about API routes in [this documentation](https://docs.medusajs.com/docs/learn/fundamentals/api-routes/index.html.md).
+
+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 `/admin/contentful/sync`, create the file `src/api/admin/contentful/sync/route.ts` with the following content:
+
+```ts title="src/api/admin/contentful/sync/route.ts" highlights={syncProductsRouteHighlights}
+import {
+  MedusaRequest,
+  MedusaResponse,
+} from "@medusajs/framework/http"
+
+export const POST = async (
+  req: MedusaRequest,
+  res: MedusaResponse
+) => {
+  const eventService = req.scope.resolve("event_bus")
+
+  await eventService.emit({
+    name: "products.sync",
+    data: {},
+  })
+
+  res.status(200).json({
+    message: "Products sync triggered successfully",
+  })
+}
+```
+
+Since you export a `POST` route handler function, you expose an `API` route at `/admin/contentful/sync`. The route handler function accepts two parameters:
+
+1. A request object with details and context on the request, such as body parameters or authenticated user details.
+2. A response object to manipulate and send the response.
+
+In the route handler, you resolve the [Event Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/infrastructure-modules/event/index.html.md)'s service from the Medusa container and emit the `products.sync` event.
+
+### Create UI Route to Trigger Sync
+
+Finally, you'll add a new page to the Medusa Admin dashboard that displays a button to trigger the sync. To add a page, you need to create a UI route.
+
+A [UI route](https://docs.medusajs.com/docs/learn/fundamentals/admin/ui-routes/index.html.md) is a React component that specifies the content to be shown in a new page of the Medusa Admin dashboard. You'll create a UI route to display a button that triggers product syncing to Contentful when clicked.
+
+Refer to the [UI Routes](https://docs.medusajs.com/docs/learn/fundamentals/admin/ui-routes/index.html.md) documentation for more information.
+
+#### Configure JS SDK
+
+Before creating the UI route, you'll configure Medusa's [JS SDK](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/js-sdk/index.html.md) so that you can use it to send requests to the Medusa server.
+
+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
+
+UI routes are created in a `page.tsx` file under a sub-directory of `src/admin/routes` directory. The file's path relative to `src/admin/routes` determines its path in the dashboard.
+
+So, create the file `src/admin/routes/contentful/page.tsx` with the following content:
+
+```tsx title="src/admin/routes/contentful/page.tsx" highlights={contentfulPageHighlights}
+import { defineRouteConfig } from "@medusajs/admin-sdk"
+import { Container, Heading, Button } from "@medusajs/ui"
+import { useMutation } from "@tanstack/react-query"
+import { sdk } from "../../lib/sdk"
+import { toast } from "@medusajs/ui"
+
+const ContentfulSettingsPage = () => {
+  const { mutate, isPending } = useMutation({
+    mutationFn: () => 
+      sdk.client.fetch("/admin/contentful/sync", {
+        method: "POST",
+      }),
+    onSuccess: () => {
+      toast.success("Sync to Contentful triggered successfully")
+    },
+  })
+
+  return (
+    <Container className="p-6">
+      <div className="flex flex-col gap-y-4">
+        <div>
+          <Heading level="h1">Contentful Settings</Heading>
+        </div>
+        <div>
+          <Button 
+            variant="primary"
+            onClick={() => mutate()}
+            isLoading={isPending}
+          >
+            Sync to Contentful
+          </Button>
+        </div>
+      </div>
+    </Container>
+  )
+}
+
+export const config = defineRouteConfig({
+  label: "Contentful",
+})
+
+export default ContentfulSettingsPage
+```
+
+A UI route's file must export:
+
+1. A React component that defines the content of the page.
+2. A configuration object that specifies the route's label in the dashboard. This label is used to show a sidebar item for the new route.
+
+In the React component, you use `useMutation` hook from `@tanstack/react-query` to create a mutation that sends a `POST` request to the API route you created earlier. In the mutation function, you use the JS SDK to send the request.
+
+Then, in the return statement, you display a button that triggers the mutation when clicked, which sends a request to the API route you created earlier.
+
+### Test the Sync
+
+To test out the sync, start the Medusa application:
+
+```bash npm2yarn
+npm run dev
+```
+
+Then, open the Medusa Admin dashboard and login. In the sidebar, you'll find a new "Contentful" item. If you click on it, you'll see the page you created with the button to trigger the sync.
+
+![The Contentful page in the Medusa Admin dashboard with a button to trigger the sync](https://res.cloudinary.com/dza7lstvk/image/upload/v1744718825/Medusa%20Resources/Screenshot_2025-04-15_at_3.06.53_PM_va8e20.png)
+
+If you click on the button, you'll see the following message in the terminal:
+
+```bash
+info: Synced 4 products to Contentful
+```
+
+Assuming you have `4` products in Medusa, the message indicates that the sync was successful.
+
+You can also see the products in the Contentful dashboard.
+
+![The Contentful dashboard showing the synced products](https://res.cloudinary.com/dza7lstvk/image/upload/v1744718896/Medusa%20Resources/Screenshot_2025-04-15_at_3.08.02_PM_qexr0x.png)
+
+***
+
+## Step 6: Retrieve Locales API Route
+
+In the next steps, you'll implement customizations that are useful for storefronts. A storefront should show the customer a list of available locales and allow them to select from them.
+
+In this step, you will:
+
+1. Add the logic to retrieve locales from Contentful in the Contentful Module's service.
+2. Create an API route that exposes the locales to the storefront.
+3. Customize the Next.js Starter Storefront to show the locales to customers.
+
+### Retrieve Locales from Contentful Method
+
+You'll start by adding two methods to the Contentful Module's service that are useful to retrieve locales from Contentful.
+
+The first method retrieves all locales from Contentful. Add it to the service at `src/modules/contentful/service.ts`:
+
+```ts title="src/modules/contentful/service.ts"
+export default class ContentfulModuleService {
+  // ...
+  async getLocales() {
+    return await this.managementClient.locale.getMany({})
+  }
+}
+```
+
+You use the `locale.getMany` method of the Contentful Management API client to retrieve all locales.
+
+The second method returns the code of the default locale:
+
+```ts title="src/modules/contentful/service.ts"
+export default class ContentfulModuleService {
+  // ...
+  async getDefaultLocaleCode() {
+    return this.options.default_locale
+  }
+}
+```
+
+You return the default locale using the `default_locale` option you set in the module's options.
+
+### Create API Route to Retrieve Locales
+
+Next, you'll create an API route that exposes the locales to the storefront.
+
+To create the API route, create the file `src/api/store/locales/route.ts` with the following content:
+
+```ts title="src/api/store/locales/route.ts" highlights={getLocalesRouteHighlights}
+import {
+  MedusaRequest,
+  MedusaResponse,
+} from "@medusajs/framework/http"
+import { CONTENTFUL_MODULE } from "../../../modules/contentful"
+import ContentfulModuleService from "../../../modules/contentful/service"
+
+export const GET = async (
+  req: MedusaRequest,
+  res: MedusaResponse
+) => {
+  const contentfulModuleService: ContentfulModuleService = req.scope.resolve(
+    CONTENTFUL_MODULE
+  )
+
+  const locales = await contentfulModuleService.getLocales()
+  const defaultLocaleCode = await contentfulModuleService.getDefaultLocaleCode()
+
+  const formattedLocales = locales.items.map((locale) => {
+    return {
+      name: locale.name,
+      code: locale.code,
+      is_default: locale.code === defaultLocaleCode,
+    }
+  })
+
+  res.json({
+    locales: formattedLocales,
+  })
+}
+```
+
+Since you export a `GET` route handler function, you expose a `GET` route at `/store/locales`.
+
+In the route handler, you resolve the Contentful Module's service from the Medusa container to retrieve the locales and the default locale code.
+
+Then, you format the locales to include their name, code, and whether they are the default locale.
+
+Finally, you return the formatted locales in the JSON response.
+
+### Customize Storefront to Show Locales
+
+In the first step of this tutorial, you installed the [Next.js Starter Storefront](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/nextjs-starter/index.html.md) along with the Medusa application. This storefront provides ecommerce features like a product catalog, a cart, and a checkout.
+
+In this section, you'll customize the storefront to show the locales to customers and allow them to select from them. The selected locale will be stored in the browser's cookies, allowing you to use it later when retrieving a product's localized data.
+
+The Next.js Starter Storefront was installed in a separate directory from Medusa. The directory's name is `{your-project}-storefront`.
+
+So, if your Medusa application's directory is `medusa-contentful`, you can find the storefront by going back to the parent directory and changing to the `medusa-contentful-storefront` directory:
+
+```bash
+cd ../medusa-contentful-storefront # change based on your project name
+```
+
+#### Add Cookie Functions
+
+You'll start by adding two functions that retrieve and set the locale in the browser's cookies.
+
+In `src/lib/data/cookies.ts` add the following functions:
+
+```ts title="src/lib/data/cookies.ts" highlights={getLocaleHighlights} badgeLabel="Storefront" badgeColor="blue"
+export const getLocale = async () => {
+  const cookies = await nextCookies()
+  return cookies.get("_medusa_locale")?.value
+}
+
+export const setLocale = async (locale: string) => {
+  const cookies = await nextCookies()
+  cookies.set("_medusa_locale", locale, {
+    maxAge: 60 * 60 * 24 * 7,
+  })
+}
+```
+
+The `getLocale` function retrieves the locale from the browser's cookies, and the `setLocale` function sets the locale in the browser's cookies.
+
+#### Manage Locales Functions
+
+Next, you'll add server actions to retrieve the locales and set the selected locale.
+
+Create the file `src/lib/data/locale.ts` with the following content:
+
+```ts title="src/lib/data/locale.ts" highlights={getLocalesHighlights} badgeLabel="Storefront" badgeColor="blue"
+"use server"
+
+import { sdk } from "@lib/config"
+import type { Document } from "@contentful/rich-text-types"
+import { getLocale, setLocale } from "./cookies"
+
+export type Locale = {
+  name: string
+  code: string
+  is_default: boolean
+}
+
+export async function getLocales() {
+  return await sdk.client.fetch<{
+    locales: Locale[]
+  }>("/store/locales")
+}
+
+export async function getSelectedLocale() {
+  let localeCode = await getLocale()
+  if (!localeCode) {
+    const locales = await getLocales()
+    localeCode = locales.locales.find((l) => l.is_default)?.code
+  }
+  return localeCode
+}
+
+export async function setSelectedLocale(locale: string) {
+  await setLocale(locale)
+}
+```
+
+You add the following functions:
+
+1. `getLocales`: Retrieves the locales from the Medusa server using the API route you created earlier.
+2. `getSelectedLocale`: Retrieves the selected locale from the browser's cookies, or the default locale if no locale is selected.
+3. `setSelectedLocale`: Sets the selected locale in the browser's cookies.
+
+You'll use these functions as you add the UI to show the locales next.
+
+#### Show Locales in the Storefront
+
+You'll now add the UI to show the locales to customers and allow them to select from them.
+
+Create the file `src/modules/layout/components/locale-select/index.tsx` with the following content:
+
+```tsx title="src/modules/layout/components/locale-select/index.tsx" highlights={localeSelectHighlights} badgeLabel="Storefront" badgeColor="blue"
+"use client"
+
+import { useState, useEffect, Fragment } from "react"
+import { getLocales, Locale, getSelectedLocale, setSelectedLocale } from "../../../../lib/data/locale"
+import { Listbox, ListboxButton, ListboxOption, ListboxOptions, Transition } from "@headlessui/react"
+import { ArrowRightMini } from "@medusajs/icons"
+import { clx } from "@medusajs/ui"
+
+const LocaleSelect = () => {
+  const [locales, setLocales] = useState<Locale[]>([])
+  const [locale, setLocale] = useState<Locale | undefined>()
+  const [open, setOpen] = useState(false)
+
+  useEffect(() => {
+    getLocales()
+      .then(({ locales }) => {
+        setLocales(locales)
+      })
+  }, [])
+
+  useEffect(() => {
+    if (!locales.length || locale) {
+      return
+    }
+
+    getSelectedLocale().then((locale) => {
+      const localeDetails = locales.find((l) => l.code === locale) 
+      setLocale(localeDetails)
+    })
+  }, [locales])
+
+  useEffect(() => {
+    if (locale) {
+      setSelectedLocale(locale.code)
+    }
+  }, [locale])
+
+  const handleChange = (locale: Locale) => {
+    setLocale(locale)
+    setOpen(false)
+  }
+
+  // TODO add return statement
+}
+
+export default LocaleSelect
+```
+
+You create a `LocaleSelect` component with the following state variables:
+
+1. `locales`: The list of locales retrieved from the Medusa server.
+2. `locale`: The selected locale.
+3. `open`: A boolean indicating whether the dropdown is open.
+
+Then, you use three `useEffect` hooks:
+
+1. The first `useEffect` hook retrieves the locales using the `getLocales` function and sets them in the `locales` state variable.
+2. The second `useEffect` hook is triggered when the `locales` state variable changes. It retrieves the selected locale using the `getSelectedLocale` function and sets the `locale` state variable.
+3. The third `useEffect` hook is triggered when the `locale` state variable changes. It sets the selected locale in the browser's cookies using the `setSelectedLocale` function.
+
+You also create a `handleChange` function that sets the selected locale and closes the dropdown. You'll execute this function when the customer selects a locale from the dropdown.
+
+Finally, you'll add a return statement that shows the locale dropdown. Replace the `TODO` with the following:
+
+```tsx title="src/modules/layout/components/locale-select/index.tsx" badgeLabel="Storefront" badgeColor="blue"
+return (
+  <div
+    className="flex justify-between"
+    onMouseEnter={() => setOpen(true)}
+    onMouseLeave={() => setOpen(false)}
+  >
+    <div>
+      <Listbox as="span" onChange={handleChange} defaultValue={locale}>
+        <ListboxButton className="py-1 w-full">
+          <div className="txt-compact-small flex items-start gap-x-2">
+            <span>Language:</span>
+            {locale && (
+              <span className="txt-compact-small flex items-center gap-x-2">
+                {locale.name}
+              </span>
+            )}
+          </div>
+        </ListboxButton>
+        <div className="flex relative w-full min-w-[320px]">
+          <Transition
+            show={open}
+            as={Fragment}
+            leave="transition ease-in duration-150"
+            leaveFrom="opacity-100"
+            leaveTo="opacity-0"
+          >
+            <ListboxOptions
+              className="absolute -bottom-[calc(100%-36px)] left-0 xsmall:left-auto xsmall:right-0 max-h-[442px] overflow-y-scroll z-[900] bg-white drop-shadow-md text-small-regular uppercase text-black no-scrollbar rounded-rounded w-full"
+              static
+            >
+              {locales?.map((l, index) => {
+                return (
+                  <ListboxOption
+                    key={index}
+                    value={l}
+                    className="py-2 hover:bg-gray-200 px-3 cursor-pointer flex items-center gap-x-2"
+                  >
+                    {l.name}
+                  </ListboxOption>
+                )
+              })}
+            </ListboxOptions>
+          </Transition>
+        </div>
+      </Listbox>
+    </div>
+    <ArrowRightMini
+      className={clx(
+        "transition-transform duration-150",
+        open ? "-rotate-90" : ""
+      )}
+    />
+  </div>
+)
+```
+
+You show the selected locale. Then, when the customer hovers over the locale, the dropdown is shown to select a different locale.
+
+When the customer selects a locale, you execute the `handleChange` function, which sets the selected locale and closes the dropdown.
+
+#### Add Locale Select to the Side Menu
+
+The last step is to show the locale selector in the side menu after the country selector.
+
+In `src/modules/layout/components/side-menu/index.tsx`, add the following import:
+
+```tsx title="src/modules/layout/components/side-menu/index.tsx" badgeLabel="Storefront" badgeColor="blue"
+import LocaleSelect from "../locale-select"
+```
+
+Then, add the `LocaleSelect` component in the return statement of the `SideMenu` component, after the `div` wrapping the country selector:
+
+```tsx title="src/modules/layout/components/side-menu/index.tsx" badgeLabel="Storefront" badgeColor="blue"
+<LocaleSelect />
+```
+
+The locale selector will now show in the side menu after the country selector.
+
+### Test out the Locale Selector
+
+To test out all the changes made in this step, start the Medusa application by running the following command in the Medusa application's directory:
+
+```bash npm2yarn
+npm run dev
+```
+
+Then, start the Next.js Starter Storefront by running the following command in the storefront's directory:
+
+```bash npm2yarn
+npm run dev
+```
+
+The storefront will run at `http://localhost:8000`. Open it in your browser, then click on "Menu" at the top right. You'll see at the bottom of the side menu the locale selector.
+
+![The locale selector in the side menu](https://res.cloudinary.com/dza7lstvk/image/upload/v1744720332/Medusa%20Resources/Screenshot_2025-04-15_at_3.31.51_PM_vdqou5.png)
+
+You can try selecting a different locale. The selected locale will be stored, but products will still be shown in the default locale. You'll implement the locale-based product retrieval in the next step.
+
+***
+
+## Step 7: Retrieve Product Details for Locale
+
+The next feature you'll implement is retrieving and displaying product details for a selected locale.
+
+You'll implement this feature by:
+
+1. Linking Medusa's product to Contentful's product.
+2. Adding the method to retrieve product details for a selected locale from Contentful.
+3. Adding a new route to retrieve the product details for a selected locale.
+4. Customizing the storefront to show the product details for the selected locale.
+
+### Link Medusa's Product to Contentful's Product
+
+Medusa facilitates retrieving data across systems using [module links](https://docs.medusajs.com/docs/learn/fundamentals/module-links/index.html.md). A module link forms an association between data models of two modules while maintaining module isolation.
+
+Not only do module links support Medusa data models, but they also support virtual data models that are not persisted in Medusa's database. In that case, you create a [read-only module link](https://docs.medusajs.com/docs/learn/fundamentals/module-links/read-only/index.html.md) that allows you to retrieve data across systems.
+
+In this section, you'll define a read-only module link between Medusa's product and Contentful's product, allowing you to later retrieve a product's entry in Contentful within a single query.
+
+Learn more about read-only module links in the [Read-Only Module Links](https://docs.medusajs.com/docs/learn/fundamentals/module-links/read-only/index.html.md) documentation.
+
+Module links are defined in a TypeScript or JavaScript file under the `src/links` directory. So, create the file `src/links/product-contentful.ts` with the following content:
+
+```ts title="src/links/product-contentful.ts" highlights={productContentfulLinkHighlights}
+import { defineLink } from "@medusajs/framework/utils"
+import ProductModule from "@medusajs/medusa/product"
+import { CONTENTFUL_MODULE } from "../modules/contentful"
+
+export default defineLink(
+  {
+    linkable: ProductModule.linkable.product,
+    field: "id",
+  },
+  {
+    linkable: {
+      serviceName: CONTENTFUL_MODULE,
+      alias: "contentful_product",
+      primaryKey: "product_id",
+    },
+  },
+  {
+    readOnly: true,
+  }
+)
+```
+
+You define a module link using `defineLink` from the Modules SDK. It accepts three parameters:
+
+1. An object with the linkable configuration of the data model in Medusa, and the field that will be passed as a filter to the Contentful Module's service.
+2. An object with the linkable configuration of the virtual data model in Contentful. This object must have the following properties:
+   - `serviceName`: The name of the service, which is the Contentful Module's name. Medusa uses this name to resolve the module's service from the Medusa container.
+   - `alias`: The alias to use when querying the linked records. You'll see how that works in a bit.
+   - `primaryKey`: The field in Contentful's virtual data model that holds the ID of a product.
+3. An object with the `readOnly` property set to `true`.
+
+You'll see how the module link works in the upcoming steps.
+
+### List Contentful Products Method
+
+Next, you'll add a method that lists Contentful products for a given locale.
+
+Add the following method to the Contentful Module's service at `src/modules/contentful/service.ts`:
+
+```ts title="src/modules/contentful/service.ts" highlights={listContentfulProductsMethodHighlights}
+export default class ContentfulModuleService {
+  // ...
+  async list(
+    filter: {
+      id: string | string[]
+      context?: {
+        locale: string
+      }
+    }
+  ) {
+    const contentfulProducts = await this.deliveryClient.getEntries({
+      limit: 15,
+      content_type: "product",
+      "fields.medusaId": filter.id,
+      locale: filter.context?.locale,
+      include: 3,
+    })
+
+    return contentfulProducts.items.map((product) => {
+      // remove links
+      const { productVariants: _, productOptions: __, ...productFields } = product.fields
+      return {
+        ...productFields,
+        product_id: product.fields.medusaId,
+        variants: product.fields.productVariants.map((variant) => {
+          // remove circular reference
+          const { product: _, productOptionValues: __, ...variantFields } = variant.fields
+          return {
+            ...variantFields,
+            product_variant_id: variant.fields.medusaId,
+            options: variant.fields.productOptionValues.map((option) => {
+              // remove circular reference
+              const { productOption: _, ...optionFields } = option.fields
+              return {
+                ...optionFields,
+                product_option_id: option.fields.medusaId,
+              }
+            }),
+          }
+        }),
+        options: product.fields.productOptions.map((option) => {
+          // remove circular reference
+          const { product: _, ...optionFields } = option.fields
+          return {
+            ...optionFields,
+            product_option_id: option.fields.medusaId,
+            values: option.fields.values.map((value) => {
+              // remove circular reference
+              const { productOptionValue: _, ...valueFields } = value.fields
+              return {
+                ...valueFields,
+                product_option_value_id: value.fields.medusaId,
+              }
+            }),
+          }
+        }),
+      }
+    })
+  }
+}
+```
+
+You add a `list` method that accepts an object with the following properties:
+
+1. `id`: The ID of the product(s) in Medusa to retrieve their entries in Contentful.
+2. `context`: An object with the `locale` property that holds the locale code to retrieve the product's entry in Contentful for that locale.
+
+In the method, you use the Delivery API client's `getEntries` method to retrieve the products. You pass the following parameters:
+
+- `limit`: The maximum number of products to retrieve.
+- `content_type`: The content type of the entries to retrieve, which is `product`.
+- `fields.medusaId`: Filter the products by their `medusaId` field, which holds the ID of the product in Medusa.
+- `locale`: The locale code to retrieve the fields of the product in that locale.
+- `include`: The depth of the included nested entries. This ensures that you can retrieve the product's variants and options, and their values.
+
+Then, you format the retrieved products to:
+
+- Pass the product's ID in the `product_id` property. This is essential to map a product in Medusa to its entry in Contentful.
+- Remove the circular references in the product's variants, options, and values to avoid infinite loops.
+
+To paginate the retrieved products, implemet a `listAndCount` method as explained in the [Query Context](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query-context#using-pagination-with-query/index.html.md) documentation.
+
+### Retrieve Product Details for Locale API Route
+
+You'll now create the API route that returns a product's details for a given locale.
+
+You can create an API route that accepts path parameters by creating a directory within the route file's path whose name is of the format `[param]`.
+
+So, create the file `src/api/store/products/[id]/[locale]/route.ts` with the following content:
+
+```ts title="src/api/store/products/[id]/[locale]/route.ts" highlights={getProductLocaleDetailsRouteHighlights}
+import {
+  MedusaRequest,
+  MedusaResponse,
+} from "@medusajs/framework/http"
+import { QueryContext } from "@medusajs/framework/utils"
+
+export const GET = async (
+  req: MedusaRequest,
+  res: MedusaResponse
+) => {
+  const { locale, id } = req.params
+  
+  const query = req.scope.resolve("query")
+
+  const { data } = await query.graph({
+    entity: "product",
+    fields: [
+      "id",
+      "contentful_product.*",
+    ],
+    filters: {
+      id,
+    },
+    context: {
+      contentful_product: QueryContext({
+        locale,
+      }),
+    },
+  })
+
+  res.json({
+    product: data[0],
+  })  
+}
+```
+
+Since you export a `GET` route handler function, you expose a `GET` route at `/store/products/[id]/[locale]`. The route accepts two path parameters: the product's ID and the locale code.
+
+In the route handler, you retrieve the `locale` and `id` path parameters from the request. Then, you resolve [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md) from the Medusa container.
+
+Next, you use Query to retrieve the localized details of the specified product. To do that, you pass an object with the following properties:
+
+- `entity`: The entity to retrieve, which is `product`.
+- `fields`: The fields to retrieve. Notice that you include the `contentful_product.*` field, which is available through the module link you created earlier.
+- `filters`: The filter to apply on the retrieved products. You apply the product's ID as a filter.
+- `context`: An additional context to be passed to the methods retrieving the data. To pass a context, you use [Query Context](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query-context/index.html.md).
+
+By specifying `contentful_product.*` in the `fields` property, Medusa will retrieve the product's entry from Contentful using the `list` method you added to the Contentful Module's service.
+
+Medusa passes the filters and context to the `list` method, and attaches the returned data to the Medusa product if its `product_id` matches the product's ID.
+
+Finally, you return the product's details in the JSON response.
+
+You can now use this route to retrieve a product's details for a given locale.
+
+### Show Localized Product Details in Storefront
+
+Now that you expose the localized product details, you can customize the storefront to show them.
+
+#### Install Contentful Rich Text Package
+
+When you retrieve the entries from Contentful, rich-text fields are returned as an object that requires special rendering. So, Contentful provides a package to render rich-text fields.
+
+Install the package by running the following command:
+
+```bash npm2yarn
+npm install @contentful/@contentful/rich-text-types
+```
+
+You'll use this package to render the product's description.
+
+#### Retrieve Localized Product Details Function
+
+To retrieve a product's details for a given locale, you'll add a function that sends a request to the API route you created.
+
+First, add the following import at the top of `src/lib/data/locale.ts`:
+
+```ts title="src/lib/data/locale.ts" badgeLabel="Storefront" badgeColor="blue"
+import type { Document } from "@contentful/rich-text-types"
+```
+
+Then, add the following type and function at the end of the file:
+
+```ts title="src/lib/data/locale.ts" badgeLabel="Storefront" badgeColor="blue"
+export type ProductLocaleDetails = {
+  id: string
+  contentful_product: {
+    product_id: string
+    title: string
+    handle: string
+    description: Document
+    subtitle?: string
+    variants: {
+      title: string
+      product_variant_id: string
+      options: {
+        value: string
+        product_option_id: string
+      }[]
+    }[]
+    options: {
+      title: string
+      product_option_id: string
+      values: {
+        title: string
+        product_option_value_id: string
+      }[]
+    }[]
+  }
+}
+
+export async function getProductLocaleDetails(
+  productId: string
+) {
+  const localeCode = await getSelectedLocale()
+
+  return await sdk.client.fetch<{
+    product: ProductLocaleDetails
+  }>(`/store/products/${productId}/${localeCode}`)
+}
+```
+
+You define a `ProductLocaleDetails` type that describes the structure of a localized product's details.
+
+You also define a `getProductLocaleDetails` function that sends a request to the API route you created and returns the localized product's details.
+
+#### Show Localized Product Title in Products Listing
+
+Next, you'll customize existing components to show the localized product details.
+
+The component defined in `src/modules/products/components/product-preview/index.tsx` shows the product's details in the products listing page. You need to retrieve the localized product details and show the product's title in the selected locale.
+
+In `src/modules/products/components/product-preview/index.tsx`, add the following import:
+
+```tsx title="src/modules/products/components/product-preview/index.tsx" badgeLabel="Storefront" badgeColor="blue"
+import { getProductLocaleDetails } from "@lib/data/locale"
+```
+
+Then, in the `ProductPreview` component in the same file, add the following before the `return` statement:
+
+```tsx title="src/modules/products/components/product-preview/index.tsx" badgeLabel="Storefront" badgeColor="blue"
+const productLocaleDetails = await getProductLocaleDetails(product.id!)
+```
+
+This will retrieve the localized product details for the selected locale.
+
+Finally, to show the localized product title, find in the `ProductPreview` component's `return` statement the following line:
+
+```tsx title="src/modules/products/components/product-preview/index.tsx" badgeLabel="Storefront" badgeColor="blue"
+{product.title}
+```
+
+And replace it with the following:
+
+```tsx title="src/modules/products/components/product-preview/index.tsx" badgeLabel="Storefront" badgeColor="blue"
+{productLocaleDetails.product.contentful_product?.title || product.title}
+```
+
+You'll test it out after the next step.
+
+#### Show Localized Product Details in Product Page
+
+Next, you'll customize the product page to show the localized product details.
+
+The product's details page is defined in `src/app/[countryCode]/(main)/products/[handle]/page.tsx`. So, add the following import at the top of the file:
+
+```tsx title="src/app/[countryCode]/(main)/products/[handle]/page.tsx" badgeLabel="Storefront" badgeColor="blue"
+import { getProductLocaleDetails } from "@lib/data/locale"
+```
+
+Then, in the `ProductPage` component in the same file, add the following before the `return` statement:
+
+```tsx title="src/app/[countryCode]/(main)/products/[handle]/page.tsx" badgeLabel="Storefront" badgeColor="blue"
+const productLocaleDetails = await getProductLocaleDetails(pricedProduct.id!)
+```
+
+This will retrieve the localized product details for the selected locale.
+
+Finally, in the `ProductPage` component in the same file, pass the following prop to `ProductTemplate`:
+
+```tsx title="src/app/[countryCode]/(main)/products/[handle]/page.tsx" badgeLabel="Storefront" badgeColor="blue"
+return (
+  <ProductTemplate
+    // ...
+    productLocaleDetails={productLocaleDetails.product}
+  />
+)
+```
+
+Next, you'll customize the `ProductTemplate` component to accept and use this prop.
+
+In `src/modules/products/templates/index.tsx`, add the following import:
+
+```tsx title="src/modules/products/templates/index.tsx" badgeLabel="Storefront" badgeColor="blue"
+import { ProductLocaleDetails } from "@lib/data/locale"
+```
+
+Then, update the `ProductTemplateProps` type to include the `productLocaleDetails` prop:
+
+```tsx title="src/modules/products/templates/index.tsx" badgeLabel="Storefront" badgeColor="blue"
+export type ProductTemplateProps = {
+  // ...
+  productLocaleDetails: ProductLocaleDetails
+}
+```
+
+Next, update the `ProductTemplate` component to destructure the `productLocaleDetails` prop:
+
+```tsx title="src/modules/products/templates/index.tsx" badgeLabel="Storefront" badgeColor="blue"
+const ProductTemplate: React.FC<ProductTemplateProps> = ({
+  // ...
+  productLocaleDetails,
+}) => {
+  // ...
+}
+```
+
+Finally, pass the `productLocaleDetails` prop to the `ProductInfo` component in the `return` statement:
+
+```tsx title="src/modules/products/templates/index.tsx" badgeLabel="Storefront" badgeColor="blue"
+<ProductInfo
+  // ...
+  productLocaleDetails={productLocaleDetails}
+/>
+```
+
+The `ProductInfo` component shows the product's details. So, you need to update it to accept and use the `productLocaleDetails` prop.
+
+In `src/modules/products/templates/product-info/index.tsx`, add the following imports:
+
+```tsx title="src/modules/products/templates/product-info/index.tsx" badgeLabel="Storefront" badgeColor="blue"
+import { ProductLocaleDetails } from "@lib/data/locale"
+import { documentToHtmlString } from "@contentful/rich-text-html-renderer"
+```
+
+Then, update the `ProductInfoProps` type to include the `productLocaleDetails` prop:
+
+```tsx title="src/modules/products/templates/product-info/index.tsx" badgeLabel="Storefront" badgeColor="blue"
+export type ProductInfoProps = {
+  // ...
+  productLocaleDetails: ProductLocaleDetails
+}
+```
+
+Next, update the `ProductInfo` component to destructure the `productLocaleDetails` prop:
+
+```tsx title="src/modules/products/templates/product-info/index.tsx" badgeLabel="Storefront" badgeColor="blue"
+const ProductInfo = ({ product, productLocaleDetails }: ProductInfoProps) => {
+  // ...
+}
+```
+
+Then, find the following line in the `return` statement:
+
+```tsx title="src/modules/products/templates/product-info/index.tsx" badgeLabel="Storefront" badgeColor="blue"
+{product.title}
+```
+
+And replace it with the following:
+
+```tsx title="src/modules/products/templates/product-info/index.tsx" badgeLabel="Storefront" badgeColor="blue"
+{productLocaleDetails.contentful_product?.title || product.title}
+```
+
+Also, find the following line:
+
+```tsx title="src/modules/products/templates/product-info/index.tsx" badgeLabel="Storefront" badgeColor="blue"
+{product.description}
+```
+
+And replace it with the following:
+
+```tsx title="src/modules/products/templates/product-info/index.tsx" badgeLabel="Storefront" badgeColor="blue"
+{productLocaleDetails.contentful_product?.description ? 
+  <div dangerouslySetInnerHTML={{ __html: documentToHtmlString(productLocaleDetails.contentful_product?.description) }} /> : 
+  product.description
+}
+```
+
+You use the `documentToHtmlString` function to render the rich-text field. The function returns an HTML string that you can use to render the description.
+
+### Test out the Localized Product Details
+
+You can now test out all the changes made in this step.
+
+To do that, start the Medusa application by running the following command in the Medusa application's directory:
+
+```bash npm2yarn
+npm run dev
+```
+
+Then, start the Next.js Starter Storefront by running the following command in the storefront's directory:
+
+```bash npm2yarn
+npm run dev
+```
+
+Open the storefront at `http://localhost:8000` and select a different locale.
+
+Then, open the products listing page by clicking on Menu -> Store. You'll see the product titles in the selected locale.
+
+![The product titles are shown in the selected locale](https://res.cloudinary.com/dza7lstvk/image/upload/v1744723796/Medusa%20Resources/Screenshot_2025-04-15_at_4.29.39_PM_izxt6j.png)
+
+Then, if you click on a product, you'll see the product's title and description in the selected locale.
+
+![The product's title and description are shown in the selected locale](https://res.cloudinary.com/dza7lstvk/image/upload/v1744723844/Medusa%20Resources/Screenshot_2025-04-15_at_4.30.31_PM_pt6ngz.png)
+
+***
+
+## Step 8: Sync Changes from Contentful to Medusa
+
+The last feature you'll implement is syncing changes from Contentful to Medusa.
+
+Contentful's webhooks allow you to listen to changes in your Contentful entries. You can then set up a webhook listener API route in Medusa that updates the product's data.
+
+In this step, you'll set up a webhook listener that updates Medusa's product data when a Contentful entry is published.
+
+### Prerequisites: Public Server
+
+Webhooks can only trigger deployed listeners. So, you must either [deploy your Medusa application](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/deployment/index.html.md), or use tools like [ngrok](https://ngrok.com/) to publicly expose your local application.
+
+### Set Up Webhooks in Contentful
+
+Before setting up the webhook listener, you need to set up a webhook in Contentful. To do that, on the Contentful dashboard:
+
+1. Click on the cog icon at the top right, then choose "Webhooks" from the dropdown.
+
+![The cog icon is at the top right next to the avatar icon. When you click on it, you see a dropdown with the "Webhooks" option](https://res.cloudinary.com/dza7lstvk/image/upload/v1744733023/Medusa%20Resources/Screenshot_2025-04-15_at_7.03.21_PM_ji7ohw.png)
+
+2. On the Webhooks page, click on the "Add Webhook" button.
+3. In the webhook form:
+   - In the Name fields, enter a name, such as "Medusa".
+   - In the URL field, enter `{your_app}/hooks/contentful`, where `{your_app}` is the public URL of your Medusa application. You'll create the `/hooks/contentful` API route in a bit.
+   - In the Triggers section, select the "Published" trigger for "Entry".
+
+![The webhook form with the URL and triggers highlighted](https://res.cloudinary.com/dza7lstvk/image/upload/v1744733332/Medusa%20Resources/Screenshot_2025-04-15_at_7.08.24_PM_coq6oo.png)
+
+- Scroll down to the "Headers" section, and choose "application/json" for the "Content type" field.
+
+![The webhook form](https://res.cloudinary.com/dza7lstvk/image/upload/v1744733411/Medusa%20Resources/Screenshot_2025-04-15_at_7.09.53_PM_kvlppv.png)
+
+4. Once you're done, click the Save button.
+
+### Setup Webhook Secret in Contentful
+
+You also need to add a webhook secret in Contentful. To do that, on the Contentful dashboard:
+
+1. Click on the cog icon at the top right, then choose "Webhooks" from the dropdown.
+2. On the Webhooks page, click on the "Settings" tab.
+3. Click on the "Enable request verification" button.
+
+![The "Enable request verification" button in the "Settings" tab](https://res.cloudinary.com/dza7lstvk/image/upload/v1744786362/Medusa%20Resources/Screenshot_2025-04-16_at_9.51.39_AM_byv3tt.png)
+
+4. Copy the secret that shows up. You can update it later but you can't see the same secret again.
+
+You'll use the secret to verify the webhook request in Medusa next.
+
+### Update Contentful Module Options
+
+First, add the webhook secret as an environment variable in the Medusa application's `.env` file:
+
+```plain
+CONTENTFUL_WEBHOOK_SECRET=aEl7...
+```
+
+Next, add the webhook secret to the Contentful Module options in the Medusa application's `medusa-config.ts` file:
+
+```ts title="medusa-config.ts"
+module.exports = defineConfig({
+  // ...
+  modules: [
+    {
+      resolve: "./src/modules/contentful",
+      options: {
+        // ...
+        webhook_secret: process.env.CONTENTFUL_WEBHOOK_SECRET,
+      },
+    },
+  ],
+})
+```
+
+Finally, update the `ModuleOptions` type in `src/modules/contentful/loader/create-content-models.ts` to include the `webhook_secret` option:
+
+```ts title="src/modules/contentful/loader/create-content-models.ts"
+export type ModuleOptions = {
+  // ...
+  webhook_secret: string
+}
+```
+
+### Add Verify Request Method
+
+Next, you'll add a method to the Contentful Module's service that verifies a webhook request.
+
+To verify the request, you'll need the `@contentful/node-apps-toolkit` package that provides utility functions for Node.js applications.
+
+So, run the following command to install it:
+
+```bash npm2yarn
+npm install @contentful/node-apps-toolkit
+```
+
+Then, add the following method to the Contentful Module's service in `src/modules/contentful/service.ts`:
+
+```ts title="src/modules/contentful/service.ts"
+// other imports...
+import { 
+  CanonicalRequest, 
+  verifyRequest,
+} from "@contentful/node-apps-toolkit"
+
+export default class ContentfulModuleService {
+  // ...
+  async verifyWebhook(request: CanonicalRequest) {
+    if (!this.options.webhook_secret) {
+      throw new MedusaError(
+        MedusaError.Types.INVALID_DATA, 
+        "Webhook secret is not set"
+      )
+    }
+    return verifyRequest(this.options.webhook_secret, request, 0)
+  }
+}
+```
+
+You add a `verifyWebhook` method that verifies a webhook request using the `verifyRequest` function.
+
+You pass to the `verifyRequest` function the webhook secret from the module's options with the request's details. You also disable time-to-live (TTL) check by passing `0` as the third argument.
+
+### Handle Contentful Webhook Workflow
+
+Before you add the webhook listener, the last piece you need is to add a workflow that handles the necessary updates based on the webhook event.
+
+The workflow will have the following steps:
+
+- [prepareUpdateDataStep](#prepareUpdateDataStep): Prepare the data for the update
+
+You only need to implement the first step, as Medusa provides the other workflows (running as steps) in the `@medusajs/medusa/core-flows` package.
+
+#### prepareUpdateDataStep
+
+The first step receives the webhook data payload and, based on the entry type, returns the data necessary for the update.
+
+To create the step, create the file `src/workflows/steps/prepare-update-data.ts` with the following content:
+
+```ts title="src/workflows/steps/prepare-update-data.ts" highlights={prepareUpdateDataStepHighlights}
+import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk"
+import { EntryProps } from "contentful-management"
+import ContentfulModuleService from "../../modules/contentful/service"
+import { CONTENTFUL_MODULE } from "../../modules/contentful"
+
+type StepInput = {
+  entry: EntryProps
+}
+
+export const prepareUpdateDataStep = createStep(
+  "prepare-update-data",
+  async ({ entry }: StepInput, { container }) => {
+    const contentfulModuleService: ContentfulModuleService = 
+      container.resolve(CONTENTFUL_MODULE)
+    
+    const defaultLocale = await contentfulModuleService.getDefaultLocaleCode()
+
+    let data: Record<string, unknown> = {}
+
+    switch (entry.sys.contentType.sys.id) {
+      case "product":
+        data = {
+          id: entry.fields.medusaId[defaultLocale!],
+          title: entry.fields.title[defaultLocale!],
+          subtitle: entry.fields.subtitle?.[defaultLocale!] || undefined,
+          handle: entry.fields.handle[defaultLocale!],
+        }
+        break
+      case "productVariant":
+        data = {
+          id: entry.fields.medusaId[defaultLocale!],
+          title: entry.fields.title[defaultLocale!],
+        }
+        break
+      case "productOption":
+        data = {
+          selector: {
+            id: entry.fields.medusaId[defaultLocale!],
+          },
+          update: {
+            title: entry.fields.title[defaultLocale!],
+          },
+        }
+        break
+    }
+
+    return new StepResponse(data)
+  }
+)
+```
+
+You define a `prepareUpdateDataStep` function that receives the webhook data payload as an input.
+
+In the step, you resolve the Contentful Module's service and use it to retrieve the default locale code. You need it to find the value to update the fields in Medusa.
+
+Next, you prepare the data to return based on the entry type:
+
+- `product`: The product's ID, title, subtitle, and handle.
+- `productVariant`: The product variant's ID and title.
+- `productOption`: The product option's ID and title.
+
+The data is prepared based on the expected input for the workflows that will be used to update the data.
+
+#### Create the Workflow
+
+You can now create the workflow that handles the webhook event.
+
+Create the file `src/workflows/handle-contentful-hook.ts` with the following content:
+
+```ts title="src/workflows/handle-contentful-hook.ts" highlights={handleContentfulHookWorkflowHighlights} collapsibleLines="1-14" expandButtonLabel="Show Imports"
+import { createWorkflow, when } from "@medusajs/framework/workflows-sdk"
+import { EntryProps } from "contentful-management"
+import { prepareUpdateDataStep } from "./steps/prepare-update-data"
+import { 
+  updateProductOptionsWorkflow, 
+  updateProductsWorkflow, 
+  updateProductVariantsWorkflow, 
+  UpdateProductOptionsWorkflowInput,
+} from "@medusajs/medusa/core-flows"
+import { 
+  UpsertProductDTO, 
+  UpsertProductVariantDTO,
+} from "@medusajs/framework/types"
+
+export type WorkflowInput = {
+  entry: EntryProps
+}
+
+export const handleContentfulHookWorkflow = createWorkflow(
+  { name: "handle-contentful-hook-workflow" },
+  (input: WorkflowInput) => {
+    const prepareUpdateData = prepareUpdateDataStep({
+      entry: input.entry,
+    })
+
+    when(input, (input) => input.entry.sys.contentType.sys.id === "product")
+      .then(() => {
+        updateProductsWorkflow.runAsStep({
+          input: {
+            products: [prepareUpdateData as UpsertProductDTO],
+          },
+        })
+      })
+
+    when(input, (input) => 
+      input.entry.sys.contentType.sys.id === "productVariant"
+    )
+    .then(() => {
+      updateProductVariantsWorkflow.runAsStep({
+        input: {
+            product_variants: [prepareUpdateData as UpsertProductVariantDTO],
+          },
+        })
+      })
+
+    when(input, (input) => 
+      input.entry.sys.contentType.sys.id === "productOption"
+    )
+    .then(() => {
+      updateProductOptionsWorkflow.runAsStep({
+        input: prepareUpdateData as unknown as UpdateProductOptionsWorkflowInput,
+      })
+    })
+  }
+)
+```
+
+You define a `handleContentfulHookWorkflow` function that receives the webhook data payload as an input.
+
+In the workflow, you:
+
+- Prepare the data for the update using the `prepareUpdateDataStep` step.
+- Use a [when](https://docs.medusajs.com/docs/learn/fundamentals/workflows/conditions/index.html.md) condition to check if the entry type is a `product`, and if so, update the product using the `updateProductsWorkflow`.
+- Use a `when` condition to check if the entry type is a `productVariant`, and if so, update the product variant using the `updateProductVariantsWorkflow`.
+- Use a `when` condition to check if the entry type is a `productOption`, and if so, update the product option using the `updateProductOptionsWorkflow`.
+
+You can't perform data manipulation in a workflow's constructor function. Instead, the Workflows SDK includes utility functions like `when` to perform typical operations that requires accessing data values. Learn more about workflow constraints in the [Workflow Constraints](https://docs.medusajs.com/docs/learn/fundamentals/workflows/constructor-constraints/index.html.md) documetation.
+
+### Add the Webhook Listener API Route
+
+You can finally add the API route that acts as a webhook listener.
+
+To add the API route, create the file `src/api/hooks/contentful/route.ts` with the following content:
+
+```ts title="src/api/hooks/contentful/route.ts" highlights={contentfulHookRouteHighlights} collapsibleLines="1-10" expandButtonLabel="Show Imports"
+import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
+import { 
+  handleContentfulHookWorkflow, 
+  HandleContentfulHookWorkflowInput,
+} from "../../../workflows/handle-contentful-hook"
+import { CONTENTFUL_MODULE } from "../../../modules/contentful"
+import { CanonicalRequest } from "@contentful/node-apps-toolkit"
+import { MedusaError } from "@medusajs/framework/utils"
+import ContentfulModuleService from "../../../modules/contentful/service"
+
+export const POST = async (
+  req: MedusaRequest,
+  res: MedusaResponse
+) => {
+  const contentfulModuleService: ContentfulModuleService = 
+    req.scope.resolve(CONTENTFUL_MODULE)
+  
+  const isValid = await contentfulModuleService.verifyWebhook({
+    path: req.path,
+    method: req.method.toUpperCase(),
+    headers: req.headers,
+    body: JSON.stringify(req.body),
+  } as unknown as CanonicalRequest)
+  
+  if (!isValid) {
+    throw new MedusaError(
+      MedusaError.Types.UNAUTHORIZED, 
+      "Invalid webhook request"
+    )
+  }
+          
+  await handleContentfulHookWorkflow(req.scope).run({
+    input: {
+      entry: req.body,
+    } as unknown as HandleContentfulHookWorkflowInput,
+  })
+
+  res.status(200).send("OK")
+}
+```
+
+Since you export a `POST` route handler function, you expose a `POST` route at `/hooks/contentful`.
+
+In the route, you first use the `verifyWebhook` method of the Contentful Module's service to verify the request. If the request is invalid, you throw an error.
+
+Then, you run the `handleContentfulHookWorkflow` passing the request's body, which is the webhook data payload, as an input.
+
+Finally, you return a `200` response to Contentful to confirm that the webhook was received and processed.
+
+### Test the Webhook Listener
+
+To test out the webhook listener, start the Medusa application:
+
+```bash npm2yarn
+npm run dev
+```
+
+Then, try updating a product's title (in the default locale) in Contentful. You should see the product's title updated in Medusa.
+
+***
+
+## Next Steps
+
+You've now integrated Contentful with Medusa and supported localized product details. You can expand on the features in this tutorial to:
+
+1. Add support for other data types, such as product categories or collections.
+   - Refer to the data model references for each [Commerce Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/index.html.md) to figure out the content types you need to create in Contentful.
+2. Listen to other product events and update the Contentful entries accordingly.
+   - Refer to the [Events Reference](https://docs.medusajs.com/references/events/index.html.md) for details on all events emitted in Medusa.
+3. Add localization for the entire Next.js Starter Storefront. You can either:
+   - Create content types in Contentful for different sections in the storefront, then use them to retrieve the localized content;
+   - Or use the approaches recommended in the [Next.js documentation](https://nextjs.org/docs/app/building-your-application/routing/internationalization).
+
+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).
+
+### Troubleshooting
+
+If you encounter issues during your development, check out the [troubleshooting guides](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/troubleshooting/index.html.md).
+
+### Getting Help
+
+If you encounter issues not covered in the troubleshooting guides:
+
+1. Visit the [Medusa GitHub repository](https://github.com/medusajs/medusa) to report issues or ask questions.
+2. Join the [Medusa Discord community](https://discord.gg/medusajs) for real-time support from community members.
+3. Contact the [sales team](https://medusajs.com/contact/) to get help from the Medusa team.
+
+
 # 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.
@@ -49897,6 +52835,1245 @@ 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 Resend (Email Notifications)
 
 In this guide, you'll learn how to integrate Medusa with Resend.
@@ -52981,4014 +57158,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).
 
 
-# Implement Localization in Medusa by Integrating Contentful
-
-In this tutorial, you'll learn how to localize your Medusa store's data with Contentful.
-
-When you install a Medusa application, you get a fully-fledged commerce platform with a Framework for customization. While Medusa provides features essential for internationalization, such as support for multiple [regions](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/region/index.html.md) and [currencies](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/currency/index.html.md), it doesn't provide content localization.
-
-However, Medusa's architecture supports the integration of third-party services to provide additional features, such as data localization. One service you can integrate is [Contentful](https://www.contentful.com/), a headless content management system (CMS) that allows you to manage and deliver content across multiple channels.
-
-## Summary
-
-By following this tutorial, you'll learn how to:
-
-- Install and set up Medusa.
-- Integrate Contentful with Medusa.
-- Create content types in Contentful for Medusa models.
-- Trigger syncing products and related data to Contentful when:
-  - A product is created.
-  - The admin user triggers syncing the products.
-- Customize the [Next.js Starter Storefront](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/nextjs-starter/index.html.md) to fetch localized data from Contentful through Medusa.
-- Listen to webhook events in Contentful to update Medusa's data accordingly.
-
-You can follow this tutorial whether you're new to Medusa or an advanced Medusa developer.
-
-![Diagram illustrating the integration of Contentful with Medusa](https://res.cloudinary.com/dza7lstvk/image/upload/v1744791908/Medusa%20Resources/contentful-summary_j5cpdx.jpg)
-
-- [Tutorial Repository](https://github.com/medusajs/examples/tree/main/localization-contentful): Find the full code for this guide in this repository.
-- [OpenApi Specs for Postman](https://res.cloudinary.com/dza7lstvk/raw/upload/v1744790686/OpenApi/Contentful_jysc07.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
-```
-
-First, you'll be asked for the project's name. Then, when prompted about installing 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 named `{project-name}-storefront`.
-
-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: Create Contentful Module
-
-To integrate third-party services into Medusa, you create a module. A [module](https://docs.medusajs.com/docs/learn/fundamentals/modules/index.html.md) is a reusable package that provides 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 module that provides the necessary functionalities to integrate Contentful with Medusa.
-
-Refer to the [Modules](https://docs.medusajs.com/docs/learn/fundamentals/modules/index.html.md) documentation to learn more about modules and their structure.
-
-### Install Contentful SDKs
-
-Before building the module, you need to install Contentful's management and delivery JS SDKs. So, run the following command in the Medusa application's directory:
-
-```bash npm2yarn
-npm install contentful contentful-management
-```
-
-Where `contentful` is the delivery SDK and `contentful-management` is the management SDK.
-
-### Create Module Directory
-
-A module is created under the `src/modules` directory of your Medusa application. So, create the directory `src/modules/contentful`.
-
-### Create Loader
-
-When the Medusa application starts, you want to establish a connection to Contentful, then create the necessary content types if they don't exist in Contentful.
-
-A module can specify a task to run on the Medusa application's startup using [loaders](https://docs.medusajs.com/docs/learn/fundamentals/modules/loaders/index.html.md). A loader is an asynchronous function that a module exports. Then, when the Medusa application starts, it runs the loader. The loader can be used to perform one-time tasks such as connecting to a database, creating content types, or initializing data.
-
-Refer to the [Loaders](https://docs.medusajs.com/docs/learn/fundamentals/modules/loaders/index.html.md) documentation to learn more about how loaders work and when to use them.
-
-Loaders are created in a TypeScript or JavaScript file under the `loaders` directory of a module. So, create the file `src/modules/contentful/loader/create-content-models.ts` with the following content:
-
-```ts title="src/modules/contentful/loader/create-content-models.ts" highlights={loaderHighlights}
-import { LoaderOptions } from "@medusajs/framework/types"
-import { asValue } from "awilix"
-import { createClient } from "contentful-management"
-import { MedusaError } from "@medusajs/framework/utils"
-
-const { createClient: createDeliveryClient } = require("contentful")
-
-export type ModuleOptions = {
-  management_access_token: string
-  delivery_token: string
-  space_id: string
-  environment: string
-  default_locale?: string
-}
-
-export default async function syncContentModelsLoader({
-  container,
-  options,
-}: LoaderOptions<ModuleOptions>) {
-  if (
-    !options?.management_access_token || !options?.delivery_token || 
-    !options?.space_id || !options?.environment
-  ) {
-    throw new MedusaError(
-      MedusaError.Types.INVALID_DATA,
-      "Contentful access token, space ID and environment are required"
-    )
-  }
-
-  const logger = container.resolve("logger")
-
-  try {
-    const managementClient = createClient({
-      accessToken: options.management_access_token,
-    }, {
-      type: "plain",
-      defaults: {
-        spaceId: options.space_id,
-        environmentId: options.environment,
-      },
-    })
-
-    const deliveryClient = createDeliveryClient({
-      accessToken: options.delivery_token,
-      space: options.space_id,
-      environment: options.environment,
-    })
-
-
-    // TODO try to create content types
-
-  } catch (error) {
-    logger.error(
-      `Failed to connect to Contentful: ${error}`
-    )
-    throw error
-  }
-}
-```
-
-The loader file exports an asynchronous function that accepts an object having the following properties:
-
-- `container`: The [Module container](https://docs.medusajs.com/docs/learn/fundamentals/modules/container/index.html.md), which is a registry of resources available to the module. You can use it to resolve or register resources in the module's container.
-- `options`: An object of options passed to the module. These options are useful to pass secrets or options that may change per environment. You'll learn how to pass these options later.
-  - The Contentful Module expects the options to include the Contentful tokens for the management and delivery APIs, the space ID, environment, and optionally the default locale to use.
-
-In the loader function, you validate the options passed to the module, and throw an error if they're invalid. Then, you resolve from the Module's container the [Logger](https://docs.medusajs.com/docs/learn/debugging-and-testing/logging/index.html.md) used to log messages in the terminal.
-
-Finally, you create clients for Contentful's management and delivery APIs, passing them the necessary module's options. If the connection fails, an error is thrown, which is handled in the `catch` block.
-
-#### Create Content Types
-
-In the loader, you need to create content types in Contentful if they don't already exist.
-
-In this tutorial, you'll only create content types for a product and its variants and options. However, you can create content types for other data models, such as categories or collections, by following the same approach.
-
-You can learn more about the product-related data models, which the content types are based on, in the [Product Module's Data Models](https://docs.medusajs.com/references/product/models/index.html.md) reference.
-
-To create the content type for products, replace the `TODO` in the loader with the following:
-
-```ts title="src/modules/contentful/loader/create-content-models.ts"
-// Try to create the product content type
-try {
-  await managementClient.contentType.get({
-    contentTypeId: "product",
-  })
-} catch (error) {
-  const productContentType = await managementClient.contentType.createWithId({
-    contentTypeId: "product",
-  }, {
-    name: "Product",
-    description: "Product content type synced from Medusa",
-    displayField: "title",
-    fields: [
-      {
-        id: "title", 
-        name: "Title",
-        type: "Symbol",
-        required: true,
-        localized: true,
-      },
-      {
-        id: "handle",
-        name: "Handle", 
-        type: "Symbol",
-        required: true,
-        localized: false,
-      },
-      {
-        id: "medusaId",
-        name: "Medusa ID",
-        type: "Symbol",
-        required: true,
-        localized: false,
-      },
-      {
-        type: "RichText",
-        name: "description", 
-        id: "description",
-        validations: [
-          {
-            enabledMarks: [
-              "bold",
-              "italic",
-              "underline", 
-              "code",
-              "superscript",
-              "subscript",
-              "strikethrough",
-            ],
-          },
-          {
-            enabledNodeTypes: [
-              "heading-1",
-              "heading-2", 
-              "heading-3",
-              "heading-4",
-              "heading-5",
-              "heading-6",
-              "ordered-list",
-              "unordered-list",
-              "hr",
-              "blockquote",
-              "embedded-entry-block",
-              "embedded-asset-block",
-              "table",
-              "asset-hyperlink",
-              "embedded-entry-inline",
-              "entry-hyperlink",
-              "hyperlink",
-            ],
-          },
-          {
-            nodes: {},
-          },
-        ],
-        localized: true,
-        required: true,
-      },
-      {
-        type: "Symbol",
-        name: "subtitle",
-        id: "subtitle",
-        localized: true,
-        required: false,
-        validations: [],
-      },
-      {
-        type: "Array",
-        items: {
-          type: "Link",
-          linkType: "Asset",
-          validations: [],
-        },
-        name: "images",
-        id: "images",
-        localized: true,
-        required: false,
-        validations: [],
-      },
-      {
-        id: "productVariants",
-        name: "Product Variants",
-        type: "Array",
-        localized: false,
-        required: false,
-        items: {
-          type: "Link",
-          validations: [
-            {
-              linkContentType: ["productVariant"],
-            },
-          ],
-          linkType: "Entry",
-        },
-        disabled: false,
-        omitted: false,
-      },
-      {
-        id: "productOptions",
-        name: "Product Options",
-        type: "Array",
-        localized: false,
-        required: false,
-        items: {
-          type: "Link",
-          validations: [
-            {
-              linkContentType: ["productOption"],
-            },
-          ],
-          linkType: "Entry",
-        },
-        disabled: false,
-        omitted: false,
-      },
-    ],
-  })
-
-  await managementClient.contentType.publish({
-    contentTypeId: "product",
-  }, productContentType)
-}
-
-// TODO create product variant content type
-```
-
-In the above snippet, you first try to retrieve the product content type using Contentful's Management APIs. If the content type doesn't exist, an error is thrown, which you handle in the `catch` block.
-
-In the `catch` block, you create the product content type with the following fields:
-
-- `title`: The product's title, which is a localized field.
-- `handle`: The product's handle, which is used to create a human-readable URL for the product in the storefront.
-- `medusaId`: The product's ID in Medusa, which is a non-localized field. You'll store in this field the ID of the product in Medusa.
-- `description`: The product's description, which is a localized rich-text field.
-- `subtitle`: The product's subtitle, which is a localized field.
-- `images`: The product's images, which is a localized array of assets in Contentful.
-- `productVariants`: The product's variants, which is an array that references content of the `productVariant` content type.
-- `productOptions`: The product's options, which is an array that references content of the `productOption` content type.
-
-Next, you'll create the `productVariant` content type that represents a product's variant. A variant is a combination of the product's options that customers can purchase. For example, a "red" shirt is a variant whose color option is `red`.
-
-To create the variant content type, replace the new `TODO` with the following:
-
-```ts title="src/modules/contentful/loader/create-content-models.ts"
-// Try to create the product variant content type
-try {
-  await managementClient.contentType.get({
-    contentTypeId: "productVariant",
-  })
-} catch (error) {
-  const productVariantContentType = await managementClient.contentType.createWithId({
-    contentTypeId: "productVariant",
-  }, {
-  name: "Product Variant",
-  description: "Product variant content type synced from Medusa",
-  displayField: "title",
-  fields: [
-    {
-      id: "title",
-      name: "Title",
-      type: "Symbol",
-      required: true,
-      localized: true,
-    },
-    {
-      id: "product",
-      name: "Product",
-      type: "Link",
-      required: true,
-      localized: false,
-      validations: [
-        {
-          linkContentType: ["product"],
-        },
-      ],
-      disabled: false,
-      omitted: false,
-      linkType: "Entry",
-    },
-    {
-      id: "medusaId",
-      name: "Medusa ID",
-      type: "Symbol",
-      required: true,
-      localized: false,
-    },
-    {
-      id: "productOptionValues",
-      name: "Product Option Values",
-      type: "Array",
-      localized: false,
-      required: false,
-      items: {
-        type: "Link",
-        validations: [
-          {
-            linkContentType: ["productOptionValue"],
-          },
-        ],
-        linkType: "Entry",
-      },
-      disabled: false,
-      omitted: false,
-      },
-    ],
-  })
-
-  await managementClient.contentType.publish({
-    contentTypeId: "productVariant",
-  }, productVariantContentType)
-}
-
-// TODO create product option content type
-```
-
-In the above snippet, you create the `productVariant` content type with the following fields:
-
-- `title`: The product variant's title, which is a localized field.
-- `product`: References the `product` content type, which is the product that the variant belongs to.
-- `medusaId`: The product variant's ID in Medusa, which is a non-localized field. You'll store in this field the ID of the variant in Medusa.
-- `productOptionValues`: The product variant's option values, which is an array that references content of the `productOptionValue` content type.
-
-Then, you'll create the `productOption` content type that represents a product's option, like size or color. Replace the new `TODO` with the following:
-
-```ts title="src/modules/contentful/loader/create-content-models.ts"
-// Try to create the product option content type
-try {
-  await managementClient.contentType.get({
-    contentTypeId: "productOption",
-  })
-} catch (error) {
-  const productOptionContentType = await managementClient.contentType.createWithId({
-    contentTypeId: "productOption",
-  }, {
-    name: "Product Option",
-    description: "Product option content type synced from Medusa",
-    displayField: "title",
-    fields: [
-    {
-      id: "title",
-      name: "Title",
-      type: "Symbol",
-      required: true,
-      localized: true,
-    },
-    {
-      id: "product",
-      name: "Product",
-      type: "Link",
-      required: true,
-      localized: false,
-      validations: [
-        {
-          linkContentType: ["product"],
-        },
-      ],
-      disabled: false,
-      omitted: false,
-      linkType: "Entry",
-    },
-    {
-      id: "medusaId",
-      name: "Medusa ID",
-      type: "Symbol",
-      required: true,
-      localized: false,
-    },
-    {
-      id: "values",
-      name: "Values",
-      type: "Array",
-      required: false,
-      localized: false,
-      items: {
-        type: "Link",
-        validations: [
-          {
-            linkContentType: ["productOptionValue"],
-          },
-        ],
-        linkType: "Entry",
-      },
-      disabled: false,
-      omitted: false,
-      },
-    ],
-  })
-
-  await managementClient.contentType.publish({
-    contentTypeId: "productOption",
-  }, productOptionContentType)
-}
-
-// TODO create product option value content type
-```
-
-In the above snippet, you create the `productOption` content type with the following fields:
-
-- `title`: The product option's title, which is a localized field.
-- `product`: References the `product` content type, which is the product that the option belongs to.
-- `medusaId`: The product option's ID in Medusa, which is a non-localized field. You'll store in this field the ID of the option in Medusa.
-- `values`: The product option's values, which is an array that references content of the `productOptionValue` content type.
-
-Finally, you'll create the `productOptionValue` content type that represents a product's option value, like "red" or "blue" for the color option. A variant references option values.
-
-To create the option value content type, replace the new `TODO` with the following:
-
-```ts title="src/modules/contentful/loader/create-content-models.ts"
-// Try to create the product option value content type
-try {
-  await managementClient.contentType.get({
-    contentTypeId: "productOptionValue",
-  })
-} catch (error) {
-  const productOptionValueContentType = await managementClient.contentType.createWithId({
-    contentTypeId: "productOptionValue",
-  }, {
-    name: "Product Option Value",
-    description: "Product option value content type synced from Medusa",
-    displayField: "value",
-    fields: [
-    {
-      id: "value",
-      name: "Value",
-      type: "Symbol",
-      required: true,
-      localized: true,
-    },
-    {
-      id: "medusaId",
-      name: "Medusa ID",
-      type: "Symbol",
-      required: true,
-      localized: false,
-    },
-  ],
-})
-
-await managementClient.contentType.publish({
-    contentTypeId: "productOptionValue",
-  }, productOptionValueContentType)
-}
-
-// TODO register clients in container
-```
-
-In the above snippet, you create the `productOptionValue` content type with the following fields:
-
-- `value`: The product option value, which is a localized field.
-- `medusaId`: The product option value's ID in Medusa, which is a non-localized field. You'll store in this field the ID of the option value in Medusa.
-
-You've now created all the necessary content types to localize products.
-
-### Register Clients in the Container
-
-The last step in the loader is to register the Contentful management and delivery clients in the module's container. This will allow you to resolve and use them in the module's service, which you'll create next.
-
-To register resources in the container, you can use its `register` method, which accepts an object containing key-value pairs. The keys are the names of the resources in the container, and the values are the resources themselves.
-
-To register the management and delivery clients, replace the last `TODO` in the loader with the following:
-
-```ts title="src/modules/contentful/loader/create-content-models.ts"
-container.register({
-  contentfulManagementClient: asValue(managementClient),
-  contentfulDeliveryClient: asValue(deliveryClient),
-})
-
-logger.info("Connected to Contentful")
-```
-
-Now, you can resolve the management and delivery clients from the module's container using the keys `contentfulManagementClient` and `contentfulDeliveryClient`, respectively.
-
-### Create Service
-
-You define a module's functionality 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 perform actions with a third-party service.
-
-In this section, you'll create the Contentful Module's service that can be used to retrieve content from Contentful, create content, and more.
-
-To create the service, create the file `src/modules/contenful/service.ts` with the following content:
-
-```ts title="src/modules/contentful/service.ts" highlights={serviceHighlights}
-import { ModuleOptions } from "./loader/create-content-models"
-import { PlainClientAPI } from "contentful-management"
-
-type InjectedDependencies = {
-  contentfulManagementClient: PlainClientAPI;
-  contentfulDeliveryClient: any;
-}
-
-export default class ContentfulModuleService {
-  private managementClient: PlainClientAPI
-  private deliveryClient: any
-  private options: ModuleOptions
-
-  constructor(
-    { 
-      contentfulManagementClient, 
-      contentfulDeliveryClient,
-    }: InjectedDependencies, 
-    options: ModuleOptions
-  ) {
-    this.managementClient = contentfulManagementClient
-    this.deliveryClient = contentfulDeliveryClient
-    this.options = {
-      ...options,
-      default_locale: options.default_locale || "en-US",
-    }
-  }
-
-  // TODO add methods
-}
-```
-
-You export a class that will be the Contentful Module's main service. In the class, you define properties for the Contentful clients and options passed to the module.
-
-You also add a constructor to the class. A service's constructor accepts the following params:
-
-1. The module's container, which you can use to resolve resources. You use it to resolve the Contentful clients you previously registered in the loader.
-2. The options passed to the module.
-
-In the constructor, you assign the clients and options to the class properties. You also set the default locale to `en-US` if it's not provided in the module's options.
-
-Since the loader is executed on application start-up, if an error occurs while connecting to Contentful, the module will not be registered and the service will not be executed. So, in the service, you're guaranteed that the clients are registered in the container and have successful connection to Contentful.
-
-As you implement the syncing and content retrieval features later, you'll add the necessary methods for them.
-
-### Export Module Definition
-
-The final piece to a module is its definition, which you export in an `index.ts` file at the module's root directory. This definition tells Medusa the name of the module, its service, and optionally its loaders.
-
-To create the module's definition, create the file `src/modules/contentful/index.ts` with the following content:
-
-```ts title="src/modules/contentful/index.ts" highlights={moduleHighlights}
-import { Module } from "@medusajs/framework/utils"
-import ContentfulModuleService from "./service"
-import createContentModelsLoader from "./loader/create-content-models"
-
-export const CONTENTFUL_MODULE = "contentful"
-
-export default Module(CONTENTFUL_MODULE, {
-  service: ContentfulModuleService,
-  loaders: [
-    createContentModelsLoader,
-  ],
-})
-```
-
-You use `Module` from the Modules SDK to create the module's definition. It accepts two parameters:
-
-1. The module's name, which is `contentful`.
-2. An object with a required property `service` indicating the module's service. You also pass the loader you created to ensure it's executed when the application starts.
-
-Aside from the module definition, you export the module's name as `CONTENTFUL_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/contentful",
-      options: {
-        management_access_token: process.env.CONTENTFUL_MANAGEMNT_ACCESS_TOKEN,
-        delivery_token: process.env.CONTENTFUL_DELIVERY_TOKEN,
-        space_id: process.env.CONTENTFUL_SPACE_ID,
-        environment: process.env.CONTENTFUL_ENVIRONMENT,
-        default_locale: "en-US",
-      },
-    },
-  ],
-})
-```
-
-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.
-
-You also pass an `options` property with the module's options, including the Contentful's tokens for the management and delivery APIs, the Contentful's space ID, environment, and default locale.
-
-### Note about Locales
-
-By default, your Contentful space will have one locale (for example, `en-US`). You can add locales as explained in the [Contentful documentation](https://www.contentful.com/help/localization/manage-locales/).
-
-When you add a locale, make sure to:
-
-- Set the fallback locale to the default locale (for example, `en-US`). This ensure that values are retrieved in the default locale if values for the requested locale are not available.
-- Allow the required fields to be empty for the locale. Otherwise, you'll have to specify the values for the localized fields in each locale when you create the products later.
-
-![Example of the locale's settings in the Contentful dashboard](https://res.cloudinary.com/dza7lstvk/image/upload/v1744716537/Medusa%20Resources/Screenshot_2025-04-15_at_2.28.46_PM_v50lrm.png)
-
-### Add Environment Variables
-
-Before you can start using the Contentful Module, you need to add the necessary environment variables used in the module's options.
-
-Add the following environment variables to your `.env` file:
-
-```plain
-CONTENTFUL_MANAGEMNT_ACCESS_TOKEN=CFPAT-...
-CONTENTFUL_DELIVERY_TOKEN=eij...
-CONTENTFUL_SPACE_ID=t2a...
-CONTENTFUL_ENVIRONMENT=master
-```
-
-Where:
-
-- `CONTENTFUL_MANAGEMNT_ACCESS_TOKEN`: The Contentful management API access token. To create it on the Contentful dashboard:
-  - Click on the cog icon at the top right, then choose "CMA tokens" from the dropdown.
-
-![The cog icon is at the top right next to the user avatar. If you click on it, a dropdown will show where you can click on "CMA tokens".](https://res.cloudinary.com/dza7lstvk/image/upload/v1744714244/Medusa%20Resources/Screenshot_2025-04-15_at_1.48.35_PM_ct2tfk.png)
-
-- In the CMA tokens page, click on the "Create personal access token" button.
-- In the window that pops up, enter a name for the token, and choose an expiry date. Once you're done, click the Generate button.
-- The token is generated and shown in the pop-up. Make sure to copy it and use it in the `.env` file, as you can't access it again.
-
-![Click on the copy button to copy the key](https://res.cloudinary.com/dza7lstvk/image/upload/v1744714749/Medusa%20Resources/Screenshot_2025-04-15_at_1.58.12_PM_tuugam.png)
-
-- `CONTENTFUL_DELIVERY_TOKEN`: An API token that you can use with the delivery API. To create it on the Contentful dashboard:
-  - Click on the cog icon at the top right, then choose "API keys" from the dropdown.
-
-![The cog icon is at the top right next to the user avatar. If you click on it, a dropdown will show where you can click on "API keys".](https://res.cloudinary.com/dza7lstvk/image/upload/v1744714971/Medusa%20Resources/Screenshot_2025-04-15_at_2.02.31_PM_qfsn1h.png)
-
-- In the APIs page, click on the "Add API key" button.
-- In the window that pops up, enter a name for the token, then click the Add API Key button.
-- This will create an API key and opens its page. On its page, copy the token for the "Content Delivery API" and use it as the value for `CONTENTFUL_DELIVERY_TOKEN`.
-
-![Copy the API key from the "Content Delivery API - access token" field](https://res.cloudinary.com/dza7lstvk/image/upload/v1744715228/Medusa%20Resources/Screenshot_2025-04-15_at_2.06.44_PM_ifu1mx.png)
-
-- `CONTENTFUL_SPACE_ID`: The ID of your Contentful space. You can copy this from the dashboard's URL which is of the format `https://app.contentful.com/spaces/{space_id}/...`.
-- `CONTENTFUL_ENVIRONMENT`: The environment to manage and retrieve the content in. By default, you have the `master` environment which you can use. However, you can use another Contentful environment that you've created.
-
-Your module is now ready for use.
-
-### Test the Module
-
-To test out the module, you'll start the Medusa application, which will run the module's loader.
-
-To start the Medusa application, run the following command:
-
-```bash npm2yarn
-npm run dev
-```
-
-If the loader ran successfully, you'll see the following message in the terminal:
-
-```bash
-info:    Connected to Contentful
-```
-
-You can also see on the Contentful dashboard that the content types were created. To view them, go to the Content Model page.
-
-![In the Contentful dashboard, go to the Content Model page](https://res.cloudinary.com/dza7lstvk/image/upload/v1744715783/Medusa%20Resources/Screenshot_2025-04-15_at_2.16.09_PM_w7oszm.png)
-
-***
-
-## Step 3: Create Products in Contentful
-
-Now that you have the Contentful Module ready for use, you can start creating products in Contentful.
-
-In this step, you'll implement the logic to create products in Contentful. Later, you'll execute it when:
-
-- A product is created in Medusa.
-- The admin user triggers a sync manually.
-
-### Add Methods to Contentful Module Service
-
-To create products in Contentful, you need to add the necessary methods in the Contentful Module's service. Then, you can use these methods later when building the creation flow.
-
-To create a product in Contentful, you'll need three methods: One to create the product's variants, another to create the product's options and values, and a third to create the product.
-
-In the service at `src/modules/contentful/service.ts`, start by adding the method to create the product's variants:
-
-```ts title="src/modules/contentful/service.ts"
-// imports...
-import { ProductVariantDTO } from "@medusajs/framework/types"
-import { EntryProps } from "contentful-management"
-
-export default class ContentfulModuleService {
-  // ...
-
-  private async createProductVariant(
-    variants: ProductVariantDTO[],
-    productEntry: EntryProps
-  ) {
-    for (const variant of variants) {
-      await this.managementClient.entry.createWithId(
-        {
-          contentTypeId: "productVariant",
-          entryId: variant.id,
-        },
-        {
-          fields: {
-            medusaId: {
-              [this.options.default_locale!]: variant.id,
-            },
-            title: {
-              [this.options.default_locale!]: variant.title,
-            },
-            product: {
-              [this.options.default_locale!]: {
-                sys: {
-                  type: "Link",
-                  linkType: "Entry",
-                  id: productEntry.sys.id,
-                },
-              },
-            },
-            productOptionValues: {
-              [this.options.default_locale!]: variant.options.map((option) => ({
-                sys: {
-                  type: "Link",
-                  linkType: "Entry",
-                  id: option.id,
-                },
-              })),
-            },
-          },
-        }
-      )
-    }
-  }
-}
-```
-
-You define a private method `createProductVariant` that accepts two parameters:
-
-1. The product's variants to create in Contentful.
-2. The product's entry in Contentful.
-
-In the method, you iterate over the product's variants and create a new entry in Contentful for each variant. You set the fields based on the product variant content type you created earlier.
-
-For each field, you specify the value for the default locale. In the Contentful dashboard, you can manage the values for other locales.
-
-Next, add the method to create the product's options and values:
-
-```ts title="src/modules/contentful/service.ts" highlights={createProductOptionHighlights}
-// other imports...
-import { ProductOptionDTO } from "@medusajs/framework/types"
-
-export default class ContentfulModuleService {
-  // ...
-  private async createProductOption(
-    options: ProductOptionDTO[],
-    productEntry: EntryProps
-  ) {
-    for (const option of options) {
-      const valueIds: {
-        sys: {
-          type: "Link",
-          linkType: "Entry",
-          id: string
-        }
-      }[] = []
-      for (const value of option.values) {
-        await this.managementClient.entry.createWithId(
-          {
-            contentTypeId: "productOptionValue",
-            entryId: value.id,
-          },
-          {
-            fields: {
-              value: {
-                [this.options.default_locale!]: value.value,
-              },
-              medusaId: {
-                [this.options.default_locale!]: value.id,
-              },
-            },
-          }
-        )
-        valueIds.push({
-          sys: {
-            type: "Link",
-            linkType: "Entry",
-            id: value.id,
-          },
-        })
-      }
-      await this.managementClient.entry.createWithId(
-        {
-          contentTypeId: "productOption",
-          entryId: option.id,
-        },
-        {
-          fields: {
-            medusaId: {
-              [this.options.default_locale!]: option.id,
-            },
-            title: {
-              [this.options.default_locale!]: option.title,
-            },
-            product: {
-              [this.options.default_locale!]: {
-                sys: {
-                  type: "Link",
-                  linkType: "Entry",
-                  id: productEntry.sys.id,
-                },
-              },
-            },
-            values: {
-              [this.options.default_locale!]: valueIds,
-            },
-          },
-        }
-      )
-    }
-  }
-}
-```
-
-You define a private method `createProductOption` that accepts two parameters:
-
-1. The product's options, which is an array of objects.
-2. The product's entry in Contentful, which is an object.
-
-In the method, you iterate over the product's options and create entries for each of its values. Then, you create an entry for the option, and reference the values you created in Contentful. You set the fields based on the option and value content types you created earlier.
-
-Finally, add the method to create the product:
-
-```ts title="src/modules/contentful/service.ts" highlights={createProductHighlights}
-// other imports...
-import { ProductDTO } from "@medusajs/framework/types"
-
-export default class ContentfulModuleService {
-  // ...
-  async createProduct(
-    product: ProductDTO
-  ) {
-    try {
-      // check if product already exists
-      const productEntry = await this.managementClient.entry.get({
-        environmentId: this.options.environment,
-        entryId: product.id,
-      })
-      
-      return productEntry
-    } catch(e) {}
-    
-    // Create product entry in Contentful
-    const productEntry = await this.managementClient.entry.createWithId(
-      {
-        contentTypeId: "product",
-        entryId: product.id,
-      },
-      {
-        fields: {
-          medusaId: {
-            [this.options.default_locale!]: product.id,
-          },
-          title: {
-            [this.options.default_locale!]: product.title,
-          },
-          description: product.description ? {
-            [this.options.default_locale!]: {
-              nodeType: "document",
-              data: {},
-              content: [
-                {
-                  nodeType: "paragraph",
-                  data: {},
-                  content: [
-                    {
-                      nodeType: "text",
-                      value: product.description,
-                      marks: [],
-                      data: {},
-                    },
-                  ],
-                },
-              ],
-            },
-          } : undefined,
-          subtitle: product.subtitle ? {
-            [this.options.default_locale!]: product.subtitle,
-          } : undefined,
-          handle: product.handle ? {
-            [this.options.default_locale!]: product.handle,
-          } : undefined,
-        },
-      }
-    )
-
-    // Create options if they exist
-    if (product.options?.length) {
-      await this.createProductOption(product.options, productEntry)
-    }
-
-    // Create variants if they exist
-    if (product.variants?.length) {
-      await this.createProductVariant(product.variants, productEntry)
-    }
-
-    // update product entry with variants and options
-    await this.managementClient.entry.update(
-      {
-        entryId: productEntry.sys.id,
-      },
-      {
-        sys: productEntry.sys,
-        fields: {
-          ...productEntry.fields,
-          productVariants: {
-            [this.options.default_locale!]: product.variants?.map((variant) => ({
-              sys: {
-                type: "Link",
-                linkType: "Entry",
-                id: variant.id,
-              },
-            })),
-          },
-          productOptions: {
-            [this.options.default_locale!]: product.options?.map((option) => ({
-              sys: {
-                type: "Link",
-                linkType: "Entry",
-                id: option.id,
-              },
-            })),
-          },
-        },
-      }
-    )
-
-    return productEntry
-  }
-}
-```
-
-You define a public method `createProduct` that accepts a product object as a parameter.
-
-In the method, you first check if the product already exists in Contentful. If it does, you return the existing product entry. Otherwise, you create a new product entry with the fields based on the product content type you created earlier.
-
-Next, you create entries for the product's options and variants using the methods you created earlier.
-
-Finally, you update the product entry to reference the variants and options you created.
-
-You now have all the methods to create products in Contentful. You'll also need one last method to delete a product in Contentful. This is useful when you implement the rollback mechanism in the flow that creates the products.
-
-Add the following method to the service:
-
-```ts title="src/modules/contentful/service.ts" highlights={deleteProductHighlights}
-// other imports...
-import { MedusaError } from "@medusajs/framework/utils"
-
-export default class ContentfulModuleService {
-  // ...
-  async deleteProduct(productId: string) {
-    try {
-      // Get the product entry
-      const productEntry = await this.managementClient.entry.get({
-        environmentId: this.options.environment,
-        entryId: productId,
-      })
-
-      if (!productEntry) {
-        return
-      }
-
-      // Delete the product entry
-      await this.managementClient.entry.unpublish({
-        environmentId: this.options.environment,
-        entryId: productId,
-      })
-
-      await this.managementClient.entry.delete({
-        environmentId: this.options.environment,
-        entryId: productId,
-      })
-
-      // Delete the product variant entries
-      for (const variant of productEntry.fields.productVariants[this.options.default_locale!]) {
-        await this.managementClient.entry.unpublish({
-          environmentId: this.options.environment,
-          entryId: variant.sys.id,
-        })
-
-        await this.managementClient.entry.delete({
-          environmentId: this.options.environment,
-          entryId: variant.sys.id,
-        })
-      }
-
-      // Delete the product options entries and values
-      for (const option of productEntry.fields.productOptions[this.options.default_locale!]) {
-        for (const value of option.fields.values[this.options.default_locale!]) {
-          await this.managementClient.entry.unpublish({
-            environmentId: this.options.environment,
-            entryId: value.sys.id,
-        })
-
-        await this.managementClient.entry.delete({
-          environmentId: this.options.environment,
-            entryId: value.sys.id,
-          })
-        }
-
-        await this.managementClient.entry.unpublish({
-          environmentId: this.options.environment,
-          entryId: option.sys.id,
-        })
-
-        await this.managementClient.entry.delete({
-          environmentId: this.options.environment,
-          entryId: option.sys.id,
-        })
-      }
-    } catch (error) {
-      throw new MedusaError(
-        MedusaError.Types.INVALID_DATA,
-        `Failed to delete product from Contentful: ${error.message}`
-      )
-    }
-  }
-}
-```
-
-You define a public method `deleteProduct` that accepts a product ID as a parameter.
-
-In the method, you retrieve the product entry from Contentful with its variants, options, and values. For each entry, you must unpublish and delete it.
-
-You now have all the methods necessary to build the creation flow.
-
-### Create Contentful Product Workflow
-
-To implement the logic that's triggered when a product is created in Medusa, or when the admin user triggers a sync manually, you need to create a workflow.
-
-A [workflow](https://docs.medusajs.com/docs/learn/fundamentals/workflows/index.html.md) is a series of 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.
-
-Learn more about workflows in the [Workflows documentation](https://docs.medusajs.com/docs/learn/fundamentals/workflows/index.html.md).
-
-In this section, you'll create a workflow that creates Medusa products in Contentful using the Contentful Module.
-
-The workflow has the following steps:
-
-- [useQueryGraphStep](https://docs.medusajs.com/references/helper-steps/useQueryGraphStep/index.html.md): Retrieve products to create in Contentful.
-- [createProductsContentfulStep](#createProductsContentfulStep): Create the products in Contentful.
-
-Medusa provides the `useQueryGraphStep` in its `@medusajs/medusa/core-flows` package. So, you only need to implement the second step.
-
-#### createProductsContentfulStep
-
-In the second step, you create the retrieved products in Contentful.
-
-To create the step, create the file `src/workflows/steps/create-products-contentful.ts` with the following content:
-
-```ts title="src/workflows/steps/create-products-contentful.ts" highlights={createProductsContentfulStepHighlights}
-import { ProductDTO } from "@medusajs/framework/types"
-import { CONTENTFUL_MODULE } from "../../modules/contentful"
-import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk"
-import ContentfulModuleService from "../../modules/contentful/service"
-import { EntryProps } from "contentful-management"
-
-type StepInput = {
-  products: ProductDTO[]
-}
-
-export const createProductsContentfulStep = createStep(
-  "create-products-contentful-step",
-  async (input: StepInput, { container }) => {
-    const contentfulModuleService: ContentfulModuleService = 
-      container.resolve(CONTENTFUL_MODULE)
-
-    const products: EntryProps[] = []
-
-    try {
-      for (const product of input.products) {
-        products.push(await contentfulModuleService.createProduct(product))
-      }
-    } catch(e) {
-      return StepResponse.permanentFailure(
-        `Error creating products in Contentful: ${e.message}`,
-        products
-      )
-    }
-
-    return new StepResponse(
-      products,
-      products
-    )
-  },
-  async (products, { container }) => {
-    if (!products) {
-      return
-    }
-
-    const contentfulModuleService: ContentfulModuleService = 
-      container.resolve(CONTENTFUL_MODULE)
-
-    for (const product of products) {
-      await contentfulModuleService.deleteProduct(product.sys.id)
-    }
-  }
-)
-```
-
-You create a step with `createStep` from the Workflows SDK. It accepts three parameters:
-
-1. The step's unique name, which is `create-products-contentful-step`.
-2. An async function that receives two parameters:
-   - The step's input, which is in this case an object holding an array of products to create in Contentful.
-   - 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.
-3. An optional compensation function that undoes the actions performed in the step if an error occurs in the workflow's execution. This mechanism ensures data consistency in your application, especially as you integrate external systems.
-
-The Medusa container is different from the module's container. Since modules are isolated, they each have a container with their resources. Refer to the [Module Container](https://docs.medusajs.com/docs/learn/fundamentals/modules/container/index.html.md) documentation for more information.
-
-In the step function, you resolve the Contentful Module's service from the Medusa container using the name you exported in the module definition's file.
-
-Then, you iterate over the products and create a new entry in Contentful for each product using the `createProduct` method you created earlier. If the creation of any product fails, you fail the step and pass the created products to the compensation function.
-
-A step function must return a `StepResponse` instance. The `StepResponse` constructor accepts two parameters:
-
-1. The step's output, which is the product entries created in Contentful.
-2. Data to pass to the step's compensation function.
-
-The compensation function accepts as a parameter the data passed from the step, and an object containing the Medusa container.
-
-In the compensation function, you iterate over the created product entries and delete them from Contentful using the `deleteProduct` method you created earlier.
-
-#### Create the Workflow
-
-Now that you have all the necessary steps, you can create the workflow.
-
-To create the workflow, create the file `src/workflows/create-products-contentful.ts` with the following content:
-
-```ts title="src/workflows/create-products-contentful.ts"
-import { createWorkflow, WorkflowResponse } from "@medusajs/framework/workflows-sdk"
-import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
-import { createProductsContentfulStep } from "./steps/create-products-contentful"
-import { ProductDTO } from "@medusajs/framework/types"
-
-type WorkflowInput = {
-  product_ids: string[]
-}
-
-export const createProductsContentfulWorkflow = createWorkflow(
-  { name: "create-products-contentful-workflow" },
-  (input: WorkflowInput) => {
-    // @ts-ignore
-    const { data } = useQueryGraphStep({
-      entity: "product",
-      fields: [
-        "id",
-        "title",
-        "description",
-        "subtitle",
-        "status",
-        "handle",
-        "variants.*",
-        "variants.options.*",
-        "options.*",
-        "options.values.*",
-      ],
-      filters: {
-        id: input.product_ids,
-      },
-    })
-    
-    const contentfulProducts = createProductsContentfulStep({
-      products: data as ProductDTO[],
-    })
-
-    return new WorkflowResponse(contentfulProducts)
-  }
-)
-```
-
-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 the product IDs to create in Contentful.
-
-In the workflow's constructor function, you:
-
-1. Retrieve the Medusa products using the `useQueryGraphStep` helper step. This step uses Medusa's [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md) tool to retrieve data across modules. You pass it the product IDs to retrieve.
-2. Create the product entries in Contentful using the `createProductsContentfulStep` step.
-
-A workflow must return an instance of `WorkflowResponse`. The `WorkflowResponse` constructor accepts the workflow's output as a parameter, which is an object of the product entries created in Contentful.
-
-You now have the workflow that you can execute when a product is created in Medusa, or when the admin user triggers a sync manually.
-
-***
-
-## Step 4: Trigger Sync on Product Creation
-
-Medusa has an event system that allows you to listen for events, such as `product.created`, and perform an asynchronous action when the event is emitted.
-
-You listen to events in a subscriber. A [subscriber](https://docs.medusajs.com/docs/learn/fundamentals/events-and-subscribers/index.html.md) is an asynchronous function that listens to one or more events and performs actions when these events are emitted. A subscriber is useful when syncing data across systems, as the operation can be time-consuming and should be performed in the background.
-
-In this step, you'll create a subscriber that listens to the `product.created` event and executes the `createProductsContentfulWorkflow` workflow.
-
-Learn more about subscribers in the [Events and Subscribers documentation](https://docs.medusajs.com/docs/learn/fundamentals/events-and-subscribers/index.html.md).
-
-To create a subscriber, create the file `src/subscribers/create-product.ts` with the following content:
-
-```ts title="src/subscribers/create-product.ts" highlights={createProductSubscriberHighlights}
-import {
-  type SubscriberConfig,
-  type SubscriberArgs,
-} from "@medusajs/framework"
-import { 
-  createProductsContentfulWorkflow,
-} from "../workflows/create-products-contentful"
-
-export default async function handleProductCreate({
-  event: { data },
-  container,
-}: SubscriberArgs<{ id: string }>) {
-  await createProductsContentfulWorkflow(container)
-    .run({
-      input: {
-        product_ids: [data.id],
-      },
-    })
-
-  console.log("Product created in Contentful")
-}
-
-export const config: SubscriberConfig = {
-  event: "product.created",
-}
-```
-
-A subscriber file must export:
-
-1. An asynchronous function, which is the subscriber that is executed when the event is emitted.
-2. A configuration object that holds the name of the event the subscriber listens to, which is `product.created` in this case.
-
-The subscriber function receives an object as a parameter that has the following properties:
-
-- `event`: An object that holds the event's data payload. The payload of the `product.created` event is an array of product IDs.
-- `container`: The Medusa container to access the Framework and commerce tools.
-
-In the subscriber function, you execute the `createProductsContentfulWorkflow` by invoking it, passing the Medusa container as a parameter. Then, you chain a `run` method, passing it the product ID from the event's data payload as input.
-
-Finally, you log a message to the console to indicate that the product was created in Contentful.
-
-### Test the Subscriber
-
-To test out the subscriber, start the Medusa application:
-
-```bash npm2yarn
-npm run dev
-```
-
-Then, open the Medusa Admin dashboard and login.
-
-Can't remember the credentials? Learn how to create a user in the [Medusa CLI reference](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/medusa-cli/commands/user/index.html.md).
-
-Next, open the Products page and create a new product.
-
-You should see the following message in the terminal:
-
-```bash
-info: Product created in Contentful
-```
-
-You can also see the product in the Contentful dashboard by going to the Content page.
-
-***
-
-## Step 5: Trigger Product Sync Manually
-
-The other way to sync products is when the admin user triggers a sync manually. This is useful when you already have products in Medusa and you want to sync them to Contentful.
-
-To allow admin users to trigger a sync manually, you need:
-
-1. A subscriber that listens to a custom event.
-2. An API route that emits the custom event when a request is sent to it.
-3. A UI route in the Medusa Admin that displays a button to trigger the sync.
-
-### Create Manual Sync Subscriber
-
-You'll start by creating the subscriber that listens to a custom event to sync the Medusa products to Contentful.
-
-To create the subscriber, create the file `src/subscribers/sync-products.ts` with the following content:
-
-```ts title="src/subscribers/sync-products.ts" highlights={syncProductsSubscriberHighlights}
-import type { 
-  SubscriberConfig,
-  SubscriberArgs,
-} from "@medusajs/framework"
-import { ContainerRegistrationKeys } from "@medusajs/framework/utils"
-import { 
-  createProductsContentfulWorkflow,
-} from "../workflows/create-products-contentful"
-
-export default async function syncProductsHandler({
-  container,
-}: SubscriberArgs<Record<string, unknown>>) {
-  const query = container.resolve(ContainerRegistrationKeys.QUERY)
-  
-  const batchSize = 100
-  let hasMore = true
-  let offset = 0
-  let totalCount = 0
-
-  while (hasMore) {
-    const {
-      data: products,
-      metadata: { count } = {},
-    } = await query.graph({
-      entity: "product",
-      fields: [
-        "id",
-      ],
-      pagination: {
-        skip: offset,
-        take: batchSize,
-      },
-    })
-
-    if (products.length) {
-      await createProductsContentfulWorkflow(container).run({
-        input: {
-          product_ids: products.map((product) => product.id),
-        },
-      })
-    }
-
-    hasMore = products.length === batchSize
-    offset += batchSize
-    totalCount = count ?? 0
-  }
-
-  console.log(`Synced ${totalCount} products to Contentful`)
-}
-
-export const config: SubscriberConfig = {
-  event: "products.sync",
-}
-```
-
-You create a subscriber that listens to the `products.sync` event.
-
-In the subscriber function, you use [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md) to retrieve all the products in Medusa with pagination. Then, for each batch of products, you execute the `createProductsContentfulWorkflow` workflow, passing the product IDs to the workflow.
-
-Finally, you log a message to the console to indicate that the products were synced to Contentful.
-
-### Create API Route to Trigger Sync
-
-Next, to allow the admin user to trigger the sync manually, you need to create an API route that emits the `products.sync` event.
-
-An API Route is an endpoint that exposes commerce features to external applications and clients, such as storefronts.
-
-Learn more about API routes in [this documentation](https://docs.medusajs.com/docs/learn/fundamentals/api-routes/index.html.md).
-
-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 `/admin/contentful/sync`, create the file `src/api/admin/contentful/sync/route.ts` with the following content:
-
-```ts title="src/api/admin/contentful/sync/route.ts" highlights={syncProductsRouteHighlights}
-import {
-  MedusaRequest,
-  MedusaResponse,
-} from "@medusajs/framework/http"
-
-export const POST = async (
-  req: MedusaRequest,
-  res: MedusaResponse
-) => {
-  const eventService = req.scope.resolve("event_bus")
-
-  await eventService.emit({
-    name: "products.sync",
-    data: {},
-  })
-
-  res.status(200).json({
-    message: "Products sync triggered successfully",
-  })
-}
-```
-
-Since you export a `POST` route handler function, you expose an `API` route at `/admin/contentful/sync`. The route handler function accepts two parameters:
-
-1. A request object with details and context on the request, such as body parameters or authenticated user details.
-2. A response object to manipulate and send the response.
-
-In the route handler, you resolve the [Event Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/infrastructure-modules/event/index.html.md)'s service from the Medusa container and emit the `products.sync` event.
-
-### Create UI Route to Trigger Sync
-
-Finally, you'll add a new page to the Medusa Admin dashboard that displays a button to trigger the sync. To add a page, you need to create a UI route.
-
-A [UI route](https://docs.medusajs.com/docs/learn/fundamentals/admin/ui-routes/index.html.md) is a React component that specifies the content to be shown in a new page of the Medusa Admin dashboard. You'll create a UI route to display a button that triggers product syncing to Contentful when clicked.
-
-Refer to the [UI Routes](https://docs.medusajs.com/docs/learn/fundamentals/admin/ui-routes/index.html.md) documentation for more information.
-
-#### Configure JS SDK
-
-Before creating the UI route, you'll configure Medusa's [JS SDK](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/js-sdk/index.html.md) so that you can use it to send requests to the Medusa server.
-
-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
-
-UI routes are created in a `page.tsx` file under a sub-directory of `src/admin/routes` directory. The file's path relative to `src/admin/routes` determines its path in the dashboard.
-
-So, create the file `src/admin/routes/contentful/page.tsx` with the following content:
-
-```tsx title="src/admin/routes/contentful/page.tsx" highlights={contentfulPageHighlights}
-import { defineRouteConfig } from "@medusajs/admin-sdk"
-import { Container, Heading, Button } from "@medusajs/ui"
-import { useMutation } from "@tanstack/react-query"
-import { sdk } from "../../lib/sdk"
-import { toast } from "@medusajs/ui"
-
-const ContentfulSettingsPage = () => {
-  const { mutate, isPending } = useMutation({
-    mutationFn: () => 
-      sdk.client.fetch("/admin/contentful/sync", {
-        method: "POST",
-      }),
-    onSuccess: () => {
-      toast.success("Sync to Contentful triggered successfully")
-    },
-  })
-
-  return (
-    <Container className="p-6">
-      <div className="flex flex-col gap-y-4">
-        <div>
-          <Heading level="h1">Contentful Settings</Heading>
-        </div>
-        <div>
-          <Button 
-            variant="primary"
-            onClick={() => mutate()}
-            isLoading={isPending}
-          >
-            Sync to Contentful
-          </Button>
-        </div>
-      </div>
-    </Container>
-  )
-}
-
-export const config = defineRouteConfig({
-  label: "Contentful",
-})
-
-export default ContentfulSettingsPage
-```
-
-A UI route's file must export:
-
-1. A React component that defines the content of the page.
-2. A configuration object that specifies the route's label in the dashboard. This label is used to show a sidebar item for the new route.
-
-In the React component, you use `useMutation` hook from `@tanstack/react-query` to create a mutation that sends a `POST` request to the API route you created earlier. In the mutation function, you use the JS SDK to send the request.
-
-Then, in the return statement, you display a button that triggers the mutation when clicked, which sends a request to the API route you created earlier.
-
-### Test the Sync
-
-To test out the sync, start the Medusa application:
-
-```bash npm2yarn
-npm run dev
-```
-
-Then, open the Medusa Admin dashboard and login. In the sidebar, you'll find a new "Contentful" item. If you click on it, you'll see the page you created with the button to trigger the sync.
-
-![The Contentful page in the Medusa Admin dashboard with a button to trigger the sync](https://res.cloudinary.com/dza7lstvk/image/upload/v1744718825/Medusa%20Resources/Screenshot_2025-04-15_at_3.06.53_PM_va8e20.png)
-
-If you click on the button, you'll see the following message in the terminal:
-
-```bash
-info: Synced 4 products to Contentful
-```
-
-Assuming you have `4` products in Medusa, the message indicates that the sync was successful.
-
-You can also see the products in the Contentful dashboard.
-
-![The Contentful dashboard showing the synced products](https://res.cloudinary.com/dza7lstvk/image/upload/v1744718896/Medusa%20Resources/Screenshot_2025-04-15_at_3.08.02_PM_qexr0x.png)
-
-***
-
-## Step 6: Retrieve Locales API Route
-
-In the next steps, you'll implement customizations that are useful for storefronts. A storefront should show the customer a list of available locales and allow them to select from them.
-
-In this step, you will:
-
-1. Add the logic to retrieve locales from Contentful in the Contentful Module's service.
-2. Create an API route that exposes the locales to the storefront.
-3. Customize the Next.js Starter Storefront to show the locales to customers.
-
-### Retrieve Locales from Contentful Method
-
-You'll start by adding two methods to the Contentful Module's service that are useful to retrieve locales from Contentful.
-
-The first method retrieves all locales from Contentful. Add it to the service at `src/modules/contentful/service.ts`:
-
-```ts title="src/modules/contentful/service.ts"
-export default class ContentfulModuleService {
-  // ...
-  async getLocales() {
-    return await this.managementClient.locale.getMany({})
-  }
-}
-```
-
-You use the `locale.getMany` method of the Contentful Management API client to retrieve all locales.
-
-The second method returns the code of the default locale:
-
-```ts title="src/modules/contentful/service.ts"
-export default class ContentfulModuleService {
-  // ...
-  async getDefaultLocaleCode() {
-    return this.options.default_locale
-  }
-}
-```
-
-You return the default locale using the `default_locale` option you set in the module's options.
-
-### Create API Route to Retrieve Locales
-
-Next, you'll create an API route that exposes the locales to the storefront.
-
-To create the API route, create the file `src/api/store/locales/route.ts` with the following content:
-
-```ts title="src/api/store/locales/route.ts" highlights={getLocalesRouteHighlights}
-import {
-  MedusaRequest,
-  MedusaResponse,
-} from "@medusajs/framework/http"
-import { CONTENTFUL_MODULE } from "../../../modules/contentful"
-import ContentfulModuleService from "../../../modules/contentful/service"
-
-export const GET = async (
-  req: MedusaRequest,
-  res: MedusaResponse
-) => {
-  const contentfulModuleService: ContentfulModuleService = req.scope.resolve(
-    CONTENTFUL_MODULE
-  )
-
-  const locales = await contentfulModuleService.getLocales()
-  const defaultLocaleCode = await contentfulModuleService.getDefaultLocaleCode()
-
-  const formattedLocales = locales.items.map((locale) => {
-    return {
-      name: locale.name,
-      code: locale.code,
-      is_default: locale.code === defaultLocaleCode,
-    }
-  })
-
-  res.json({
-    locales: formattedLocales,
-  })
-}
-```
-
-Since you export a `GET` route handler function, you expose a `GET` route at `/store/locales`.
-
-In the route handler, you resolve the Contentful Module's service from the Medusa container to retrieve the locales and the default locale code.
-
-Then, you format the locales to include their name, code, and whether they are the default locale.
-
-Finally, you return the formatted locales in the JSON response.
-
-### Customize Storefront to Show Locales
-
-In the first step of this tutorial, you installed the [Next.js Starter Storefront](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/nextjs-starter/index.html.md) along with the Medusa application. This storefront provides ecommerce features like a product catalog, a cart, and a checkout.
-
-In this section, you'll customize the storefront to show the locales to customers and allow them to select from them. The selected locale will be stored in the browser's cookies, allowing you to use it later when retrieving a product's localized data.
-
-The Next.js Starter Storefront was installed in a separate directory from Medusa. The directory's name is `{your-project}-storefront`.
-
-So, if your Medusa application's directory is `medusa-contentful`, you can find the storefront by going back to the parent directory and changing to the `medusa-contentful-storefront` directory:
-
-```bash
-cd ../medusa-contentful-storefront # change based on your project name
-```
-
-#### Add Cookie Functions
-
-You'll start by adding two functions that retrieve and set the locale in the browser's cookies.
-
-In `src/lib/data/cookies.ts` add the following functions:
-
-```ts title="src/lib/data/cookies.ts" highlights={getLocaleHighlights} badgeLabel="Storefront" badgeColor="blue"
-export const getLocale = async () => {
-  const cookies = await nextCookies()
-  return cookies.get("_medusa_locale")?.value
-}
-
-export const setLocale = async (locale: string) => {
-  const cookies = await nextCookies()
-  cookies.set("_medusa_locale", locale, {
-    maxAge: 60 * 60 * 24 * 7,
-  })
-}
-```
-
-The `getLocale` function retrieves the locale from the browser's cookies, and the `setLocale` function sets the locale in the browser's cookies.
-
-#### Manage Locales Functions
-
-Next, you'll add server actions to retrieve the locales and set the selected locale.
-
-Create the file `src/lib/data/locale.ts` with the following content:
-
-```ts title="src/lib/data/locale.ts" highlights={getLocalesHighlights} badgeLabel="Storefront" badgeColor="blue"
-"use server"
-
-import { sdk } from "@lib/config"
-import type { Document } from "@contentful/rich-text-types"
-import { getLocale, setLocale } from "./cookies"
-
-export type Locale = {
-  name: string
-  code: string
-  is_default: boolean
-}
-
-export async function getLocales() {
-  return await sdk.client.fetch<{
-    locales: Locale[]
-  }>("/store/locales")
-}
-
-export async function getSelectedLocale() {
-  let localeCode = await getLocale()
-  if (!localeCode) {
-    const locales = await getLocales()
-    localeCode = locales.locales.find((l) => l.is_default)?.code
-  }
-  return localeCode
-}
-
-export async function setSelectedLocale(locale: string) {
-  await setLocale(locale)
-}
-```
-
-You add the following functions:
-
-1. `getLocales`: Retrieves the locales from the Medusa server using the API route you created earlier.
-2. `getSelectedLocale`: Retrieves the selected locale from the browser's cookies, or the default locale if no locale is selected.
-3. `setSelectedLocale`: Sets the selected locale in the browser's cookies.
-
-You'll use these functions as you add the UI to show the locales next.
-
-#### Show Locales in the Storefront
-
-You'll now add the UI to show the locales to customers and allow them to select from them.
-
-Create the file `src/modules/layout/components/locale-select/index.tsx` with the following content:
-
-```tsx title="src/modules/layout/components/locale-select/index.tsx" highlights={localeSelectHighlights} badgeLabel="Storefront" badgeColor="blue"
-"use client"
-
-import { useState, useEffect, Fragment } from "react"
-import { getLocales, Locale, getSelectedLocale, setSelectedLocale } from "../../../../lib/data/locale"
-import { Listbox, ListboxButton, ListboxOption, ListboxOptions, Transition } from "@headlessui/react"
-import { ArrowRightMini } from "@medusajs/icons"
-import { clx } from "@medusajs/ui"
-
-const LocaleSelect = () => {
-  const [locales, setLocales] = useState<Locale[]>([])
-  const [locale, setLocale] = useState<Locale | undefined>()
-  const [open, setOpen] = useState(false)
-
-  useEffect(() => {
-    getLocales()
-      .then(({ locales }) => {
-        setLocales(locales)
-      })
-  }, [])
-
-  useEffect(() => {
-    if (!locales.length || locale) {
-      return
-    }
-
-    getSelectedLocale().then((locale) => {
-      const localeDetails = locales.find((l) => l.code === locale) 
-      setLocale(localeDetails)
-    })
-  }, [locales])
-
-  useEffect(() => {
-    if (locale) {
-      setSelectedLocale(locale.code)
-    }
-  }, [locale])
-
-  const handleChange = (locale: Locale) => {
-    setLocale(locale)
-    setOpen(false)
-  }
-
-  // TODO add return statement
-}
-
-export default LocaleSelect
-```
-
-You create a `LocaleSelect` component with the following state variables:
-
-1. `locales`: The list of locales retrieved from the Medusa server.
-2. `locale`: The selected locale.
-3. `open`: A boolean indicating whether the dropdown is open.
-
-Then, you use three `useEffect` hooks:
-
-1. The first `useEffect` hook retrieves the locales using the `getLocales` function and sets them in the `locales` state variable.
-2. The second `useEffect` hook is triggered when the `locales` state variable changes. It retrieves the selected locale using the `getSelectedLocale` function and sets the `locale` state variable.
-3. The third `useEffect` hook is triggered when the `locale` state variable changes. It sets the selected locale in the browser's cookies using the `setSelectedLocale` function.
-
-You also create a `handleChange` function that sets the selected locale and closes the dropdown. You'll execute this function when the customer selects a locale from the dropdown.
-
-Finally, you'll add a return statement that shows the locale dropdown. Replace the `TODO` with the following:
-
-```tsx title="src/modules/layout/components/locale-select/index.tsx" badgeLabel="Storefront" badgeColor="blue"
-return (
-  <div
-    className="flex justify-between"
-    onMouseEnter={() => setOpen(true)}
-    onMouseLeave={() => setOpen(false)}
-  >
-    <div>
-      <Listbox as="span" onChange={handleChange} defaultValue={locale}>
-        <ListboxButton className="py-1 w-full">
-          <div className="txt-compact-small flex items-start gap-x-2">
-            <span>Language:</span>
-            {locale && (
-              <span className="txt-compact-small flex items-center gap-x-2">
-                {locale.name}
-              </span>
-            )}
-          </div>
-        </ListboxButton>
-        <div className="flex relative w-full min-w-[320px]">
-          <Transition
-            show={open}
-            as={Fragment}
-            leave="transition ease-in duration-150"
-            leaveFrom="opacity-100"
-            leaveTo="opacity-0"
-          >
-            <ListboxOptions
-              className="absolute -bottom-[calc(100%-36px)] left-0 xsmall:left-auto xsmall:right-0 max-h-[442px] overflow-y-scroll z-[900] bg-white drop-shadow-md text-small-regular uppercase text-black no-scrollbar rounded-rounded w-full"
-              static
-            >
-              {locales?.map((l, index) => {
-                return (
-                  <ListboxOption
-                    key={index}
-                    value={l}
-                    className="py-2 hover:bg-gray-200 px-3 cursor-pointer flex items-center gap-x-2"
-                  >
-                    {l.name}
-                  </ListboxOption>
-                )
-              })}
-            </ListboxOptions>
-          </Transition>
-        </div>
-      </Listbox>
-    </div>
-    <ArrowRightMini
-      className={clx(
-        "transition-transform duration-150",
-        open ? "-rotate-90" : ""
-      )}
-    />
-  </div>
-)
-```
-
-You show the selected locale. Then, when the customer hovers over the locale, the dropdown is shown to select a different locale.
-
-When the customer selects a locale, you execute the `handleChange` function, which sets the selected locale and closes the dropdown.
-
-#### Add Locale Select to the Side Menu
-
-The last step is to show the locale selector in the side menu after the country selector.
-
-In `src/modules/layout/components/side-menu/index.tsx`, add the following import:
-
-```tsx title="src/modules/layout/components/side-menu/index.tsx" badgeLabel="Storefront" badgeColor="blue"
-import LocaleSelect from "../locale-select"
-```
-
-Then, add the `LocaleSelect` component in the return statement of the `SideMenu` component, after the `div` wrapping the country selector:
-
-```tsx title="src/modules/layout/components/side-menu/index.tsx" badgeLabel="Storefront" badgeColor="blue"
-<LocaleSelect />
-```
-
-The locale selector will now show in the side menu after the country selector.
-
-### Test out the Locale Selector
-
-To test out all the changes made in this step, start the Medusa application by running the following command in the Medusa application's directory:
-
-```bash npm2yarn
-npm run dev
-```
-
-Then, start the Next.js Starter Storefront by running the following command in the storefront's directory:
-
-```bash npm2yarn
-npm run dev
-```
-
-The storefront will run at `http://localhost:8000`. Open it in your browser, then click on "Menu" at the top right. You'll see at the bottom of the side menu the locale selector.
-
-![The locale selector in the side menu](https://res.cloudinary.com/dza7lstvk/image/upload/v1744720332/Medusa%20Resources/Screenshot_2025-04-15_at_3.31.51_PM_vdqou5.png)
-
-You can try selecting a different locale. The selected locale will be stored, but products will still be shown in the default locale. You'll implement the locale-based product retrieval in the next step.
-
-***
-
-## Step 7: Retrieve Product Details for Locale
-
-The next feature you'll implement is retrieving and displaying product details for a selected locale.
-
-You'll implement this feature by:
-
-1. Linking Medusa's product to Contentful's product.
-2. Adding the method to retrieve product details for a selected locale from Contentful.
-3. Adding a new route to retrieve the product details for a selected locale.
-4. Customizing the storefront to show the product details for the selected locale.
-
-### Link Medusa's Product to Contentful's Product
-
-Medusa facilitates retrieving data across systems using [module links](https://docs.medusajs.com/docs/learn/fundamentals/module-links/index.html.md). A module link forms an association between data models of two modules while maintaining module isolation.
-
-Not only do module links support Medusa data models, but they also support virtual data models that are not persisted in Medusa's database. In that case, you create a [read-only module link](https://docs.medusajs.com/docs/learn/fundamentals/module-links/read-only/index.html.md) that allows you to retrieve data across systems.
-
-In this section, you'll define a read-only module link between Medusa's product and Contentful's product, allowing you to later retrieve a product's entry in Contentful within a single query.
-
-Learn more about read-only module links in the [Read-Only Module Links](https://docs.medusajs.com/docs/learn/fundamentals/module-links/read-only/index.html.md) documentation.
-
-Module links are defined in a TypeScript or JavaScript file under the `src/links` directory. So, create the file `src/links/product-contentful.ts` with the following content:
-
-```ts title="src/links/product-contentful.ts" highlights={productContentfulLinkHighlights}
-import { defineLink } from "@medusajs/framework/utils"
-import ProductModule from "@medusajs/medusa/product"
-import { CONTENTFUL_MODULE } from "../modules/contentful"
-
-export default defineLink(
-  {
-    linkable: ProductModule.linkable.product,
-    field: "id",
-  },
-  {
-    linkable: {
-      serviceName: CONTENTFUL_MODULE,
-      alias: "contentful_product",
-      primaryKey: "product_id",
-    },
-  },
-  {
-    readOnly: true,
-  }
-)
-```
-
-You define a module link using `defineLink` from the Modules SDK. It accepts three parameters:
-
-1. An object with the linkable configuration of the data model in Medusa, and the field that will be passed as a filter to the Contentful Module's service.
-2. An object with the linkable configuration of the virtual data model in Contentful. This object must have the following properties:
-   - `serviceName`: The name of the service, which is the Contentful Module's name. Medusa uses this name to resolve the module's service from the Medusa container.
-   - `alias`: The alias to use when querying the linked records. You'll see how that works in a bit.
-   - `primaryKey`: The field in Contentful's virtual data model that holds the ID of a product.
-3. An object with the `readOnly` property set to `true`.
-
-You'll see how the module link works in the upcoming steps.
-
-### List Contentful Products Method
-
-Next, you'll add a method that lists Contentful products for a given locale.
-
-Add the following method to the Contentful Module's service at `src/modules/contentful/service.ts`:
-
-```ts title="src/modules/contentful/service.ts" highlights={listContentfulProductsMethodHighlights}
-export default class ContentfulModuleService {
-  // ...
-  async list(
-    filter: {
-      id: string | string[]
-      context?: {
-        locale: string
-      }
-    }
-  ) {
-    const contentfulProducts = await this.deliveryClient.getEntries({
-      limit: 15,
-      content_type: "product",
-      "fields.medusaId": filter.id,
-      locale: filter.context?.locale,
-      include: 3,
-    })
-
-    return contentfulProducts.items.map((product) => {
-      // remove links
-      const { productVariants: _, productOptions: __, ...productFields } = product.fields
-      return {
-        ...productFields,
-        product_id: product.fields.medusaId,
-        variants: product.fields.productVariants.map((variant) => {
-          // remove circular reference
-          const { product: _, productOptionValues: __, ...variantFields } = variant.fields
-          return {
-            ...variantFields,
-            product_variant_id: variant.fields.medusaId,
-            options: variant.fields.productOptionValues.map((option) => {
-              // remove circular reference
-              const { productOption: _, ...optionFields } = option.fields
-              return {
-                ...optionFields,
-                product_option_id: option.fields.medusaId,
-              }
-            }),
-          }
-        }),
-        options: product.fields.productOptions.map((option) => {
-          // remove circular reference
-          const { product: _, ...optionFields } = option.fields
-          return {
-            ...optionFields,
-            product_option_id: option.fields.medusaId,
-            values: option.fields.values.map((value) => {
-              // remove circular reference
-              const { productOptionValue: _, ...valueFields } = value.fields
-              return {
-                ...valueFields,
-                product_option_value_id: value.fields.medusaId,
-              }
-            }),
-          }
-        }),
-      }
-    })
-  }
-}
-```
-
-You add a `list` method that accepts an object with the following properties:
-
-1. `id`: The ID of the product(s) in Medusa to retrieve their entries in Contentful.
-2. `context`: An object with the `locale` property that holds the locale code to retrieve the product's entry in Contentful for that locale.
-
-In the method, you use the Delivery API client's `getEntries` method to retrieve the products. You pass the following parameters:
-
-- `limit`: The maximum number of products to retrieve.
-- `content_type`: The content type of the entries to retrieve, which is `product`.
-- `fields.medusaId`: Filter the products by their `medusaId` field, which holds the ID of the product in Medusa.
-- `locale`: The locale code to retrieve the fields of the product in that locale.
-- `include`: The depth of the included nested entries. This ensures that you can retrieve the product's variants and options, and their values.
-
-Then, you format the retrieved products to:
-
-- Pass the product's ID in the `product_id` property. This is essential to map a product in Medusa to its entry in Contentful.
-- Remove the circular references in the product's variants, options, and values to avoid infinite loops.
-
-To paginate the retrieved products, implemet a `listAndCount` method as explained in the [Query Context](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query-context#using-pagination-with-query/index.html.md) documentation.
-
-### Retrieve Product Details for Locale API Route
-
-You'll now create the API route that returns a product's details for a given locale.
-
-You can create an API route that accepts path parameters by creating a directory within the route file's path whose name is of the format `[param]`.
-
-So, create the file `src/api/store/products/[id]/[locale]/route.ts` with the following content:
-
-```ts title="src/api/store/products/[id]/[locale]/route.ts" highlights={getProductLocaleDetailsRouteHighlights}
-import {
-  MedusaRequest,
-  MedusaResponse,
-} from "@medusajs/framework/http"
-import { QueryContext } from "@medusajs/framework/utils"
-
-export const GET = async (
-  req: MedusaRequest,
-  res: MedusaResponse
-) => {
-  const { locale, id } = req.params
-  
-  const query = req.scope.resolve("query")
-
-  const { data } = await query.graph({
-    entity: "product",
-    fields: [
-      "id",
-      "contentful_product.*",
-    ],
-    filters: {
-      id,
-    },
-    context: {
-      contentful_product: QueryContext({
-        locale,
-      }),
-    },
-  })
-
-  res.json({
-    product: data[0],
-  })  
-}
-```
-
-Since you export a `GET` route handler function, you expose a `GET` route at `/store/products/[id]/[locale]`. The route accepts two path parameters: the product's ID and the locale code.
-
-In the route handler, you retrieve the `locale` and `id` path parameters from the request. Then, you resolve [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md) from the Medusa container.
-
-Next, you use Query to retrieve the localized details of the specified product. To do that, you pass an object with the following properties:
-
-- `entity`: The entity to retrieve, which is `product`.
-- `fields`: The fields to retrieve. Notice that you include the `contentful_product.*` field, which is available through the module link you created earlier.
-- `filters`: The filter to apply on the retrieved products. You apply the product's ID as a filter.
-- `context`: An additional context to be passed to the methods retrieving the data. To pass a context, you use [Query Context](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query-context/index.html.md).
-
-By specifying `contentful_product.*` in the `fields` property, Medusa will retrieve the product's entry from Contentful using the `list` method you added to the Contentful Module's service.
-
-Medusa passes the filters and context to the `list` method, and attaches the returned data to the Medusa product if its `product_id` matches the product's ID.
-
-Finally, you return the product's details in the JSON response.
-
-You can now use this route to retrieve a product's details for a given locale.
-
-### Show Localized Product Details in Storefront
-
-Now that you expose the localized product details, you can customize the storefront to show them.
-
-#### Install Contentful Rich Text Package
-
-When you retrieve the entries from Contentful, rich-text fields are returned as an object that requires special rendering. So, Contentful provides a package to render rich-text fields.
-
-Install the package by running the following command:
-
-```bash npm2yarn
-npm install @contentful/@contentful/rich-text-types
-```
-
-You'll use this package to render the product's description.
-
-#### Retrieve Localized Product Details Function
-
-To retrieve a product's details for a given locale, you'll add a function that sends a request to the API route you created.
-
-First, add the following import at the top of `src/lib/data/locale.ts`:
-
-```ts title="src/lib/data/locale.ts" badgeLabel="Storefront" badgeColor="blue"
-import type { Document } from "@contentful/rich-text-types"
-```
-
-Then, add the following type and function at the end of the file:
-
-```ts title="src/lib/data/locale.ts" badgeLabel="Storefront" badgeColor="blue"
-export type ProductLocaleDetails = {
-  id: string
-  contentful_product: {
-    product_id: string
-    title: string
-    handle: string
-    description: Document
-    subtitle?: string
-    variants: {
-      title: string
-      product_variant_id: string
-      options: {
-        value: string
-        product_option_id: string
-      }[]
-    }[]
-    options: {
-      title: string
-      product_option_id: string
-      values: {
-        title: string
-        product_option_value_id: string
-      }[]
-    }[]
-  }
-}
-
-export async function getProductLocaleDetails(
-  productId: string
-) {
-  const localeCode = await getSelectedLocale()
-
-  return await sdk.client.fetch<{
-    product: ProductLocaleDetails
-  }>(`/store/products/${productId}/${localeCode}`)
-}
-```
-
-You define a `ProductLocaleDetails` type that describes the structure of a localized product's details.
-
-You also define a `getProductLocaleDetails` function that sends a request to the API route you created and returns the localized product's details.
-
-#### Show Localized Product Title in Products Listing
-
-Next, you'll customize existing components to show the localized product details.
-
-The component defined in `src/modules/products/components/product-preview/index.tsx` shows the product's details in the products listing page. You need to retrieve the localized product details and show the product's title in the selected locale.
-
-In `src/modules/products/components/product-preview/index.tsx`, add the following import:
-
-```tsx title="src/modules/products/components/product-preview/index.tsx" badgeLabel="Storefront" badgeColor="blue"
-import { getProductLocaleDetails } from "@lib/data/locale"
-```
-
-Then, in the `ProductPreview` component in the same file, add the following before the `return` statement:
-
-```tsx title="src/modules/products/components/product-preview/index.tsx" badgeLabel="Storefront" badgeColor="blue"
-const productLocaleDetails = await getProductLocaleDetails(product.id!)
-```
-
-This will retrieve the localized product details for the selected locale.
-
-Finally, to show the localized product title, find in the `ProductPreview` component's `return` statement the following line:
-
-```tsx title="src/modules/products/components/product-preview/index.tsx" badgeLabel="Storefront" badgeColor="blue"
-{product.title}
-```
-
-And replace it with the following:
-
-```tsx title="src/modules/products/components/product-preview/index.tsx" badgeLabel="Storefront" badgeColor="blue"
-{productLocaleDetails.product.contentful_product?.title || product.title}
-```
-
-You'll test it out after the next step.
-
-#### Show Localized Product Details in Product Page
-
-Next, you'll customize the product page to show the localized product details.
-
-The product's details page is defined in `src/app/[countryCode]/(main)/products/[handle]/page.tsx`. So, add the following import at the top of the file:
-
-```tsx title="src/app/[countryCode]/(main)/products/[handle]/page.tsx" badgeLabel="Storefront" badgeColor="blue"
-import { getProductLocaleDetails } from "@lib/data/locale"
-```
-
-Then, in the `ProductPage` component in the same file, add the following before the `return` statement:
-
-```tsx title="src/app/[countryCode]/(main)/products/[handle]/page.tsx" badgeLabel="Storefront" badgeColor="blue"
-const productLocaleDetails = await getProductLocaleDetails(pricedProduct.id!)
-```
-
-This will retrieve the localized product details for the selected locale.
-
-Finally, in the `ProductPage` component in the same file, pass the following prop to `ProductTemplate`:
-
-```tsx title="src/app/[countryCode]/(main)/products/[handle]/page.tsx" badgeLabel="Storefront" badgeColor="blue"
-return (
-  <ProductTemplate
-    // ...
-    productLocaleDetails={productLocaleDetails.product}
-  />
-)
-```
-
-Next, you'll customize the `ProductTemplate` component to accept and use this prop.
-
-In `src/modules/products/templates/index.tsx`, add the following import:
-
-```tsx title="src/modules/products/templates/index.tsx" badgeLabel="Storefront" badgeColor="blue"
-import { ProductLocaleDetails } from "@lib/data/locale"
-```
-
-Then, update the `ProductTemplateProps` type to include the `productLocaleDetails` prop:
-
-```tsx title="src/modules/products/templates/index.tsx" badgeLabel="Storefront" badgeColor="blue"
-export type ProductTemplateProps = {
-  // ...
-  productLocaleDetails: ProductLocaleDetails
-}
-```
-
-Next, update the `ProductTemplate` component to destructure the `productLocaleDetails` prop:
-
-```tsx title="src/modules/products/templates/index.tsx" badgeLabel="Storefront" badgeColor="blue"
-const ProductTemplate: React.FC<ProductTemplateProps> = ({
-  // ...
-  productLocaleDetails,
-}) => {
-  // ...
-}
-```
-
-Finally, pass the `productLocaleDetails` prop to the `ProductInfo` component in the `return` statement:
-
-```tsx title="src/modules/products/templates/index.tsx" badgeLabel="Storefront" badgeColor="blue"
-<ProductInfo
-  // ...
-  productLocaleDetails={productLocaleDetails}
-/>
-```
-
-The `ProductInfo` component shows the product's details. So, you need to update it to accept and use the `productLocaleDetails` prop.
-
-In `src/modules/products/templates/product-info/index.tsx`, add the following imports:
-
-```tsx title="src/modules/products/templates/product-info/index.tsx" badgeLabel="Storefront" badgeColor="blue"
-import { ProductLocaleDetails } from "@lib/data/locale"
-import { documentToHtmlString } from "@contentful/rich-text-html-renderer"
-```
-
-Then, update the `ProductInfoProps` type to include the `productLocaleDetails` prop:
-
-```tsx title="src/modules/products/templates/product-info/index.tsx" badgeLabel="Storefront" badgeColor="blue"
-export type ProductInfoProps = {
-  // ...
-  productLocaleDetails: ProductLocaleDetails
-}
-```
-
-Next, update the `ProductInfo` component to destructure the `productLocaleDetails` prop:
-
-```tsx title="src/modules/products/templates/product-info/index.tsx" badgeLabel="Storefront" badgeColor="blue"
-const ProductInfo = ({ product, productLocaleDetails }: ProductInfoProps) => {
-  // ...
-}
-```
-
-Then, find the following line in the `return` statement:
-
-```tsx title="src/modules/products/templates/product-info/index.tsx" badgeLabel="Storefront" badgeColor="blue"
-{product.title}
-```
-
-And replace it with the following:
-
-```tsx title="src/modules/products/templates/product-info/index.tsx" badgeLabel="Storefront" badgeColor="blue"
-{productLocaleDetails.contentful_product?.title || product.title}
-```
-
-Also, find the following line:
-
-```tsx title="src/modules/products/templates/product-info/index.tsx" badgeLabel="Storefront" badgeColor="blue"
-{product.description}
-```
-
-And replace it with the following:
-
-```tsx title="src/modules/products/templates/product-info/index.tsx" badgeLabel="Storefront" badgeColor="blue"
-{productLocaleDetails.contentful_product?.description ? 
-  <div dangerouslySetInnerHTML={{ __html: documentToHtmlString(productLocaleDetails.contentful_product?.description) }} /> : 
-  product.description
-}
-```
-
-You use the `documentToHtmlString` function to render the rich-text field. The function returns an HTML string that you can use to render the description.
-
-### Test out the Localized Product Details
-
-You can now test out all the changes made in this step.
-
-To do that, start the Medusa application by running the following command in the Medusa application's directory:
-
-```bash npm2yarn
-npm run dev
-```
-
-Then, start the Next.js Starter Storefront by running the following command in the storefront's directory:
-
-```bash npm2yarn
-npm run dev
-```
-
-Open the storefront at `http://localhost:8000` and select a different locale.
-
-Then, open the products listing page by clicking on Menu -> Store. You'll see the product titles in the selected locale.
-
-![The product titles are shown in the selected locale](https://res.cloudinary.com/dza7lstvk/image/upload/v1744723796/Medusa%20Resources/Screenshot_2025-04-15_at_4.29.39_PM_izxt6j.png)
-
-Then, if you click on a product, you'll see the product's title and description in the selected locale.
-
-![The product's title and description are shown in the selected locale](https://res.cloudinary.com/dza7lstvk/image/upload/v1744723844/Medusa%20Resources/Screenshot_2025-04-15_at_4.30.31_PM_pt6ngz.png)
-
-***
-
-## Step 8: Sync Changes from Contentful to Medusa
-
-The last feature you'll implement is syncing changes from Contentful to Medusa.
-
-Contentful's webhooks allow you to listen to changes in your Contentful entries. You can then set up a webhook listener API route in Medusa that updates the product's data.
-
-In this step, you'll set up a webhook listener that updates Medusa's product data when a Contentful entry is published.
-
-### Prerequisites: Public Server
-
-Webhooks can only trigger deployed listeners. So, you must either [deploy your Medusa application](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/deployment/index.html.md), or use tools like [ngrok](https://ngrok.com/) to publicly expose your local application.
-
-### Set Up Webhooks in Contentful
-
-Before setting up the webhook listener, you need to set up a webhook in Contentful. To do that, on the Contentful dashboard:
-
-1. Click on the cog icon at the top right, then choose "Webhooks" from the dropdown.
-
-![The cog icon is at the top right next to the avatar icon. When you click on it, you see a dropdown with the "Webhooks" option](https://res.cloudinary.com/dza7lstvk/image/upload/v1744733023/Medusa%20Resources/Screenshot_2025-04-15_at_7.03.21_PM_ji7ohw.png)
-
-2. On the Webhooks page, click on the "Add Webhook" button.
-3. In the webhook form:
-   - In the Name fields, enter a name, such as "Medusa".
-   - In the URL field, enter `{your_app}/hooks/contentful`, where `{your_app}` is the public URL of your Medusa application. You'll create the `/hooks/contentful` API route in a bit.
-   - In the Triggers section, select the "Published" trigger for "Entry".
-
-![The webhook form with the URL and triggers highlighted](https://res.cloudinary.com/dza7lstvk/image/upload/v1744733332/Medusa%20Resources/Screenshot_2025-04-15_at_7.08.24_PM_coq6oo.png)
-
-- Scroll down to the "Headers" section, and choose "application/json" for the "Content type" field.
-
-![The webhook form](https://res.cloudinary.com/dza7lstvk/image/upload/v1744733411/Medusa%20Resources/Screenshot_2025-04-15_at_7.09.53_PM_kvlppv.png)
-
-4. Once you're done, click the Save button.
-
-### Setup Webhook Secret in Contentful
-
-You also need to add a webhook secret in Contentful. To do that, on the Contentful dashboard:
-
-1. Click on the cog icon at the top right, then choose "Webhooks" from the dropdown.
-2. On the Webhooks page, click on the "Settings" tab.
-3. Click on the "Enable request verification" button.
-
-![The "Enable request verification" button in the "Settings" tab](https://res.cloudinary.com/dza7lstvk/image/upload/v1744786362/Medusa%20Resources/Screenshot_2025-04-16_at_9.51.39_AM_byv3tt.png)
-
-4. Copy the secret that shows up. You can update it later but you can't see the same secret again.
-
-You'll use the secret to verify the webhook request in Medusa next.
-
-### Update Contentful Module Options
-
-First, add the webhook secret as an environment variable in the Medusa application's `.env` file:
-
-```plain
-CONTENTFUL_WEBHOOK_SECRET=aEl7...
-```
-
-Next, add the webhook secret to the Contentful Module options in the Medusa application's `medusa-config.ts` file:
-
-```ts title="medusa-config.ts"
-module.exports = defineConfig({
-  // ...
-  modules: [
-    {
-      resolve: "./src/modules/contentful",
-      options: {
-        // ...
-        webhook_secret: process.env.CONTENTFUL_WEBHOOK_SECRET,
-      },
-    },
-  ],
-})
-```
-
-Finally, update the `ModuleOptions` type in `src/modules/contentful/loader/create-content-models.ts` to include the `webhook_secret` option:
-
-```ts title="src/modules/contentful/loader/create-content-models.ts"
-export type ModuleOptions = {
-  // ...
-  webhook_secret: string
-}
-```
-
-### Add Verify Request Method
-
-Next, you'll add a method to the Contentful Module's service that verifies a webhook request.
-
-To verify the request, you'll need the `@contentful/node-apps-toolkit` package that provides utility functions for Node.js applications.
-
-So, run the following command to install it:
-
-```bash npm2yarn
-npm install @contentful/node-apps-toolkit
-```
-
-Then, add the following method to the Contentful Module's service in `src/modules/contentful/service.ts`:
-
-```ts title="src/modules/contentful/service.ts"
-// other imports...
-import { 
-  CanonicalRequest, 
-  verifyRequest,
-} from "@contentful/node-apps-toolkit"
-
-export default class ContentfulModuleService {
-  // ...
-  async verifyWebhook(request: CanonicalRequest) {
-    if (!this.options.webhook_secret) {
-      throw new MedusaError(
-        MedusaError.Types.INVALID_DATA, 
-        "Webhook secret is not set"
-      )
-    }
-    return verifyRequest(this.options.webhook_secret, request, 0)
-  }
-}
-```
-
-You add a `verifyWebhook` method that verifies a webhook request using the `verifyRequest` function.
-
-You pass to the `verifyRequest` function the webhook secret from the module's options with the request's details. You also disable time-to-live (TTL) check by passing `0` as the third argument.
-
-### Handle Contentful Webhook Workflow
-
-Before you add the webhook listener, the last piece you need is to add a workflow that handles the necessary updates based on the webhook event.
-
-The workflow will have the following steps:
-
-- [prepareUpdateDataStep](#prepareUpdateDataStep): Prepare the data for the update
-
-You only need to implement the first step, as Medusa provides the other workflows (running as steps) in the `@medusajs/medusa/core-flows` package.
-
-#### prepareUpdateDataStep
-
-The first step receives the webhook data payload and, based on the entry type, returns the data necessary for the update.
-
-To create the step, create the file `src/workflows/steps/prepare-update-data.ts` with the following content:
-
-```ts title="src/workflows/steps/prepare-update-data.ts" highlights={prepareUpdateDataStepHighlights}
-import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk"
-import { EntryProps } from "contentful-management"
-import ContentfulModuleService from "../../modules/contentful/service"
-import { CONTENTFUL_MODULE } from "../../modules/contentful"
-
-type StepInput = {
-  entry: EntryProps
-}
-
-export const prepareUpdateDataStep = createStep(
-  "prepare-update-data",
-  async ({ entry }: StepInput, { container }) => {
-    const contentfulModuleService: ContentfulModuleService = 
-      container.resolve(CONTENTFUL_MODULE)
-    
-    const defaultLocale = await contentfulModuleService.getDefaultLocaleCode()
-
-    let data: Record<string, unknown> = {}
-
-    switch (entry.sys.contentType.sys.id) {
-      case "product":
-        data = {
-          id: entry.fields.medusaId[defaultLocale!],
-          title: entry.fields.title[defaultLocale!],
-          subtitle: entry.fields.subtitle?.[defaultLocale!] || undefined,
-          handle: entry.fields.handle[defaultLocale!],
-        }
-        break
-      case "productVariant":
-        data = {
-          id: entry.fields.medusaId[defaultLocale!],
-          title: entry.fields.title[defaultLocale!],
-        }
-        break
-      case "productOption":
-        data = {
-          selector: {
-            id: entry.fields.medusaId[defaultLocale!],
-          },
-          update: {
-            title: entry.fields.title[defaultLocale!],
-          },
-        }
-        break
-    }
-
-    return new StepResponse(data)
-  }
-)
-```
-
-You define a `prepareUpdateDataStep` function that receives the webhook data payload as an input.
-
-In the step, you resolve the Contentful Module's service and use it to retrieve the default locale code. You need it to find the value to update the fields in Medusa.
-
-Next, you prepare the data to return based on the entry type:
-
-- `product`: The product's ID, title, subtitle, and handle.
-- `productVariant`: The product variant's ID and title.
-- `productOption`: The product option's ID and title.
-
-The data is prepared based on the expected input for the workflows that will be used to update the data.
-
-#### Create the Workflow
-
-You can now create the workflow that handles the webhook event.
-
-Create the file `src/workflows/handle-contentful-hook.ts` with the following content:
-
-```ts title="src/workflows/handle-contentful-hook.ts" highlights={handleContentfulHookWorkflowHighlights} collapsibleLines="1-14" expandButtonLabel="Show Imports"
-import { createWorkflow, when } from "@medusajs/framework/workflows-sdk"
-import { EntryProps } from "contentful-management"
-import { prepareUpdateDataStep } from "./steps/prepare-update-data"
-import { 
-  updateProductOptionsWorkflow, 
-  updateProductsWorkflow, 
-  updateProductVariantsWorkflow, 
-  UpdateProductOptionsWorkflowInput,
-} from "@medusajs/medusa/core-flows"
-import { 
-  UpsertProductDTO, 
-  UpsertProductVariantDTO,
-} from "@medusajs/framework/types"
-
-export type WorkflowInput = {
-  entry: EntryProps
-}
-
-export const handleContentfulHookWorkflow = createWorkflow(
-  { name: "handle-contentful-hook-workflow" },
-  (input: WorkflowInput) => {
-    const prepareUpdateData = prepareUpdateDataStep({
-      entry: input.entry,
-    })
-
-    when(input, (input) => input.entry.sys.contentType.sys.id === "product")
-      .then(() => {
-        updateProductsWorkflow.runAsStep({
-          input: {
-            products: [prepareUpdateData as UpsertProductDTO],
-          },
-        })
-      })
-
-    when(input, (input) => 
-      input.entry.sys.contentType.sys.id === "productVariant"
-    )
-    .then(() => {
-      updateProductVariantsWorkflow.runAsStep({
-        input: {
-            product_variants: [prepareUpdateData as UpsertProductVariantDTO],
-          },
-        })
-      })
-
-    when(input, (input) => 
-      input.entry.sys.contentType.sys.id === "productOption"
-    )
-    .then(() => {
-      updateProductOptionsWorkflow.runAsStep({
-        input: prepareUpdateData as unknown as UpdateProductOptionsWorkflowInput,
-      })
-    })
-  }
-)
-```
-
-You define a `handleContentfulHookWorkflow` function that receives the webhook data payload as an input.
-
-In the workflow, you:
-
-- Prepare the data for the update using the `prepareUpdateDataStep` step.
-- Use a [when](https://docs.medusajs.com/docs/learn/fundamentals/workflows/conditions/index.html.md) condition to check if the entry type is a `product`, and if so, update the product using the `updateProductsWorkflow`.
-- Use a `when` condition to check if the entry type is a `productVariant`, and if so, update the product variant using the `updateProductVariantsWorkflow`.
-- Use a `when` condition to check if the entry type is a `productOption`, and if so, update the product option using the `updateProductOptionsWorkflow`.
-
-You can't perform data manipulation in a workflow's constructor function. Instead, the Workflows SDK includes utility functions like `when` to perform typical operations that requires accessing data values. Learn more about workflow constraints in the [Workflow Constraints](https://docs.medusajs.com/docs/learn/fundamentals/workflows/constructor-constraints/index.html.md) documetation.
-
-### Add the Webhook Listener API Route
-
-You can finally add the API route that acts as a webhook listener.
-
-To add the API route, create the file `src/api/hooks/contentful/route.ts` with the following content:
-
-```ts title="src/api/hooks/contentful/route.ts" highlights={contentfulHookRouteHighlights} collapsibleLines="1-10" expandButtonLabel="Show Imports"
-import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
-import { 
-  handleContentfulHookWorkflow, 
-  HandleContentfulHookWorkflowInput,
-} from "../../../workflows/handle-contentful-hook"
-import { CONTENTFUL_MODULE } from "../../../modules/contentful"
-import { CanonicalRequest } from "@contentful/node-apps-toolkit"
-import { MedusaError } from "@medusajs/framework/utils"
-import ContentfulModuleService from "../../../modules/contentful/service"
-
-export const POST = async (
-  req: MedusaRequest,
-  res: MedusaResponse
-) => {
-  const contentfulModuleService: ContentfulModuleService = 
-    req.scope.resolve(CONTENTFUL_MODULE)
-  
-  const isValid = await contentfulModuleService.verifyWebhook({
-    path: req.path,
-    method: req.method.toUpperCase(),
-    headers: req.headers,
-    body: JSON.stringify(req.body),
-  } as unknown as CanonicalRequest)
-  
-  if (!isValid) {
-    throw new MedusaError(
-      MedusaError.Types.UNAUTHORIZED, 
-      "Invalid webhook request"
-    )
-  }
-          
-  await handleContentfulHookWorkflow(req.scope).run({
-    input: {
-      entry: req.body,
-    } as unknown as HandleContentfulHookWorkflowInput,
-  })
-
-  res.status(200).send("OK")
-}
-```
-
-Since you export a `POST` route handler function, you expose a `POST` route at `/hooks/contentful`.
-
-In the route, you first use the `verifyWebhook` method of the Contentful Module's service to verify the request. If the request is invalid, you throw an error.
-
-Then, you run the `handleContentfulHookWorkflow` passing the request's body, which is the webhook data payload, as an input.
-
-Finally, you return a `200` response to Contentful to confirm that the webhook was received and processed.
-
-### Test the Webhook Listener
-
-To test out the webhook listener, start the Medusa application:
-
-```bash npm2yarn
-npm run dev
-```
-
-Then, try updating a product's title (in the default locale) in Contentful. You should see the product's title updated in Medusa.
-
-***
-
-## Next Steps
-
-You've now integrated Contentful with Medusa and supported localized product details. You can expand on the features in this tutorial to:
-
-1. Add support for other data types, such as product categories or collections.
-   - Refer to the data model references for each [Commerce Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/index.html.md) to figure out the content types you need to create in Contentful.
-2. Listen to other product events and update the Contentful entries accordingly.
-   - Refer to the [Events Reference](https://docs.medusajs.com/references/events/index.html.md) for details on all events emitted in Medusa.
-3. Add localization for the entire Next.js Starter Storefront. You can either:
-   - Create content types in Contentful for different sections in the storefront, then use them to retrieve the localized content;
-   - Or use the approaches recommended in the [Next.js documentation](https://nextjs.org/docs/app/building-your-application/routing/internationalization).
-
-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).
-
-### Troubleshooting
-
-If you encounter issues during your development, check out the [troubleshooting guides](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/troubleshooting/index.html.md).
-
-### Getting Help
-
-If you encounter issues not covered in the troubleshooting guides:
-
-1. Visit the [Medusa GitHub repository](https://github.com/medusajs/medusa) to report issues or ask questions.
-2. Join the [Medusa Discord community](https://discord.gg/medusajs) for real-time support from community members.
-3. Contact the [sales team](https://medusajs.com/contact/) to get help from the Medusa team.
-
-
-# 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).
-
-
 # How to Build a Wishlist Plugin
 
 In this guide, you'll learn how to build a wishlist [plugin](https://docs.medusajs.com/docs/learn/fundamentals/plugins/index.html.md) in Medusa.
@@ -58826,67 +58995,75 @@ To learn more about the commerce features that Medusa provides, check out Medusa
 
 ## JS SDK Admin
 
+- [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)
+- [getJwtHeader\_](https://docs.medusajs.com/references/js_sdk/admin/Client/methods/js_sdk.admin.Client.getJwtHeader_/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)
+- [fetch](https://docs.medusajs.com/references/js_sdk/admin/Client/methods/js_sdk.admin.Client.fetch/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)
+- [initClient](https://docs.medusajs.com/references/js_sdk/admin/Client/methods/js_sdk.admin.Client.initClient/index.html.md)
+- [setToken](https://docs.medusajs.com/references/js_sdk/admin/Client/methods/js_sdk.admin.Client.setToken/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)
+- [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)
 - [create](https://docs.medusajs.com/references/js_sdk/admin/ApiKey/methods/js_sdk.admin.ApiKey.create/index.html.md)
-- [batchSalesChannels](https://docs.medusajs.com/references/js_sdk/admin/ApiKey/methods/js_sdk.admin.ApiKey.batchSalesChannels/index.html.md)
 - [delete](https://docs.medusajs.com/references/js_sdk/admin/ApiKey/methods/js_sdk.admin.ApiKey.delete/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)
 - [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)
+- [update](https://docs.medusajs.com/references/js_sdk/admin/ApiKey/methods/js_sdk.admin.ApiKey.update/index.html.md)
+- [revoke](https://docs.medusajs.com/references/js_sdk/admin/ApiKey/methods/js_sdk.admin.ApiKey.revoke/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)
+- [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/Campaign/methods/js_sdk.admin.Campaign.list/index.html.md)
+- [delete](https://docs.medusajs.com/references/js_sdk/admin/Campaign/methods/js_sdk.admin.Campaign.delete/index.html.md)
+- [retrieve](https://docs.medusajs.com/references/js_sdk/admin/Campaign/methods/js_sdk.admin.Campaign.retrieve/index.html.md)
+- [update](https://docs.medusajs.com/references/js_sdk/admin/Campaign/methods/js_sdk.admin.Campaign.update/index.html.md)
 - [addInboundItems](https://docs.medusajs.com/references/js_sdk/admin/Claim/methods/js_sdk.admin.Claim.addInboundItems/index.html.md)
 - [addInboundShipping](https://docs.medusajs.com/references/js_sdk/admin/Claim/methods/js_sdk.admin.Claim.addInboundShipping/index.html.md)
-- [addItems](https://docs.medusajs.com/references/js_sdk/admin/Claim/methods/js_sdk.admin.Claim.addItems/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)
+- [addItems](https://docs.medusajs.com/references/js_sdk/admin/Claim/methods/js_sdk.admin.Claim.addItems/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)
 - [cancelRequest](https://docs.medusajs.com/references/js_sdk/admin/Claim/methods/js_sdk.admin.Claim.cancelRequest/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)
-- [list](https://docs.medusajs.com/references/js_sdk/admin/Claim/methods/js_sdk.admin.Claim.list/index.html.md)
 - [removeInboundItem](https://docs.medusajs.com/references/js_sdk/admin/Claim/methods/js_sdk.admin.Claim.removeInboundItem/index.html.md)
 - [removeItem](https://docs.medusajs.com/references/js_sdk/admin/Claim/methods/js_sdk.admin.Claim.removeItem/index.html.md)
-- [request](https://docs.medusajs.com/references/js_sdk/admin/Claim/methods/js_sdk.admin.Claim.request/index.html.md)
+- [list](https://docs.medusajs.com/references/js_sdk/admin/Claim/methods/js_sdk.admin.Claim.list/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)
+- [request](https://docs.medusajs.com/references/js_sdk/admin/Claim/methods/js_sdk.admin.Claim.request/index.html.md)
 - [retrieve](https://docs.medusajs.com/references/js_sdk/admin/Claim/methods/js_sdk.admin.Claim.retrieve/index.html.md)
 - [updateInboundShipping](https://docs.medusajs.com/references/js_sdk/admin/Claim/methods/js_sdk.admin.Claim.updateInboundShipping/index.html.md)
+- [updateInboundItem](https://docs.medusajs.com/references/js_sdk/admin/Claim/methods/js_sdk.admin.Claim.updateInboundItem/index.html.md)
 - [updateOutboundItem](https://docs.medusajs.com/references/js_sdk/admin/Claim/methods/js_sdk.admin.Claim.updateOutboundItem/index.html.md)
-- [updateItem](https://docs.medusajs.com/references/js_sdk/admin/Claim/methods/js_sdk.admin.Claim.updateItem/index.html.md)
 - [updateOutboundShipping](https://docs.medusajs.com/references/js_sdk/admin/Claim/methods/js_sdk.admin.Claim.updateOutboundShipping/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)
-- [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)
-- [getJwtHeader\_](https://docs.medusajs.com/references/js_sdk/admin/Client/methods/js_sdk.admin.Client.getJwtHeader_/index.html.md)
-- [getPublishableKeyHeader\_](https://docs.medusajs.com/references/js_sdk/admin/Client/methods/js_sdk.admin.Client.getPublishableKeyHeader_/index.html.md)
-- [getTokenStorageInfo\_](https://docs.medusajs.com/references/js_sdk/admin/Client/methods/js_sdk.admin.Client.getTokenStorageInfo_/index.html.md)
-- [initClient](https://docs.medusajs.com/references/js_sdk/admin/Client/methods/js_sdk.admin.Client.initClient/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)
-- [throwError\_](https://docs.medusajs.com/references/js_sdk/admin/Client/methods/js_sdk.admin.Client.throwError_/index.html.md)
-- [getToken\_](https://docs.medusajs.com/references/js_sdk/admin/Client/methods/js_sdk.admin.Client.getToken_/index.html.md)
+- [updateItem](https://docs.medusajs.com/references/js_sdk/admin/Claim/methods/js_sdk.admin.Claim.updateItem/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)
-- [list](https://docs.medusajs.com/references/js_sdk/admin/Currency/methods/js_sdk.admin.Currency.list/index.html.md)
 - [setItem](https://docs.medusajs.com/references/js_sdk/admin/CustomStorage/methods/js_sdk.admin.CustomStorage.setItem/index.html.md)
-- [retrieve](https://docs.medusajs.com/references/js_sdk/admin/Currency/methods/js_sdk.admin.Currency.retrieve/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)
+- [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)
 - [batchCustomerGroups](https://docs.medusajs.com/references/js_sdk/admin/Customer/methods/js_sdk.admin.Customer.batchCustomerGroups/index.html.md)
+- [update](https://docs.medusajs.com/references/js_sdk/admin/CustomerGroup/methods/js_sdk.admin.CustomerGroup.update/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)
 - [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)
+- [delete](https://docs.medusajs.com/references/js_sdk/admin/Customer/methods/js_sdk.admin.Customer.delete/index.html.md)
+- [retrieve](https://docs.medusajs.com/references/js_sdk/admin/Customer/methods/js_sdk.admin.Customer.retrieve/index.html.md)
 - [listAddresses](https://docs.medusajs.com/references/js_sdk/admin/Customer/methods/js_sdk.admin.Customer.listAddresses/index.html.md)
-- [removeItem](https://docs.medusajs.com/references/js_sdk/admin/CustomStorage/methods/js_sdk.admin.CustomStorage.removeItem/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)
-- [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)
 - [addItems](https://docs.medusajs.com/references/js_sdk/admin/DraftOrder/methods/js_sdk.admin.DraftOrder.addItems/index.html.md)
 - [addPromotions](https://docs.medusajs.com/references/js_sdk/admin/DraftOrder/methods/js_sdk.admin.DraftOrder.addPromotions/index.html.md)
 - [addShippingMethod](https://docs.medusajs.com/references/js_sdk/admin/DraftOrder/methods/js_sdk.admin.DraftOrder.addShippingMethod/index.html.md)
@@ -58897,7 +59074,6 @@ To learn more about the commerce features that Medusa provides, check out Medusa
 - [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)
-- [delete](https://docs.medusajs.com/references/js_sdk/admin/CustomerGroup/methods/js_sdk.admin.CustomerGroup.delete/index.html.md)
 - [removeActionShippingMethod](https://docs.medusajs.com/references/js_sdk/admin/DraftOrder/methods/js_sdk.admin.DraftOrder.removeActionShippingMethod/index.html.md)
 - [removePromotions](https://docs.medusajs.com/references/js_sdk/admin/DraftOrder/methods/js_sdk.admin.DraftOrder.removePromotions/index.html.md)
 - [requestEdit](https://docs.medusajs.com/references/js_sdk/admin/DraftOrder/methods/js_sdk.admin.DraftOrder.requestEdit/index.html.md)
@@ -58907,269 +59083,262 @@ To learn more about the commerce features that Medusa provides, check out Medusa
 - [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)
 - [updateItem](https://docs.medusajs.com/references/js_sdk/admin/DraftOrder/methods/js_sdk.admin.DraftOrder.updateItem/index.html.md)
-- [retrieve](https://docs.medusajs.com/references/js_sdk/admin/Customer/methods/js_sdk.admin.Customer.retrieve/index.html.md)
-- [addInboundItems](https://docs.medusajs.com/references/js_sdk/admin/Exchange/methods/js_sdk.admin.Exchange.addInboundItems/index.html.md)
-- [addInboundShipping](https://docs.medusajs.com/references/js_sdk/admin/Exchange/methods/js_sdk.admin.Exchange.addInboundShipping/index.html.md)
 - [updateShippingMethod](https://docs.medusajs.com/references/js_sdk/admin/DraftOrder/methods/js_sdk.admin.DraftOrder.updateShippingMethod/index.html.md)
+- [addInboundItems](https://docs.medusajs.com/references/js_sdk/admin/Exchange/methods/js_sdk.admin.Exchange.addInboundItems/index.html.md)
 - [addOutboundItems](https://docs.medusajs.com/references/js_sdk/admin/Exchange/methods/js_sdk.admin.Exchange.addOutboundItems/index.html.md)
+- [addInboundShipping](https://docs.medusajs.com/references/js_sdk/admin/Exchange/methods/js_sdk.admin.Exchange.addInboundShipping/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)
+- [create](https://docs.medusajs.com/references/js_sdk/admin/Exchange/methods/js_sdk.admin.Exchange.create/index.html.md)
+- [cancel](https://docs.medusajs.com/references/js_sdk/admin/Exchange/methods/js_sdk.admin.Exchange.cancel/index.html.md)
 - [deleteInboundShipping](https://docs.medusajs.com/references/js_sdk/admin/Exchange/methods/js_sdk.admin.Exchange.deleteInboundShipping/index.html.md)
 - [deleteOutboundShipping](https://docs.medusajs.com/references/js_sdk/admin/Exchange/methods/js_sdk.admin.Exchange.deleteOutboundShipping/index.html.md)
-- [cancel](https://docs.medusajs.com/references/js_sdk/admin/Exchange/methods/js_sdk.admin.Exchange.cancel/index.html.md)
-- [removeInboundItem](https://docs.medusajs.com/references/js_sdk/admin/Exchange/methods/js_sdk.admin.Exchange.removeInboundItem/index.html.md)
-- [request](https://docs.medusajs.com/references/js_sdk/admin/Exchange/methods/js_sdk.admin.Exchange.request/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)
-- [updateInboundShipping](https://docs.medusajs.com/references/js_sdk/admin/Exchange/methods/js_sdk.admin.Exchange.updateInboundShipping/index.html.md)
-- [updateInboundItem](https://docs.medusajs.com/references/js_sdk/admin/Exchange/methods/js_sdk.admin.Exchange.updateInboundItem/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)
+- [request](https://docs.medusajs.com/references/js_sdk/admin/Exchange/methods/js_sdk.admin.Exchange.request/index.html.md)
+- [retrieve](https://docs.medusajs.com/references/js_sdk/admin/Exchange/methods/js_sdk.admin.Exchange.retrieve/index.html.md)
 - [updateOutboundItem](https://docs.medusajs.com/references/js_sdk/admin/Exchange/methods/js_sdk.admin.Exchange.updateOutboundItem/index.html.md)
+- [updateInboundItem](https://docs.medusajs.com/references/js_sdk/admin/Exchange/methods/js_sdk.admin.Exchange.updateInboundItem/index.html.md)
 - [updateOutboundShipping](https://docs.medusajs.com/references/js_sdk/admin/Exchange/methods/js_sdk.admin.Exchange.updateOutboundShipping/index.html.md)
+- [updateInboundShipping](https://docs.medusajs.com/references/js_sdk/admin/Exchange/methods/js_sdk.admin.Exchange.updateInboundShipping/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)
 - [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)
-- [list](https://docs.medusajs.com/references/js_sdk/admin/FulfillmentProvider/methods/js_sdk.admin.FulfillmentProvider.list/index.html.md)
-- [create](https://docs.medusajs.com/references/js_sdk/admin/Exchange/methods/js_sdk.admin.Exchange.create/index.html.md)
-- [listFulfillmentOptions](https://docs.medusajs.com/references/js_sdk/admin/FulfillmentProvider/methods/js_sdk.admin.FulfillmentProvider.listFulfillmentOptions/index.html.md)
 - [batchInventoryItemLocationLevels](https://docs.medusajs.com/references/js_sdk/admin/InventoryItem/methods/js_sdk.admin.InventoryItem.batchInventoryItemLocationLevels/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/Fulfillment/methods/js_sdk.admin.Fulfillment.create/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)
 - [delete](https://docs.medusajs.com/references/js_sdk/admin/InventoryItem/methods/js_sdk.admin.InventoryItem.delete/index.html.md)
+- [create](https://docs.medusajs.com/references/js_sdk/admin/InventoryItem/methods/js_sdk.admin.InventoryItem.create/index.html.md)
 - [deleteLevel](https://docs.medusajs.com/references/js_sdk/admin/InventoryItem/methods/js_sdk.admin.InventoryItem.deleteLevel/index.html.md)
 - [list](https://docs.medusajs.com/references/js_sdk/admin/InventoryItem/methods/js_sdk.admin.InventoryItem.list/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)
 - [update](https://docs.medusajs.com/references/js_sdk/admin/InventoryItem/methods/js_sdk.admin.InventoryItem.update/index.html.md)
 - [updateLevel](https://docs.medusajs.com/references/js_sdk/admin/InventoryItem/methods/js_sdk.admin.InventoryItem.updateLevel/index.html.md)
-- [create](https://docs.medusajs.com/references/js_sdk/admin/InventoryItem/methods/js_sdk.admin.InventoryItem.create/index.html.md)
-- [create](https://docs.medusajs.com/references/js_sdk/admin/Campaign/methods/js_sdk.admin.Campaign.create/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)
-- [batchPromotions](https://docs.medusajs.com/references/js_sdk/admin/Campaign/methods/js_sdk.admin.Campaign.batchPromotions/index.html.md)
-- [retrieve](https://docs.medusajs.com/references/js_sdk/admin/Campaign/methods/js_sdk.admin.Campaign.retrieve/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/InventoryItem/methods/js_sdk.admin.InventoryItem.retrieve/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)
+- [delete](https://docs.medusajs.com/references/js_sdk/admin/Invite/methods/js_sdk.admin.Invite.delete/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)
-- [delete](https://docs.medusajs.com/references/js_sdk/admin/Invite/methods/js_sdk.admin.Invite.delete/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)
-- [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)
-- [list](https://docs.medusajs.com/references/js_sdk/admin/Order/methods/js_sdk.admin.Order.list/index.html.md)
-- [createFulfillment](https://docs.medusajs.com/references/js_sdk/admin/Order/methods/js_sdk.admin.Order.createFulfillment/index.html.md)
-- [listChanges](https://docs.medusajs.com/references/js_sdk/admin/Order/methods/js_sdk.admin.Order.listChanges/index.html.md)
-- [listLineItems](https://docs.medusajs.com/references/js_sdk/admin/Order/methods/js_sdk.admin.Order.listLineItems/index.html.md)
-- [retrieve](https://docs.medusajs.com/references/js_sdk/admin/Order/methods/js_sdk.admin.Order.retrieve/index.html.md)
-- [requestTransfer](https://docs.medusajs.com/references/js_sdk/admin/Order/methods/js_sdk.admin.Order.requestTransfer/index.html.md)
-- [markAsDelivered](https://docs.medusajs.com/references/js_sdk/admin/Order/methods/js_sdk.admin.Order.markAsDelivered/index.html.md)
-- [retrievePreview](https://docs.medusajs.com/references/js_sdk/admin/Order/methods/js_sdk.admin.Order.retrievePreview/index.html.md)
-- [cancelTransfer](https://docs.medusajs.com/references/js_sdk/admin/Order/methods/js_sdk.admin.Order.cancelTransfer/index.html.md)
-- [update](https://docs.medusajs.com/references/js_sdk/admin/Order/methods/js_sdk.admin.Order.update/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/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)
 - [list](https://docs.medusajs.com/references/js_sdk/admin/Notification/methods/js_sdk.admin.Notification.list/index.html.md)
-- [cancelRequest](https://docs.medusajs.com/references/js_sdk/admin/OrderEdit/methods/js_sdk.admin.OrderEdit.cancelRequest/index.html.md)
+- [retrieve](https://docs.medusajs.com/references/js_sdk/admin/Notification/methods/js_sdk.admin.Notification.retrieve/index.html.md)
 - [addItems](https://docs.medusajs.com/references/js_sdk/admin/OrderEdit/methods/js_sdk.admin.OrderEdit.addItems/index.html.md)
+- [cancelRequest](https://docs.medusajs.com/references/js_sdk/admin/OrderEdit/methods/js_sdk.admin.OrderEdit.cancelRequest/index.html.md)
 - [confirm](https://docs.medusajs.com/references/js_sdk/admin/OrderEdit/methods/js_sdk.admin.OrderEdit.confirm/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)
 - [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)
-- [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)
-- [updateServiceZone](https://docs.medusajs.com/references/js_sdk/admin/FulfillmentSet/methods/js_sdk.admin.FulfillmentSet.updateServiceZone/index.html.md)
 - [capture](https://docs.medusajs.com/references/js_sdk/admin/Payment/methods/js_sdk.admin.Payment.capture/index.html.md)
-- [listPaymentProviders](https://docs.medusajs.com/references/js_sdk/admin/Payment/methods/js_sdk.admin.Payment.listPaymentProviders/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)
-- [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/Plugin/methods/js_sdk.admin.Plugin.list/index.html.md)
+- [retrieve](https://docs.medusajs.com/references/js_sdk/admin/Payment/methods/js_sdk.admin.Payment.retrieve/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)
+- [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)
+- [list](https://docs.medusajs.com/references/js_sdk/admin/Order/methods/js_sdk.admin.Order.list/index.html.md)
+- [listChanges](https://docs.medusajs.com/references/js_sdk/admin/Order/methods/js_sdk.admin.Order.listChanges/index.html.md)
+- [createFulfillment](https://docs.medusajs.com/references/js_sdk/admin/Order/methods/js_sdk.admin.Order.createFulfillment/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)
+- [batchPrices](https://docs.medusajs.com/references/js_sdk/admin/PriceList/methods/js_sdk.admin.PriceList.batchPrices/index.html.md)
+- [delete](https://docs.medusajs.com/references/js_sdk/admin/PriceList/methods/js_sdk.admin.PriceList.delete/index.html.md)
+- [create](https://docs.medusajs.com/references/js_sdk/admin/PriceList/methods/js_sdk.admin.PriceList.create/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)
 - [create](https://docs.medusajs.com/references/js_sdk/admin/PricePreference/methods/js_sdk.admin.PricePreference.create/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)
 - [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)
+- [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)
 - [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)
+- [batchVariantInventoryItems](https://docs.medusajs.com/references/js_sdk/admin/Product/methods/js_sdk.admin.Product.batchVariantInventoryItems/index.html.md)
 - [create](https://docs.medusajs.com/references/js_sdk/admin/Product/methods/js_sdk.admin.Product.create/index.html.md)
+- [batchVariants](https://docs.medusajs.com/references/js_sdk/admin/Product/methods/js_sdk.admin.Product.batchVariants/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)
-- [batchVariants](https://docs.medusajs.com/references/js_sdk/admin/Product/methods/js_sdk.admin.Product.batchVariants/index.html.md)
 - [delete](https://docs.medusajs.com/references/js_sdk/admin/Product/methods/js_sdk.admin.Product.delete/index.html.md)
 - [deleteOption](https://docs.medusajs.com/references/js_sdk/admin/Product/methods/js_sdk.admin.Product.deleteOption/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)
 - [deleteVariant](https://docs.medusajs.com/references/js_sdk/admin/Product/methods/js_sdk.admin.Product.deleteVariant/index.html.md)
-- [listOptions](https://docs.medusajs.com/references/js_sdk/admin/Product/methods/js_sdk.admin.Product.listOptions/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)
-- [retrieve](https://docs.medusajs.com/references/js_sdk/admin/Product/methods/js_sdk.admin.Product.retrieve/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)
 - [retrieveOption](https://docs.medusajs.com/references/js_sdk/admin/Product/methods/js_sdk.admin.Product.retrieveOption/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)
+- [create](https://docs.medusajs.com/references/js_sdk/admin/ProductCategory/methods/js_sdk.admin.ProductCategory.create/index.html.md)
+- [list](https://docs.medusajs.com/references/js_sdk/admin/ProductCategory/methods/js_sdk.admin.ProductCategory.list/index.html.md)
 - [updateVariant](https://docs.medusajs.com/references/js_sdk/admin/Product/methods/js_sdk.admin.Product.updateVariant/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)
-- [batchPrices](https://docs.medusajs.com/references/js_sdk/admin/PriceList/methods/js_sdk.admin.PriceList.batchPrices/index.html.md)
-- [delete](https://docs.medusajs.com/references/js_sdk/admin/PriceList/methods/js_sdk.admin.PriceList.delete/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)
-- [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)
+- [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)
+- [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)
 - [create](https://docs.medusajs.com/references/js_sdk/admin/ProductTag/methods/js_sdk.admin.ProductTag.create/index.html.md)
 - [delete](https://docs.medusajs.com/references/js_sdk/admin/ProductTag/methods/js_sdk.admin.ProductTag.delete/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/ProductCollection/methods/js_sdk.admin.ProductCollection.delete/index.html.md)
+- [retrieve](https://docs.medusajs.com/references/js_sdk/admin/ProductTag/methods/js_sdk.admin.ProductTag.retrieve/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)
-- [create](https://docs.medusajs.com/references/js_sdk/admin/ProductCollection/methods/js_sdk.admin.ProductCollection.create/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)
+- [addRules](https://docs.medusajs.com/references/js_sdk/admin/Promotion/methods/js_sdk.admin.Promotion.addRules/index.html.md)
+- [update](https://docs.medusajs.com/references/js_sdk/admin/ProductCollection/methods/js_sdk.admin.ProductCollection.update/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)
+- [listRuleValues](https://docs.medusajs.com/references/js_sdk/admin/Promotion/methods/js_sdk.admin.Promotion.listRuleValues/index.html.md)
+- [list](https://docs.medusajs.com/references/js_sdk/admin/Promotion/methods/js_sdk.admin.Promotion.list/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)
+- [update](https://docs.medusajs.com/references/js_sdk/admin/Promotion/methods/js_sdk.admin.Promotion.update/index.html.md)
+- [retrieve](https://docs.medusajs.com/references/js_sdk/admin/Promotion/methods/js_sdk.admin.Promotion.retrieve/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/ProductType/methods/js_sdk.admin.ProductType.create/index.html.md)
 - [list](https://docs.medusajs.com/references/js_sdk/admin/ProductType/methods/js_sdk.admin.ProductType.list/index.html.md)
 - [delete](https://docs.medusajs.com/references/js_sdk/admin/ProductType/methods/js_sdk.admin.ProductType.delete/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)
 - [list](https://docs.medusajs.com/references/js_sdk/admin/RefundReason/methods/js_sdk.admin.RefundReason.list/index.html.md)
+- [delete](https://docs.medusajs.com/references/js_sdk/admin/ReturnReason/methods/js_sdk.admin.ReturnReason.delete/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/ProductVariant/methods/js_sdk.admin.ProductVariant.list/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)
-- [create](https://docs.medusajs.com/references/js_sdk/admin/ProductCategory/methods/js_sdk.admin.ProductCategory.create/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)
-- [addRules](https://docs.medusajs.com/references/js_sdk/admin/Promotion/methods/js_sdk.admin.Promotion.addRules/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/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)
-- [list](https://docs.medusajs.com/references/js_sdk/admin/Promotion/methods/js_sdk.admin.Promotion.list/index.html.md)
-- [listRuleAttributes](https://docs.medusajs.com/references/js_sdk/admin/Promotion/methods/js_sdk.admin.Promotion.listRuleAttributes/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)
-- [removeRules](https://docs.medusajs.com/references/js_sdk/admin/Promotion/methods/js_sdk.admin.Promotion.removeRules/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)
-- [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/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)
-- [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)
-- [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/Reservation/methods/js_sdk.admin.Reservation.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)
-- [retrieve](https://docs.medusajs.com/references/js_sdk/admin/SalesChannel/methods/js_sdk.admin.SalesChannel.retrieve/index.html.md)
-- [list](https://docs.medusajs.com/references/js_sdk/admin/SalesChannel/methods/js_sdk.admin.SalesChannel.list/index.html.md)
-- [update](https://docs.medusajs.com/references/js_sdk/admin/SalesChannel/methods/js_sdk.admin.SalesChannel.update/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/ReturnReason/methods/js_sdk.admin.ReturnReason.update/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)
-- [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/Region/methods/js_sdk.admin.Region.list/index.html.md)
-- [addReturnItem](https://docs.medusajs.com/references/js_sdk/admin/Return/methods/js_sdk.admin.Return.addReturnItem/index.html.md)
 - [retrieve](https://docs.medusajs.com/references/js_sdk/admin/Region/methods/js_sdk.admin.Region.retrieve/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)
-- [deleteReturnShipping](https://docs.medusajs.com/references/js_sdk/admin/Return/methods/js_sdk.admin.Return.deleteReturnShipping/index.html.md)
-- [confirmRequest](https://docs.medusajs.com/references/js_sdk/admin/Return/methods/js_sdk.admin.Return.confirmRequest/index.html.md)
-- [initiateReceive](https://docs.medusajs.com/references/js_sdk/admin/Return/methods/js_sdk.admin.Return.initiateReceive/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)
-- [initiateRequest](https://docs.medusajs.com/references/js_sdk/admin/Return/methods/js_sdk.admin.Return.initiateRequest/index.html.md)
-- [receiveItems](https://docs.medusajs.com/references/js_sdk/admin/Return/methods/js_sdk.admin.Return.receiveItems/index.html.md)
-- [removeReceiveItem](https://docs.medusajs.com/references/js_sdk/admin/Return/methods/js_sdk.admin.Return.removeReceiveItem/index.html.md)
-- [removeDismissItem](https://docs.medusajs.com/references/js_sdk/admin/Return/methods/js_sdk.admin.Return.removeDismissItem/index.html.md)
-- [retrieve](https://docs.medusajs.com/references/js_sdk/admin/Return/methods/js_sdk.admin.Return.retrieve/index.html.md)
-- [removeReturnItem](https://docs.medusajs.com/references/js_sdk/admin/Return/methods/js_sdk.admin.Return.removeReturnItem/index.html.md)
-- [updateDismissItem](https://docs.medusajs.com/references/js_sdk/admin/Return/methods/js_sdk.admin.Return.updateDismissItem/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)
-- [updateReturnShipping](https://docs.medusajs.com/references/js_sdk/admin/Return/methods/js_sdk.admin.Return.updateReturnShipping/index.html.md)
-- [updateReturnItem](https://docs.medusajs.com/references/js_sdk/admin/Return/methods/js_sdk.admin.Return.updateReturnItem/index.html.md)
-- [create](https://docs.medusajs.com/references/js_sdk/admin/ReturnReason/methods/js_sdk.admin.ReturnReason.create/index.html.md)
-- [delete](https://docs.medusajs.com/references/js_sdk/admin/ReturnReason/methods/js_sdk.admin.ReturnReason.delete/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/Region/methods/js_sdk.admin.Region.list/index.html.md)
 - [list](https://docs.medusajs.com/references/js_sdk/admin/ReturnReason/methods/js_sdk.admin.ReturnReason.list/index.html.md)
-- [update](https://docs.medusajs.com/references/js_sdk/admin/ReturnReason/methods/js_sdk.admin.ReturnReason.update/index.html.md)
-- [delete](https://docs.medusajs.com/references/js_sdk/admin/ShippingProfile/methods/js_sdk.admin.ShippingProfile.delete/index.html.md)
+- [update](https://docs.medusajs.com/references/js_sdk/admin/Region/methods/js_sdk.admin.Region.update/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)
+- [retrieve](https://docs.medusajs.com/references/js_sdk/admin/Reservation/methods/js_sdk.admin.Reservation.retrieve/index.html.md)
+- [update](https://docs.medusajs.com/references/js_sdk/admin/Reservation/methods/js_sdk.admin.Reservation.update/index.html.md)
+- [addReturnShipping](https://docs.medusajs.com/references/js_sdk/admin/Return/methods/js_sdk.admin.Return.addReturnShipping/index.html.md)
+- [addReturnItem](https://docs.medusajs.com/references/js_sdk/admin/Return/methods/js_sdk.admin.Return.addReturnItem/index.html.md)
+- [cancelReceive](https://docs.medusajs.com/references/js_sdk/admin/Return/methods/js_sdk.admin.Return.cancelReceive/index.html.md)
+- [cancelRequest](https://docs.medusajs.com/references/js_sdk/admin/Return/methods/js_sdk.admin.Return.cancelRequest/index.html.md)
+- [list](https://docs.medusajs.com/references/js_sdk/admin/Reservation/methods/js_sdk.admin.Reservation.list/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)
+- [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)
+- [initiateRequest](https://docs.medusajs.com/references/js_sdk/admin/Return/methods/js_sdk.admin.Return.initiateRequest/index.html.md)
+- [removeReceiveItem](https://docs.medusajs.com/references/js_sdk/admin/Return/methods/js_sdk.admin.Return.removeReceiveItem/index.html.md)
+- [cancel](https://docs.medusajs.com/references/js_sdk/admin/Return/methods/js_sdk.admin.Return.cancel/index.html.md)
+- [removeReturnItem](https://docs.medusajs.com/references/js_sdk/admin/Return/methods/js_sdk.admin.Return.removeReturnItem/index.html.md)
+- [retrieve](https://docs.medusajs.com/references/js_sdk/admin/Return/methods/js_sdk.admin.Return.retrieve/index.html.md)
+- [removeDismissItem](https://docs.medusajs.com/references/js_sdk/admin/Return/methods/js_sdk.admin.Return.removeDismissItem/index.html.md)
+- [updateDismissItem](https://docs.medusajs.com/references/js_sdk/admin/Return/methods/js_sdk.admin.Return.updateDismissItem/index.html.md)
+- [updateReceiveItem](https://docs.medusajs.com/references/js_sdk/admin/Return/methods/js_sdk.admin.Return.updateReceiveItem/index.html.md)
+- [updateRequest](https://docs.medusajs.com/references/js_sdk/admin/Return/methods/js_sdk.admin.Return.updateRequest/index.html.md)
+- [updateReturnItem](https://docs.medusajs.com/references/js_sdk/admin/Return/methods/js_sdk.admin.Return.updateReturnItem/index.html.md)
+- [batchProducts](https://docs.medusajs.com/references/js_sdk/admin/SalesChannel/methods/js_sdk.admin.SalesChannel.batchProducts/index.html.md)
+- [delete](https://docs.medusajs.com/references/js_sdk/admin/SalesChannel/methods/js_sdk.admin.SalesChannel.delete/index.html.md)
+- [updateReturnShipping](https://docs.medusajs.com/references/js_sdk/admin/Return/methods/js_sdk.admin.Return.updateReturnShipping/index.html.md)
+- [create](https://docs.medusajs.com/references/js_sdk/admin/SalesChannel/methods/js_sdk.admin.SalesChannel.create/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)
+- [updateProducts](https://docs.medusajs.com/references/js_sdk/admin/SalesChannel/methods/js_sdk.admin.SalesChannel.updateProducts/index.html.md)
 - [create](https://docs.medusajs.com/references/js_sdk/admin/ShippingProfile/methods/js_sdk.admin.ShippingProfile.create/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)
 - [list](https://docs.medusajs.com/references/js_sdk/admin/ShippingProfile/methods/js_sdk.admin.ShippingProfile.list/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)
-- [list](https://docs.medusajs.com/references/js_sdk/admin/ShippingOption/methods/js_sdk.admin.ShippingOption.list/index.html.md)
-- [update](https://docs.medusajs.com/references/js_sdk/admin/ShippingOption/methods/js_sdk.admin.ShippingOption.update/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)
 - [retrieve](https://docs.medusajs.com/references/js_sdk/admin/Store/methods/js_sdk.admin.Store.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/SalesChannel/methods/js_sdk.admin.SalesChannel.update/index.html.md)
 - [update](https://docs.medusajs.com/references/js_sdk/admin/Store/methods/js_sdk.admin.Store.update/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)
-- [create](https://docs.medusajs.com/references/js_sdk/admin/TaxRate/methods/js_sdk.admin.TaxRate.create/index.html.md)
-- [list](https://docs.medusajs.com/references/js_sdk/admin/TaxRegion/methods/js_sdk.admin.TaxRegion.list/index.html.md)
-- [list](https://docs.medusajs.com/references/js_sdk/admin/TaxRate/methods/js_sdk.admin.TaxRate.list/index.html.md)
-- [delete](https://docs.medusajs.com/references/js_sdk/admin/TaxRate/methods/js_sdk.admin.TaxRate.delete/index.html.md)
-- [update](https://docs.medusajs.com/references/js_sdk/admin/TaxRate/methods/js_sdk.admin.TaxRate.update/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/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)
+- [update](https://docs.medusajs.com/references/js_sdk/admin/ShippingOption/methods/js_sdk.admin.ShippingOption.update/index.html.md)
+- [updateRules](https://docs.medusajs.com/references/js_sdk/admin/ShippingOption/methods/js_sdk.admin.ShippingOption.updateRules/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)
-- [createFulfillmentSet](https://docs.medusajs.com/references/js_sdk/admin/StockLocation/methods/js_sdk.admin.StockLocation.createFulfillmentSet/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/Upload/methods/js_sdk.admin.Upload.retrieve/index.html.md)
-- [create](https://docs.medusajs.com/references/js_sdk/admin/StockLocation/methods/js_sdk.admin.StockLocation.create/index.html.md)
-- [list](https://docs.medusajs.com/references/js_sdk/admin/StockLocation/methods/js_sdk.admin.StockLocation.list/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)
-- [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)
-- [updateSalesChannels](https://docs.medusajs.com/references/js_sdk/admin/StockLocation/methods/js_sdk.admin.StockLocation.updateSalesChannels/index.html.md)
-- [retrieve](https://docs.medusajs.com/references/js_sdk/admin/WorkflowExecution/methods/js_sdk.admin.WorkflowExecution.retrieve/index.html.md)
+- [create](https://docs.medusajs.com/references/js_sdk/admin/TaxRegion/methods/js_sdk.admin.TaxRegion.create/index.html.md)
+- [list](https://docs.medusajs.com/references/js_sdk/admin/TaxRegion/methods/js_sdk.admin.TaxRegion.list/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/User/methods/js_sdk.admin.User.delete/index.html.md)
+- [list](https://docs.medusajs.com/references/js_sdk/admin/ShippingOption/methods/js_sdk.admin.ShippingOption.list/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/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)
-- [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/User/methods/js_sdk.admin.User.retrieve/index.html.md)
+- [create](https://docs.medusajs.com/references/js_sdk/admin/TaxRate/methods/js_sdk.admin.TaxRate.create/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/TaxRate/methods/js_sdk.admin.TaxRate.delete/index.html.md)
+- [list](https://docs.medusajs.com/references/js_sdk/admin/TaxRate/methods/js_sdk.admin.TaxRate.list/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)
+- [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)
+- [delete](https://docs.medusajs.com/references/js_sdk/admin/StockLocation/methods/js_sdk.admin.StockLocation.delete/index.html.md)
+- [update](https://docs.medusajs.com/references/js_sdk/admin/TaxRate/methods/js_sdk.admin.TaxRate.update/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)
+- [updateFulfillmentProviders](https://docs.medusajs.com/references/js_sdk/admin/StockLocation/methods/js_sdk.admin.StockLocation.updateFulfillmentProviders/index.html.md)
+- [updateSalesChannels](https://docs.medusajs.com/references/js_sdk/admin/StockLocation/methods/js_sdk.admin.StockLocation.updateSalesChannels/index.html.md)
+- [retrieve](https://docs.medusajs.com/references/js_sdk/admin/TaxRate/methods/js_sdk.admin.TaxRate.retrieve/index.html.md)
+- [update](https://docs.medusajs.com/references/js_sdk/admin/StockLocation/methods/js_sdk.admin.StockLocation.update/index.html.md)
 
 
 ## JS SDK Auth
 
 - [callback](https://docs.medusajs.com/references/js-sdk/auth/callback/index.html.md)
-- [logout](https://docs.medusajs.com/references/js-sdk/auth/logout/index.html.md)
-- [login](https://docs.medusajs.com/references/js-sdk/auth/login/index.html.md)
+- [refresh](https://docs.medusajs.com/references/js-sdk/auth/refresh/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)
-- [refresh](https://docs.medusajs.com/references/js-sdk/auth/refresh/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)
+- [logout](https://docs.medusajs.com/references/js-sdk/auth/logout/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)
 - [collection](https://docs.medusajs.com/references/js-sdk/store/collection/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)
-- [category](https://docs.medusajs.com/references/js-sdk/store/category/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)
-- [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)
+- [product](https://docs.medusajs.com/references/js-sdk/store/product/index.html.md)
+- [region](https://docs.medusajs.com/references/js-sdk/store/region/index.html.md)
 
 
 # Configure Medusa Backend
@@ -59822,65 +59991,6 @@ These layout components allow you to set the layout of your [UI routes](https://
 These components allow you to use common Medusa Admin components in your custom UI routes and widgets.
 
 
-# Container - Admin Components
-
-The Medusa Admin wraps each section of a page in a container.
-
-![Example of a container in the Medusa Admin](https://res.cloudinary.com/dza7lstvk/image/upload/v1728287102/Medusa%20Resources/container_soenir.png)
-
-To create a component that uses the same container styling in your widgets or UI routes, create the file `src/admin/components/container.tsx` with the following content:
-
-```tsx
-import { 
-  Container as UiContainer,
-  clx,
-} from "@medusajs/ui"
-
-type ContainerProps = React.ComponentProps<typeof UiContainer>
-
-export const Container = (props: ContainerProps) => {
-  return (
-    <UiContainer {...props} className={clx(
-      "divide-y p-0",
-      props.className
-    )} />
-  )
-}
-```
-
-The `Container` component re-uses the component from the [Medusa UI package](https://docs.medusajs.com/ui/components/container/index.html.md) and applies to it classes to match the Medusa Admin's design conventions.
-
-***
-
-## Example
-
-Use that `Container` component in any 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"
-
-const ProductWidget = () => {
-  return (
-    <Container>
-      <Header title="Product Widget" />
-    </Container>
-  )
-}
-
-export const config = defineWidgetConfig({
-  zone: "product.details.before",
-})
-
-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.
-
-
 # Action Menu - Admin Components
 
 The Medusa Admin often provides additional actions in a dropdown shown when users click a three-dot icon.
@@ -60106,222 +60216,140 @@ export default ProductWidget
 ```
 
 
-# JSON View - Admin Components
+# Header - Admin Components
 
-Detail pages in the Medusa Admin show a JSON section to view the current page's details in JSON format.
+Each section in the Medusa Admin has a header with a title, and optionally a subtitle with buttons to perform an action.
 
-![Example of a JSON section in the admin](https://res.cloudinary.com/dza7lstvk/image/upload/v1728295129/Medusa%20Resources/json_dtbsgm.png)
+![Example of a header in a section](https://res.cloudinary.com/dza7lstvk/image/upload/v1728288562/Medusa%20Resources/header_dtz4gl.png)
 
-To create a component that shows a JSON section in your customizations, create the file `src/admin/components/json-view-section.tsx` with the following content:
+To create a component that uses the same header styling and structure, create the file `src/admin/components/header.tsx` with the following content:
 
-```tsx title="src/admin/components/json-view-section.tsx"
-import {
-  ArrowUpRightOnBox,
-  Check,
-  SquareTwoStack,
-  TriangleDownMini,
-  XMarkMini,
-} from "@medusajs/icons"
-import {
-  Badge,
-  Container,
-  Drawer,
-  Heading,
-  IconButton,
-  Kbd,
-} from "@medusajs/ui"
-import Primitive from "@uiw/react-json-view"
-import { CSSProperties, MouseEvent, Suspense, useState } from "react"
+```tsx title="src/admin/components/header.tsx"
+import { Heading, Button, Text } from "@medusajs/ui"
+import React from "react"
+import { Link, LinkProps } from "react-router-dom"
+import { ActionMenu, ActionMenuProps } from "./action-menu"
 
-type JsonViewSectionProps = {
-  data: object
-  title?: string
-}
-
-export const JsonViewSection = ({ data }: JsonViewSectionProps) => {
-  const numberOfKeys = Object.keys(data).length
-
-  return (
-    <Container className="flex items-center justify-between px-6 py-4">
-      <div className="flex items-center gap-x-4">
-        <Heading level="h2">JSON</Heading>
-        <Badge size="2xsmall" rounded="full">
-          {numberOfKeys} keys
-        </Badge>
-      </div>
-      <Drawer>
-        <Drawer.Trigger asChild>
-          <IconButton
-            size="small"
-            variant="transparent"
-            className="text-ui-fg-muted hover:text-ui-fg-subtle"
-          >
-            <ArrowUpRightOnBox />
-          </IconButton>
-        </Drawer.Trigger>
-        <Drawer.Content className="bg-ui-contrast-bg-base text-ui-code-fg-subtle !shadow-elevation-commandbar overflow-hidden border border-none max-md:inset-x-2 max-md:max-w-[calc(100%-16px)]">
-          <div className="bg-ui-code-bg-base flex items-center justify-between px-6 py-4">
-            <div className="flex items-center gap-x-4">
-              <Drawer.Title asChild>
-                <Heading className="text-ui-contrast-fg-primary">
-                <span className="text-ui-fg-subtle">
-                  {numberOfKeys}
-                </span>
-                </Heading>
-              </Drawer.Title>
-            </div>
-            <div className="flex items-center gap-x-2">
-              <Kbd className="bg-ui-contrast-bg-subtle border-ui-contrast-border-base text-ui-contrast-fg-secondary">
-                esc
-              </Kbd>
-              <Drawer.Close asChild>
-                <IconButton
-                  size="small"
-                  variant="transparent"
-                  className="text-ui-contrast-fg-secondary hover:text-ui-contrast-fg-primary hover:bg-ui-contrast-bg-base-hover active:bg-ui-contrast-bg-base-pressed focus-visible:bg-ui-contrast-bg-base-hover focus-visible:shadow-borders-interactive-with-active"
-                >
-                  <XMarkMini />
-                </IconButton>
-              </Drawer.Close>
-            </div>
-          </div>
-          <Drawer.Body className="flex flex-1 flex-col overflow-hidden px-[5px] py-0 pb-[5px]">
-            <div className="bg-ui-contrast-bg-subtle flex-1 overflow-auto rounded-b-[4px] rounded-t-lg p-3">
-              <Suspense
-                fallback={<div className="flex size-full flex-col"></div>}
-              >
-                <Primitive
-                  value={data}
-                  displayDataTypes={false}
-                  style={
-                    {
-                      "--w-rjv-font-family": "Roboto Mono, monospace",
-                      "--w-rjv-line-color": "var(--contrast-border-base)",
-                      "--w-rjv-curlybraces-color":
-                        "var(--contrast-fg-secondary)",
-                      "--w-rjv-brackets-color": "var(--contrast-fg-secondary)",
-                      "--w-rjv-key-string": "var(--contrast-fg-primary)",
-                      "--w-rjv-info-color": "var(--contrast-fg-secondary)",
-                      "--w-rjv-type-string-color": "var(--tag-green-icon)",
-                      "--w-rjv-quotes-string-color": "var(--tag-green-icon)",
-                      "--w-rjv-type-boolean-color": "var(--tag-orange-icon)",
-                      "--w-rjv-type-int-color": "var(--tag-orange-icon)",
-                      "--w-rjv-type-float-color": "var(--tag-orange-icon)",
-                      "--w-rjv-type-bigint-color": "var(--tag-orange-icon)",
-                      "--w-rjv-key-number": "var(--contrast-fg-secondary)",
-                      "--w-rjv-arrow-color": "var(--contrast-fg-secondary)",
-                      "--w-rjv-copied-color": "var(--contrast-fg-secondary)",
-                      "--w-rjv-copied-success-color":
-                        "var(--contrast-fg-primary)",
-                      "--w-rjv-colon-color": "var(--contrast-fg-primary)",
-                      "--w-rjv-ellipsis-color": "var(--contrast-fg-secondary)",
-                    } as CSSProperties
-                  }
-                  collapsed={1}
-                >
-                  <Primitive.Quote render={() => <span />} />
-                  <Primitive.Null
-                    render={() => (
-                      <span className="text-ui-tag-red-icon">null</span>
-                    )}
-                  />
-                  <Primitive.Undefined
-                    render={() => (
-                      <span className="text-ui-tag-blue-icon">undefined</span>
-                    )}
-                  />
-                  <Primitive.CountInfo
-                    render={(_props, { value }) => {
-                      return (
-                        <span className="text-ui-contrast-fg-secondary ml-2">
-                          {Object.keys(value as object).length} items
-                        </span>
-                      )
-                    }}
-                  />
-                  <Primitive.Arrow>
-                    <TriangleDownMini className="text-ui-contrast-fg-secondary -ml-[0.5px]" />
-                  </Primitive.Arrow>
-                  <Primitive.Colon>
-                    <span className="mr-1">:</span>
-                  </Primitive.Colon>
-                  <Primitive.Copied
-                    render={({ style }, { value }) => {
-                      return <Copied style={style} value={value} />
-                    }}
-                  />
-                </Primitive>
-              </Suspense>
-            </div>
-          </Drawer.Body>
-        </Drawer.Content>
-      </Drawer>
-    </Container>
-  )
-}
-
-type CopiedProps = {
-  style?: CSSProperties
-  value: object | undefined
-}
-
-const Copied = ({ style, value }: CopiedProps) => {
-  const [copied, setCopied] = useState(false)
-
-  const handler = (e: MouseEvent<HTMLSpanElement>) => {
-    e.stopPropagation()
-    setCopied(true)
-
-    if (typeof value === "string") {
-      navigator.clipboard.writeText(value)
-    } else {
-      const json = JSON.stringify(value, null, 2)
-      navigator.clipboard.writeText(json)
+export type HeadingProps = {
+  title: string
+  subtitle?: string
+  actions?: (
+    {
+      type: "button",
+      props: React.ComponentProps<typeof Button>
+      link?: LinkProps
+    } |  
+    {
+      type: "action-menu"
+      props: ActionMenuProps
+    } |
+    {
+      type: "custom"
+      children: React.ReactNode
     }
+  )[]
+}
 
-    setTimeout(() => {
-      setCopied(false)
-    }, 2000)
-  }
-
-  const styl = { whiteSpace: "nowrap", width: "20px" }
-
-  if (copied) {
-    return (
-      <span style={{ ...style, ...styl }}>
-        <Check className="text-ui-contrast-fg-primary" />
-      </span>
-    )
-  }
-
+export const Header = ({
+  title,
+  subtitle,
+  actions = [],
+}: HeadingProps) => {
   return (
-    <span style={{ ...style, ...styl }} onClick={handler}>
-      <SquareTwoStack className="text-ui-contrast-fg-secondary" />
-    </span>
+    <div className="flex items-center justify-between px-6 py-4">
+      <div>
+        <Heading level="h2">{title}</Heading>
+        {subtitle && (
+          <Text className="text-ui-fg-subtle" size="small">
+            {subtitle}
+          </Text>
+        )}
+      </div>
+      {actions.length > 0 && (
+        <div className="flex items-center justify-center gap-x-2">
+          {actions.map((action, index) => (
+            <>
+              {action.type === "button" && (
+                <Button 
+                  {...action.props} 
+                  size={action.props.size || "small"}
+                  key={index}
+                >
+                  <>
+                    {action.props.children}
+                    {action.link && <Link {...action.link} />}
+                  </>
+                </Button>
+              )}
+              {action.type === "action-menu" && (
+                <ActionMenu {...action.props} />
+              )}
+              {action.type === "custom" && action.children}
+            </>
+          ))}
+        </div>
+      )}
+    </div>
   )
 }
 ```
 
-The `JsonViewSection` component shows a section with the "JSON" title and a button to show the data as JSON in a drawer or side window.
+The `Header` component shows a title, and optionally a subtitle and action buttons.
 
-The `JsonViewSection` accepts a `data` prop, which is the data to show as a JSON object in the drawer.
+The component also uses the [Action Menu](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/admin-components/components/action-menu/index.html.md) custom component.
+
+It accepts the following props:
+
+- title: (\`string\`) The section's title.
+- subtitle: (\`string\`) The section's subtitle.
+- actions: (\`object\[]\`) An array of actions to show.
+
+  - type: (\`button\` \\| \`action-menu\` \\| \`custom\`) The type of action to add.
+
+    \- If its value is \`button\`, it'll show a button that can have a link or an on-click action.
+
+    \- If its value is \`action-menu\`, it'll show a three dot icon with a dropdown of actions.
+
+    \- If its value is \`custom\`, you can pass any React nodes to render.
+
+  - props: (object)
+
+  - children: (React.ReactNode) This property is only accepted if \`type\` is \`custom\`. Its content is rendered as part of the actions.
 
 ***
 
 ## Example
 
-Use the `JsonViewSection` component in any widget or UI route.
+Use the `Header` component in any 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 { JsonViewSection } from "../components/json-view-section"
+import { Container } from "../components/container"
+import { Header } from "../components/header"
 
 const ProductWidget = () => {
-  return <JsonViewSection data={{
-    name: "John",
-  }} />
+  return (
+    <Container>
+      <Header 
+        title="Product Widget"
+        subtitle="This is my custom product widget"
+        actions={[
+          {
+            type: "button",
+            props: {
+              children: "Click me",
+              variant: "secondary",
+              onClick: () => {
+                alert("You clicked the button.")
+              },
+            },
+          },
+        ]}
+      />
+    </Container>
+  )
 }
 
 export const config = defineWidgetConfig({
@@ -60331,7 +60359,553 @@ export const config = defineWidgetConfig({
 export default ProductWidget
 ```
 
-This shows the JSON section at the top of the product page, passing it the object `{ name: "John" }`.
+This widget also uses a [Container](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/admin-components/components/container/index.html.md) custom component.
+
+
+# Data Table - Admin Components
+
+This component is available after [Medusa v2.4.0+](https://github.com/medusajs/medusa/releases/tag/v2.4.0).
+
+The [DataTable component in Medusa UI](https://docs.medusajs.com/ui/components/data-table/index.html.md) allows you to display data in a table with sorting, filtering, and pagination. It's used across the Medusa Admin dashboard to showcase a list of items, such as a list of products.
+
+![Example of a table in the product listing page](https://res.cloudinary.com/dza7lstvk/image/upload/v1728295658/Medusa%20Resources/list_ddt9zc.png)
+
+You can use this component in your Admin Extensions to display data in a table format, especially if you're retrieving them from API routes of the Medusa application.
+
+This guide focuses on how to use the `DataTable` component while fetching data from the backend. Refer to the [Medusa UI documentation](https://docs.medusajs.com/ui/components/data-table/index.html.md) for detailed information about the DataTable component and its different usages.
+
+## Example: DataTable with Data Fetching
+
+In this example, you'll create a UI widget that shows the list of products retrieved from the [List Products API Route](https://docs.medusajs.com/api/admin#products_getproducts) in a data table with pagination, filtering, searching, and sorting.
+
+Start by initializing the columns in the data table. To do that, use the `createDataTableColumnHelper` from Medusa UI:
+
+```tsx title="src/admin/routes/custom/page.tsx"
+import {
+  createDataTableColumnHelper,
+} from "@medusajs/ui"
+import { 
+  HttpTypes,
+} from "@medusajs/framework/types"
+
+const columnHelper = createDataTableColumnHelper<HttpTypes.AdminProduct>()
+
+const columns = [
+  columnHelper.accessor("title", {
+    header: "Title",
+    // Enables sorting for the column.
+    enableSorting: true,
+    // If omitted, the header will be used instead if it's a string, 
+    // otherwise the accessor key (id) will be used.
+    sortLabel: "Title",
+    // If omitted the default value will be "A-Z"
+    sortAscLabel: "A-Z",
+    // If omitted the default value will be "Z-A"
+    sortDescLabel: "Z-A",
+  }),
+  columnHelper.accessor("status", {
+    header: "Status",
+    cell: ({ getValue }) => {
+      const status = getValue()
+      return (
+        <Badge color={status === "published" ? "green" : "grey"} size="xsmall">
+          {status === "published" ? "Published" : "Draft"}
+        </Badge>
+      )
+    },
+  }),
+]
+```
+
+`createDataTableColumnHelper` utility creates a column helper that helps you define the columns for the data table. The column helper has an `accessor` method that accepts two parameters:
+
+1. The column's key in the table's data.
+2. An object with the following properties:
+   - `header`: The column's header.
+   - `cell`: (optional) By default, a data's value for a column is displayed as a string. Use this property to specify custom rendering of the value. It accepts a function that returns a string or a React node. The function receives an object that has a `getValue` property function to retrieve the raw value of the cell.
+   - `enableSorting`: (optional) A boolean that enables sorting data by this column.
+   - `sortLabel`: (optional) The label for the sorting button. If omitted, the `header` will be used instead if it's a string, otherwise the accessor key (id) will be used.
+   - `sortAscLabel`: (optional) The label for the ascending sorting button. If omitted, the default value will be "A-Z".
+   - `sortDescLabel`: (optional) The label for the descending sorting button. If omitted, the default value will be "Z-A".
+
+Next, you'll define the filters that can be applied to the data table. You'll configure filtering by product status.
+
+To define the filters, add the following:
+
+```tsx title="src/admin/routes/custom/page.tsx"
+// other imports...
+import {
+  // ...
+  createDataTableFilterHelper,
+} from "@medusajs/ui"
+
+const filterHelper = createDataTableFilterHelper<HttpTypes.AdminProduct>()
+
+const filters = [
+  filterHelper.accessor("status", {
+    type: "select",
+    label: "Status",
+    options: [
+      {
+        label: "Published",
+        value: "published",
+      },
+      {
+        label: "Draft",
+        value: "draft",
+      },
+    ],
+  }),
+]
+```
+
+`createDataTableFilterHelper` utility creates a filter helper that helps you define the filters for the data table. The filter helper has an `accessor` method that accepts two parameters:
+
+1. The key of a column in the table's data.
+2. An object with the following properties:
+   - `type`: The type of filter. It can be either:
+     - `select`: A select dropdown allowing users to choose multiple values.
+     - `radio`: A radio button allowing users to choose one value.
+     - `date`: A date picker allowing users to choose a date.
+   - `label`: The filter's label.
+   - `options`: An array of objects with `label` and `value` properties. The `label` is the option's label, and the `value` is the value to filter by.
+
+You'll now start creating the UI widget's component. Start by adding the necessary state variables:
+
+```tsx title="src/admin/routes/custom/page.tsx"
+// other imports...
+import {
+  // ...
+  DataTablePaginationState,
+  DataTableFilteringState,
+  DataTableSortingState,
+} from "@medusajs/ui"
+import { useMemo, useState } from "react"
+
+// ...
+
+const limit = 15
+
+const CustomPage = () => {
+  const [pagination, setPagination] = useState<DataTablePaginationState>({
+    pageSize: limit,
+    pageIndex: 0,
+  })
+	const [search, setSearch] = useState<string>("")
+	const [filtering, setFiltering] = useState<DataTableFilteringState>({})
+  const [sorting, setSorting] = useState<DataTableSortingState | null>(null)
+
+  const offset = useMemo(() => {
+    return pagination.pageIndex * limit
+  }, [pagination])
+  const statusFilters = useMemo(() => {
+    return (filtering.status || []) as ProductStatus
+  }, [filtering])
+
+  // TODO add data fetching logic
+}
+```
+
+In the component, you've added the following state variables:
+
+- `pagination`: An object of type `DataTablePaginationState` that holds the pagination state. It has two properties:
+  - `pageSize`: The number of items to show per page.
+  - `pageIndex`: The current page index.
+- `search`: A string that holds the search query.
+- `filtering`: An object of type `DataTableFilteringState` that holds the filtering state.
+- `sorting`: An object of type `DataTableSortingState` that holds the sorting state.
+
+You've also added two memoized variables:
+
+- `offset`: How many items to skip when fetching data based on the current page.
+- `statusFilters`: The selected status filters, if any.
+
+Next, you'll fetch the products from the Medusa application. Assuming you have the JS SDK configured as explained in [this guide](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/js-sdk/index.html.md), add the following imports at the top of the file:
+
+```tsx title="src/admin/routes/custom/page.tsx"
+import { sdk } from "../../lib/config"
+import { useQuery } from "@tanstack/react-query"
+```
+
+This imports the JS SDK instance and `useQuery` from [Tanstack Query](https://tanstack.com/query/latest).
+
+Then, replace the `TODO` in the component with the following:
+
+```tsx title="src/admin/routes/custom/page.tsx"
+const { data, isLoading } = useQuery({
+  queryFn: () => sdk.admin.product.list({
+    limit,
+    offset,
+    q: search,
+    status: statusFilters,
+    order: sorting ? `${sorting.desc ? "-" : ""}${sorting.id}` : undefined,
+  }),
+  queryKey: [["products", limit, offset, search, statusFilters, sorting?.id, sorting?.desc]],
+})
+
+// TODO configure data table
+```
+
+You use the `useQuery` hook to fetch the products from the Medusa application. In the `queryFn`, you call the `sdk.admin.product.list` method to fetch the products. You pass the following query parameters to the method:
+
+- `limit`: The number of products to fetch per page.
+- `offset`: The number of products to skip based on the current page.
+- `q`: The search query, if set.
+- `status`: The status filters, if set.
+- `order`: The sorting order, if set.
+
+So, whenever the user changes the current page, search query, status filters, or sorting, the products are fetched based on the new parameters.
+
+Next, you'll configure the data table. Medusa UI provides a `useDataTable` hook that helps you configure the data table. Add the following imports at the top of the file:
+
+```tsx title="src/admin/routes/custom/page.tsx"
+import {
+  // ...
+  useDataTable,
+} from "@medusajs/ui"
+import { useNavigate } from "react-router-dom"
+```
+
+Then, replace the `TODO` in the component with the following:
+
+```tsx title="src/admin/routes/custom/page.tsx"
+const navigate = useNavigate()
+
+const table = useDataTable({
+  columns,
+  data: data?.products || [],
+  getRowId: (row) => row.id,
+  rowCount: data?.count || 0,
+  isLoading,
+  pagination: {
+    state: pagination,
+    onPaginationChange: setPagination,
+  },
+  search: {
+    state: search,
+    onSearchChange: setSearch,
+  },
+  filtering: {
+    state: filtering,
+    onFilteringChange: setFiltering,
+  },
+  filters,
+  sorting: {
+    // Pass the pagination state and updater to the table instance
+    state: sorting,
+    onSortingChange: setSorting,
+  },
+  onRowClick: (event, row) => {
+    // Handle row click, for example
+    navigate(`/products/${row.id}`)
+  },
+})
+
+// TODO render component
+```
+
+The `useDataTable` hook accepts an object with the following properties:
+
+- columns: (\`array\`) The columns to display in the data table. You created this using the \`createDataTableColumnHelper\` utility.
+- data: (\`array\`) The products fetched from the Medusa application.
+- getRowId: (\`function\`) A function that returns the unique ID of a row.
+- rowCount: (\`number\`) The total number of products that can be retrieved. This is used to determine the number of pages.
+- isLoading: (\`boolean\`) A boolean that indicates if the data is being fetched.
+- pagination: (\`object\`) An object to configure pagination.
+
+  - state: (\`object\`) The pagination React state variable.
+
+  - onPaginationChange: (\`function\`) A function that updates the pagination state.
+- search: (\`object\`) An object to configure searching.
+
+  - state: (\`string\`) The search query React state variable.
+
+  - onSearchChange: (\`function\`) A function that updates the search query state.
+- filtering: (\`object\`) An object to configure filtering.
+
+  - state: (\`object\`) The filtering React state variable.
+
+  - onFilteringChange: (\`function\`) A function that updates the filtering state.
+- filters: (\`array\`) The filters to display in the data table. You created this using the \`createDataTableFilterHelper\` utility.
+- sorting: (\`object\`) An object to configure sorting.
+
+  - state: (\`object\`) The sorting React state variable.
+
+  - onSortingChange: (\`function\`) A function that updates the sorting state.
+- onRowClick: (\`function\`) A function that allows you to perform an action when the user clicks on a row. In this example, you navigate to the product's detail page.
+
+  - event: (\`mouseevent\`) An instance of the \[MouseClickEvent]\(https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent) object.
+
+  - row: (\`object\`) The data of the row that was clicked.
+
+Finally, you'll render the data table. But first, add the following imports at the top of the page:
+
+```tsx title="src/admin/routes/custom/page.tsx"
+import {
+  // ...
+  DataTable,
+} from "@medusajs/ui"
+import { SingleColumnLayout } from "../../layouts/single-column"
+import { Container } from "../../components/container"
+```
+
+Aside from the `DataTable` component, you also import the [SingleColumnLayout](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/admin-components/layouts/single-column/index.html.md) and [Container](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/admin-components/components/container/index.html.md) components implemented in other Admin Component guides. These components ensure a style consistent to other pages in the admin dashboard.
+
+Then, replace the `TODO` in the component with the following:
+
+```tsx title="src/admin/routes/custom/page.tsx"
+return (
+  <SingleColumnLayout>
+    <Container>
+      <DataTable instance={table}>
+        <DataTable.Toolbar className="flex flex-col items-start justify-between gap-2 md:flex-row md:items-center">
+          <Heading>Products</Heading>
+          <div className="flex gap-2">
+            <DataTable.FilterMenu tooltip="Filter" />
+            <DataTable.SortingMenu tooltip="Sort" />
+            <DataTable.Search placeholder="Search..." />
+          </div>
+        </DataTable.Toolbar>
+        <DataTable.Table />
+        <DataTable.Pagination />
+      </DataTable>
+    </Container>
+  </SingleColumnLayout>
+)
+```
+
+You render the `DataTable` component and pass the `table` instance as a prop. In the `DataTable` component, you render a toolbar showing a heading, filter menu, sorting menu, and a search input. You also show pagination after the table.
+
+Lastly, export the component and the UI widget's configuration at the end of the file:
+
+```tsx title="src/admin/routes/custom/page.tsx"
+// other imports...
+import { defineRouteConfig } from "@medusajs/admin-sdk"
+import { ChatBubbleLeftRight } from "@medusajs/icons"
+
+// ...
+
+export const config = defineRouteConfig({
+  label: "Custom",
+  icon: ChatBubbleLeftRight,
+})
+
+export default CustomPage
+```
+
+If you start your Medusa application and go to `localhost:9000/app/custom`, you'll see the data table showing the list of products with pagination, filtering, searching, and sorting functionalities.
+
+### Full Example Code
+
+```tsx title="src/admin/routes/custom/page.tsx"
+import { defineRouteConfig } from "@medusajs/admin-sdk"
+import { ChatBubbleLeftRight } from "@medusajs/icons"
+import { 
+  Badge,
+  createDataTableColumnHelper,
+  createDataTableFilterHelper,
+  DataTable,
+  DataTableFilteringState,
+  DataTablePaginationState,
+  DataTableSortingState,
+  Heading,
+  useDataTable,
+} from "@medusajs/ui"
+import { useQuery } from "@tanstack/react-query"
+import { SingleColumnLayout } from "../../layouts/single-column"
+import { sdk } from "../../lib/config"
+import { useMemo, useState } from "react"
+import { Container } from "../../components/container"
+import { HttpTypes, ProductStatus } from "@medusajs/framework/types"
+
+const columnHelper = createDataTableColumnHelper<HttpTypes.AdminProduct>()
+
+const columns = [
+  columnHelper.accessor("title", {
+    header: "Title",
+    // Enables sorting for the column.
+    enableSorting: true,
+    // If omitted, the header will be used instead if it's a string, 
+    // otherwise the accessor key (id) will be used.
+    sortLabel: "Title",
+    // If omitted the default value will be "A-Z"
+    sortAscLabel: "A-Z",
+    // If omitted the default value will be "Z-A"
+    sortDescLabel: "Z-A",
+  }),
+  columnHelper.accessor("status", {
+    header: "Status",
+    cell: ({ getValue }) => {
+      const status = getValue()
+      return (
+        <Badge color={status === "published" ? "green" : "grey"} size="xsmall">
+          {status === "published" ? "Published" : "Draft"}
+        </Badge>
+      )
+    },
+  }),
+]
+
+const filterHelper = createDataTableFilterHelper<HttpTypes.AdminProduct>()
+
+const filters = [
+  filterHelper.accessor("status", {
+    type: "select",
+    label: "Status",
+    options: [
+      {
+        label: "Published",
+        value: "published",
+      },
+      {
+        label: "Draft",
+        value: "draft",
+      },
+    ],
+  }),
+]
+
+const limit = 15
+
+const CustomPage = () => {
+  const [pagination, setPagination] = useState<DataTablePaginationState>({
+    pageSize: limit,
+    pageIndex: 0,
+  })
+	const [search, setSearch] = useState<string>("")
+	const [filtering, setFiltering] = useState<DataTableFilteringState>({})
+  const [sorting, setSorting] = useState<DataTableSortingState | null>(null)
+
+  const offset = useMemo(() => {
+    return pagination.pageIndex * limit
+  }, [pagination])
+  const statusFilters = useMemo(() => {
+    return (filtering.status || []) as ProductStatus
+  }, [filtering])
+
+  const { data, isLoading } = useQuery({
+    queryFn: () => sdk.admin.product.list({
+      limit,
+      offset,
+      q: search,
+      status: statusFilters,
+      order: sorting ? `${sorting.desc ? "-" : ""}${sorting.id}` : undefined,
+    }),
+    queryKey: [["products", limit, offset, search, statusFilters, sorting?.id, sorting?.desc]],
+  })
+
+  const table = useDataTable({
+    columns,
+    data: data?.products || [],
+    getRowId: (row) => row.id,
+    rowCount: data?.count || 0,
+    isLoading,
+    pagination: {
+      state: pagination,
+      onPaginationChange: setPagination,
+    },
+    search: {
+	    state: search,
+	    onSearchChange: setSearch,
+    },
+    filtering: {
+      state: filtering,
+      onFilteringChange: setFiltering,
+    },
+    filters,
+    sorting: {
+      // Pass the pagination state and updater to the table instance
+      state: sorting,
+      onSortingChange: setSorting,
+    },
+  })
+
+  return (
+    <SingleColumnLayout>
+      <Container>
+        <DataTable instance={table}>
+          <DataTable.Toolbar className="flex flex-col items-start justify-between gap-2 md:flex-row md:items-center">
+            <Heading>Products</Heading>
+            <div className="flex gap-2">
+              <DataTable.FilterMenu tooltip="Filter" />
+              <DataTable.SortingMenu tooltip="Sort" />
+              <DataTable.Search placeholder="Search..." />
+            </div>
+          </DataTable.Toolbar>
+          <DataTable.Table />
+          <DataTable.Pagination />
+        </DataTable>
+      </Container>
+    </SingleColumnLayout>
+  )
+}
+
+export const config = defineRouteConfig({
+  label: "Custom",
+  icon: ChatBubbleLeftRight,
+})
+
+export default CustomPage
+```
+
+
+# Container - Admin Components
+
+The Medusa Admin wraps each section of a page in a container.
+
+![Example of a container in the Medusa Admin](https://res.cloudinary.com/dza7lstvk/image/upload/v1728287102/Medusa%20Resources/container_soenir.png)
+
+To create a component that uses the same container styling in your widgets or UI routes, create the file `src/admin/components/container.tsx` with the following content:
+
+```tsx
+import { 
+  Container as UiContainer,
+  clx,
+} from "@medusajs/ui"
+
+type ContainerProps = React.ComponentProps<typeof UiContainer>
+
+export const Container = (props: ContainerProps) => {
+  return (
+    <UiContainer {...props} className={clx(
+      "divide-y p-0",
+      props.className
+    )} />
+  )
+}
+```
+
+The `Container` component re-uses the component from the [Medusa UI package](https://docs.medusajs.com/ui/components/container/index.html.md) and applies to it classes to match the Medusa Admin's design conventions.
+
+***
+
+## Example
+
+Use that `Container` component in any 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"
+
+const ProductWidget = () => {
+  return (
+    <Container>
+      <Header title="Product Widget" />
+    </Container>
+  )
+}
+
+export const config = defineWidgetConfig({
+  zone: "product.details.before",
+})
+
+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
@@ -60907,140 +61481,222 @@ This component uses the [Container](https://docs.medusajs.com/Users/shahednasser
 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
+# JSON View - Admin Components
 
-Each section in the Medusa Admin has a header with a title, and optionally a subtitle with buttons to perform an action.
+Detail pages in the Medusa Admin show a JSON section to view the current page's details in JSON format.
 
-![Example of a header in a section](https://res.cloudinary.com/dza7lstvk/image/upload/v1728288562/Medusa%20Resources/header_dtz4gl.png)
+![Example of a JSON section in the admin](https://res.cloudinary.com/dza7lstvk/image/upload/v1728295129/Medusa%20Resources/json_dtbsgm.png)
 
-To create a component that uses the same header styling and structure, create the file `src/admin/components/header.tsx` with the following content:
+To create a component that shows a JSON section in your customizations, create the file `src/admin/components/json-view-section.tsx` with the following content:
 
-```tsx title="src/admin/components/header.tsx"
-import { Heading, Button, Text } from "@medusajs/ui"
-import React from "react"
-import { Link, LinkProps } from "react-router-dom"
-import { ActionMenu, ActionMenuProps } from "./action-menu"
+```tsx title="src/admin/components/json-view-section.tsx"
+import {
+  ArrowUpRightOnBox,
+  Check,
+  SquareTwoStack,
+  TriangleDownMini,
+  XMarkMini,
+} from "@medusajs/icons"
+import {
+  Badge,
+  Container,
+  Drawer,
+  Heading,
+  IconButton,
+  Kbd,
+} from "@medusajs/ui"
+import Primitive from "@uiw/react-json-view"
+import { CSSProperties, MouseEvent, Suspense, useState } from "react"
 
-export type HeadingProps = {
-  title: string
-  subtitle?: string
-  actions?: (
-    {
-      type: "button",
-      props: React.ComponentProps<typeof Button>
-      link?: LinkProps
-    } |  
-    {
-      type: "action-menu"
-      props: ActionMenuProps
-    } |
-    {
-      type: "custom"
-      children: React.ReactNode
-    }
-  )[]
+type JsonViewSectionProps = {
+  data: object
+  title?: string
 }
 
-export const Header = ({
-  title,
-  subtitle,
-  actions = [],
-}: HeadingProps) => {
+export const JsonViewSection = ({ data }: JsonViewSectionProps) => {
+  const numberOfKeys = Object.keys(data).length
+
   return (
-    <div className="flex items-center justify-between px-6 py-4">
-      <div>
-        <Heading level="h2">{title}</Heading>
-        {subtitle && (
-          <Text className="text-ui-fg-subtle" size="small">
-            {subtitle}
-          </Text>
-        )}
+    <Container className="flex items-center justify-between px-6 py-4">
+      <div className="flex items-center gap-x-4">
+        <Heading level="h2">JSON</Heading>
+        <Badge size="2xsmall" rounded="full">
+          {numberOfKeys} keys
+        </Badge>
       </div>
-      {actions.length > 0 && (
-        <div className="flex items-center justify-center gap-x-2">
-          {actions.map((action, index) => (
-            <>
-              {action.type === "button" && (
-                <Button 
-                  {...action.props} 
-                  size={action.props.size || "small"}
-                  key={index}
+      <Drawer>
+        <Drawer.Trigger asChild>
+          <IconButton
+            size="small"
+            variant="transparent"
+            className="text-ui-fg-muted hover:text-ui-fg-subtle"
+          >
+            <ArrowUpRightOnBox />
+          </IconButton>
+        </Drawer.Trigger>
+        <Drawer.Content className="bg-ui-contrast-bg-base text-ui-code-fg-subtle !shadow-elevation-commandbar overflow-hidden border border-none max-md:inset-x-2 max-md:max-w-[calc(100%-16px)]">
+          <div className="bg-ui-code-bg-base flex items-center justify-between px-6 py-4">
+            <div className="flex items-center gap-x-4">
+              <Drawer.Title asChild>
+                <Heading className="text-ui-contrast-fg-primary">
+                <span className="text-ui-fg-subtle">
+                  {numberOfKeys}
+                </span>
+                </Heading>
+              </Drawer.Title>
+            </div>
+            <div className="flex items-center gap-x-2">
+              <Kbd className="bg-ui-contrast-bg-subtle border-ui-contrast-border-base text-ui-contrast-fg-secondary">
+                esc
+              </Kbd>
+              <Drawer.Close asChild>
+                <IconButton
+                  size="small"
+                  variant="transparent"
+                  className="text-ui-contrast-fg-secondary hover:text-ui-contrast-fg-primary hover:bg-ui-contrast-bg-base-hover active:bg-ui-contrast-bg-base-pressed focus-visible:bg-ui-contrast-bg-base-hover focus-visible:shadow-borders-interactive-with-active"
                 >
-                  <>
-                    {action.props.children}
-                    {action.link && <Link {...action.link} />}
-                  </>
-                </Button>
-              )}
-              {action.type === "action-menu" && (
-                <ActionMenu {...action.props} />
-              )}
-              {action.type === "custom" && action.children}
-            </>
-          ))}
-        </div>
-      )}
-    </div>
+                  <XMarkMini />
+                </IconButton>
+              </Drawer.Close>
+            </div>
+          </div>
+          <Drawer.Body className="flex flex-1 flex-col overflow-hidden px-[5px] py-0 pb-[5px]">
+            <div className="bg-ui-contrast-bg-subtle flex-1 overflow-auto rounded-b-[4px] rounded-t-lg p-3">
+              <Suspense
+                fallback={<div className="flex size-full flex-col"></div>}
+              >
+                <Primitive
+                  value={data}
+                  displayDataTypes={false}
+                  style={
+                    {
+                      "--w-rjv-font-family": "Roboto Mono, monospace",
+                      "--w-rjv-line-color": "var(--contrast-border-base)",
+                      "--w-rjv-curlybraces-color":
+                        "var(--contrast-fg-secondary)",
+                      "--w-rjv-brackets-color": "var(--contrast-fg-secondary)",
+                      "--w-rjv-key-string": "var(--contrast-fg-primary)",
+                      "--w-rjv-info-color": "var(--contrast-fg-secondary)",
+                      "--w-rjv-type-string-color": "var(--tag-green-icon)",
+                      "--w-rjv-quotes-string-color": "var(--tag-green-icon)",
+                      "--w-rjv-type-boolean-color": "var(--tag-orange-icon)",
+                      "--w-rjv-type-int-color": "var(--tag-orange-icon)",
+                      "--w-rjv-type-float-color": "var(--tag-orange-icon)",
+                      "--w-rjv-type-bigint-color": "var(--tag-orange-icon)",
+                      "--w-rjv-key-number": "var(--contrast-fg-secondary)",
+                      "--w-rjv-arrow-color": "var(--contrast-fg-secondary)",
+                      "--w-rjv-copied-color": "var(--contrast-fg-secondary)",
+                      "--w-rjv-copied-success-color":
+                        "var(--contrast-fg-primary)",
+                      "--w-rjv-colon-color": "var(--contrast-fg-primary)",
+                      "--w-rjv-ellipsis-color": "var(--contrast-fg-secondary)",
+                    } as CSSProperties
+                  }
+                  collapsed={1}
+                >
+                  <Primitive.Quote render={() => <span />} />
+                  <Primitive.Null
+                    render={() => (
+                      <span className="text-ui-tag-red-icon">null</span>
+                    )}
+                  />
+                  <Primitive.Undefined
+                    render={() => (
+                      <span className="text-ui-tag-blue-icon">undefined</span>
+                    )}
+                  />
+                  <Primitive.CountInfo
+                    render={(_props, { value }) => {
+                      return (
+                        <span className="text-ui-contrast-fg-secondary ml-2">
+                          {Object.keys(value as object).length} items
+                        </span>
+                      )
+                    }}
+                  />
+                  <Primitive.Arrow>
+                    <TriangleDownMini className="text-ui-contrast-fg-secondary -ml-[0.5px]" />
+                  </Primitive.Arrow>
+                  <Primitive.Colon>
+                    <span className="mr-1">:</span>
+                  </Primitive.Colon>
+                  <Primitive.Copied
+                    render={({ style }, { value }) => {
+                      return <Copied style={style} value={value} />
+                    }}
+                  />
+                </Primitive>
+              </Suspense>
+            </div>
+          </Drawer.Body>
+        </Drawer.Content>
+      </Drawer>
+    </Container>
+  )
+}
+
+type CopiedProps = {
+  style?: CSSProperties
+  value: object | undefined
+}
+
+const Copied = ({ style, value }: CopiedProps) => {
+  const [copied, setCopied] = useState(false)
+
+  const handler = (e: MouseEvent<HTMLSpanElement>) => {
+    e.stopPropagation()
+    setCopied(true)
+
+    if (typeof value === "string") {
+      navigator.clipboard.writeText(value)
+    } else {
+      const json = JSON.stringify(value, null, 2)
+      navigator.clipboard.writeText(json)
+    }
+
+    setTimeout(() => {
+      setCopied(false)
+    }, 2000)
+  }
+
+  const styl = { whiteSpace: "nowrap", width: "20px" }
+
+  if (copied) {
+    return (
+      <span style={{ ...style, ...styl }}>
+        <Check className="text-ui-contrast-fg-primary" />
+      </span>
+    )
+  }
+
+  return (
+    <span style={{ ...style, ...styl }} onClick={handler}>
+      <SquareTwoStack className="text-ui-contrast-fg-secondary" />
+    </span>
   )
 }
 ```
 
-The `Header` component shows a title, and optionally a subtitle and action buttons.
+The `JsonViewSection` component shows a section with the "JSON" title and a button to show the data as JSON in a drawer or side window.
 
-The component also uses the [Action Menu](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/admin-components/components/action-menu/index.html.md) custom component.
-
-It accepts the following props:
-
-- title: (\`string\`) The section's title.
-- subtitle: (\`string\`) The section's subtitle.
-- actions: (\`object\[]\`) An array of actions to show.
-
-  - type: (\`button\` \\| \`action-menu\` \\| \`custom\`) The type of action to add.
-
-    \- If its value is \`button\`, it'll show a button that can have a link or an on-click action.
-
-    \- If its value is \`action-menu\`, it'll show a three dot icon with a dropdown of actions.
-
-    \- If its value is \`custom\`, you can pass any React nodes to render.
-
-  - props: (object)
-
-  - children: (React.ReactNode) This property is only accepted if \`type\` is \`custom\`. Its content is rendered as part of the actions.
+The `JsonViewSection` accepts a `data` prop, which is the data to show as a JSON object in the drawer.
 
 ***
 
 ## Example
 
-Use the `Header` component in any widget or UI route.
+Use the `JsonViewSection` component in any 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 { JsonViewSection } from "../components/json-view-section"
 
 const ProductWidget = () => {
-  return (
-    <Container>
-      <Header 
-        title="Product Widget"
-        subtitle="This is my custom product widget"
-        actions={[
-          {
-            type: "button",
-            props: {
-              children: "Click me",
-              variant: "secondary",
-              onClick: () => {
-                alert("You clicked the button.")
-              },
-            },
-          },
-        ]}
-      />
-    </Container>
-  )
+  return <JsonViewSection data={{
+    name: "John",
+  }} />
 }
 
 export const config = defineWidgetConfig({
@@ -61050,7 +61706,7 @@ export const config = defineWidgetConfig({
 export default ProductWidget
 ```
 
-This widget also uses a [Container](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/admin-components/components/container/index.html.md) custom component.
+This shows the JSON section at the top of the product page, passing it the object `{ name: "John" }`.
 
 
 # Section Row - Admin Components
@@ -61145,493 +61801,6 @@ 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.
 
 
-# Data Table - Admin Components
-
-This component is available after [Medusa v2.4.0+](https://github.com/medusajs/medusa/releases/tag/v2.4.0).
-
-The [DataTable component in Medusa UI](https://docs.medusajs.com/ui/components/data-table/index.html.md) allows you to display data in a table with sorting, filtering, and pagination. It's used across the Medusa Admin dashboard to showcase a list of items, such as a list of products.
-
-![Example of a table in the product listing page](https://res.cloudinary.com/dza7lstvk/image/upload/v1728295658/Medusa%20Resources/list_ddt9zc.png)
-
-You can use this component in your Admin Extensions to display data in a table format, especially if you're retrieving them from API routes of the Medusa application.
-
-This guide focuses on how to use the `DataTable` component while fetching data from the backend. Refer to the [Medusa UI documentation](https://docs.medusajs.com/ui/components/data-table/index.html.md) for detailed information about the DataTable component and its different usages.
-
-## Example: DataTable with Data Fetching
-
-In this example, you'll create a UI widget that shows the list of products retrieved from the [List Products API Route](https://docs.medusajs.com/api/admin#products_getproducts) in a data table with pagination, filtering, searching, and sorting.
-
-Start by initializing the columns in the data table. To do that, use the `createDataTableColumnHelper` from Medusa UI:
-
-```tsx title="src/admin/routes/custom/page.tsx"
-import {
-  createDataTableColumnHelper,
-} from "@medusajs/ui"
-import { 
-  HttpTypes,
-} from "@medusajs/framework/types"
-
-const columnHelper = createDataTableColumnHelper<HttpTypes.AdminProduct>()
-
-const columns = [
-  columnHelper.accessor("title", {
-    header: "Title",
-    // Enables sorting for the column.
-    enableSorting: true,
-    // If omitted, the header will be used instead if it's a string, 
-    // otherwise the accessor key (id) will be used.
-    sortLabel: "Title",
-    // If omitted the default value will be "A-Z"
-    sortAscLabel: "A-Z",
-    // If omitted the default value will be "Z-A"
-    sortDescLabel: "Z-A",
-  }),
-  columnHelper.accessor("status", {
-    header: "Status",
-    cell: ({ getValue }) => {
-      const status = getValue()
-      return (
-        <Badge color={status === "published" ? "green" : "grey"} size="xsmall">
-          {status === "published" ? "Published" : "Draft"}
-        </Badge>
-      )
-    },
-  }),
-]
-```
-
-`createDataTableColumnHelper` utility creates a column helper that helps you define the columns for the data table. The column helper has an `accessor` method that accepts two parameters:
-
-1. The column's key in the table's data.
-2. An object with the following properties:
-   - `header`: The column's header.
-   - `cell`: (optional) By default, a data's value for a column is displayed as a string. Use this property to specify custom rendering of the value. It accepts a function that returns a string or a React node. The function receives an object that has a `getValue` property function to retrieve the raw value of the cell.
-   - `enableSorting`: (optional) A boolean that enables sorting data by this column.
-   - `sortLabel`: (optional) The label for the sorting button. If omitted, the `header` will be used instead if it's a string, otherwise the accessor key (id) will be used.
-   - `sortAscLabel`: (optional) The label for the ascending sorting button. If omitted, the default value will be "A-Z".
-   - `sortDescLabel`: (optional) The label for the descending sorting button. If omitted, the default value will be "Z-A".
-
-Next, you'll define the filters that can be applied to the data table. You'll configure filtering by product status.
-
-To define the filters, add the following:
-
-```tsx title="src/admin/routes/custom/page.tsx"
-// other imports...
-import {
-  // ...
-  createDataTableFilterHelper,
-} from "@medusajs/ui"
-
-const filterHelper = createDataTableFilterHelper<HttpTypes.AdminProduct>()
-
-const filters = [
-  filterHelper.accessor("status", {
-    type: "select",
-    label: "Status",
-    options: [
-      {
-        label: "Published",
-        value: "published",
-      },
-      {
-        label: "Draft",
-        value: "draft",
-      },
-    ],
-  }),
-]
-```
-
-`createDataTableFilterHelper` utility creates a filter helper that helps you define the filters for the data table. The filter helper has an `accessor` method that accepts two parameters:
-
-1. The key of a column in the table's data.
-2. An object with the following properties:
-   - `type`: The type of filter. It can be either:
-     - `select`: A select dropdown allowing users to choose multiple values.
-     - `radio`: A radio button allowing users to choose one value.
-     - `date`: A date picker allowing users to choose a date.
-   - `label`: The filter's label.
-   - `options`: An array of objects with `label` and `value` properties. The `label` is the option's label, and the `value` is the value to filter by.
-
-You'll now start creating the UI widget's component. Start by adding the necessary state variables:
-
-```tsx title="src/admin/routes/custom/page.tsx"
-// other imports...
-import {
-  // ...
-  DataTablePaginationState,
-  DataTableFilteringState,
-  DataTableSortingState,
-} from "@medusajs/ui"
-import { useMemo, useState } from "react"
-
-// ...
-
-const limit = 15
-
-const CustomPage = () => {
-  const [pagination, setPagination] = useState<DataTablePaginationState>({
-    pageSize: limit,
-    pageIndex: 0,
-  })
-	const [search, setSearch] = useState<string>("")
-	const [filtering, setFiltering] = useState<DataTableFilteringState>({})
-  const [sorting, setSorting] = useState<DataTableSortingState | null>(null)
-
-  const offset = useMemo(() => {
-    return pagination.pageIndex * limit
-  }, [pagination])
-  const statusFilters = useMemo(() => {
-    return (filtering.status || []) as ProductStatus
-  }, [filtering])
-
-  // TODO add data fetching logic
-}
-```
-
-In the component, you've added the following state variables:
-
-- `pagination`: An object of type `DataTablePaginationState` that holds the pagination state. It has two properties:
-  - `pageSize`: The number of items to show per page.
-  - `pageIndex`: The current page index.
-- `search`: A string that holds the search query.
-- `filtering`: An object of type `DataTableFilteringState` that holds the filtering state.
-- `sorting`: An object of type `DataTableSortingState` that holds the sorting state.
-
-You've also added two memoized variables:
-
-- `offset`: How many items to skip when fetching data based on the current page.
-- `statusFilters`: The selected status filters, if any.
-
-Next, you'll fetch the products from the Medusa application. Assuming you have the JS SDK configured as explained in [this guide](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/js-sdk/index.html.md), add the following imports at the top of the file:
-
-```tsx title="src/admin/routes/custom/page.tsx"
-import { sdk } from "../../lib/config"
-import { useQuery } from "@tanstack/react-query"
-```
-
-This imports the JS SDK instance and `useQuery` from [Tanstack Query](https://tanstack.com/query/latest).
-
-Then, replace the `TODO` in the component with the following:
-
-```tsx title="src/admin/routes/custom/page.tsx"
-const { data, isLoading } = useQuery({
-  queryFn: () => sdk.admin.product.list({
-    limit,
-    offset,
-    q: search,
-    status: statusFilters,
-    order: sorting ? `${sorting.desc ? "-" : ""}${sorting.id}` : undefined,
-  }),
-  queryKey: [["products", limit, offset, search, statusFilters, sorting?.id, sorting?.desc]],
-})
-
-// TODO configure data table
-```
-
-You use the `useQuery` hook to fetch the products from the Medusa application. In the `queryFn`, you call the `sdk.admin.product.list` method to fetch the products. You pass the following query parameters to the method:
-
-- `limit`: The number of products to fetch per page.
-- `offset`: The number of products to skip based on the current page.
-- `q`: The search query, if set.
-- `status`: The status filters, if set.
-- `order`: The sorting order, if set.
-
-So, whenever the user changes the current page, search query, status filters, or sorting, the products are fetched based on the new parameters.
-
-Next, you'll configure the data table. Medusa UI provides a `useDataTable` hook that helps you configure the data table. Add the following imports at the top of the file:
-
-```tsx title="src/admin/routes/custom/page.tsx"
-import {
-  // ...
-  useDataTable,
-} from "@medusajs/ui"
-import { useNavigate } from "react-router-dom"
-```
-
-Then, replace the `TODO` in the component with the following:
-
-```tsx title="src/admin/routes/custom/page.tsx"
-const navigate = useNavigate()
-
-const table = useDataTable({
-  columns,
-  data: data?.products || [],
-  getRowId: (row) => row.id,
-  rowCount: data?.count || 0,
-  isLoading,
-  pagination: {
-    state: pagination,
-    onPaginationChange: setPagination,
-  },
-  search: {
-    state: search,
-    onSearchChange: setSearch,
-  },
-  filtering: {
-    state: filtering,
-    onFilteringChange: setFiltering,
-  },
-  filters,
-  sorting: {
-    // Pass the pagination state and updater to the table instance
-    state: sorting,
-    onSortingChange: setSorting,
-  },
-  onRowClick: (event, row) => {
-    // Handle row click, for example
-    navigate(`/products/${row.id}`)
-  },
-})
-
-// TODO render component
-```
-
-The `useDataTable` hook accepts an object with the following properties:
-
-- columns: (\`array\`) The columns to display in the data table. You created this using the \`createDataTableColumnHelper\` utility.
-- data: (\`array\`) The products fetched from the Medusa application.
-- getRowId: (\`function\`) A function that returns the unique ID of a row.
-- rowCount: (\`number\`) The total number of products that can be retrieved. This is used to determine the number of pages.
-- isLoading: (\`boolean\`) A boolean that indicates if the data is being fetched.
-- pagination: (\`object\`) An object to configure pagination.
-
-  - state: (\`object\`) The pagination React state variable.
-
-  - onPaginationChange: (\`function\`) A function that updates the pagination state.
-- search: (\`object\`) An object to configure searching.
-
-  - state: (\`string\`) The search query React state variable.
-
-  - onSearchChange: (\`function\`) A function that updates the search query state.
-- filtering: (\`object\`) An object to configure filtering.
-
-  - state: (\`object\`) The filtering React state variable.
-
-  - onFilteringChange: (\`function\`) A function that updates the filtering state.
-- filters: (\`array\`) The filters to display in the data table. You created this using the \`createDataTableFilterHelper\` utility.
-- sorting: (\`object\`) An object to configure sorting.
-
-  - state: (\`object\`) The sorting React state variable.
-
-  - onSortingChange: (\`function\`) A function that updates the sorting state.
-- onRowClick: (\`function\`) A function that allows you to perform an action when the user clicks on a row. In this example, you navigate to the product's detail page.
-
-  - event: (\`mouseevent\`) An instance of the \[MouseClickEvent]\(https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent) object.
-
-  - row: (\`object\`) The data of the row that was clicked.
-
-Finally, you'll render the data table. But first, add the following imports at the top of the page:
-
-```tsx title="src/admin/routes/custom/page.tsx"
-import {
-  // ...
-  DataTable,
-} from "@medusajs/ui"
-import { SingleColumnLayout } from "../../layouts/single-column"
-import { Container } from "../../components/container"
-```
-
-Aside from the `DataTable` component, you also import the [SingleColumnLayout](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/admin-components/layouts/single-column/index.html.md) and [Container](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/admin-components/components/container/index.html.md) components implemented in other Admin Component guides. These components ensure a style consistent to other pages in the admin dashboard.
-
-Then, replace the `TODO` in the component with the following:
-
-```tsx title="src/admin/routes/custom/page.tsx"
-return (
-  <SingleColumnLayout>
-    <Container>
-      <DataTable instance={table}>
-        <DataTable.Toolbar className="flex flex-col items-start justify-between gap-2 md:flex-row md:items-center">
-          <Heading>Products</Heading>
-          <div className="flex gap-2">
-            <DataTable.FilterMenu tooltip="Filter" />
-            <DataTable.SortingMenu tooltip="Sort" />
-            <DataTable.Search placeholder="Search..." />
-          </div>
-        </DataTable.Toolbar>
-        <DataTable.Table />
-        <DataTable.Pagination />
-      </DataTable>
-    </Container>
-  </SingleColumnLayout>
-)
-```
-
-You render the `DataTable` component and pass the `table` instance as a prop. In the `DataTable` component, you render a toolbar showing a heading, filter menu, sorting menu, and a search input. You also show pagination after the table.
-
-Lastly, export the component and the UI widget's configuration at the end of the file:
-
-```tsx title="src/admin/routes/custom/page.tsx"
-// other imports...
-import { defineRouteConfig } from "@medusajs/admin-sdk"
-import { ChatBubbleLeftRight } from "@medusajs/icons"
-
-// ...
-
-export const config = defineRouteConfig({
-  label: "Custom",
-  icon: ChatBubbleLeftRight,
-})
-
-export default CustomPage
-```
-
-If you start your Medusa application and go to `localhost:9000/app/custom`, you'll see the data table showing the list of products with pagination, filtering, searching, and sorting functionalities.
-
-### Full Example Code
-
-```tsx title="src/admin/routes/custom/page.tsx"
-import { defineRouteConfig } from "@medusajs/admin-sdk"
-import { ChatBubbleLeftRight } from "@medusajs/icons"
-import { 
-  Badge,
-  createDataTableColumnHelper,
-  createDataTableFilterHelper,
-  DataTable,
-  DataTableFilteringState,
-  DataTablePaginationState,
-  DataTableSortingState,
-  Heading,
-  useDataTable,
-} from "@medusajs/ui"
-import { useQuery } from "@tanstack/react-query"
-import { SingleColumnLayout } from "../../layouts/single-column"
-import { sdk } from "../../lib/config"
-import { useMemo, useState } from "react"
-import { Container } from "../../components/container"
-import { HttpTypes, ProductStatus } from "@medusajs/framework/types"
-
-const columnHelper = createDataTableColumnHelper<HttpTypes.AdminProduct>()
-
-const columns = [
-  columnHelper.accessor("title", {
-    header: "Title",
-    // Enables sorting for the column.
-    enableSorting: true,
-    // If omitted, the header will be used instead if it's a string, 
-    // otherwise the accessor key (id) will be used.
-    sortLabel: "Title",
-    // If omitted the default value will be "A-Z"
-    sortAscLabel: "A-Z",
-    // If omitted the default value will be "Z-A"
-    sortDescLabel: "Z-A",
-  }),
-  columnHelper.accessor("status", {
-    header: "Status",
-    cell: ({ getValue }) => {
-      const status = getValue()
-      return (
-        <Badge color={status === "published" ? "green" : "grey"} size="xsmall">
-          {status === "published" ? "Published" : "Draft"}
-        </Badge>
-      )
-    },
-  }),
-]
-
-const filterHelper = createDataTableFilterHelper<HttpTypes.AdminProduct>()
-
-const filters = [
-  filterHelper.accessor("status", {
-    type: "select",
-    label: "Status",
-    options: [
-      {
-        label: "Published",
-        value: "published",
-      },
-      {
-        label: "Draft",
-        value: "draft",
-      },
-    ],
-  }),
-]
-
-const limit = 15
-
-const CustomPage = () => {
-  const [pagination, setPagination] = useState<DataTablePaginationState>({
-    pageSize: limit,
-    pageIndex: 0,
-  })
-	const [search, setSearch] = useState<string>("")
-	const [filtering, setFiltering] = useState<DataTableFilteringState>({})
-  const [sorting, setSorting] = useState<DataTableSortingState | null>(null)
-
-  const offset = useMemo(() => {
-    return pagination.pageIndex * limit
-  }, [pagination])
-  const statusFilters = useMemo(() => {
-    return (filtering.status || []) as ProductStatus
-  }, [filtering])
-
-  const { data, isLoading } = useQuery({
-    queryFn: () => sdk.admin.product.list({
-      limit,
-      offset,
-      q: search,
-      status: statusFilters,
-      order: sorting ? `${sorting.desc ? "-" : ""}${sorting.id}` : undefined,
-    }),
-    queryKey: [["products", limit, offset, search, statusFilters, sorting?.id, sorting?.desc]],
-  })
-
-  const table = useDataTable({
-    columns,
-    data: data?.products || [],
-    getRowId: (row) => row.id,
-    rowCount: data?.count || 0,
-    isLoading,
-    pagination: {
-      state: pagination,
-      onPaginationChange: setPagination,
-    },
-    search: {
-	    state: search,
-	    onSearchChange: setSearch,
-    },
-    filtering: {
-      state: filtering,
-      onFilteringChange: setFiltering,
-    },
-    filters,
-    sorting: {
-      // Pass the pagination state and updater to the table instance
-      state: sorting,
-      onSortingChange: setSorting,
-    },
-  })
-
-  return (
-    <SingleColumnLayout>
-      <Container>
-        <DataTable instance={table}>
-          <DataTable.Toolbar className="flex flex-col items-start justify-between gap-2 md:flex-row md:items-center">
-            <Heading>Products</Heading>
-            <div className="flex gap-2">
-              <DataTable.FilterMenu tooltip="Filter" />
-              <DataTable.SortingMenu tooltip="Sort" />
-              <DataTable.Search placeholder="Search..." />
-            </div>
-          </DataTable.Toolbar>
-          <DataTable.Table />
-          <DataTable.Pagination />
-        </DataTable>
-      </Container>
-    </SingleColumnLayout>
-  )
-}
-
-export const config = defineRouteConfig({
-  label: "Custom",
-  icon: ChatBubbleLeftRight,
-})
-
-export default CustomPage
-```
-
-
 # Table - Admin Components
 
 If you're using [Medusa v2.4.0+](https://github.com/medusajs/medusa/releases/tag/v2.4.0), it's recommended to use the [Data Table](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/admin-components/components/data-table/index.html.md) component instead as it provides features for sorting, filtering, pagination, and more with a simpler API.
@@ -62126,6 +62295,142 @@ const posts = await postModuleService.createPosts([
 If an array is passed of the method, an array of the created records is also returned.
 
 
+# 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.
@@ -62284,63 +62589,6 @@ To sort records by one or more properties, pass to the second object parameter t
 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.
-
-
 # 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).
@@ -62428,6 +62676,63 @@ restoredPosts = {
 ```
 
 
+# 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.
@@ -62515,265 +62820,6 @@ deletedPosts = {
 ```
 
 
-# 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.
-
-
-# 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.
@@ -63061,6 +63107,129 @@ The following operators are supported by the service factory filtering mechanism
 |\`$not\`|Inverts the logic of a condition. For example, |
 
 
+# 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>
@@ -69941,6 +70110,49 @@ If you're using the `Tooltip` component in a project other than the Medusa Admin
 - disableHoverableContent: (boolean) When \`true\`, trying to hover the content will result in the tooltip closing as the pointer leaves the trigger.
 
 
+# clx
+
+Utility function for working with classNames.
+
+## Usage
+
+***
+
+The `clx` function is a utility function for working with classNames. It is built using [clsx](https://www.npmjs.com/package/clsx) and [tw-merge](https://www.npmjs.com/package/tw-merge) and is intended to be used with [Tailwind CSS](https://tailwindcss.com/).
+
+```tsx
+import { clx } from "@medusajs/ui"
+
+type BoxProps = {
+  className?: string
+  children: React.ReactNode
+  mt: "sm" | "md" | "lg"
+}
+
+const Box = ({ className, children, mt }: BoxProps) => {
+  return (
+    <div
+      className={clx(
+        "flex items-center justify-center",
+        {
+          "mt-4": mt === "sm",
+          "mt-8": mt === "md",
+          "mt-12": mt === "lg",
+        },
+        className
+      )}
+    >
+      {children}
+    </div>
+  )
+}
+
+```
+
+In the above example the utility is used to apply a base style, a margin top that is dependent on the `mt` prop and a custom className.
+The Box component accepts a `className` prop that is merged with the other classNames, and the underlying usage of `tw-merge` ensures that all Tailwind CSS classes are merged without style conflicts.
+
+
 # Medusa Admin Extension
 
 How to install and use Medusa UI for building Admin extensions.
@@ -70058,46 +70270,3 @@ To update these packages, update their version in your `package.json` file and r
 ```bash
 npm install @medusajs/ui
 ```
-
-
-# clx
-
-Utility function for working with classNames.
-
-## Usage
-
-***
-
-The `clx` function is a utility function for working with classNames. It is built using [clsx](https://www.npmjs.com/package/clsx) and [tw-merge](https://www.npmjs.com/package/tw-merge) and is intended to be used with [Tailwind CSS](https://tailwindcss.com/).
-
-```tsx
-import { clx } from "@medusajs/ui"
-
-type BoxProps = {
-  className?: string
-  children: React.ReactNode
-  mt: "sm" | "md" | "lg"
-}
-
-const Box = ({ className, children, mt }: BoxProps) => {
-  return (
-    <div
-      className={clx(
-        "flex items-center justify-center",
-        {
-          "mt-4": mt === "sm",
-          "mt-8": mt === "md",
-          "mt-12": mt === "lg",
-        },
-        className
-      )}
-    >
-      {children}
-    </div>
-  )
-}
-
-```
-
-In the above example the utility is used to apply a base style, a margin top that is dependent on the `mt` prop and a custom className.
-The Box component accepts a `className` prop that is merged with the other classNames, and the underlying usage of `tw-merge` ensures that all Tailwind CSS classes are merged without style conflicts.
diff --git a/www/apps/resources/app/commerce-modules/auth/auth-providers/page.mdx b/www/apps/resources/app/commerce-modules/auth/auth-providers/page.mdx
index 79c31b841f..19806c4d88 100644
--- a/www/apps/resources/app/commerce-modules/auth/auth-providers/page.mdx
+++ b/www/apps/resources/app/commerce-modules/auth/auth-providers/page.mdx
@@ -1,16 +1,16 @@
 import { CardList } from "docs-ui"
 
 export const metadata = {
-  title: `Auth Providers`,
+  title: `Auth Module Provider`,
 }
 
 # {metadata.title}
 
-In this document, you’ll learn how the Auth Module handles authentication using providers.
+In this guide, you’ll learn about the Auth Module Provider and how it's used.
 
-## What's an Auth Module Provider?
+## What is an Auth Module Provider?
 
-An auth module provider handles authenticating customers and users, either using custom logic or by integrating a third-party service.
+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.
 
@@ -35,9 +35,19 @@ For example, the EmailPass Auth Module Provider authenticates a user using their
 
 ---
 
+## How to Create an Auth Module Provider?
+
+An Auth Module Provider is a module whose service extends the `AbstractAuthModuleProvider` imported from `@medusajs/framework/utils`.
+
+The module can have multiple auth provider services, where each is registered as a separate auth provider.
+
+Refer to the [Create Auth Module Provider](/references/auth/provider) guide to learn how to create an Auth Module Provider.
+
+---
+
 ## Configure Allowed Auth Providers of Actor Types
 
-By default, users of all actor types can authenticate with all installed auth module providers.
+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](!docs!/learn/configurations/medusa-config#httpauthMethodsPerActor) in Medusa's configurations:
 
@@ -61,9 +71,3 @@ module.exports = defineConfig({
 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.
 
 </Note>
-
----
-
-## How to Create an Auth Module Provider
-
-Refer to [this guide](/references/auth/provider) to learn how to create an auth module provider.
diff --git a/www/apps/resources/app/commerce-modules/fulfillment/fulfillment-provider/page.mdx b/www/apps/resources/app/commerce-modules/fulfillment/fulfillment-provider/page.mdx
index dfc3834916..9bdc485862 100644
--- a/www/apps/resources/app/commerce-modules/fulfillment/fulfillment-provider/page.mdx
+++ b/www/apps/resources/app/commerce-modules/fulfillment/fulfillment-provider/page.mdx
@@ -4,7 +4,7 @@ export const metadata = {
 
 # {metadata.title}
 
-In this document, you’ll learn what a fulfillment module provider is.
+In this guide, you’ll learn about the Fulfillment Module Provider and how it's used.
 
 <Note title="Looking for no-code docs?">
 
@@ -12,22 +12,75 @@ Refer to this [Medusa Admin User Guide](!user-guide!/settings/locations-and-ship
 
 </Note>
 
-## What’s a Fulfillment Module Provider?
+## What is a Fulfillment Module Provider?
 
-A fulfillment module provider handles fulfilling items, typically using a third-party integration.
+A Fulfillment Module Provider handles fulfilling items, typically using a third-party integration.
 
-Fulfillment module providers registered in the Fulfillment Module's [options](../module-options/page.mdx) are stored and represented by the [FulfillmentProvider data model](/references/fulfillment/models/FulfillmentProvider).
+Fulfillment Module Providers registered in the Fulfillment Module's [options](../module-options/page.mdx) are stored and represented by the [FulfillmentProvider data model](/references/fulfillment/models/FulfillmentProvider).
+
+![Diagram showcasing the communication between Medusa, the Fulfillment Module Provider, and the third-party fulfillment provider.](https://res.cloudinary.com/dza7lstvk/image/upload/v1746794800/Medusa%20Resources/fulfillment-provider-service_ljsqpq.jpg)
 
 ---
 
-## Configure Fulfillment Providers
+## Default Fulfillment Provider
 
-The Fulfillment Module accepts a `providers` option that allows you to register providers in your application.
+Medusa provides a Manual Fulfillment Provider that acts as a placeholder fulfillment provider. It doesn't process fulfillment and delegates that to the merchant.
 
-Learn more about the `providers` option in [this documentation](../module-options/page.mdx).
+This provider is installed by default in your application and you can use it to fulfill items manually.
+
+<Note title="Tip">
+
+The identifier of the manual fulfillment provider is `fp_manual_manual`.
+
+</Note>
 
 ---
 
-## How to Create a Fulfillment Provider?
+## How to Create a Custom Fulfillment Provider?
 
-Refer to [this guide](/references/fulfillment/provider) to learn how to create a fulfillment module provider.
+A Fulfillment Module Provider is a module whose service implements the `IFulfillmentProvider` imported from `@medusajs/framework/types`.
+
+The module can have multiple fulfillment provider services, where each are registered as separate fulfillment providers.
+
+Refer to the [Create Fulfillment Module Provider](/references/fulfillment/provider) guide to learn how to create a Fulfillment Module Provider.
+
+{/* TODO add link to user guide */}
+
+After you create a fulfillment provider, you can choose it as the default Fulfillment Module Provider for a stock location in the Medusa Admin dashboard.
+
+---
+
+## How are Fulfillment Providers Registered?
+
+### Configure Fulfillment Module's Providers
+
+The Fulfillment Module accepts a `providers` option that allows you to configure the providers registered in your application.
+
+Learn more about this option in the [Module Options](../module-options/page.mdx) guide.
+
+### Registration on Application Start
+
+When the Medusa application starts, it registers the Fulfillment Module Providers defined in the `providers` option of the Fulfillment Module.
+
+For each Fulfillment Module Provider, the Medusa application finds all fulfillment provider services defined in them to register.
+
+### FulfillmentProvider Data Model
+
+A registered fulfillment provider is represented by the [FulfillmentProvider data model](/references/fulfillment/models/FulfillmentProvider) in the Medusa application.
+
+This data model is used to reference a service in the Fulfillment Module Provider and determine whether it's installed in the application.
+
+![Diagram showcasing the FulfillmentProvider data model](https://res.cloudinary.com/dza7lstvk/image/upload/v1746794803/Medusa%20Resources/fulfillment-provider-model_wo2ato.jpg)
+
+The `FulfillmentProvider` data model has the following properties:
+
+- `id`: The unique identifier of the fulfillment provider. The ID's format is `fp_{identifier}_{id}`, where:
+    - `identifier` is the value of the `identifier` property in the Fulfillment Module Provider's service.
+    - `id` is the value of the `id` property of the Fulfillment Module Provider in `medusa-config.ts`.
+- `is_enabled`: A boolean indicating whether the fulfillment provider is enabled.
+
+### How to Remove a Fulfillment Provider?
+
+You can remove a registered fulfillment provider from the Medusa application by removing it from the `providers` option in the Fulfillment Module's configuration.
+
+Then, the next time the Medusa application starts, it will set the `is_enabled` property of the `FulfillmentProvider`'s record to `false`. This allows you to re-enable the fulfillment provider later if needed by adding it back to the `providers` option.
diff --git a/www/apps/resources/app/commerce-modules/payment/payment-provider/page.mdx b/www/apps/resources/app/commerce-modules/payment/payment-provider/page.mdx
index 803ec780c3..23a1d5c1e0 100644
--- a/www/apps/resources/app/commerce-modules/payment/payment-provider/page.mdx
+++ b/www/apps/resources/app/commerce-modules/payment/payment-provider/page.mdx
@@ -6,7 +6,7 @@ export const metadata = {
 
 # {metadata.title}
 
-In this document, you’ll learn what a payment module provider is.
+In this guide, you’ll learn about the Payment Module Provider and how it's used.
 
 <Note title="Looking for no-code docs?">
 
@@ -14,14 +14,18 @@ Refer to this [Medusa Admin User Guide](!user-guide!/settings/regions) to learn
 
 </Note>
 
-## What's a Payment Module Provider?
+---
 
-A payment module provider registers a payment provider that handles payment processing in the Medusa application. It integrates third-party payment providers, such as Stripe.
+## What is a Payment Module Provider?
+
+The Payment Module Provider handles payment processing in the Medusa application. It integrates third-party payment services, such as [Stripe](./stripe/page.mdx).
 
 To authorize a payment amount with a payment provider, a payment session is created and associated with that payment provider. The payment provider is then used to handle the authorization.
 
 After the payment session is authorized, the payment provider is associated with the resulting payment and handles its payment processing, such as to capture or refund payment.
 
+![Diagram showcasing the communication between Medusa, the Payment Module Provider, and the third-party payment provider.](https://res.cloudinary.com/dza7lstvk/image/upload/v1746791374/Medusa%20Resources/payment-provider-service_l4zi6m.jpg)
+
 ### List of Payment Module Providers
 
 <CardList
@@ -33,35 +37,63 @@ After the payment session is authorized, the payment provider is associated with
   ]}
 />
 
-
----
-
-## System Payment Provider
+### Default Payment Provider
 
 The Payment Module provides a `system` payment provider that acts as a placeholder payment provider.
 
 It doesn’t handle payment processing and delegates that to the merchant. It acts similarly to a cash-on-delivery (COD) payment method.
 
+<Note title="Tip">
+
+The identifier of the system payment provider is `pp_system`.
+
+</Note>
+
 ---
 
-## How are Payment Providers Created?
+## How to Create a Custom Payment Provider?
 
 A payment provider is a module whose main service extends the `AbstractPaymentProvider` imported from `@medusajs/framework/utils`.
 
+The module can have multiple payment provider services, where each is registered as a separate payment provider.
+
 Refer to [this guide](/references/payment/provider) on how to create a payment provider for the Payment Module.
 
----
-
-## Configure Payment Providers
-
-The Payment Module accepts a `providers` option that allows you to register providers in your application.
-
-Learn more about this option in [this documentation](../module-options/page.mdx#providers).
+After you create a payment provider, you can enable it as a payment provider in a region using the [Medusa Admin dashboard](!user-guide!/settings/regions).
 
 ---
 
-## PaymentProvider Data Model
+## How are Payment Providers Registered?
 
-When the Medusa application starts and registers the payment providers, it also creates a record of the `PaymentProvider` data model if none exists.
+### Configure Payment Module's Providers
 
-This data model is used to reference a payment provider and determine whether it’s installed in the application.
+The Payment Module accepts a `providers` option that allows you to configure the providers registered in your application.
+
+Learn more about this option in the [Module Options](../module-options/page.mdx) guide.
+
+### Registration on Application Start
+
+When the Medusa application starts, it registers the Payment Module Providers defined in the `providers` option of the Payment Module.
+
+For each Payment Module Provider, the Medusa application finds all payment provider services defined in them to register.
+
+### PaymentProvider Data Model
+
+A registered payment provider is represented by the [PaymentProvider data model](/references/payment/models/PaymentProvider) in the Medusa application.
+
+![Diagram showcasing the PaymentProvider data model](https://res.cloudinary.com/dza7lstvk/image/upload/v1746791364/Medusa%20Resources/payment-provider-model_lx91oa.jpg)
+
+This data model is used to reference a service in the Payment Module Provider and determine whether it's installed in the application.
+
+The `PaymentProvider` data model has the following properties:
+
+- `id`: The unique identifier of the Payment Module Provider. The ID's format is `pp_{identifier}_{id}`, where:
+    - `identifier` is the value of the `identifier` property in the Payment Module Provider's service.
+    - `id` is the value of the `id` property of the Payment Module Provider in `medusa-config.ts`.
+- `is_enabled`: A boolean indicating whether the payment provider is enabled.
+
+### How to Remove a Payment Provider?
+
+If you remove a payment provider from the `providers` option, the Medusa application will not remove the associated `PaymentProvider` data model record.
+
+Instead, the Medusa application will set the `is_enabled` property of the `PaymentProvider`'s record to `false`. This allows you to re-enable the payment provider later if needed by adding it back to the `providers` option.
diff --git a/www/apps/resources/app/commerce-modules/tax/module-options/page.mdx b/www/apps/resources/app/commerce-modules/tax/module-options/page.mdx
index 77722c9bdb..d96ec9646b 100644
--- a/www/apps/resources/app/commerce-modules/tax/module-options/page.mdx
+++ b/www/apps/resources/app/commerce-modules/tax/module-options/page.mdx
@@ -10,11 +10,11 @@ export const metadata = {
 
 # {metadata.title}
 
-In this document, you'll learn about the options of the Tax Module.
+In this guide, you'll learn about the options of the Tax Module.
 
 ## providers
 
-The `providers` option is an array of either tax module providers or path to a file that defines a tax provider.
+The `providers` option is an array of either [tax module providers](../tax-provider/page.mdx) or path to a file that defines a tax provider.
 
 When the Medusa application starts, these providers are registered and can be used to retrieve tax lines.
 
diff --git a/www/apps/resources/app/commerce-modules/tax/page.mdx b/www/apps/resources/app/commerce-modules/tax/page.mdx
index 284b9b3260..45b7c10fe1 100644
--- a/www/apps/resources/app/commerce-modules/tax/page.mdx
+++ b/www/apps/resources/app/commerce-modules/tax/page.mdx
@@ -27,6 +27,7 @@ Learn more about why modules are isolated in [this documentation](!docs!/learn/f
 - [Tax Settings Per Region](./tax-region/page.mdx): Set different tax settings for each tax region.
 - [Tax Rates and Rules](./tax-rates-and-rules/page.mdx): Manage each region's default tax rates and override them with conditioned tax rates.
 - [Retrieve Tax Lines for carts and orders](./tax-calculation-with-provider/page.mdx): Calculate and retrieve the tax lines of a cart or order's line items and shipping methods with tax providers.
+- [Custom Tax Providers](./tax-provider/page.mdx): Create custom tax providers to calculate tax lines differently for each tax region.
 
 ---
 
diff --git a/www/apps/resources/app/commerce-modules/tax/tax-calculation-with-provider/page.mdx b/www/apps/resources/app/commerce-modules/tax/tax-calculation-with-provider/page.mdx
index 1b2729db30..afd5e30edc 100644
--- a/www/apps/resources/app/commerce-modules/tax/tax-calculation-with-provider/page.mdx
+++ b/www/apps/resources/app/commerce-modules/tax/tax-calculation-with-provider/page.mdx
@@ -4,7 +4,7 @@ export const metadata = {
 
 # {metadata.title}
 
-In this document, you’ll learn how tax lines are calculated and what a tax provider is.
+In this guide, you’ll learn how tax lines are calculated using the tax provider.
 
 ## Tax Lines Calculation
 
@@ -64,16 +64,8 @@ The method returns tax lines for the line item and shipping methods. For example
 
 ## Using the Tax Provider in the Calculation
 
-The tax lines retrieved by the `getTaxLines` method are actually retrieved from the tax region’s provider.
+The tax lines retrieved by the `getTaxLines` method are actually retrieved from the tax region’s [Tax Module Provider](../tax-provider/page.mdx).
 
-A tax module provider whose main service implements the logic to shape tax lines. Each tax region has a tax provider.
+A tax module implements the logic to shape tax lines. Each tax region uses a tax provider.
 
-The Tax Module provides a `system` tax provider that only transforms calculated item and shipping tax rates into the required return type.
-
-{/* ---
-
-TODO add once tax provider guide is updated + add module providers match other modules.
-
-## Create Tax Provider
-
-Refer to [this guide](/modules/tax/provider) to learn more about creating a tax provider. */}
+Learn more about tax providers, configuring, and creating them in the [Tax Module Provider](../tax-provider/page.mdx) guide.
diff --git a/www/apps/resources/app/commerce-modules/tax/tax-provider/page.mdx b/www/apps/resources/app/commerce-modules/tax/tax-provider/page.mdx
new file mode 100644
index 0000000000..b953dbbb9b
--- /dev/null
+++ b/www/apps/resources/app/commerce-modules/tax/tax-provider/page.mdx
@@ -0,0 +1,84 @@
+export const metadata = {
+  title: `Tax Module Provider`,
+}
+
+# {metadata.title}
+
+In this guide, you’ll learn about the Tax Module Provider and how it's used.
+
+<Note title="Looking for no-code docs?">
+
+Refer to this [Medusa Admin User Guide](!user-guide!/settings/tax-regions) to learn how to manage tax provider of a tax region using the dashboard.
+
+</Note>
+
+## What is a Tax Module Provider?
+
+The Tax Module Provider handles tax line calculations in the Medusa application. It integrates third-party tax services, such as TaxJar, or implements custom tax calculation logic.
+
+The Medusa application uses the Tax Module Provider whenever it needs to calculate tax lines for a cart or order, or when you [calculate the tax lines using the Tax Module's service](../tax-calculation-with-provider/page.mdx).
+
+![Diagram showcasing the communication between Medusa the Tax Module Provider, and the third-party tax provider.](https://res.cloudinary.com/dza7lstvk/image/upload/v1746790996/Medusa%20Resources/tax-provider-service_kcgpne.jpg)
+
+---
+
+## Default Tax Provider
+
+The Tax Module provides a `system` tax provider that acts as a placeholder tax provider. It performs basic tax calculation, as you can see in the [Create Tax Module Provider](/references/tax/provider#gettaxlines) guide.
+
+This provider is installed by default in your application and you can use it with tax regions.
+
+<Note title="Tip">
+
+The identifier of the system tax provider is `tp_system`.
+
+</Note>
+
+---
+
+## How to Create a Custom Tax Provider?
+
+A Tax Module Provider is a module whose service implements the `ITaxProvider` imported from `@medusajs/framework/types`.
+
+The module can have multiple tax provider services, where each are registered as separate tax providers.
+
+Refer to the [Create Tax Module Provider](/references/tax/provider) guide to learn how to create a Tax Module Provider.
+
+After you create a tax provider, you can choose it as the default Tax Module Provider for a region in the [Medusa Admin dashboard](!user-guide!/settings/tax-regions).
+
+---
+
+## How are Tax Providers Registered?
+
+### Configure Tax Module's Providers
+
+The Tax Module accepts a `providers` option that allows you to configure the providers registered in your application.
+
+Learn more about this option in the [Module Options](../module-options/page.mdx) guide.
+
+### Registration on Application Start
+
+When the Medusa application starts, it registers the Tax Module Providers defined in the `providers` option of the Tax Module.
+
+For each Tax Module Provider, the Medusa application finds all tax provider services defined in them to register.
+
+### TaxProvider Data Model
+
+A registered tax provider is represented by the [TaxProvider data model](/references/tax/models/TaxProvider) in the Medusa application.
+
+This data model is used to reference a service in the Tax Module Provider and determine whether it's installed in the application.
+
+![Diagram showcasing the TaxProvider data model](https://res.cloudinary.com/dza7lstvk/image/upload/v1746791254/Medusa%20Resources/tax-provider-model_r6ktjw.jpg)
+
+The `TaxProvider` data model has the following properties:
+
+- `id`: The unique identifier of the tax provider. The ID's format is `tp_{identifier}_{id}`, where:
+    - `identifier` is the value of the `identifier` property in the Tax Module Provider's service.
+    - `id` is the value of the `id` property of the Tax Module Provider in `medusa-config.ts`.
+- `is_enabled`: A boolean indicating whether the tax provider is enabled.
+
+### How to Remove a Tax Provider?
+
+You can remove a registered tax provider from the Medusa application by removing it from the `providers` option in the Tax Module's configuration.
+
+Then, the next time the Medusa application starts, it will set the `is_enabled` property of the `TaxProvider`'s record to `false`. This allows you to re-enable the tax provider later if needed by adding it back to the `providers` option.
diff --git a/www/apps/resources/app/commerce-modules/tax/tax-region/page.mdx b/www/apps/resources/app/commerce-modules/tax/tax-region/page.mdx
index adfa86893f..854d22662a 100644
--- a/www/apps/resources/app/commerce-modules/tax/tax-region/page.mdx
+++ b/www/apps/resources/app/commerce-modules/tax/tax-region/page.mdx
@@ -18,4 +18,24 @@ A tax region, represented by the [TaxRegion data model](/references/tax/models/T
 
 Tax regions can inherit settings and rules from a parent tax region.
 
-Each tax region has tax rules and a tax provider.
+---
+
+## Tax Rules in a Tax Region
+
+Tax rules define the tax rates and behavior within a tax region. They specify:
+
+- The tax rate percentage.
+- Which products the tax applies to.
+- Other custom rules to determine tax applicability.
+
+Learn more about tax rules in the [Tax Rates and Rules](../tax-rates-and-rules/page.mdx) guide.
+
+---
+
+## Tax Provider
+
+Each tax region can have a default tax provider. The tax provider is responsible for calculating the tax lines for carts and orders in that region.
+
+You can use Medusa's default tax provider or create a custom one, allowing you to integrate with third-party tax services or implement your own tax calculation logic.
+
+Learn more about tax providers in the [Tax Provider](../tax-provider/page.mdx) guide.
\ No newline at end of file
diff --git a/www/apps/resources/generated/edit-dates.mjs b/www/apps/resources/generated/edit-dates.mjs
index ff98eb29da..ddff708572 100644
--- a/www/apps/resources/generated/edit-dates.mjs
+++ b/www/apps/resources/generated/edit-dates.mjs
@@ -49,7 +49,7 @@ export const generatedEditDates = {
   "app/commerce-modules/payment/payment-collection/page.mdx": "2024-10-09T10:56:49.510Z",
   "app/commerce-modules/payment/payment-flow/page.mdx": "2025-01-16T10:43:25.958Z",
   "app/commerce-modules/payment/payment-provider/stripe/page.mdx": "2025-04-25T12:43:03.674Z",
-  "app/commerce-modules/payment/payment-provider/page.mdx": "2025-02-26T11:25:50.645Z",
+  "app/commerce-modules/payment/payment-provider/page.mdx": "2025-05-09T11:29:10.212Z",
   "app/commerce-modules/payment/payment-session/page.mdx": "2024-10-09T10:58:00.960Z",
   "app/commerce-modules/payment/webhook-events/page.mdx": "2024-11-19T11:45:02.167Z",
   "app/commerce-modules/payment/page.mdx": "2025-04-17T08:48:11.702Z",
@@ -88,11 +88,11 @@ export const generatedEditDates = {
   "app/commerce-modules/store/page.mdx": "2025-04-17T08:48:34.141Z",
   "app/commerce-modules/tax/_events/_events-table/page.mdx": "2024-07-03T19:27:13+03:00",
   "app/commerce-modules/tax/_events/page.mdx": "2024-07-03T19:27:13+03:00",
-  "app/commerce-modules/tax/module-options/page.mdx": "2024-10-15T14:35:46.117Z",
-  "app/commerce-modules/tax/tax-calculation-with-provider/page.mdx": "2024-10-15T14:43:00.700Z",
+  "app/commerce-modules/tax/module-options/page.mdx": "2025-05-09T11:31:32.715Z",
+  "app/commerce-modules/tax/tax-calculation-with-provider/page.mdx": "2025-05-09T11:31:02.958Z",
   "app/commerce-modules/tax/tax-rates-and-rules/page.mdx": "2025-02-26T11:35:15.214Z",
   "app/commerce-modules/tax/tax-region/page.mdx": "2025-02-26T11:34:21.259Z",
-  "app/commerce-modules/tax/page.mdx": "2025-04-17T08:48:12.479Z",
+  "app/commerce-modules/tax/page.mdx": "2025-05-09T11:29:31.846Z",
   "app/commerce-modules/user/_events/_events-table/page.mdx": "2024-07-03T19:27:13+03:00",
   "app/commerce-modules/user/_events/page.mdx": "2024-07-03T19:27:13+03:00",
   "app/commerce-modules/user/module-options/page.mdx": "2024-09-30T08:43:53.171Z",
@@ -6246,5 +6246,6 @@ export const generatedEditDates = {
   "references/events/events.Region/page.mdx": "2025-05-07T15:35:18.145Z",
   "references/events/events.Sales_Channel/page.mdx": "2025-05-07T15:35:18.138Z",
   "references/events/events.User/page.mdx": "2025-05-07T15:35:18.135Z",
+  "app/commerce-modules/tax/tax-provider/page.mdx": "2025-05-09T11:25:27.906Z",
   "app/how-to-tutorials/tutorials/saved-payment-methods/page.mdx": "2025-05-13T07:40:15.969Z"
 }
\ No newline at end of file
diff --git a/www/apps/resources/generated/files-map.mjs b/www/apps/resources/generated/files-map.mjs
index 192d0b5406..513fb8fbee 100644
--- a/www/apps/resources/generated/files-map.mjs
+++ b/www/apps/resources/generated/files-map.mjs
@@ -615,6 +615,10 @@ export const filesMap = [
     "filePath": "/www/apps/resources/app/commerce-modules/tax/tax-calculation-with-provider/page.mdx",
     "pathname": "/commerce-modules/tax/tax-calculation-with-provider"
   },
+  {
+    "filePath": "/www/apps/resources/app/commerce-modules/tax/tax-provider/page.mdx",
+    "pathname": "/commerce-modules/tax/tax-provider"
+  },
   {
     "filePath": "/www/apps/resources/app/commerce-modules/tax/tax-rates-and-rules/page.mdx",
     "pathname": "/commerce-modules/tax/tax-rates-and-rules"
diff --git a/www/apps/resources/generated/generated-commerce-modules-sidebar.mjs b/www/apps/resources/generated/generated-commerce-modules-sidebar.mjs
index dc0116b114..c57bd169c0 100644
--- a/www/apps/resources/generated/generated-commerce-modules-sidebar.mjs
+++ b/www/apps/resources/generated/generated-commerce-modules-sidebar.mjs
@@ -445,7 +445,7 @@ const generatedgeneratedCommerceModulesSidebarSidebar = {
               "isPathHref": true,
               "type": "link",
               "path": "/commerce-modules/auth/auth-providers",
-              "title": "Auth Providers",
+              "title": "Auth Module Provider",
               "children": []
             },
             {
@@ -489,7 +489,7 @@ const generatedgeneratedCommerceModulesSidebarSidebar = {
               "isPathHref": true,
               "type": "link",
               "path": "/references/auth/provider",
-              "title": "Create Auth Provider Module",
+              "title": "Create Auth Provider",
               "children": []
             },
             {
@@ -3323,7 +3323,7 @@ const generatedgeneratedCommerceModulesSidebarSidebar = {
               "isPathHref": true,
               "type": "link",
               "path": "/commerce-modules/fulfillment/fulfillment-provider",
-              "title": "Fulfillment Provider",
+              "title": "Fulfillment Module Provider",
               "children": []
             },
             {
@@ -3383,7 +3383,7 @@ const generatedgeneratedCommerceModulesSidebarSidebar = {
               "isPathHref": true,
               "type": "link",
               "path": "/references/fulfillment/provider",
-              "title": "Create Fulfillment Provider Module",
+              "title": "Create Fulfillment Provider",
               "children": []
             },
             {
@@ -9046,7 +9046,7 @@ const generatedgeneratedCommerceModulesSidebarSidebar = {
               "isPathHref": true,
               "type": "link",
               "path": "/commerce-modules/payment/payment-provider",
-              "title": "Payment Provider Module",
+              "title": "Payment Module Provider",
               "children": []
             },
             {
@@ -15850,12 +15850,20 @@ const generatedgeneratedCommerceModulesSidebarSidebar = {
               "title": "Tax Rates and Rules",
               "children": []
             },
+            {
+              "loaded": true,
+              "isPathHref": true,
+              "type": "link",
+              "path": "/commerce-modules/tax/tax-provider",
+              "title": "Tax Module Providers",
+              "children": []
+            },
             {
               "loaded": true,
               "isPathHref": true,
               "type": "link",
               "path": "/commerce-modules/tax/tax-calculation-with-provider",
-              "title": "Tax Calculation and Providers",
+              "title": "Tax Calculation",
               "children": []
             }
           ]
diff --git a/www/apps/resources/sidebars/auth.mjs b/www/apps/resources/sidebars/auth.mjs
index 0bc343f9d1..efdc1168a3 100644
--- a/www/apps/resources/sidebars/auth.mjs
+++ b/www/apps/resources/sidebars/auth.mjs
@@ -30,7 +30,7 @@ export const authSidebar = [
           {
             type: "link",
             path: "/commerce-modules/auth/auth-providers",
-            title: "Auth Providers",
+            title: "Auth Module Provider",
           },
           {
             type: "link",
@@ -66,7 +66,7 @@ export const authSidebar = [
           {
             type: "link",
             path: "/references/auth/provider",
-            title: "Create Auth Provider Module",
+            title: "Create Auth Provider",
           },
         ],
       },
diff --git a/www/apps/resources/sidebars/fulfillment.mjs b/www/apps/resources/sidebars/fulfillment.mjs
index d3c83fd57e..268fe347ef 100644
--- a/www/apps/resources/sidebars/fulfillment.mjs
+++ b/www/apps/resources/sidebars/fulfillment.mjs
@@ -32,7 +32,7 @@ export const fulfillmentSidebar = [
           {
             type: "link",
             path: "/commerce-modules/fulfillment/fulfillment-provider",
-            title: "Fulfillment Provider",
+            title: "Fulfillment Module Provider",
           },
           {
             type: "link",
@@ -63,7 +63,7 @@ export const fulfillmentSidebar = [
           {
             type: "link",
             path: "/references/fulfillment/provider",
-            title: "Create Fulfillment Provider Module",
+            title: "Create Fulfillment Provider",
           },
           {
             type: "ref",
diff --git a/www/apps/resources/sidebars/payment.mjs b/www/apps/resources/sidebars/payment.mjs
index ce3fa287d3..5f9c7e9539 100644
--- a/www/apps/resources/sidebars/payment.mjs
+++ b/www/apps/resources/sidebars/payment.mjs
@@ -40,7 +40,7 @@ export const paymentSidebar = [
           {
             type: "link",
             path: "/commerce-modules/payment/payment-provider",
-            title: "Payment Provider Module",
+            title: "Payment Module Provider",
           },
           {
             type: "link",
diff --git a/www/apps/resources/sidebars/tax.mjs b/www/apps/resources/sidebars/tax.mjs
index a1f56cb083..b477761290 100644
--- a/www/apps/resources/sidebars/tax.mjs
+++ b/www/apps/resources/sidebars/tax.mjs
@@ -32,10 +32,15 @@ export const taxSidebar = [
             path: "/commerce-modules/tax/tax-rates-and-rules",
             title: "Tax Rates and Rules",
           },
+          {
+            type: "link",
+            path: "/commerce-modules/tax/tax-provider",
+            title: "Tax Module Providers",
+          },
           {
             type: "link",
             path: "/commerce-modules/tax/tax-calculation-with-provider",
-            title: "Tax Calculation and Providers",
+            title: "Tax Calculation",
           },
         ],
       },
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 153b3534cd..f354058ca1 100644
--- a/www/apps/user-guide/app/settings/tax-regions/page.mdx
+++ b/www/apps/user-guide/app/settings/tax-regions/page.mdx
@@ -45,7 +45,7 @@ To create a tax region:
     - Under the "Default tax rate" section, you can optionally enter a name, tax rate, and tax code in their respective fields.
 4. Once you're done, click the Save button.
 
-![Create tax region form](https://res.cloudinary.com/dza7lstvk/image/upload/v1739971037/User%20Guide/Screenshot_2025-02-19_at_3.17.05_PM_vc0uqk.png)
+![Create tax region form](https://res.cloudinary.com/dza7lstvk/image/upload/v1746803850/User%20Guide/Screenshot_2025-05-09_at_6.14.41_PM_vzpyza.png)
 
 ---
 
@@ -58,7 +58,21 @@ To view the details of a tax region:
 
 This opens the tax region's details page where you can also manage the tax region.
 
-![Tax region details](https://res.cloudinary.com/dza7lstvk/image/upload/v1739970845/User%20Guide/Screenshot_2025-02-19_at_3.13.51_PM_fjoyyu.png)
+![Tax region details](https://res.cloudinary.com/dza7lstvk/image/upload/v1746796437/User%20Guide/Screenshot_2025-05-09_at_4.13.06_PM_m23ili.png)
+
+---
+
+## Edit Tax Region
+
+To edit a tax region:
+
+1. Go to the tax region's details page.
+2. Click the <InlineIcon Icon={EllipsisHorizontal} alt="three-dots" /> icon at the right of the tax region's name.
+3. Choose Edit from the dropdown.
+4. In the side window that opens, you can edit the tax region's default tax provider.
+5. Once you're done, click the Save button.
+
+![Edit tax region form](https://res.cloudinary.com/dza7lstvk/image/upload/v1746803872/User%20Guide/Screenshot_2025-05-09_at_6.15.25_PM_ebb76k.png)
 
 ---
 
@@ -66,7 +80,7 @@ This opens the tax region's details page where you can also manage the tax regio
 
 To edit the default tax rate of the region:
 
-1. Go to the region's details page.
+1. Go to the tax region's details page.
 2. In the first section, you'll find details of the default tax rate, including its tax rate and code. Click on the <InlineIcon Icon={EllipsisHorizontal} alt="three-dots" /> icon at its right.
 
 ![The icon to click on](https://res.cloudinary.com/dza7lstvk/image/upload/v1739974452/User%20Guide/Screenshot_2025-02-19_at_4.13.51_PM_zclvnp.png)
@@ -171,3 +185,35 @@ This opens the sublevel tax region's details page where you can also manage the
 ### Manage Sublevel Tax Region's Rates
 
 You can manage the sublevel tax region's [default](#edit-default-tax-rate) and [override](#manage-tax-rate-overrides) rates the same way you manage the parent tax region's rates.
+
+### Delete Sublevel Tax Region
+
+<Note type="warning">
+
+Deleting a sublevel tax region is irreversible.
+
+</Note>
+
+To delete a sublevel tax region:
+
+1. Go to the sublevel tax region's details page.
+2. Click the <InlineIcon Icon={EllipsisHorizontal} alt="three-dots" /> icon at the right of the sublevel tax region's name.
+3. Choose Delete from the dropdown.
+4. Confirm deleting the sublevel tax region by clicking the Delete button in the pop-up.
+
+---
+
+## Delete Tax Region
+
+<Note type="warning">
+
+Deleting a tax region is irreversible.
+
+</Note>
+
+To delete a tax region:
+
+1. Go to the tax region's details page.
+2. Click the <InlineIcon Icon={EllipsisHorizontal} alt="three-dots" /> icon at the right of the tax region's name.
+3. Choose Delete from the dropdown.
+4. Confirm deleting the tax region by clicking the Delete button in the pop-up.
diff --git a/www/apps/user-guide/generated/edit-dates.mjs b/www/apps/user-guide/generated/edit-dates.mjs
index 134ad77ca8..9003863d43 100644
--- a/www/apps/user-guide/generated/edit-dates.mjs
+++ b/www/apps/user-guide/generated/edit-dates.mjs
@@ -46,7 +46,7 @@ export const generatedEditDates = {
   "app/price-lists/create/page.mdx": "2025-02-19T10:11:33.113Z",
   "app/price-lists/manage/page.mdx": "2025-02-19T10:35:49.881Z",
   "app/price-lists/page.mdx": "2025-02-19T09:51:32.546Z",
-  "app/settings/tax-regions/page.mdx": "2025-02-19T17:33:43.806Z",
+  "app/settings/tax-regions/page.mdx": "2025-05-09T13:58:40.440Z",
   "app/settings/locations-and-shipping/locations/page.mdx": "2025-04-17T13:47:40.883Z",
   "app/settings/locations-and-shipping/page.mdx": "2025-02-19T17:23:45.824Z",
   "app/settings/locations-and-shipping/shipping-profiles/page.mdx": "2025-02-19T17:36:46.339Z",