diff --git a/www/apps/book/app/learn/fundamentals/modules/db-operations/page.mdx b/www/apps/book/app/learn/fundamentals/modules/db-operations/page.mdx
index b2278bcd0f..534652ec56 100644
--- a/www/apps/book/app/learn/fundamentals/modules/db-operations/page.mdx
+++ b/www/apps/book/app/learn/fundamentals/modules/db-operations/page.mdx
@@ -1,4 +1,4 @@
-import { CodeTabs, CodeTab } from "docs-ui"
+import { CodeTabs, CodeTab, TypeList } from "docs-ui"
 
 export const metadata = {
   title: `${pageNumber} Perform Database Operations in a Service`,
@@ -78,7 +78,18 @@ Refer to [MikroORM's reference](https://mikro-orm.io/api/knex/class/EntityManage
 
 ---
 
-## Execute Operations in Transactions
+## Perform Database Operations
+
+There are two ways to perform database operations in transactional methods:
+
+1. Using the [data model repositories](#perform-database-operations-with-data-model-repositories) in your module.
+2. Using the [transactional entity manager](#perform-database-operations-with-the-transactional-entity-manager) injected into the method's shared context.
+
+For both approaches, you must wrap the method performing the database operations in a transaction.
+
+### Wrap Database Operations in Transactions
+
+When performing database operations without using the [Service Factory](../service-factory/page.mdx), you must wrap the method performing the database operations in a transaction.
 
 To wrap database operations in a transaction, you create two methods:
 
@@ -92,9 +103,7 @@ For example:
 export const opHighlights = [
   ["11", "InjectTransactionManager", "A decorator that injects the a transactional entity manager into the `sharedContext` parameter."],
   ["17", "MedusaContext", "A decorator to use Medusa's shared context."],
-  ["20", "nativeUpdate", "Update a record."],
-  ["31", "execute", "Retrieve the updated record."],
-  ["38", "InjectManager", "A decorator that injects a forked entity manager into the context."],
+  ["24", "InjectManager", "A decorator that injects a forked entity manager into the context."],
 ]
 
 ```ts highlights={opHighlights}
@@ -106,6 +115,273 @@ import {
 import { Context } from "@medusajs/framework/types"
 import { EntityManager } from "@mikro-orm/knex"
 
+class BlogModuleService {
+  // ...
+  @InjectTransactionManager()
+  protected async update_(
+    input: {
+      id: string,
+      name: string
+    },
+    @MedusaContext() sharedContext?: Context<EntityManager>
+  ): Promise<any> {
+    const transactionManager = sharedContext?.transactionManager
+    
+    // TODO: update the record
+  }
+
+  @InjectManager()
+  async update(
+    input: {
+      id: string,
+      name: string
+    },
+    @MedusaContext() sharedContext?: Context<EntityManager>
+  ) {
+    return await this.update_(input, sharedContext)
+  }
+}
+```
+
+The `BlogModuleService` has two methods:
+
+- A protected `update_` that performs the database operations inside a transaction.
+- A public `update` that executes the transactional protected method.
+
+You can then perform in the transactional method the database operations either using the [data model repository](#perform-database-operations-with-data-model-repositories) or the [transactional entity manager](#perform-database-operations-with-the-transactional-entity-manager).
+
+#### Why Wrap a Transactional Method
+
+The variables in the transactional method (such as `update_`) hold values that are uncommitted to the database. They're only committed once the method finishes execution.
+
+So, if in your method you perform database operations, then use their result to perform other actions, such as connecting to a third-party service, you'll be working with uncommitted data.
+
+By placing only the database operations in a method that has the `InjectTransactionManager` and using it in a wrapper method, the wrapper method receives the committed result of the transactional method.
+
+<Note title="Optimization Tip">
+
+This is also useful if you perform heavy data normalization outside of the database operations. In that case, you don't hold the transaction for a longer time than needed.
+
+</Note>
+
+For example, the `update` method may call other methods than `update_` to perform other actions:
+
+```ts
+// other imports...
+import { 
+  InjectManager,
+  InjectTransactionManager,
+  MedusaContext,
+} from "@medusajs/framework/utils"
+import { Context } from "@medusajs/framework/types"
+import { EntityManager } from "@mikro-orm/knex"
+
+class BlogModuleService {
+  // ...
+  @InjectTransactionManager()
+  protected async update_(
+    // ...
+  ): Promise<any> {
+    // ...
+  }
+  @InjectManager()
+  async update(
+    input: {
+      id: string,
+      name: string
+    },
+    @MedusaContext() sharedContext?: Context<EntityManager>
+  ) {
+    const newData = await this.update_(input, sharedContext)
+
+    // example method that sends data to another system
+    await this.sendNewDataToSystem(newData)
+
+    return newData
+  }
+}
+```
+
+In this case, only the `update_` method is wrapped in a transaction. The returned value `newData` holds the committed result, which can be used for other operations, such as passed to a `sendNewDataToSystem` method.
+
+#### Using Methods in Transactional Methods
+
+If your protected transactional method uses other methods that accept a Medusa context, pass the shared context to those methods.
+
+For example:
+
+export const anotherMethodHighlights = [
+  ["26", "sharedContext", "Pass the context to the other transactional method."]
+]
+
+```ts highlights={anotherMethodHighlights}
+// other imports...
+import { 
+  InjectTransactionManager,
+  MedusaContext,
+} from "@medusajs/framework/utils"
+import { Context } from "@medusajs/framework/types"
+import { EntityManager } from "@mikro-orm/knex"
+
+class BlogModuleService {
+  // ...
+  @InjectTransactionManager()
+  protected async anotherMethod(
+    @MedusaContext() sharedContext?: Context<EntityManager>
+  ) {
+    // ...
+  }
+  
+  @InjectTransactionManager()
+  protected async update_(
+    input: {
+      id: string,
+      name: string
+    },
+    @MedusaContext() sharedContext?: Context<EntityManager>
+  ): Promise<any> {
+    this.anotherMethod(sharedContext)
+  }
+}
+```
+
+You use the `anotherMethod` transactional method in the `update_` transactional method, so you pass it the shared context.
+
+The `anotherMethod` now runs in the same transaction as the `update_` method.
+
+### Perform Database Operations with Data Model Repositories
+
+For every data model in your module, Medusa generates a data model repository that has methods to perform database operations.
+
+For example, if your module has a `Post` model, it has a `postRepository` in the container.
+
+The data model repository is a wrapper around the [entity manager](https://mikro-orm.io/api/knex/class/EntityManager) that provides a higher-level API for performing database operations.
+
+<Note>
+
+To use the low-level entity manager, use the [transactional entity manager](#perform-database-operations-with-the-transactional-entity-manager) instead.
+
+</Note>
+
+#### Resolve Data Model Repository
+
+When the Medusa application injects a data model repository into a module's container, it formats the registration name by:
+
+- Taking the data model's name that's passed as the first parameter of `model.define`
+- Lower-casing the first character
+- Suffixing the result with `Repository`.
+
+For example:
+
+- `Post` model: `postRepository`
+- `My_Custom` model: `my_CustomRepository`
+
+So, to resolve a data model repository from a module's container, pass the expected registration name of the repository in the first parameter of the module's constructor (the container).
+
+For example:
+
+<CodeTabs group="service-type">
+  <CodeTab label="Extending Service Factory" value="service-factory">
+
+export const serviceFactoryRepoHighlights = [
+  ["20", "postRepository", "Resolve the data model repository of the `Post` model."],
+]
+
+```ts highlights={serviceFactoryRepoHighlights}
+import { MedusaService } from "@medusajs/framework/utils"
+import { InferTypeOf, DAL } from "@medusajs/framework/types"
+import Post from "./models/post"
+
+type Post = InferTypeOf<typeof Post>
+
+type InjectedDependencies = {
+  postRepository: DAL.RepositoryService<Post>
+}
+
+class BlogModuleService extends MedusaService({
+  Post,
+}){
+  protected postRepository_: DAL.RepositoryService<Post>
+
+  constructor({ 
+    postRepository 
+  }: InjectedDependencies) {
+    super(...arguments)
+    this.postRepository_ = postRepository
+  }
+}
+
+export default BlogModuleService
+```
+  </CodeTab>
+  <CodeTab label="Without Service Factory" value="no-service-factory">
+
+export const noServiceFactoryRepoHighlights = [
+  ["17", "postRepository", "Resolve the data model repository of the `Post` model."],
+]
+
+```ts highlights={noServiceFactoryRepoHighlights}
+import { InferTypeOf, DAL } from "@medusajs/framework/types"
+import Post from "./models/post"
+
+type Post = InferTypeOf<typeof Post>
+
+type InjectedDependencies = {
+  postRepository: DAL.RepositoryService<Post>
+}
+
+class BlogModuleService {
+  protected postRepository_: DAL.RepositoryService<Post>
+
+  constructor({ 
+    postRepository 
+  }: InjectedDependencies) {
+    super(...arguments)
+    this.postRepository_ = postRepository
+  }
+}
+
+export default BlogModuleService
+```
+
+  </CodeTab>
+</CodeTabs>
+
+You can then use the data model repository in your service to perform database operations.
+
+#### Data Model Repository Methods
+
+A data model repository has methods that allows you to create, update, and delete records, among other operations.
+
+To learn about the methods available in a data model repository, refer to the [Data Model Repository](!resources!/data-model-repository-reference) reference.
+
+### Perform Database Operations with the Transactional Entity Manager
+
+Your transactional method can use the transactional entity manager injected into the method's shared context to perform database operations. It's an instance of the [MikroORM EntityManager](https://mikro-orm.io/api/knex/class/EntityManager) class.
+
+<Note>
+
+To use an easier higher-level API focused on each data model, use the [data model repository](#perform-database-operations-with-data-model-repositories) instead.
+
+</Note>
+
+For example:
+
+export const transactionalEntityManagerHighlights = [
+  ["19", "transactionManager", "Use the transactional entity manager injected\ninto the `sharedContext` parameter."],
+  ["20", "nativeUpdate", "Perform a native update operation."],
+  ["31", "execute", "Perform a native query operation."],
+]
+
+```ts highlights={transactionalEntityManagerHighlights}
+import { 
+  InjectManager,
+  InjectTransactionManager,
+  MedusaContext,
+} from "@medusajs/framework/utils"
+import { Context } from "@medusajs/framework/types"
+import { EntityManager } from "@mikro-orm/knex"
+
 class BlogModuleService {
   // ...
   @InjectTransactionManager()
@@ -148,119 +424,15 @@ class BlogModuleService {
 }
 ```
 
-The `BlogModuleService` has two methods:
+The `update_` method uses the transactional entity manager injected into the `sharedContext.transactionManager` property to perform the database operations.
 
-- A protected `update_` that performs the database operations inside a transaction.
-- A public `update` that executes the transactional protected method.
-
-The shared context's `transactionManager` property holds the transactional entity manager (injected by `InjectTransactionManager`) that you use to perform database operations.
-
-<Note>
-
-Refer to [MikroORM's reference](https://mikro-orm.io/api/knex/class/EntityManager) for a full list of the entity manager's methods.
-
-</Note>
-
-### Why Wrap a Transactional Method
-
-The variables in the transactional method (for example, `update_`) hold values that are uncommitted to the database. They're only committed once the method finishes execution.
-
-So, if in your method you perform database operations, then use their result to perform other actions, such as connecting to a third-party service, you'll be working with uncommitted data.
-
-By placing only the database operations in a method that has the `InjectTransactionManager` and using it in a wrapper method, the wrapper method receives the committed result of the transactional method.
-
-<Note title="Optimization Tip">
-
-This is also useful if you perform heavy data normalization outside of the database operations. In that case, you don't hold the transaction for a longer time than needed.
-
-</Note>
-
-For example, the `update` method could be changed to the following:
-
-```ts
-// other imports...
-import { 
-  InjectManager,
-  InjectTransactionManager,
-  MedusaContext,
-} from "@medusajs/framework/utils"
-import { Context } from "@medusajs/framework/types"
-import { EntityManager } from "@mikro-orm/knex"
-
-class BlogModuleService {
-  // ...
-  @InjectTransactionManager()
-  protected async update_(
-    // ...
-  ): Promise<any> {
-    // ...
-  }
-  @InjectManager()
-  async update(
-    input: {
-      id: string,
-      name: string
-    },
-    @MedusaContext() sharedContext?: Context<EntityManager>
-  ) {
-    const newData = await this.update_(input, sharedContext)
-
-    // example method that sends data to another system
-    await this.sendNewDataToSystem(newData)
-
-    return newData
-  }
-}
-```
-
-In this case, only the `update_` method is wrapped in a transaction. The returned value `newData` holds the committed result, which can be used for other operations, such as passed to a `sendNewDataToSystem` method.
-
-### Using Methods in Transactional Methods
-
-If your transactional method uses other methods that accept a Medusa context, pass the shared context to those methods.
-
-For example:
-
-```ts
-// other imports...
-import { 
-  InjectTransactionManager,
-  MedusaContext,
-} from "@medusajs/framework/utils"
-import { Context } from "@medusajs/framework/types"
-import { EntityManager } from "@mikro-orm/knex"
-
-class BlogModuleService {
-  // ...
-  @InjectTransactionManager()
-  protected async anotherMethod(
-    @MedusaContext() sharedContext?: Context<EntityManager>
-  ) {
-    // ...
-  }
-  
-  @InjectTransactionManager()
-  protected async update_(
-    input: {
-      id: string,
-      name: string
-    },
-    @MedusaContext() sharedContext?: Context<EntityManager>
-  ): Promise<any> {
-    this.anotherMethod(sharedContext)
-  }
-}
-```
-
-You use the `anotherMethod` transactional method in the `update_` transactional method, so you pass it the shared context.
-
-The `anotherMethod` now runs in the same transaction as the `update_` method.
+Find all available methods in the [MikroORM EntityManager](https://mikro-orm.io/api/knex/class/EntityManager) reference.
 
 ---
 
-## Configure Transactions
+## Configure Transactions with the Base Repository
 
-To configure the transaction, such as its [isolation level](https://www.postgresql.org/docs/current/transaction-iso.html), use the `baseRepository` dependency registered in your module's container.
+To configure the transaction, such as its [isolation level](https://www.postgresql.org/docs/current/transaction-iso.html), use the `baseRepository` class registered in your module's container.
 
 The `baseRepository` is an instance of a repository class that provides methods to create transactions, run database operations, and more.
 
@@ -271,7 +443,11 @@ For example, resolve the `baseRepository` in your service's constructor:
 <CodeTabs group="service-type">
   <CodeTab label="Extending Service Factory" value="service-factory">
 
-```ts highlights={[["14"]]}
+export const baseRepoHighlights = [
+  ["16", "baseRepository", "Resolve the base repository."],
+]
+
+```ts highlights={baseRepoHighlights}
 import { MedusaService } from "@medusajs/framework/utils"
 import Post from "./models/post"
 import { DAL } from "@medusajs/framework/types"
@@ -293,10 +469,15 @@ class BlogModuleService extends MedusaService({
 
 export default BlogModuleService
 ```
+
   </CodeTab>
   <CodeTab label="Without Service Factory" value="no-service-factory">
 
-```ts highlights={[["10"]]}
+export const noServiceFactoryBaseRepoHighlights = [
+  ["11", "baseRepository", "Resolve the base repository."],
+]
+
+```ts highlights={noServiceFactoryBaseRepoHighlights}
 import { DAL } from "@medusajs/framework/types"
 
 type InjectedDependencies = {
@@ -317,7 +498,7 @@ export default BlogModuleService
   </CodeTab>
 </CodeTabs>
 
-Then, add the following method that uses it:
+Then, use it in the service's transactional methods:
 
 export const repoHighlights = [
   ["20", "transaction", "Wrap the function parameter in a transaction."]
@@ -399,7 +580,7 @@ The second parameter of the `baseRepository_.transaction` method is an object of
 
 1. `transaction`: Set the transactional entity manager passed to the function. You must provide this option as explained in the previous section.
 
-```ts highlights={[["16"]]}
+```ts highlights={[["24"]]}
 // other imports...
 import { EntityManager } from "@mikro-orm/knex"
 import { 
@@ -407,7 +588,6 @@ import {
   MedusaContext,
 } from "@medusajs/framework/utils"
 import { Context } from "@medusajs/framework/types"
-import { EntityManager } from "@mikro-orm/knex"
 
 class BlogModuleService {
   // ...
@@ -438,7 +618,7 @@ class BlogModuleService {
     - `repeatable read`
     - `serializable`
 
-```ts highlights={[["19"]]}
+```ts highlights={[["25"]]}
 // other imports...
 import { 
   InjectTransactionManager,
@@ -473,7 +653,7 @@ class BlogModuleService {
 3. `enableNestedTransactions`: (default: `false`) whether to allow using nested transactions.
     - If `transaction` is provided and this is disabled, the manager in `transaction` is re-used.
 
-```ts highlights={[["16"]]}
+```ts highlights={[["24"]]}
 // other imports...
 import { 
   InjectTransactionManager,
diff --git a/www/apps/book/generated/edit-dates.mjs b/www/apps/book/generated/edit-dates.mjs
index af40de05ff..02f239afb7 100644
--- a/www/apps/book/generated/edit-dates.mjs
+++ b/www/apps/book/generated/edit-dates.mjs
@@ -68,7 +68,7 @@ export const generatedEditDates = {
   "app/learn/fundamentals/module-links/directions/page.mdx": "2025-03-17T12:52:06.161Z",
   "app/learn/fundamentals/module-links/page.mdx": "2025-04-17T08:50:17.036Z",
   "app/learn/fundamentals/module-links/query/page.mdx": "2025-04-18T11:13:02.240Z",
-  "app/learn/fundamentals/modules/db-operations/page.mdx": "2025-03-21T09:21:46.901Z",
+  "app/learn/fundamentals/modules/db-operations/page.mdx": "2025-04-23T14:24:37.910Z",
   "app/learn/fundamentals/modules/multiple-services/page.mdx": "2025-03-18T15:11:44.632Z",
   "app/learn/fundamentals/modules/page.mdx": "2025-03-18T07:51:09.049Z",
   "app/learn/debugging-and-testing/instrumentation/page.mdx": "2025-02-24T08:12:53.132Z",
diff --git a/www/apps/book/public/llms-full.txt b/www/apps/book/public/llms-full.txt
index 20447894b6..5bbe86ec07 100644
--- a/www/apps/book/public/llms-full.txt
+++ b/www/apps/book/public/llms-full.txt
@@ -330,6 +330,28 @@ Refer to [this documentation](https://docs.medusajs.com/learn/update/index.html.
 In the next chapters, you'll learn about the architecture of your Medusa application, then learn how to customize your application to build custom features.
 
 
+# Storefront Development
+
+The Medusa application is made up of a Node.js server and an admin dashboard. Storefronts are installed, built, and hosted separately from the Medusa application, giving you the flexibility to choose the frontend tech stack that you and your team are proficient in, and implement unique design systems and user experience.
+
+You can build your storefront from scratch with your preferred tech stack, or start with our Next.js Starter storefront. The Next.js Starter storefront provides rich commerce features and a sleek design. Developers and businesses can use it as-is or build on top of it to tailor it for the business's unique use case, design, and customer experience.
+
+- [Install Next.js Starter Storefront](https://docs.medusajs.com/resources/nextjs-starter/index.html.md)
+- [Build Custom Storefront](https://docs.medusajs.com/resources/storefront-development/index.html.md)
+
+***
+
+## Passing a Publishable API Key in Storefront Requests
+
+When sending a request to an API route starting with `/store`, you must include a publishable API key in the header of your request.
+
+A publishable API key sets the scope of your request to one or more sales channels.
+
+Then, when you retrieve products, only products of those sales channels are retrieved. This also ensures you retrieve correct inventory data, and associate created orders with the scoped sales channel.
+
+Learn more about passing the publishable API key in [this storefront development guide](https://docs.medusajs.com/resources/storefront-development/publishable-api-keys/index.html.md).
+
+
 # Updating Medusa
 
 In this chapter, you'll learn about updating your Medusa application and packages.
@@ -436,26 +458,350 @@ npm  install
 ```
 
 
-# Storefront Development
+# Configure Instrumentation
 
-The Medusa application is made up of a Node.js server and an admin dashboard. Storefronts are installed, built, and hosted separately from the Medusa application, giving you the flexibility to choose the frontend tech stack that you and your team are proficient in, and implement unique design systems and user experience.
+In this chapter, you'll learn about observability in Medusa and how to configure instrumentation with OpenTelemetry.
 
-You can build your storefront from scratch with your preferred tech stack, or start with our Next.js Starter storefront. The Next.js Starter storefront provides rich commerce features and a sleek design. Developers and businesses can use it as-is or build on top of it to tailor it for the business's unique use case, design, and customer experience.
+## Observability with OpenTelemtry
 
-- [Install Next.js Starter Storefront](https://docs.medusajs.com/resources/nextjs-starter/index.html.md)
-- [Build Custom Storefront](https://docs.medusajs.com/resources/storefront-development/index.html.md)
+Medusa uses [OpenTelemetry](https://opentelemetry.io/) for instrumentation and reporting. When configured, it reports traces for:
+
+- HTTP requests
+- Workflow executions
+- Query usages
+- Database queries and operations
 
 ***
 
-## Passing a Publishable API Key in Storefront Requests
+## How to Configure Instrumentation in Medusa?
 
-When sending a request to an API route starting with `/store`, you must include a publishable API key in the header of your request.
+### Prerequisites
 
-A publishable API key sets the scope of your request to one or more sales channels.
+- [An exporter to visualize your application's traces, such as Zipkin.](https://zipkin.io/pages/quickstart.html)
 
-Then, when you retrieve products, only products of those sales channels are retrieved. This also ensures you retrieve correct inventory data, and associate created orders with the scoped sales channel.
+### Install Dependencies
 
-Learn more about passing the publishable API key in [this storefront development guide](https://docs.medusajs.com/resources/storefront-development/publishable-api-keys/index.html.md).
+Start by installing the following OpenTelemetry dependencies in your Medusa project:
+
+```bash npm2yarn
+npm install @opentelemetry/sdk-node @opentelemetry/resources @opentelemetry/sdk-trace-node @opentelemetry/instrumentation-pg
+```
+
+Also, install the dependencies relevant for the exporter you use. If you're using Zipkin, install the following dependencies:
+
+```bash npm2yarn
+npm install @opentelemetry/exporter-zipkin
+```
+
+### Add instrumentation.ts
+
+Next, create the file `instrumentation.ts` with the following content:
+
+```ts title="instrumentation.ts"
+import { registerOtel } from "@medusajs/medusa"
+import { ZipkinExporter } from "@opentelemetry/exporter-zipkin"
+
+// If using an exporter other than Zipkin, initialize it here.
+const exporter = new ZipkinExporter({
+  serviceName: "my-medusa-project",
+})
+
+export function register() {
+  registerOtel({
+    serviceName: "medusajs",
+    // pass exporter
+    exporter,
+    instrument: {
+      http: true,
+      workflows: true,
+      query: true,
+    },
+  })
+}
+```
+
+In the `instrumentation.ts` file, you export a `register` function that uses Medusa's `registerOtel` utility function. You also initialize an instance of the exporter, such as Zipkin, and pass it to the `registerOtel` function.
+
+`registerOtel` accepts an object where you can pass any [NodeSDKConfiguration](https://open-telemetry.github.io/opentelemetry-js/interfaces/_opentelemetry_sdk_node.NodeSDKConfiguration.html) property along with the following properties:
+
+The `NodeSDKConfiguration` properties are accepted since Medusa v2.5.1.
+
+- serviceName: (\`string\`) The name of the service traced.
+- exporter: (\[SpanExporter]\(https://open-telemetry.github.io/opentelemetry-js/interfaces/\_opentelemetry\_sdk\_trace\_base.SpanExporter.html)) An instance of an exporter, such as Zipkin.
+- instrument: (\`object\`) Options specifying what to trace.
+
+  - http: (\`boolean\`) Whether to trace HTTP requests.
+
+  - query: (\`boolean\`) Whether to trace Query usages.
+
+  - workflows: (\`boolean\`) Whether to trace Workflow executions.
+
+  - db: (\`boolean\`) Whether to trace database queries and operations.
+- instrumentations: (\[Instrumentation\[]]\(https://open-telemetry.github.io/opentelemetry-js/interfaces/\_opentelemetry\_instrumentation.Instrumentation.html)) Additional instrumentation options that OpenTelemetry accepts.
+
+***
+
+## Test it Out
+
+To test it out, start your exporter, such as Zipkin.
+
+Then, start your Medusa application:
+
+```bash npm2yarn
+npm run dev
+```
+
+Try to open the Medusa Admin or send a request to an API route.
+
+If you check traces in your exporter, you'll find new traces reported.
+
+### Trace Span Names
+
+Trace span names start with the following keywords based on what it's reporting:
+
+- `{methodName} {URL}` when reporting HTTP requests, where `{methodName}` is the HTTP method, and `{URL}` is the URL the request is sent to.
+- `route:` when reporting route handlers running on an HTTP request.
+- `middleware:` when reporting a middleware running on an HTTP request.
+- `workflow:` when reporting a workflow execution.
+- `step:` when reporting a step in a workflow execution.
+- `query.graph:` when reporting Query usages.
+- `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
@@ -1361,134 +1707,6 @@ npx medusa db:migrate
 ```
 
 
-# Using TypeScript Aliases
-
-By default, Medusa doesn't support TypeScript aliases in production.
-
-If you prefer using TypeScript aliases, install following development dependencies:
-
-```bash npm2yarn
-npm install --save-dev tsc-alias rimraf
-```
-
-Where `tsc-alias` is a package that resolves TypeScript aliases, and `rimraf` is a package that removes files and directories.
-
-Then, add a new `resolve:aliases` script to your `package.json` and update the `build` script:
-
-```json title="package.json"
-{
-  "scripts": {
-    // other scripts...
-    "resolve:aliases": "tsc --showConfig -p tsconfig.json > tsconfig.resolved.json && tsc-alias -p tsconfig.resolved.json && rimraf tsconfig.resolved.json",
-    "build": "npm run resolve:aliases && medusa build"
-  }
-}
-```
-
-You can now use TypeScript aliases in your Medusa application. For example, add the following in `tsconfig.json`:
-
-```json title="tsconfig.json"
-{
-  "compilerOptions": {
-    // ...
-    "paths": {
-      "@/*": ["./src/*"]
-    }
-  }
-}
-```
-
-Now, you can import modules, for example, using TypeScript aliases:
-
-```ts
-import { BrandModuleService } from "@/modules/brand/service"
-```
-
-
-# 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.
-
-
-# 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.
-
-
-# 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).
-
-
 # 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.
@@ -1797,99 +2015,94 @@ 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.
 
 
-# Customizations Next Steps: Learn the Fundamentals
+# Using TypeScript Aliases
 
-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.
+By default, Medusa doesn't support TypeScript aliases in production.
 
-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.
+If you prefer using TypeScript aliases, install following development dependencies:
 
-## Useful Guides
+```bash npm2yarn
+npm install --save-dev tsc-alias rimraf
+```
 
-The following guides and references are useful for your development journey:
+Where `tsc-alias` is a package that resolves TypeScript aliases, and `rimraf` is a package that removes files and directories.
 
-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.
+Then, add a new `resolve:aliases` script to your `package.json` and update the `build` script:
+
+```json title="package.json"
+{
+  "scripts": {
+    // other scripts...
+    "resolve:aliases": "tsc --showConfig -p tsconfig.json > tsconfig.resolved.json && tsc-alias -p tsconfig.resolved.json && rimraf tsconfig.resolved.json",
+    "build": "npm run resolve:aliases && medusa build"
+  }
+}
+```
+
+You can now use TypeScript aliases in your Medusa application. For example, add the following in `tsconfig.json`:
+
+```json title="tsconfig.json"
+{
+  "compilerOptions": {
+    // ...
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  }
+}
+```
+
+Now, you can import modules, for example, using TypeScript aliases:
+
+```ts
+import { BrandModuleService } from "@/modules/brand/service"
+```
+
+
+# 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)
 
 ***
 
-## More Examples in Recipes
+## Next Chapters: Brand Module Example
 
-In the [Recipes](https://docs.medusajs.com/resources/recipes/index.html.md) documentation, you'll also find step-by-step guides for different use cases, such as building a marketplace, digital products, and more.
+The 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.
 
 
-# Medusa's Architecture
+# Customize Medusa Admin Dashboard
 
-In this chapter, you'll learn about the architectural layers in Medusa.
+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).
 
-Find the full architectural diagram at the [end of this chapter](#full-diagram-of-medusas-architecture).
+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:
 
-## HTTP, Workflow, and Module Layers
+- 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).
 
-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)
+From these customizations, you can send requests to custom API routes, allowing admin users to manage custom resources on the dashboard
 
 ***
 
-## Database Layer
+## Next Chapters: View Brands in Dashboard
 
-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.
+In the next chapters, you'll continue with the brands example to:
 
-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)
+- 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
@@ -1915,6 +2128,66 @@ In the previous chapters, you've [added brands](https://docs.medusajs.com/learn/
 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.
+
+
+# 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).
+
+
+# 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.
+
+
 # Custom CLI Scripts
 
 In this chapter, you'll learn how to create and execute custom scripts from Medusa's CLI tool.
@@ -2031,6 +2304,65 @@ 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.
+
+
 # Data Models
 
 In this chapter, you'll learn what a data model is and how to create a data model.
@@ -2135,65 +2467,6 @@ For example, the Blog Module's service would have methods like `retrievePost` an
 Refer to the [Service Factory](https://docs.medusajs.com/learn/fundamentals/modules/service-factory/index.html.md) chapter to learn more about how to extend the service factory and manage data models, and refer to the [Service Factory Reference](https://docs.medusajs.com/resources/service-factory-reference/index.html.md) for the full list of generated methods and how to use them.
 
 
-# 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.
-
-
 # Environment Variables
 
 In this chapter, you'll learn how environment variables are loaded in Medusa.
@@ -3145,6 +3418,156 @@ To learn more about the different concepts useful for building plugins, check ou
 - [Plugins](https://docs.medusajs.com/learn/fundamentals/plugins/index.html.md)
 
 
+# Medusa Container
+
+In this chapter, you’ll learn about the Medusa container and how to use it.
+
+## What is the Medusa Container?
+
+The Medusa container is a registry of Framework and commerce tools that's accessible across your application. Medusa automatically registers these tools in the container, including custom ones that you've built, so that you can use them in your customizations.
+
+In other platforms, if you have a resource A (for example, a class) that depends on a resource B, you have to manually add resource B to the container or specify it beforehand as A's dependency, which is often done in a file separate from A's code. This becomes difficult to manage as you maintain larger applications with many changing dependencies.
+
+Medusa simplifies this process by giving you access to the container, with the tools or resources already registered, at all times in your customizations. When you reach a point in your code where you need a tool, you resolve it from the container and use it.
+
+For example, consider you're creating an API route that retrieves products based on filters using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query/index.html.md), a tool that fetches data across the application. In the API route's function, you can resolve Query from the container passed to the API route and use it:
+
+```ts highlights={highlights}
+import { MedusaRequest, MedusaResponse } from "@medusajs/framework"
+import { ContainerRegistrationKeys } from "@medusajs/framework/utils"
+
+export async function GET(
+  req: MedusaRequest,
+  res: MedusaResponse
+) {
+  const query = req.scope.resolve("query")
+
+  const { data: products } = await query.graph({
+    entity: "product",
+    fields: ["*"],
+    filters: {
+      id: "prod_123",
+    },
+  })
+
+  res.json({
+    products,
+  })
+}
+```
+
+The API route accepts as a first parameter a request object that has a `scope` property, which is the Medusa container. It has a `resolve` method that resolves a resource from the container by the key it's registered with.
+
+You can learn more about how Query works in [this chapter](https://docs.medusajs.com/learn/fundamentals/module-links/query/index.html.md).
+
+***
+
+## List of Resources Registered in the Medusa Container
+
+Find a full list of the registered resources and their registration key in [this reference](https://docs.medusajs.com/resources/medusa-container-resources/index.html.md)
+
+***
+
+## How to Resolve From the Medusa Container
+
+This section gives quick examples of how to resolve resources from the Medusa container in customizations other than an API route, which is covered in the section above.
+
+### Subscriber
+
+A [subscriber](https://docs.medusajs.com/learn/fundamentals/events-and-subscribers/index.html.md) function, which is executed when an event is emitted, accepts as a parameter an object with a `container` property, whose value is the Medusa container. Use its `resolve` method to resolve a resource by its registration key:
+
+```ts highlights={subscriberHighlights}
+import { SubscriberArgs, type SubscriberConfig } from "@medusajs/framework"
+import { ContainerRegistrationKeys } from "@medusajs/framework/utils"
+
+export default async function productCreateHandler({
+  event: { data },
+  container,
+}: SubscriberArgs<{ id: string }>) {
+  const query = container.resolve(ContainerRegistrationKeys.QUERY)
+
+  const { data: products } = await query.graph({
+    entity: "product",
+    fields: ["*"],
+    filters: {
+      id: data.id,
+    },
+  })
+
+  console.log(`You created a product with the title ${products[0].title}`)
+}
+
+export const config: SubscriberConfig = {
+  event: `product.created`,
+}
+```
+
+### Scheduled Job
+
+A [scheduled job](https://docs.medusajs.com/learn/fundamentals/scheduled-jobs/index.html.md) function, which is executed at a specified interval, accepts the Medusa container as a parameter. Use its `resolve` method to resolve a resource by its registration key:
+
+```ts highlights={scheduledJobHighlights}
+import { MedusaContainer } from "@medusajs/framework/types"
+import { ContainerRegistrationKeys } from "@medusajs/framework/utils"
+
+export default async function myCustomJob(
+  container: MedusaContainer
+) {
+  const query = container.resolve(ContainerRegistrationKeys.QUERY)
+
+  const { data: products } = await query.graph({
+    entity: "product",
+    fields: ["*"],
+    filters: {
+      id: "prod_123",
+    },
+  })
+
+  console.log(
+    `You have ${products.length} matching your filters.`
+  )
+}
+
+export const config = {
+  name: "every-minute-message",
+  // execute every minute
+  schedule: "* * * * *",
+}
+```
+
+### Workflow Step
+
+A [step in a workflow](https://docs.medusajs.com/learn/fundamentals/workflows/index.html.md), which is a special function where you build durable execution logic across multiple modules, accepts in its second parameter a `container` property, whose value is the Medusa container. Use its `resolve` method to resolve a resource by its registration key:
+
+```ts highlights={workflowStepsHighlight}
+import {
+  createStep,
+  StepResponse,
+} from "@medusajs/framework/workflows-sdk"
+import { ContainerRegistrationKeys } from "@medusajs/framework/utils"
+
+const step1 = createStep("step-1", async (_, { container }) => {
+  const query = container.resolve(ContainerRegistrationKeys.QUERY)
+
+  const { data: products } = await query.graph({
+    entity: "product",
+    fields: ["*"],
+    filters: {
+      id: "prod_123",
+    },
+  })
+
+  return new StepResponse(products)
+})
+```
+
+### Module Services and Loaders
+
+A [module](https://docs.medusajs.com/learn/fundamentals/modules/index.html.md), which is a package of functionalities for a single feature or domain, has its own container, so it can't resolve resources from the Medusa container.
+
+Learn more about the module's container in [this chapter](https://docs.medusajs.com/learn/fundamentals/modules/container/index.html.md).
+
+
 # Define Module Link
 
 In this chapter, you’ll learn what a module link is and how to define one.
@@ -3360,156 +3783,6 @@ npx medusa db:migrate
 ```
 
 
-# Medusa Container
-
-In this chapter, you’ll learn about the Medusa container and how to use it.
-
-## What is the Medusa Container?
-
-The Medusa container is a registry of Framework and commerce tools that's accessible across your application. Medusa automatically registers these tools in the container, including custom ones that you've built, so that you can use them in your customizations.
-
-In other platforms, if you have a resource A (for example, a class) that depends on a resource B, you have to manually add resource B to the container or specify it beforehand as A's dependency, which is often done in a file separate from A's code. This becomes difficult to manage as you maintain larger applications with many changing dependencies.
-
-Medusa simplifies this process by giving you access to the container, with the tools or resources already registered, at all times in your customizations. When you reach a point in your code where you need a tool, you resolve it from the container and use it.
-
-For example, consider you're creating an API route that retrieves products based on filters using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query/index.html.md), a tool that fetches data across the application. In the API route's function, you can resolve Query from the container passed to the API route and use it:
-
-```ts highlights={highlights}
-import { MedusaRequest, MedusaResponse } from "@medusajs/framework"
-import { ContainerRegistrationKeys } from "@medusajs/framework/utils"
-
-export async function GET(
-  req: MedusaRequest,
-  res: MedusaResponse
-) {
-  const query = req.scope.resolve("query")
-
-  const { data: products } = await query.graph({
-    entity: "product",
-    fields: ["*"],
-    filters: {
-      id: "prod_123",
-    },
-  })
-
-  res.json({
-    products,
-  })
-}
-```
-
-The API route accepts as a first parameter a request object that has a `scope` property, which is the Medusa container. It has a `resolve` method that resolves a resource from the container by the key it's registered with.
-
-You can learn more about how Query works in [this chapter](https://docs.medusajs.com/learn/fundamentals/module-links/query/index.html.md).
-
-***
-
-## List of Resources Registered in the Medusa Container
-
-Find a full list of the registered resources and their registration key in [this reference](https://docs.medusajs.com/resources/medusa-container-resources/index.html.md)
-
-***
-
-## How to Resolve From the Medusa Container
-
-This section gives quick examples of how to resolve resources from the Medusa container in customizations other than an API route, which is covered in the section above.
-
-### Subscriber
-
-A [subscriber](https://docs.medusajs.com/learn/fundamentals/events-and-subscribers/index.html.md) function, which is executed when an event is emitted, accepts as a parameter an object with a `container` property, whose value is the Medusa container. Use its `resolve` method to resolve a resource by its registration key:
-
-```ts highlights={subscriberHighlights}
-import { SubscriberArgs, type SubscriberConfig } from "@medusajs/framework"
-import { ContainerRegistrationKeys } from "@medusajs/framework/utils"
-
-export default async function productCreateHandler({
-  event: { data },
-  container,
-}: SubscriberArgs<{ id: string }>) {
-  const query = container.resolve(ContainerRegistrationKeys.QUERY)
-
-  const { data: products } = await query.graph({
-    entity: "product",
-    fields: ["*"],
-    filters: {
-      id: data.id,
-    },
-  })
-
-  console.log(`You created a product with the title ${products[0].title}`)
-}
-
-export const config: SubscriberConfig = {
-  event: `product.created`,
-}
-```
-
-### Scheduled Job
-
-A [scheduled job](https://docs.medusajs.com/learn/fundamentals/scheduled-jobs/index.html.md) function, which is executed at a specified interval, accepts the Medusa container as a parameter. Use its `resolve` method to resolve a resource by its registration key:
-
-```ts highlights={scheduledJobHighlights}
-import { MedusaContainer } from "@medusajs/framework/types"
-import { ContainerRegistrationKeys } from "@medusajs/framework/utils"
-
-export default async function myCustomJob(
-  container: MedusaContainer
-) {
-  const query = container.resolve(ContainerRegistrationKeys.QUERY)
-
-  const { data: products } = await query.graph({
-    entity: "product",
-    fields: ["*"],
-    filters: {
-      id: "prod_123",
-    },
-  })
-
-  console.log(
-    `You have ${products.length} matching your filters.`
-  )
-}
-
-export const config = {
-  name: "every-minute-message",
-  // execute every minute
-  schedule: "* * * * *",
-}
-```
-
-### Workflow Step
-
-A [step in a workflow](https://docs.medusajs.com/learn/fundamentals/workflows/index.html.md), which is a special function where you build durable execution logic across multiple modules, accepts in its second parameter a `container` property, whose value is the Medusa container. Use its `resolve` method to resolve a resource by its registration key:
-
-```ts highlights={workflowStepsHighlight}
-import {
-  createStep,
-  StepResponse,
-} from "@medusajs/framework/workflows-sdk"
-import { ContainerRegistrationKeys } from "@medusajs/framework/utils"
-
-const step1 = createStep("step-1", async (_, { container }) => {
-  const query = container.resolve(ContainerRegistrationKeys.QUERY)
-
-  const { data: products } = await query.graph({
-    entity: "product",
-    fields: ["*"],
-    filters: {
-      id: "prod_123",
-    },
-  })
-
-  return new StepResponse(products)
-})
-```
-
-### Module Services and Loaders
-
-A [module](https://docs.medusajs.com/learn/fundamentals/modules/index.html.md), which is a package of functionalities for a single feature or domain, has its own container, so it can't resolve resources from the Medusa container.
-
-Learn more about the module's container in [this chapter](https://docs.medusajs.com/learn/fundamentals/modules/container/index.html.md).
-
-
 # Plugins
 
 In this chapter, you'll learn what a plugin is in Medusa.
@@ -3642,254 +3915,377 @@ In the scheduled job function, you execute the `syncProductToErpWorkflow` by inv
 The next time you start the Medusa application, it will run this job every day at midnight.
 
 
-# Configure Instrumentation
+# Modules
 
-In this chapter, you'll learn about observability in Medusa and how to configure instrumentation with OpenTelemetry.
+In this chapter, you’ll learn about modules and how to create them.
 
-## Observability with OpenTelemtry
+## What is a Module?
 
-Medusa uses [OpenTelemetry](https://opentelemetry.io/) for instrumentation and reporting. When configured, it reports traces for:
+A module is a reusable package of functionalities related to a single domain or integration. Medusa comes with multiple pre-built modules for core commerce needs, such as the [Cart Module](https://docs.medusajs.com/resources/commerce-modules/cart/index.html.md) that holds the data models and business logic for cart operations.
 
-- HTTP requests
-- Workflow executions
-- Query usages
-- Database queries and operations
+When building a commerce application, you often need to introduce custom behavior specific to your products, tech stack, or your general ways of working. In other commerce platforms, introducing custom business logic and data models requires setting up separate applications to manage these customizations.
+
+Medusa removes this overhead by allowing you to easily write custom modules that integrate into the Medusa application without affecting the existing setup. You can also re-use your modules across Medusa projects.
+
+As you learn more about Medusa, you will see that modules are central to customizations and integrations. With modules, your Medusa application can turn into a middleware solution for your commerce ecosystem.
+
+- You want to build a custom feature related to a single domain or integrate a third-party service.
+
+- You want to create a reusable package of customizations that include not only modules, but also API routes, workflows, and other customizations. Instead, use a [plugin](https://docs.medusajs.com/learn/fundamentals/plugins/index.html.md).
 
 ***
 
-## How to Configure Instrumentation in Medusa?
+## How to Create a Module?
 
-### Prerequisites
+In a module, you define data models that represent new tables in the database, and you manage these models in a class called a service. Then, the Medusa application registers the module's service in the [Medusa container](https://docs.medusajs.com/learn/fundamentals/medusa-container/index.html.md) so that you can build commerce flows and features around the functionalities provided by the module.
 
-- [An exporter to visualize your application's traces, such as Zipkin.](https://zipkin.io/pages/quickstart.html)
+In this section, you'll build a Blog Module that has a `Post` data model and a service to manage that data model. You'll also expose an API endpoint to create a blog post.
 
-### Install Dependencies
+Modules are created in a sub-directory of `src/modules`. So, start by creating the directory `src/modules/blog`.
 
-Start by installing the following OpenTelemetry dependencies in your Medusa project:
+### 1. Create Data Model
 
-```bash npm2yarn
-npm install @opentelemetry/sdk-node @opentelemetry/resources @opentelemetry/sdk-trace-node @opentelemetry/instrumentation-pg
-```
+A data model represents a table in the database. You create data models using Medusa's data modeling language (DML). It simplifies defining a table's columns, relations, and indexes with straightforward methods and configurations.
 
-Also, install the dependencies relevant for the exporter you use. If you're using Zipkin, install the following dependencies:
+You create a data model in a TypeScript or JavaScript file under the `models` directory of a module. So, to create a `Post` data model in the Blog Module, create the file `src/modules/blog/models/post.ts` with the following content:
 
-```bash npm2yarn
-npm install @opentelemetry/exporter-zipkin
-```
+![Updated directory overview after adding the data model](https://res.cloudinary.com/dza7lstvk/image/upload/v1732806790/Medusa%20Book/blog-dir-overview-1_jfvovj.jpg)
 
-### Add instrumentation.ts
+```ts title="src/modules/blog/models/post.ts"
+import { model } from "@medusajs/framework/utils"
 
-Next, create the file `instrumentation.ts` with the following content:
-
-```ts title="instrumentation.ts"
-import { registerOtel } from "@medusajs/medusa"
-import { ZipkinExporter } from "@opentelemetry/exporter-zipkin"
-
-// If using an exporter other than Zipkin, initialize it here.
-const exporter = new ZipkinExporter({
-  serviceName: "my-medusa-project",
+const Post = model.define("post", {
+  id: model.id().primaryKey(),
+  title: model.text(),
 })
 
-export function register() {
-  registerOtel({
-    serviceName: "medusajs",
-    // pass exporter
-    exporter,
-    instrument: {
-      http: true,
-      workflows: true,
-      query: true,
+export default Post
+```
+
+You define the data model using the `define` method of the DML. It accepts two parameters:
+
+1. The first one is the name of the data model's table in the database. Use snake-case names.
+2. The second is an object, which is the data model's schema. The schema's properties are defined using the `model`'s methods, such as `text` and `id`.
+   - Data models automatically have the date properties `created_at`, `updated_at`, and `deleted_at`, so you don't need to add them manually.
+
+Learn about other property types in [this chapter](https://docs.medusajs.com/learn/fundamentals/data-models/properties#property-types/index.html.md).
+
+The code snippet above defines a `Post` data model with `id` and `title` properties.
+
+### 2. Create Service
+
+You perform database operations on your data models in a service, which is a class exported by the module and acts like an interface to its functionalities. Medusa registers the service in its [container](https://docs.medusajs.com/learn/fundamentals/medusa-container/index.html.md), allowing you to resolve and use it when building custom commerce flows.
+
+You define a service in a `service.ts` or `service.js` file at the root of your module's directory. So, to create the Blog Module's service, create the file `src/modules/blog/service.ts` with the following content:
+
+![Updated directory overview after adding the service](https://res.cloudinary.com/dza7lstvk/image/upload/v1732807230/Medusa%20Book/blog-dir-overview-2_avzb9l.jpg)
+
+```ts title="src/modules/blog/service.ts" highlights={highlights}
+import { MedusaService } from "@medusajs/framework/utils"
+import Post from "./models/post"
+
+class BlogModuleService extends MedusaService({
+  Post,
+}){
+}
+
+export default BlogModuleService
+```
+
+Your module's service extends a class generated by `MedusaService` from the Modules SDK. This class comes with generated methods for data-management Create, Read, Update, and Delete (CRUD) operations on each of your modules, saving you time that can be spent on building custom business logic.
+
+The `MedusaService` function accepts an object of data models to generate methods for. You can pass all data models in your module in this object.
+
+For example, the `BlogModuleService` now has a `createPosts` method to create post records, and a `retrievePost` method to retrieve a post record. The suffix of each method (except for `retrieve`) is the pluralized name of the data model.
+
+Find all methods generated by the `MedusaService` in [this reference](https://docs.medusajs.com/resources/service-factory-reference/index.html.md)
+
+If a module doesn't have data models, such as when it's integrating a third-party service, it doesn't need to extend `MedusaService`.
+
+### 3. Export Module Definition
+
+The final piece to a module is its definition, which is exported in an `index.ts` file at its root directory. This definition tells Medusa the name of the module and its main service. Medusa will then register the main service in the container under the module's name.
+
+So, to export the definition of the Blog Module, create the file `src/modules/blog/index.ts` with the following content:
+
+![Updated directory overview after adding the module definition](https://res.cloudinary.com/dza7lstvk/image/upload/v1732808511/Medusa%20Book/blog-dir-overview-3_dcgjaa.jpg)
+
+```ts title="src/modules/blog/index.ts" highlights={moduleDefinitionHighlights}
+import BlogModuleService from "./service"
+import { Module } from "@medusajs/framework/utils"
+
+export const BLOG_MODULE = "blog"
+
+export default Module(BLOG_MODULE, {
+  service: BlogModuleService,
+})
+```
+
+You use `Module` from the Modules SDK to create the module's definition. It accepts two parameters:
+
+1. The name that the module's main service is registered under (`blog`). The module name can contain only alphanumeric characters and underscores.
+2. An object with a required property `service` indicating the module's main service.
+
+You export `BLOG_MODULE` to reference the module's name more reliably when resolving its service in other customizations.
+
+### 4. Add Module to Medusa's Configurations
+
+If you're creating the module in a plugin, this step isn't required as the module is registered when the plugin is registered. Learn more about plugins in [this documentation](https://docs.medusajs.com/learn/fundamentals/plugins/index.html.md).
+
+Once you finish building the module, add it to Medusa's configurations to start using it. Medusa will then register the module's main service in the Medusa container, allowing you to resolve and use it in other customizations.
+
+In `medusa-config.ts`, add a `modules` property and pass an array with your custom module:
+
+```ts title="medusa-config.ts" highlights={[["7"]]}
+module.exports = defineConfig({
+  projectConfig: {
+    // ...
+  },
+  modules: [
+    {
+      resolve: "./src/modules/blog",
     },
+  ],
+})
+```
+
+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.
+
+### 5. Generate Migrations
+
+Since data models represent tables in the database, you define how they're created in the database with migrations. A migration is a TypeScript or JavaScript file that defines database changes made by a module.
+
+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.
+
+You don't have to write migrations yourself. Medusa's CLI tool has a command that generates the migrations for you. You can also use this command again when you make changes to the module at a later point, and it will generate new migrations for that change.
+
+To generate a migration for the Blog Module, run the following command in your Medusa application's directory:
+
+If you're creating the module in a plugin, use the [plugin:db:generate command](https://docs.medusajs.com/resources/medusa-cli/commands/plugin#plugindbgenerate/index.html.md) instead.
+
+```bash
+npx medusa db:generate blog
+```
+
+The `db:generate` command of the Medusa CLI accepts one or more module names to generate the migration for. It will create a migration file for the Blog Module in the directory `src/modules/blog/migrations` similar to the following:
+
+```ts
+import { Migration } from "@mikro-orm/migrations"
+
+export class Migration20241121103722 extends Migration {
+
+  async up(): Promise<void> {
+    this.addSql("create table if not exists \"post\" (\"id\" text not null, \"title\" text not null, \"created_at\" timestamptz not null default now(), \"updated_at\" timestamptz not null default now(), \"deleted_at\" timestamptz null, constraint \"post_pkey\" primary key (\"id\"));")
+  }
+
+  async down(): Promise<void> {
+    this.addSql("drop table if exists \"post\" cascade;")
+  }
+
+}
+```
+
+In the migration class, the `up` method creates the table `post` and defines its columns using PostgreSQL syntax. The `down` method drops the table.
+
+### 6. Run Migrations
+
+To reflect the changes in the generated migration file on the database, run the `db:migrate` command:
+
+If you're creating the module in a plugin, run this command on the Medusa application that the plugin is installed in.
+
+```bash
+npx medusa db:migrate
+```
+
+This creates the `post` table in the database.
+
+***
+
+## Test the Module
+
+Since the module's main service is registered in the Medusa container, you can resolve it in other customizations to use its methods.
+
+To test out the Blog Module, you'll add the functionality to create a post in a [workflow](https://docs.medusajs.com/learn/fundamentals/workflows/index.html.md), which is a special function that performs a task in a series of steps with rollback logic. Then, you'll expose an [API route](https://docs.medusajs.com/learn/fundamentals/api-routes/index.html.md) that creates a blog post by executing the workflow.
+
+By building a commerce feature in a workflow, you can execute it in other customizations while ensuring data consistency across systems. If an error occurs during execution, every step has its own rollback logic to undo its actions. Workflows have other special features which you can learn about in [this chapter](https://docs.medusajs.com/learn/fundamentals/workflows/index.html.md).
+
+To create the workflow, create the file `src/workflows/create-post.ts` with the following content:
+
+```ts title="src/workflows/create-post.ts" highlights={workflowHighlights}
+import { 
+  createStep, 
+  createWorkflow, 
+  StepResponse, 
+  WorkflowResponse,
+} from "@medusajs/framework/workflows-sdk"
+import { BLOG_MODULE } from "../modules/blog"
+import BlogModuleService from "../modules/blog/service"
+
+type CreatePostWorkflowInput = {
+  title: string
+}
+
+const createPostStep = createStep(
+  "create-post",
+  async ({ title }: CreatePostWorkflowInput, { container }) => {
+    const blogModuleService: BlogModuleService = container.resolve(BLOG_MODULE)
+
+    const post = await blogModuleService.createPosts({
+      title,
+    })
+
+    return new StepResponse(post, post)
+  },
+  async (post, { container }) => {
+    const blogModuleService: BlogModuleService = container.resolve(BLOG_MODULE)
+
+    await blogModuleService.deletePosts(post.id)
+  }
+)
+
+export const createPostWorkflow = createWorkflow(
+  "create-post",
+  (postInput: CreatePostWorkflowInput) => {
+    const post = createPostStep(postInput)
+
+    return new WorkflowResponse(post)
+  }
+)
+```
+
+The workflow has a single step `createPostStep` that creates a post. In the step, you resolve the Blog Module's service from the Medusa container, which the step receives as a parameter. Then, you create the post using the method `createPosts` of the service, which was generated by `MedusaService`.
+
+The step also has a compensation function, which is a function passed as a third-parameter to `createStep` that implements the logic to rollback the change made by a step in case an error occurs during the workflow's execution.
+
+You'll now execute that workflow in an API route to expose the feature of creating blog posts to clients. To create an API route, create the file `src/api/blog/posts/route.ts` with the following content:
+
+```ts
+import type { 
+  MedusaRequest, 
+  MedusaResponse,
+} from "@medusajs/framework/http"
+import { 
+  createPostWorkflow,
+} from "../../../workflows/create-post"
+
+export async function POST(
+  req: MedusaRequest, 
+  res: MedusaResponse
+) {
+  const { result: post } = await createPostWorkflow(req.scope)
+    .run({
+      input: {
+        title: "My Post",
+      },
+    })
+
+  res.json({
+    post,
   })
 }
 ```
 
-In the `instrumentation.ts` file, you export a `register` function that uses Medusa's `registerOtel` utility function. You also initialize an instance of the exporter, such as Zipkin, and pass it to the `registerOtel` function.
+This adds a `POST` API route at `/blog/posts`. In the API route, you execute the `createPostWorkflow` by invoking it, passing it the Medusa container in `req.scope`, then invoking the `run` method. In the `run` method, you pass the workflow's input in the `input` property.
 
-`registerOtel` accepts an object where you can pass any [NodeSDKConfiguration](https://open-telemetry.github.io/opentelemetry-js/interfaces/_opentelemetry_sdk_node.NodeSDKConfiguration.html) property along with the following properties:
-
-The `NodeSDKConfiguration` properties are accepted since Medusa v2.5.1.
-
-- serviceName: (\`string\`) The name of the service traced.
-- exporter: (\[SpanExporter]\(https://open-telemetry.github.io/opentelemetry-js/interfaces/\_opentelemetry\_sdk\_trace\_base.SpanExporter.html)) An instance of an exporter, such as Zipkin.
-- instrument: (\`object\`) Options specifying what to trace.
-
-  - http: (\`boolean\`) Whether to trace HTTP requests.
-
-  - query: (\`boolean\`) Whether to trace Query usages.
-
-  - workflows: (\`boolean\`) Whether to trace Workflow executions.
-
-  - db: (\`boolean\`) Whether to trace database queries and operations.
-- instrumentations: (\[Instrumentation\[]]\(https://open-telemetry.github.io/opentelemetry-js/interfaces/\_opentelemetry\_instrumentation.Instrumentation.html)) Additional instrumentation options that OpenTelemetry accepts.
-
-***
-
-## Test it Out
-
-To test it out, start your exporter, such as Zipkin.
-
-Then, start your Medusa application:
+To test this out, start the Medusa application:
 
 ```bash npm2yarn
 npm run dev
 ```
 
-Try to open the Medusa Admin or send a request to an API route.
-
-If you check traces in your exporter, you'll find new traces reported.
-
-### Trace Span Names
-
-Trace span names start with the following keywords based on what it's reporting:
-
-- `{methodName} {URL}` when reporting HTTP requests, where `{methodName}` is the HTTP method, and `{URL}` is the URL the request is sent to.
-- `route:` when reporting route handlers running on an HTTP request.
-- `middleware:` when reporting a middleware running on an HTTP request.
-- `workflow:` when reporting a workflow execution.
-- `step:` when reporting a step in a workflow execution.
-- `query.graph:` when reporting Query usages.
-- `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:
+Then, send a `POST` request to `/blog/posts`:
 
 ```bash
-LOG_LEVEL=error
+curl -X POST http://localhost:9000/blog/posts
 ```
 
-This logs `error` messages only.
+This will create a post and return it in the response:
 
-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")
+```json
+{
+  "post": {
+    "id": "123...",
+    "title": "My Post",
+    "created_at": "...",
+    "updated_at": "..."
+  }
 }
 ```
 
-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:
+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.
 
-- `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'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
@@ -4238,400 +4634,451 @@ ADMIN_DISABLED=true
 ```
 
 
-# Medusa Testing Tools
+# Usage Information
 
-In this chapter, you'll learn about Medusa's testing tools and how to install and configure them.
+At Medusa, we strive to provide the best experience for developers using our platform. For that reason, Medusa collects anonymous and non-sensitive data that provides a global understanding of how users are using Medusa.
 
-## @medusajs/test-utils Package
+***
 
-Medusa provides a Testing Framework to create integration tests for your custom API routes, modules, or other Medusa customizations.
+## Purpose
 
-To use the Testing Framework, install `@medusajs/test-utils` as a `devDependency`:
+As an open source solution, we work closely and constantly interact with our community to ensure that we provide the best experience for everyone using Medusa.
 
-```bash npm2yarn
-npm install --save-dev @medusajs/test-utils@latest
+We are capable of getting a general understanding of how developers use Medusa and what general issues they run into through different means such as our Discord server, GitHub issues and discussions, and occasional one-on-one sessions.
+
+However, although these methods can be insightful, they’re not enough to get a full and global understanding of how developers are using Medusa, especially in production.
+
+Collecting this data allows us to understand certain details such as:
+
+- What operating system do most Medusa developers use?
+- What version of Medusa is widely used?
+- What parts of the Medusa Admin are generally undiscovered by our users?
+- How much data do users manage through our Medusa Admin? Is it being used for large number of products, orders, and other types of data?
+- What Node version is globally used? Should we focus our efforts on providing support for versions that we don’t currently support?
+
+***
+
+## Medusa Application Analytics
+
+This section covers which data in the Medusa application are collected and how to opt out of it.
+
+### Collected Data in the Medusa Application
+
+The following data is being collected on your Medusa application:
+
+- Unique project ID generated with UUID.
+- Unique machine ID generated with UUID.
+- Operating system information including Node version or operating system platform used.
+- The version of the Medusa application and Medusa CLI are used.
+
+Data is only collected when the Medusa application is run with the command `medusa start`.
+
+### How to Opt Out
+
+If you prefer to disable data collection, you can do it either by setting the following environment variable to true:
+
+```bash
+MEDUSA_DISABLE_TELEMETRY=true
+```
+
+Or, you can run the following command in the root of your Medusa application project to disable it:
+
+```bash
+npx medusa telemetry --disable
 ```
 
 ***
 
-## Install and Configure Jest
+## Admin Analytics
 
-Writing tests with `@medusajs/test-utils`'s tools requires installing and configuring Jest in your project.
+This section covers which data in the admin are collected and how to opt out of it.
 
-Run the following command to install the required Jest dependencies:
+### Collected Data in Admin
 
-```bash npm2yarn
-npm install --save-dev jest @types/jest @swc/jest
+Users have the option to [enable or disable the anonymization](#how-to-enable-anonymization) of the collected data.
+
+The following data is being collected on your admin:
+
+- The name of the store.
+- The email of the user.
+- The total number of products, orders, discounts, and users.
+- The number of regions and their names.
+- The currencies used in the store.
+- Errors that occur while using the admin.
+
+### How to Enable Anonymization
+
+To enable anonymization of your data from the Medusa Admin:
+
+1. Go to Settings → Personal Information.
+2. In the Usage insights section, click on the “Edit preferences” button.
+3. Enable the "Anonymize my usage data” toggle.
+4. Click on the “Submit and close” button.
+
+### How to Opt-Out
+
+To opt out of analytics collection in the Medusa Admin, set the following environment variable:
+
+```bash
+MEDUSA_FF_ANALYTICS=false
 ```
 
-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())
+# Write Integration Tests
 
-module.exports = {
-  transform: {
-    "^.+\\.[jt]s$": [
-      "@swc/jest",
-      {
-        jsc: {
-          parser: { syntax: "typescript", decorators: true },
-        },
-      },
-    ],
+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...
   },
-  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"]
-}
+jest.setTimeout(60 * 1000)
 ```
 
-Next, create the `integration-tests/setup.js` file with the following content:
+The `medusaIntegrationTestRunner` function accepts an object as a parameter. The object has a required property `testSuite`.
 
-```js title="integration-tests/setup.js"
-const { MetadataStorage } = require("@mikro-orm/core")
+`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:
 
-MetadataStorage.clear()
+- `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)
 ```
 
 ***
 
-## Add Test Commands
+### Run Tests
 
-Finally, add the following scripts to `package.json`:
+Run the following command to run your tests:
 
-```json title="package.json"
-"scripts": {
+```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",
+  },
   // ...
-  "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
+## Write Tests for Modules without Data Models
 
-The next chapters explain how to use the testing tools provided by `@medusajs/test-utils` to write tests.
+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).
 
 
-# Modules
+# Guide: Implement Brand Module
 
-In this chapter, you’ll learn about modules and how to create them.
-
-## What is a Module?
+In this chapter, you'll build a Brand Module that adds a `brand` table to the database and provides data-management features for it.
 
 A module is a reusable package of functionalities related to a single domain or integration. Medusa comes with multiple pre-built modules for core commerce needs, such as the [Cart Module](https://docs.medusajs.com/resources/commerce-modules/cart/index.html.md) that holds the data models and business logic for cart operations.
 
-When building a commerce application, you often need to introduce custom behavior specific to your products, tech stack, or your general ways of working. In other commerce platforms, introducing custom business logic and data models requires setting up separate applications to manage these customizations.
+In a module, you create data models and business logic to manage them. In the next chapters, you'll see how you use the module to build commerce features.
 
-Medusa removes this overhead by allowing you to easily write custom modules that integrate into the Medusa application without affecting the existing setup. You can also re-use your modules across Medusa projects.
+Learn more about modules in [this chapter](https://docs.medusajs.com/learn/fundamentals/modules/index.html.md).
 
-As you learn more about Medusa, you will see that modules are central to customizations and integrations. With modules, your Medusa application can turn into a middleware solution for your commerce ecosystem.
+## 1. Create Module Directory
 
-- You want to build a custom feature related to a single domain or integrate a third-party service.
+Modules are created in a sub-directory of `src/modules`. So, start by creating the directory `src/modules/brand` that will hold the Brand Module's files.
 
-- You want to create a reusable package of customizations that include not only modules, but also API routes, workflows, and other customizations. Instead, use a [plugin](https://docs.medusajs.com/learn/fundamentals/plugins/index.html.md).
+![Directory structure in Medusa project after adding the brand directory](https://res.cloudinary.com/dza7lstvk/image/upload/v1732868844/Medusa%20Book/brand-dir-overview-1_hxwvgx.jpg)
 
 ***
 
-## How to Create a Module?
+## 2. Create Data Model
 
-In a module, you define data models that represent new tables in the database, and you manage these models in a class called a service. Then, the Medusa application registers the module's service in the [Medusa container](https://docs.medusajs.com/learn/fundamentals/medusa-container/index.html.md) so that you can build commerce flows and features around the functionalities provided by the module.
+A data model represents a table in the database. You create data models using Medusa's Data Model Language (DML). It simplifies defining a table's columns, relations, and indexes with straightforward methods and configurations.
 
-In this section, you'll build a Blog Module that has a `Post` data model and a service to manage that data model. You'll also expose an API endpoint to create a blog post.
+Learn more about data models in [this chapter](https://docs.medusajs.com/learn/fundamentals/modules#1-create-data-model/index.html.md).
 
-Modules are created in a sub-directory of `src/modules`. So, start by creating the directory `src/modules/blog`.
+You create a data model in a TypeScript or JavaScript file under the `models` directory of a module. So, to create a data model that represents a new `brand` table in the database, create the file `src/modules/brand/models/brand.ts` with the following content:
 
-### 1. Create Data Model
+![Directory structure in module after adding the brand data model](https://res.cloudinary.com/dza7lstvk/image/upload/v1732868920/Medusa%20Book/brand-dir-overview-2_lexhdl.jpg)
 
-A data model represents a table in the database. You create data models using Medusa's data modeling language (DML). It simplifies defining a table's columns, relations, and indexes with straightforward methods and configurations.
-
-You create a data model in a TypeScript or JavaScript file under the `models` directory of a module. So, to create a `Post` data model in the Blog Module, create the file `src/modules/blog/models/post.ts` with the following content:
-
-![Updated directory overview after adding the data model](https://res.cloudinary.com/dza7lstvk/image/upload/v1732806790/Medusa%20Book/blog-dir-overview-1_jfvovj.jpg)
-
-```ts title="src/modules/blog/models/post.ts"
+```ts title="src/modules/brand/models/brand.ts"
 import { model } from "@medusajs/framework/utils"
 
-const Post = model.define("post", {
+export const Brand = model.define("brand", {
   id: model.id().primaryKey(),
-  title: model.text(),
+  name: model.text(),
 })
-
-export default Post
 ```
 
+You create a `Brand` data model which has an `id` primary key property, and a `name` text property.
+
 You define the data model using the `define` method of the DML. It accepts two parameters:
 
 1. The first one is the name of the data model's table in the database. Use snake-case names.
-2. The second is an object, which is the data model's schema. The schema's properties are defined using the `model`'s methods, such as `text` and `id`.
-   - Data models automatically have the date properties `created_at`, `updated_at`, and `deleted_at`, so you don't need to add them manually.
+2. The second is an object, which is the data model's schema.
 
-Learn about other property types in [this chapter](https://docs.medusajs.com/learn/fundamentals/data-models/properties#property-types/index.html.md).
+Learn about other property types in [this chapter](https://docs.medusajs.com/learn/fundamentals/data-models/properties/index.html.md).
 
-The code snippet above defines a `Post` data model with `id` and `title` properties.
+***
 
-### 2. Create Service
+## 3. Create Module Service
 
-You perform database operations on your data models in a service, which is a class exported by the module and acts like an interface to its functionalities. Medusa registers the service in its [container](https://docs.medusajs.com/learn/fundamentals/medusa-container/index.html.md), allowing you to resolve and use it when building custom commerce flows.
+You perform database operations on your data models in a service, which is a class exported by the module and acts like an interface to its functionalities.
 
-You define a service in a `service.ts` or `service.js` file at the root of your module's directory. So, to create the Blog Module's service, create the file `src/modules/blog/service.ts` with the following content:
+In this step, you'll create the Brand Module's service that provides methods to manage the `Brand` data model. In the next chapters, you'll use this service when exposing custom features that involve managing brands.
 
-![Updated directory overview after adding the service](https://res.cloudinary.com/dza7lstvk/image/upload/v1732807230/Medusa%20Book/blog-dir-overview-2_avzb9l.jpg)
+Learn more about services in [this chapter](https://docs.medusajs.com/learn/fundamentals/modules#2-create-service/index.html.md).
 
-```ts title="src/modules/blog/service.ts" highlights={highlights}
+You define a service in a `service.ts` or `service.js` file at the root of your module's directory. So, create the file `src/modules/brand/service.ts` with the following content:
+
+![Directory structure in module after adding the service](https://res.cloudinary.com/dza7lstvk/image/upload/v1732868984/Medusa%20Book/brand-dir-overview-3_jo7baj.jpg)
+
+```ts title="src/modules/brand/service.ts" highlights={serviceHighlights}
 import { MedusaService } from "@medusajs/framework/utils"
-import Post from "./models/post"
+import { Brand } from "./models/brand"
+
+class BrandModuleService extends MedusaService({
+  Brand,
+}) {
 
-class BlogModuleService extends MedusaService({
-  Post,
-}){
 }
 
-export default BlogModuleService
+export default BrandModuleService
 ```
 
-Your module's service extends a class generated by `MedusaService` from the Modules SDK. This class comes with generated methods for data-management Create, Read, Update, and Delete (CRUD) operations on each of your modules, saving you time that can be spent on building custom business logic.
+The `BrandModuleService` extends a class returned by `MedusaService` from the Modules SDK. This function generates a class with data-management methods for your module's data models.
 
-The `MedusaService` function accepts an object of data models to generate methods for. You can pass all data models in your module in this object.
+The `MedusaService` function receives an object of the module's data models as a parameter, and generates methods to manage those data models. So, the `BrandModuleService` now has methods like `createBrands` and `retrieveBrand` to manage the `Brand` data model.
 
-For example, the `BlogModuleService` now has a `createPosts` method to create post records, and a `retrievePost` method to retrieve a post record. The suffix of each method (except for `retrieve`) is the pluralized name of the data model.
+You'll use these methods in the [next chapter](https://docs.medusajs.com/learn/customization/custom-features/workflow/index.html.md).
 
-Find all methods generated by the `MedusaService` in [this reference](https://docs.medusajs.com/resources/service-factory-reference/index.html.md)
+Find a reference of all generated methods in [this guide](https://docs.medusajs.com/resources/service-factory-reference/index.html.md).
 
-If a module doesn't have data models, such as when it's integrating a third-party service, it doesn't need to extend `MedusaService`.
+***
 
-### 3. Export Module Definition
+## 4. Export Module Definition
 
-The final piece to a module is its definition, which is exported in an `index.ts` file at its root directory. This definition tells Medusa the name of the module and its main service. Medusa will then register the main service in the container under the module's name.
+A module must export a definition that tells Medusa the name of the module and its main service. This definition is exported in an `index.ts` file at the module's root directory.
 
-So, to export the definition of the Blog Module, create the file `src/modules/blog/index.ts` with the following content:
+So, to export the Brand Module's definition, create the file `src/modules/brand/index.ts` with the following content:
 
-![Updated directory overview after adding the module definition](https://res.cloudinary.com/dza7lstvk/image/upload/v1732808511/Medusa%20Book/blog-dir-overview-3_dcgjaa.jpg)
+![Directory structure in module after adding the definition file](https://res.cloudinary.com/dza7lstvk/image/upload/v1732869045/Medusa%20Book/brand-dir-overview-4_nf8ymw.jpg)
 
-```ts title="src/modules/blog/index.ts" highlights={moduleDefinitionHighlights}
-import BlogModuleService from "./service"
+```ts title="src/modules/brand/index.ts"
 import { Module } from "@medusajs/framework/utils"
+import BrandModuleService from "./service"
 
-export const BLOG_MODULE = "blog"
+export const BRAND_MODULE = "brand"
 
-export default Module(BLOG_MODULE, {
-  service: BlogModuleService,
+export default Module(BRAND_MODULE, {
+  service: BrandModuleService,
 })
 ```
 
 You use `Module` from the Modules SDK to create the module's definition. It accepts two parameters:
 
-1. The name that the module's main service is registered under (`blog`). The module name can contain only alphanumeric characters and underscores.
+1. The module's name (`brand`). You'll use this name when you use this module in other customizations.
 2. An object with a required property `service` indicating the module's main service.
 
-You export `BLOG_MODULE` to reference the module's name more reliably when resolving its service in other customizations.
+You export `BRAND_MODULE` to reference the module's name more reliably in other customizations.
 
-### 4. Add Module to Medusa's Configurations
+***
 
-If you're creating the module in a plugin, this step isn't required as the module is registered when the plugin is registered. Learn more about plugins in [this documentation](https://docs.medusajs.com/learn/fundamentals/plugins/index.html.md).
+## 5. Add Module to Medusa's Configurations
 
-Once you finish building the module, add it to Medusa's configurations to start using it. Medusa will then register the module's main service in the Medusa container, allowing you to resolve and use it in other customizations.
+To start using your module, you must add it to Medusa's configurations in `medusa-config.ts`.
 
-In `medusa-config.ts`, add a `modules` property and pass an array with your custom module:
+The object passed to `defineConfig` in `medusa-config.ts` accepts a `modules` property, whose value is an array of modules to add to the application. So, add the following in `medusa-config.ts`:
 
-```ts title="medusa-config.ts" highlights={[["7"]]}
+```ts title="medusa-config.ts"
 module.exports = defineConfig({
-  projectConfig: {
-    // ...
-  },
+  // ...
   modules: [
     {
-      resolve: "./src/modules/blog",
+      resolve: "./src/modules/brand",
     },
   ],
 })
 ```
 
-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.
-
-### 5. Generate Migrations
-
-Since data models represent tables in the database, you define how they're created in the database with migrations. A migration is a TypeScript or JavaScript file that defines database changes made by a module.
-
-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.
-
-You don't have to write migrations yourself. Medusa's CLI tool has a command that generates the migrations for you. You can also use this command again when you make changes to the module at a later point, and it will generate new migrations for that change.
-
-To generate a migration for the Blog Module, run the following command in your Medusa application's directory:
-
-If you're creating the module in a plugin, use the [plugin:db:generate command](https://docs.medusajs.com/resources/medusa-cli/commands/plugin#plugindbgenerate/index.html.md) instead.
-
-```bash
-npx medusa db:generate blog
-```
-
-The `db:generate` command of the Medusa CLI accepts one or more module names to generate the migration for. It will create a migration file for the Blog Module in the directory `src/modules/blog/migrations` similar to the following:
-
-```ts
-import { Migration } from "@mikro-orm/migrations"
-
-export class Migration20241121103722 extends Migration {
-
-  async up(): Promise<void> {
-    this.addSql("create table if not exists \"post\" (\"id\" text not null, \"title\" text not null, \"created_at\" timestamptz not null default now(), \"updated_at\" timestamptz not null default now(), \"deleted_at\" timestamptz null, constraint \"post_pkey\" primary key (\"id\"));")
-  }
-
-  async down(): Promise<void> {
-    this.addSql("drop table if exists \"post\" cascade;")
-  }
-
-}
-```
-
-In the migration class, the `up` method creates the table `post` and defines its columns using PostgreSQL syntax. The `down` method drops the table.
-
-### 6. Run Migrations
-
-To reflect the changes in the generated migration file on the database, run the `db:migrate` command:
-
-If you're creating the module in a plugin, run this command on the Medusa application that the plugin is installed in.
-
-```bash
-npx medusa db:migrate
-```
-
-This creates the `post` table in the database.
+The Brand Module is now added to your Medusa application. You'll start using it in the [next chapter](https://docs.medusajs.com/learn/customization/custom-features/workflow/index.html.md).
 
 ***
 
-## Test the Module
+## 6. Generate and Run Migrations
 
-Since the module's main service is registered in the Medusa container, you can resolve it in other customizations to use its methods.
+A migration is a TypeScript or JavaScript file that defines database changes made by a module. Migrations ensure that your module is re-usable and removes friction when working in a team, making it easy to reflect changes across team members' databases.
 
-To test out the Blog Module, you'll add the functionality to create a post in a [workflow](https://docs.medusajs.com/learn/fundamentals/workflows/index.html.md), which is a special function that performs a task in a series of steps with rollback logic. Then, you'll expose an [API route](https://docs.medusajs.com/learn/fundamentals/api-routes/index.html.md) that creates a blog post by executing the workflow.
+Learn more about migrations in [this chapter](https://docs.medusajs.com/learn/fundamentals/modules#5-generate-migrations/index.html.md).
 
-By building a commerce feature in a workflow, you can execute it in other customizations while ensuring data consistency across systems. If an error occurs during execution, every step has its own rollback logic to undo its actions. Workflows have other special features which you can learn about in [this chapter](https://docs.medusajs.com/learn/fundamentals/workflows/index.html.md).
-
-To create the workflow, create the file `src/workflows/create-post.ts` with the following content:
-
-```ts title="src/workflows/create-post.ts" highlights={workflowHighlights}
-import { 
-  createStep, 
-  createWorkflow, 
-  StepResponse, 
-  WorkflowResponse,
-} from "@medusajs/framework/workflows-sdk"
-import { BLOG_MODULE } from "../modules/blog"
-import BlogModuleService from "../modules/blog/service"
-
-type CreatePostWorkflowInput = {
-  title: string
-}
-
-const createPostStep = createStep(
-  "create-post",
-  async ({ title }: CreatePostWorkflowInput, { container }) => {
-    const blogModuleService: BlogModuleService = container.resolve(BLOG_MODULE)
-
-    const post = await blogModuleService.createPosts({
-      title,
-    })
-
-    return new StepResponse(post, post)
-  },
-  async (post, { container }) => {
-    const blogModuleService: BlogModuleService = container.resolve(BLOG_MODULE)
-
-    await blogModuleService.deletePosts(post.id)
-  }
-)
-
-export const createPostWorkflow = createWorkflow(
-  "create-post",
-  (postInput: CreatePostWorkflowInput) => {
-    const post = createPostStep(postInput)
-
-    return new WorkflowResponse(post)
-  }
-)
-```
-
-The workflow has a single step `createPostStep` that creates a post. In the step, you resolve the Blog Module's service from the Medusa container, which the step receives as a parameter. Then, you create the post using the method `createPosts` of the service, which was generated by `MedusaService`.
-
-The step also has a compensation function, which is a function passed as a third-parameter to `createStep` that implements the logic to rollback the change made by a step in case an error occurs during the workflow's execution.
-
-You'll now execute that workflow in an API route to expose the feature of creating blog posts to clients. To create an API route, create the file `src/api/blog/posts/route.ts` with the following content:
-
-```ts
-import type { 
-  MedusaRequest, 
-  MedusaResponse,
-} from "@medusajs/framework/http"
-import { 
-  createPostWorkflow,
-} from "../../../workflows/create-post"
-
-export async function POST(
-  req: MedusaRequest, 
-  res: MedusaResponse
-) {
-  const { result: post } = await createPostWorkflow(req.scope)
-    .run({
-      input: {
-        title: "My Post",
-      },
-    })
-
-  res.json({
-    post,
-  })
-}
-```
-
-This adds a `POST` API route at `/blog/posts`. In the API route, you execute the `createPostWorkflow` by invoking it, passing it the Medusa container in `req.scope`, then invoking the `run` method. In the `run` method, you pass the workflow's input in the `input` property.
-
-To test this out, start the Medusa application:
-
-```bash npm2yarn
-npm run dev
-```
-
-Then, send a `POST` request to `/blog/posts`:
+[Medusa's CLI tool](https://docs.medusajs.com/resources/medusa-cli/index.html.md) allows you to generate migration files for your module, then run those migrations to reflect the changes in the database. So, run the following commands in your Medusa application's directory:
 
 ```bash
-curl -X POST http://localhost:9000/blog/posts
+npx medusa db:generate brand
+npx medusa db:migrate
 ```
 
-This will create a post and return it in the response:
+The `db:generate` command accepts as an argument the name of the module to generate the migrations for, and the `db:migrate` command runs all migrations that haven't been run yet in the Medusa application.
 
-```json
-{
-  "post": {
-    "id": "123...",
-    "title": "My Post",
-    "created_at": "...",
-    "updated_at": "..."
-  }
-}
-```
+***
 
-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.
+## Next Step: Create Brand Workflow
+
+The Brand Module now creates a `brand` table in the database and provides a class to manage its records.
+
+In the next chapter, you'll implement the functionality to create a brand in a workflow. You'll then use that workflow in a later chapter to expose an endpoint that allows admin users to create a brand.
 
 
 # Guide: Create Brand API Route
@@ -4842,234 +5289,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.
 
 
-# Usage Information
-
-At Medusa, we strive to provide the best experience for developers using our platform. For that reason, Medusa collects anonymous and non-sensitive data that provides a global understanding of how users are using Medusa.
-
-***
-
-## Purpose
-
-As an open source solution, we work closely and constantly interact with our community to ensure that we provide the best experience for everyone using Medusa.
-
-We are capable of getting a general understanding of how developers use Medusa and what general issues they run into through different means such as our Discord server, GitHub issues and discussions, and occasional one-on-one sessions.
-
-However, although these methods can be insightful, they’re not enough to get a full and global understanding of how developers are using Medusa, especially in production.
-
-Collecting this data allows us to understand certain details such as:
-
-- What operating system do most Medusa developers use?
-- What version of Medusa is widely used?
-- What parts of the Medusa Admin are generally undiscovered by our users?
-- How much data do users manage through our Medusa Admin? Is it being used for large number of products, orders, and other types of data?
-- What Node version is globally used? Should we focus our efforts on providing support for versions that we don’t currently support?
-
-***
-
-## Medusa Application Analytics
-
-This section covers which data in the Medusa application are collected and how to opt out of it.
-
-### Collected Data in the Medusa Application
-
-The following data is being collected on your Medusa application:
-
-- Unique project ID generated with UUID.
-- Unique machine ID generated with UUID.
-- Operating system information including Node version or operating system platform used.
-- The version of the Medusa application and Medusa CLI are used.
-
-Data is only collected when the Medusa application is run with the command `medusa start`.
-
-### How to Opt Out
-
-If you prefer to disable data collection, you can do it either by setting the following environment variable to true:
-
-```bash
-MEDUSA_DISABLE_TELEMETRY=true
-```
-
-Or, you can run the following command in the root of your Medusa application project to disable it:
-
-```bash
-npx medusa telemetry --disable
-```
-
-***
-
-## Admin Analytics
-
-This section covers which data in the admin are collected and how to opt out of it.
-
-### Collected Data in Admin
-
-Users have the option to [enable or disable the anonymization](#how-to-enable-anonymization) of the collected data.
-
-The following data is being collected on your admin:
-
-- The name of the store.
-- The email of the user.
-- The total number of products, orders, discounts, and users.
-- The number of regions and their names.
-- The currencies used in the store.
-- Errors that occur while using the admin.
-
-### How to Enable Anonymization
-
-To enable anonymization of your data from the Medusa Admin:
-
-1. Go to Settings → Personal Information.
-2. In the Usage insights section, click on the “Edit preferences” button.
-3. Enable the "Anonymize my usage data” toggle.
-4. Click on the “Submit and close” button.
-
-### How to Opt-Out
-
-To opt out of analytics collection in the Medusa Admin, set the following environment variable:
-
-```bash
-MEDUSA_FF_ANALYTICS=false
-```
-
-
-# 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.
-
-
 # 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.
@@ -5442,518 +5661,142 @@ 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: Add Product's Brand Widget in Admin
+# Guide: Create Brand Workflow
 
-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.
+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.
 
-### Prerequisites
+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.
 
-- [Brands linked to products](https://docs.medusajs.com/learn/customization/extend-features/define-link/index.html.md)
+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.
 
-## 1. Initialize JS SDK
-
-In your custom widget, you'll retrieve the product's brand by sending a request to the Medusa server. Medusa has a [JS SDK](https://docs.medusajs.com/resources/js-sdk/index.html.md) that simplifies sending requests to the server's API routes.
-
-So, you'll start by configuring the JS SDK. Create the file `src/admin/lib/sdk.ts` with the following content:
-
-![The directory structure of the Medusa application after adding the file](https://res.cloudinary.com/dza7lstvk/image/upload/v1733414606/Medusa%20Book/brands-admin-dir-overview-1_jleg0t.jpg)
-
-```ts title="src/admin/lib/sdk.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",
-  },
-})
-```
-
-You initialize the SDK passing it the following options:
-
-- `baseUrl`: The URL to the Medusa server.
-- `debug`: Whether to enable logging debug messages. This should only be enabled in development.
-- `auth.type`: The authentication method used in the client application, which is `session` in the Medusa Admin dashboard.
-
-Notice that you use `import.meta.env` to access environment variables in your customizations because the Medusa Admin is built on top of Vite. Learn more in [this chapter](https://docs.medusajs.com/learn/fundamentals/admin/environment-variables/index.html.md).
-
-You can now use the SDK to send requests to the Medusa server.
-
-Learn more about the JS SDK and its options in [this reference](https://docs.medusajs.com/resources/js-sdk/index.html.md).
-
-***
-
-## 2. Add Widget to Product Details Page
-
-You'll now add a widget to the product-details page. A widget is a React component that's injected into pre-defined zones in the Medusa Admin dashboard. It's created in a `.tsx` file under the `src/admin/widgets` directory.
-
-Learn more about widgets in [this documentation](https://docs.medusajs.com/learn/fundamentals/admin/widgets/index.html.md).
-
-To create a widget that shows a product's brand in its details page, create the file `src/admin/widgets/product-brand.tsx` with the following content:
-
-![Directory structure of the Medusa application after adding the widget](https://res.cloudinary.com/dza7lstvk/image/upload/v1733414684/Medusa%20Book/brands-admin-dir-overview-2_eq5xhi.jpg)
-
-```tsx title="src/admin/widgets/product-brand.tsx" highlights={highlights}
-import { defineWidgetConfig } from "@medusajs/admin-sdk"
-import { DetailWidgetProps, AdminProduct } from "@medusajs/framework/types"
-import { clx, Container, Heading, Text } from "@medusajs/ui"
-import { useQuery } from "@tanstack/react-query"
-import { sdk } from "../lib/sdk"
-
-type AdminProductBrand = AdminProduct & {
-  brand?: {
-    id: string
-    name: string
-  }
-}
-
-const ProductBrandWidget = ({ 
-  data: product,
-}: DetailWidgetProps<AdminProduct>) => {
-  const { data: queryResult } = useQuery({
-    queryFn: () => sdk.admin.product.retrieve(product.id, {
-      fields: "+brand.*",
-    }),
-    queryKey: [["product", product.id]],
-  })
-  const brandName = (queryResult?.product as AdminProductBrand)?.brand?.name
-
-  return (
-    <Container className="divide-y p-0">
-      <div className="flex items-center justify-between px-6 py-4">
-        <div>
-          <Heading level="h2">Brand</Heading>
-        </div>
-      </div>
-      <div
-        className={clx(
-          `text-ui-fg-subtle grid grid-cols-2 items-center px-6 py-4`
-        )}
-      >
-        <Text size="small" weight="plus" leading="compact">
-          Name
-        </Text>
-
-        <Text
-          size="small"
-          leading="compact"
-          className="whitespace-pre-line text-pretty"
-        >
-          {brandName || "-"}
-        </Text>
-      </div>
-    </Container>
-  )
-}
-
-export const config = defineWidgetConfig({
-  zone: "product.details.before",
-})
-
-export default ProductBrandWidget
-```
-
-A widget's file must export:
-
-- A React component to be rendered in the specified injection zone. The component must be the file's default export.
-- A configuration object created with `defineWidgetConfig` from the Admin Extension SDK. The function receives an object as a parameter that has a `zone` property, whose value is the zone to inject the widget to.
-
-Since the widget is injected at the top of the product details page, the widget receives the product's details as a parameter.
-
-In the widget, you use [Tanstack (React) Query](https://tanstack.com/query/latest) to query the Medusa server. Tanstack Query provides features like asynchronous state management and optimized caching. In the `queryFn` function that executes the query, you use the JS SDK to send a request to the [Get Product API Route](https://docs.medusajs.com/api/admin#products_getproductsid), passing `+brand.*` in the `fields` query parameter to retrieve the product's brand.
-
-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.
-
-You then render a section that shows the brand's name. In admin customizations, use components from the [Medusa UI package](https://docs.medusajs.com/ui/index.html.md) to maintain a consistent user interface and design in the dashboard.
-
-***
-
-## Test it Out
-
-To test out your widget, start the Medusa application:
-
-```bash npm2yarn
-npm run dev
-```
-
-Then, open the admin dashboard at `http://localhost:9000/app`. After you log in, open the page of a product that has a brand. You'll see a new section at the top showing the brand's name.
-
-![The widget is added as the first section of the product details page.](https://res.cloudinary.com/dza7lstvk/image/upload/v1733414415/Medusa%20Book/Screenshot_2024-12-05_at_5.59.25_PM_y85m14.png)
-
-***
-
-## Admin Components Guides
-
-When building your widget, you may need more complicated components. For example, you may add a form to the above widget to set the product's brand.
-
-The [Admin Components guides](https://docs.medusajs.com/resources/admin-components/index.html.md) show you how to build and use common components in the Medusa Admin, such as forms, tables, JSON data viewer, and more. The components in the guides also follow the Medusa Admin's design convention.
-
-***
-
-## Next Chapter: Add UI Route for Brands
-
-In the next chapter, you'll add a UI route that displays the list of brands in your application and allows admin users.
-
-
-# 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.
-
-Some API routes, including the [Create Product API route](https://docs.medusajs.com/api/admin#products_postproducts), accept an `additional_data` request body parameter. This parameter can hold custom data that's passed to the [hooks](https://docs.medusajs.com/learn/fundamentals/workflows/workflow-hooks/index.html.md) of the workflow executed in the API route, allowing you to consume those hooks and perform actions with the custom data.
-
-So, in this chapter, to extend the create product flow and associate a brand with a product, you will:
-
-- Consume the [productsCreated](https://docs.medusajs.com/resources/references/medusa-workflows/createProductsWorkflow#productsCreated/index.html.md) hook of the [createProductsWorkflow](https://docs.medusajs.com/resources/references/medusa-workflows/createProductsWorkflow/index.html.md), which is executed within the workflow after the product is created. You'll link the product with the brand passed in the `additional_data` parameter.
-- Extend the Create Product API route to allow passing a brand ID in `additional_data`.
-
-To learn more about the `additional_data` property and the API routes that accept additional data, refer to [this chapter](https://docs.medusajs.com/learn/fundamentals/api-routes/additional-data/index.html.md).
+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)
-- [Defined link between the Brand and Product data models.](https://docs.medusajs.com/learn/customization/extend-features/define-link/index.html.md)
 
 ***
 
-## 1. Consume the productsCreated Hook
+## 1. Create createBrandStep
 
-A workflow hook is a point in a workflow where you can inject a step to perform a custom functionality. Consuming a workflow hook allows you to extend the features of a workflow and, consequently, the API route that uses it.
+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
 
-Learn more about the workflow hooks in [this chapter](https://docs.medusajs.com/learn/fundamentals/workflows/workflow-hooks/index.html.md).
+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:
 
-The [createProductsWorkflow](https://docs.medusajs.com/resources/references/medusa-workflows/createProductsWorkflow/index.html.md) used in the [Create Product API route](https://docs.medusajs.com/api/admin#products_postproducts) has a `productsCreated` hook that runs after the product is created. You'll consume this hook to link the created product with the brand specified in the request parameters.
+![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)
 
-To consume the `productsCreated` hook, create the file `src/workflows/hooks/created-product.ts` with the following content:
+```ts title="src/workflows/create-brand.ts"
+import {
+  createStep,
+  StepResponse,
+} from "@medusajs/framework/workflows-sdk"
+import { BRAND_MODULE } from "../modules/brand"
+import BrandModuleService from "../modules/brand/service"
 
-![Directory structure after creating the hook's file.](https://res.cloudinary.com/dza7lstvk/image/upload/v1733384338/Medusa%20Book/brands-hook-dir-overview_ltwr5h.jpg)
-
-```ts title="src/workflows/hooks/created-product.ts" highlights={hook1Highlights}
-import { createProductsWorkflow } from "@medusajs/medusa/core-flows"
-import { StepResponse } from "@medusajs/framework/workflows-sdk"
-import { Modules } from "@medusajs/framework/utils"
-import { LinkDefinition } from "@medusajs/framework/types"
-import { BRAND_MODULE } from "../../modules/brand"
-import BrandModuleService from "../../modules/brand/service"
-
-createProductsWorkflow.hooks.productsCreated(
-  (async ({ products, additional_data }, { container }) => {
-    if (!additional_data?.brand_id) {
-      return new StepResponse([], [])
-    }
+export type CreateBrandStepInput = {
+  name: string
+}
 
+export const createBrandStep = createStep(
+  "create-brand-step",
+  async (input: CreateBrandStepInput, { container }) => {
     const brandModuleService: BrandModuleService = container.resolve(
       BRAND_MODULE
     )
-    // if the brand doesn't exist, an error is thrown.
-    await brandModuleService.retrieveBrand(additional_data.brand_id as string)
 
-    // TODO link brand to product
-  })
+    const brand = await brandModuleService.createBrands(input)
+
+    return new StepResponse(brand, brand.id)
+  }
 )
 ```
 
-Workflows have a special `hooks` property to access its hooks and consume them. Each hook, such as `productsCreated`, accepts a step function as a parameter. The step function accepts the following parameters:
+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.
 
-1. An object having an `additional_data` property, which is the custom data passed in the request body under `additional_data`. The object will also have properties passed from the workflow to the hook, which in this case is the `products` property that holds an array of the created products.
-2. An object of properties related to the step's context. It has a `container` property whose value is the [Medusa container](https://docs.medusajs.com/learn/fundamentals/medusa-container/index.html.md) to resolve Framework and commerce tools.
+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.
 
-In the step, if a brand ID is passed in `additional_data`, you resolve the Brand Module's service and use its generated `retrieveBrand` method to retrieve the brand by its ID. The `retrieveBrand` method will throw an error if the brand doesn't exist.
+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.
 
-### Link Brand to Product
+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.
 
-Next, you want to create a link between the created products and the brand. To do so, you use Link, which is a class from the Modules SDK that provides methods to manage linked records.
+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).
 
-Learn more about Link in [this chapter](https://docs.medusajs.com/learn/fundamentals/module-links/link/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.
 
-To use Link in the `productsCreated` hook, replace the `TODO` with the following:
+### Add Compensation Function to Step
 
-```ts title="src/workflows/hooks/created-product.ts" highlights={hook2Highlights}
-const link = container.resolve("link")
-const logger = container.resolve("logger")
+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.
 
-const links: LinkDefinition[] = []
+Learn more about the compensation function in [this chapter](https://docs.medusajs.com/learn/fundamentals/workflows/compensation-function/index.html.md).
 
-for (const product of products) {
-  links.push({
-    [Modules.PRODUCT]: {
-      product_id: product.id,
-    },
-    [BRAND_MODULE]: {
-      brand_id: additional_data.brand_id,
-    },
-  })
-}
+To add a compensation function to the `createBrandStep`, pass it as a third parameter to `createStep`:
 
-await link.create(links)
-
-logger.info("Linked brand to products")
-
-return new StepResponse(links, links)
-```
-
-You resolve Link from the container. Then you loop over the created products to assemble an array of links to be created. After that, you pass the array of links to Link's `create` method, which will link the product and brand records.
-
-Each property in the link object is the name of a module, and its value is an object having a `{model_name}_id` property, where `{model_name}` is the snake-case name of the module's data model. Its value is the ID of the record to be linked. The link object's properties must be set in the same order as the link configurations passed to `defineLink`.
-
-![Diagram showcasing how the order of defining a link affects creating the link](https://res.cloudinary.com/dza7lstvk/image/upload/v1733386156/Medusa%20Book/remote-link-brand-product-exp_fhjmg4.jpg)
-
-Finally, you return an instance of `StepResponse` returning the created links.
-
-### Dismiss Links in Compensation
-
-You can pass as a second parameter of the hook a compensation function that undoes what the step did. It receives as a first parameter the returned `StepResponse`'s second parameter, and the step context object as a second parameter.
-
-To undo creating the links in the hook, pass the following compensation function as a second parameter to `productsCreated`:
-
-```ts title="src/workflows/hooks/created-product.ts"
-createProductsWorkflow.hooks.productsCreated(
+```ts title="src/workflows/create-brand.ts"
+export const createBrandStep = createStep(
   // ...
-  (async (links, { container }) => {
-    if (!links?.length) {
-      return
-    }
+  async (id: string, { container }) => {
+    const brandModuleService: BrandModuleService = container.resolve(
+      BRAND_MODULE
+    )
 
-    const link = container.resolve("link")
-
-    await link.dismiss(links)
-  })
+    await brandModuleService.deleteBrands(id)
+  }
 )
 ```
 
-In the compensation function, if the `links` parameter isn't empty, you resolve Link from the container and use its `dismiss` method. This method removes a link between two records. It accepts the same parameter as the `create` method.
+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. Configure Additional Data Validation
+## 2. Create createBrandWorkflow
 
-Now that you've consumed the `productsCreated` hook, you want to configure the `/admin/products` API route that creates a new product to accept a brand ID in its `additional_data` parameter.
+You can now create the workflow that runs the `createBrandStep`. A workflow is created in a TypeScript or JavaScript file under the `src/workflows` directory. In the file, you use `createWorkflow` from the Workflows SDK to create the workflow.
 
-You configure the properties accepted in `additional_data` in the `src/api/middlewares.ts` that exports middleware configurations. So, create the file (or, if already existing, add to the file) `src/api/middlewares.ts` the following content:
+Add the following content in the same `src/workflows/create-brand.ts` file:
 
-![Directory structure after adding the middelwares file](https://res.cloudinary.com/dza7lstvk/image/upload/v1733386868/Medusa%20Book/brands-middleware-dir-overview_uczos1.jpg)
-
-```ts title="src/api/middlewares.ts"
-import { defineMiddlewares } from "@medusajs/framework/http"
-import { z } from "zod"
+```ts title="src/workflows/create-brand.ts"
+// other imports...
+import {
+  // ...
+  createWorkflow,
+  WorkflowResponse,
+} from "@medusajs/framework/workflows-sdk"
 
 // ...
 
-export default defineMiddlewares({
-  routes: [
-    // ...
-    {
-      matcher: "/admin/products",
-      method: ["POST"],
-      additionalDataValidator: {
-        brand_id: z.string().optional(),
-      },
-    },
-  ],
-})
-```
+type CreateBrandWorkflowInput = {
+  name: string
+}
 
-Objects in `routes` accept an `additionalDataValidator` property that configures the validation rules for custom properties passed in the `additional_data` request parameter. It accepts an object whose keys are custom property names, and their values are validation rules created using [Zod](https://zod.dev/).
+export const createBrandWorkflow = createWorkflow(
+  "create-brand",
+  (input: CreateBrandWorkflowInput) => {
+    const brand = createBrandStep(input)
 
-So, `POST` requests sent to `/admin/products` can now pass the ID of a brand in the `brand_id` property of `additional_data`.
-
-***
-
-## Test it Out
-
-To test it out, first, retrieve the authentication token of your admin user by sending a `POST` request to `/auth/user/emailpass`:
-
-```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 in the request body with your user's credentials.
-
-Then, send a `POST` request to `/admin/products` to create a product, and pass in the `additional_data` parameter a brand's ID:
-
-```bash
-curl -X POST 'http://localhost:9000/admin/products' \
--H 'Content-Type: application/json' \
--H 'Authorization: Bearer {token}' \
---data '{
-    "title": "Product 1",
-    "options": [
-      {
-        "title": "Default option",
-        "values": ["Default option value"]
-      }
-    ],
-    "shipping_profile_id": "{shipping_profile_id}",
-    "additional_data": {
-        "brand_id": "{brand_id}"
-    }
-}'
-```
-
-Make sure to replace `{token}` with the token you received from the previous request, `shipping_profile_id` with the ID of a shipping profile in your application, and `{brand_id}` with the ID of a brand in your application. You can retrieve the ID of a shipping profile either from the Medusa Admin, or the [List Shipping Profiles API route](https://docs.medusajs.com/api/admin#shipping-profiles_getshippingprofiles).
-
-The request creates a product and returns it.
-
-In the Medusa application's logs, you'll find the message `Linked brand to products`, indicating that the workflow hook handler ran and linked the brand to the products.
-
-***
-
-## Next Steps: Query Linked Brands and Products
-
-Now that you've extending the create-product flow to link a brand to it, you want to retrieve the brand details of a product. You'll learn how to do so in the next chapter.
-
-
-# Guide: 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
+    return new WorkflowResponse(brand)
   }
-}
+)
 ```
 
-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.
+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.
 
-### Limitations: Filtering by Brands in Existing API Routes
+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.
 
-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).
+A workflow must return an instance of `WorkflowResponse`. It accepts as a parameter the data to return to the workflow's executor.
 
 ***
 
-## Approach 2: Use Query to Retrieve Linked Records
+## Next Steps: Expose Create Brand API Route
 
-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.
+You now have a `createBrandWorkflow` that you can execute to create a brand.
 
-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.
+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
@@ -6228,230 +6071,158 @@ info:    API Key: "123"
 You can also automate syncing data from a third-party system to Medusa at a regular interval. In the next chapter, you'll learn how to sync brands from the third-party CMS to Medusa once a day.
 
 
-# Guide: Define Module Link Between Brand and Product
+# Guide: Add Product's Brand Widget in Admin
 
-In this chapter, you'll learn how to define a module link between a brand defined in the [custom Brand Module](https://docs.medusajs.com/learn/customization/custom-features/module/index.html.md), and a product defined in the [Product Module](https://docs.medusajs.com/resources/commerce-modules/product/index.html.md) that's available in your Medusa application out-of-the-box.
-
-Modules are [isolated](https://docs.medusajs.com/learn/fundamentals/modules/isolation/index.html.md) from other resources, ensuring that they're integrated into the Medusa application without side effects. However, you may need to associate data models of different modules, or you're trying to extend data models from Commerce Modules with custom properties. To do that, you define module links.
-
-A module link forms an association between two data models of different modules while maintaining module isolation. You can then manage and query linked records of the data models using Medusa's Modules SDK.
-
-In this chapter, you'll define a module link between the `Brand` data model of the Brand Module, and the `Product` data model of the Product Module. In later chapters, you'll manage and retrieve linked product and brand records.
-
-Learn more about module links in [this chapters](https://docs.medusajs.com/learn/fundamentals/module-links/index.html.md).
+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.
 
 ### Prerequisites
 
-- [Brand Module having a Brand data model](https://docs.medusajs.com/learn/customization/custom-features/module/index.html.md)
+- [Brands linked to products](https://docs.medusajs.com/learn/customization/extend-features/define-link/index.html.md)
 
-## 1. Define Link
+## 1. Initialize JS SDK
 
-Links are defined in a TypeScript or JavaScript file under the `src/links` directory. The file defines and exports the link using `defineLink` from the Modules SDK.
+In your custom widget, you'll retrieve the product's brand by sending a request to the Medusa server. Medusa has a [JS SDK](https://docs.medusajs.com/resources/js-sdk/index.html.md) that simplifies sending requests to the server's API routes.
 
-So, to define a link between the `Product` and `Brand` models, create the file `src/links/product-brand.ts` with the following content:
+So, you'll start by configuring the JS SDK. Create the file `src/admin/lib/sdk.ts` with the following content:
 
-![The directory structure of the Medusa application after adding the link.](https://res.cloudinary.com/dza7lstvk/image/upload/v1733329897/Medusa%20Book/brands-link-dir-overview_t1rhlp.jpg)
+![The directory structure of the Medusa application after adding the file](https://res.cloudinary.com/dza7lstvk/image/upload/v1733414606/Medusa%20Book/brands-admin-dir-overview-1_jleg0t.jpg)
 
-```ts title="src/links/product-brand.ts" highlights={highlights}
-import BrandModule from "../modules/brand"
-import ProductModule from "@medusajs/medusa/product"
-import { defineLink } from "@medusajs/framework/utils"
+```ts title="src/admin/lib/sdk.ts"
+import Medusa from "@medusajs/js-sdk"
 
-export default defineLink(
-  {
-    linkable: ProductModule.linkable.product,
-    isList: true,
+export const sdk = new Medusa({
+  baseUrl: import.meta.env.VITE_BACKEND_URL || "/",
+  debug: import.meta.env.DEV,
+  auth: {
+    type: "session",
   },
-  BrandModule.linkable.brand
-)
-```
-
-You import each module's definition object from the `index.ts` file of the module's directory. Each module object has a special `linkable` property that holds the data models' link configurations.
-
-The `defineLink` function accepts two parameters of the same type, which is either:
-
-- The data model's link configuration, which you access from the Module's `linkable` property;
-- Or an object that has two properties:
-  - `linkable`: the data model's link configuration, which you access from the Module's `linkable` property.
-  - `isList`: A boolean indicating whether many records of the data model can be linked to the other model.
-
-So, in the above code snippet, you define a link between the `Product` and `Brand` data models. Since a brand can be associated with multiple products, you enable `isList` in the `Product` model's object.
-
-***
-
-## 2. Sync the Link to the Database
-
-A module link is represented in the database as a table that stores the IDs of linked records. So, after defining the link, run the following command to create the module link's table in the database:
-
-```bash
-npx medusa db:migrate
-```
-
-This command reflects migrations on the database and syncs module links, which creates a table for the `product-brand` link.
-
-You can also run the `npx medusa db:sync-links` to just sync module links without running migrations.
-
-***
-
-## Next Steps: Extend Create Product Flow
-
-In the next chapter, you'll extend Medusa's workflow and API route that create a product to allow associating a brand with a product. You'll also learn how to link brand and product records.
-
-
-# Guide: Implement Brand Module
-
-In this chapter, you'll build a Brand Module that adds a `brand` table to the database and provides data-management features for it.
-
-A module is a reusable package of functionalities related to a single domain or integration. Medusa comes with multiple pre-built modules for core commerce needs, such as the [Cart Module](https://docs.medusajs.com/resources/commerce-modules/cart/index.html.md) that holds the data models and business logic for cart operations.
-
-In a module, you create data models and business logic to manage them. In the next chapters, you'll see how you use the module to build commerce features.
-
-Learn more about modules in [this chapter](https://docs.medusajs.com/learn/fundamentals/modules/index.html.md).
-
-## 1. Create Module Directory
-
-Modules are created in a sub-directory of `src/modules`. So, start by creating the directory `src/modules/brand` that will hold the Brand Module's files.
-
-![Directory structure in Medusa project after adding the brand directory](https://res.cloudinary.com/dza7lstvk/image/upload/v1732868844/Medusa%20Book/brand-dir-overview-1_hxwvgx.jpg)
-
-***
-
-## 2. Create Data Model
-
-A data model represents a table in the database. You create data models using Medusa's Data Model Language (DML). It simplifies defining a table's columns, relations, and indexes with straightforward methods and configurations.
-
-Learn more about data models in [this chapter](https://docs.medusajs.com/learn/fundamentals/modules#1-create-data-model/index.html.md).
-
-You create a data model in a TypeScript or JavaScript file under the `models` directory of a module. So, to create a data model that represents a new `brand` table in the database, create the file `src/modules/brand/models/brand.ts` with the following content:
-
-![Directory structure in module after adding the brand data model](https://res.cloudinary.com/dza7lstvk/image/upload/v1732868920/Medusa%20Book/brand-dir-overview-2_lexhdl.jpg)
-
-```ts title="src/modules/brand/models/brand.ts"
-import { model } from "@medusajs/framework/utils"
-
-export const Brand = model.define("brand", {
-  id: model.id().primaryKey(),
-  name: model.text(),
 })
 ```
 
-You create a `Brand` data model which has an `id` primary key property, and a `name` text property.
+You initialize the SDK passing it the following options:
 
-You define the data model using the `define` method of the DML. It accepts two parameters:
+- `baseUrl`: The URL to the Medusa server.
+- `debug`: Whether to enable logging debug messages. This should only be enabled in development.
+- `auth.type`: The authentication method used in the client application, which is `session` in the Medusa Admin dashboard.
 
-1. The first one is the name of the data model's table in the database. Use snake-case names.
-2. The second is an object, which is the data model's schema.
+Notice that you use `import.meta.env` to access environment variables in your customizations because the Medusa Admin is built on top of Vite. Learn more in [this chapter](https://docs.medusajs.com/learn/fundamentals/admin/environment-variables/index.html.md).
 
-Learn about other property types in [this chapter](https://docs.medusajs.com/learn/fundamentals/data-models/properties/index.html.md).
+You can now use the SDK to send requests to the Medusa server.
+
+Learn more about the JS SDK and its options in [this reference](https://docs.medusajs.com/resources/js-sdk/index.html.md).
 
 ***
 
-## 3. Create Module Service
+## 2. Add Widget to Product Details Page
 
-You perform database operations on your data models in a service, which is a class exported by the module and acts like an interface to its functionalities.
+You'll now add a widget to the product-details page. A widget is a React component that's injected into pre-defined zones in the Medusa Admin dashboard. It's created in a `.tsx` file under the `src/admin/widgets` directory.
 
-In this step, you'll create the Brand Module's service that provides methods to manage the `Brand` data model. In the next chapters, you'll use this service when exposing custom features that involve managing brands.
+Learn more about widgets in [this documentation](https://docs.medusajs.com/learn/fundamentals/admin/widgets/index.html.md).
 
-Learn more about services in [this chapter](https://docs.medusajs.com/learn/fundamentals/modules#2-create-service/index.html.md).
+To create a widget that shows a product's brand in its details page, create the file `src/admin/widgets/product-brand.tsx` with the following content:
 
-You define a service in a `service.ts` or `service.js` file at the root of your module's directory. So, create the file `src/modules/brand/service.ts` with the following content:
+![Directory structure of the Medusa application after adding the widget](https://res.cloudinary.com/dza7lstvk/image/upload/v1733414684/Medusa%20Book/brands-admin-dir-overview-2_eq5xhi.jpg)
 
-![Directory structure in module after adding the service](https://res.cloudinary.com/dza7lstvk/image/upload/v1732868984/Medusa%20Book/brand-dir-overview-3_jo7baj.jpg)
-
-```ts title="src/modules/brand/service.ts" highlights={serviceHighlights}
-import { MedusaService } from "@medusajs/framework/utils"
-import { Brand } from "./models/brand"
-
-class BrandModuleService extends MedusaService({
-  Brand,
-}) {
+```tsx title="src/admin/widgets/product-brand.tsx" highlights={highlights}
+import { defineWidgetConfig } from "@medusajs/admin-sdk"
+import { DetailWidgetProps, AdminProduct } from "@medusajs/framework/types"
+import { clx, Container, Heading, Text } from "@medusajs/ui"
+import { useQuery } from "@tanstack/react-query"
+import { sdk } from "../lib/sdk"
 
+type AdminProductBrand = AdminProduct & {
+  brand?: {
+    id: string
+    name: string
+  }
 }
 
-export default BrandModuleService
-```
+const ProductBrandWidget = ({ 
+  data: product,
+}: DetailWidgetProps<AdminProduct>) => {
+  const { data: queryResult } = useQuery({
+    queryFn: () => sdk.admin.product.retrieve(product.id, {
+      fields: "+brand.*",
+    }),
+    queryKey: [["product", product.id]],
+  })
+  const brandName = (queryResult?.product as AdminProductBrand)?.brand?.name
 
-The `BrandModuleService` extends a class returned by `MedusaService` from the Modules SDK. This function generates a class with data-management methods for your module's data models.
+  return (
+    <Container className="divide-y p-0">
+      <div className="flex items-center justify-between px-6 py-4">
+        <div>
+          <Heading level="h2">Brand</Heading>
+        </div>
+      </div>
+      <div
+        className={clx(
+          `text-ui-fg-subtle grid grid-cols-2 items-center px-6 py-4`
+        )}
+      >
+        <Text size="small" weight="plus" leading="compact">
+          Name
+        </Text>
 
-The `MedusaService` function receives an object of the module's data models as a parameter, and generates methods to manage those data models. So, the `BrandModuleService` now has methods like `createBrands` and `retrieveBrand` to manage the `Brand` data model.
+        <Text
+          size="small"
+          leading="compact"
+          className="whitespace-pre-line text-pretty"
+        >
+          {brandName || "-"}
+        </Text>
+      </div>
+    </Container>
+  )
+}
 
-You'll use these methods in the [next chapter](https://docs.medusajs.com/learn/customization/custom-features/workflow/index.html.md).
-
-Find a reference of all generated methods in [this guide](https://docs.medusajs.com/resources/service-factory-reference/index.html.md).
-
-***
-
-## 4. Export Module Definition
-
-A module must export a definition that tells Medusa the name of the module and its main service. This definition is exported in an `index.ts` file at the module's root directory.
-
-So, to export the Brand Module's definition, create the file `src/modules/brand/index.ts` with the following content:
-
-![Directory structure in module after adding the definition file](https://res.cloudinary.com/dza7lstvk/image/upload/v1732869045/Medusa%20Book/brand-dir-overview-4_nf8ymw.jpg)
-
-```ts title="src/modules/brand/index.ts"
-import { Module } from "@medusajs/framework/utils"
-import BrandModuleService from "./service"
-
-export const BRAND_MODULE = "brand"
-
-export default Module(BRAND_MODULE, {
-  service: BrandModuleService,
+export const config = defineWidgetConfig({
+  zone: "product.details.before",
 })
+
+export default ProductBrandWidget
 ```
 
-You use `Module` from the Modules SDK to create the module's definition. It accepts two parameters:
+A widget's file must export:
 
-1. The module's name (`brand`). You'll use this name when you use this module in other customizations.
-2. An object with a required property `service` indicating the module's main service.
+- A React component to be rendered in the specified injection zone. The component must be the file's default export.
+- A configuration object created with `defineWidgetConfig` from the Admin Extension SDK. The function receives an object as a parameter that has a `zone` property, whose value is the zone to inject the widget to.
 
-You export `BRAND_MODULE` to reference the module's name more reliably in other customizations.
+Since the widget is injected at the top of the product details page, the widget receives the product's details as a parameter.
+
+In the widget, you use [Tanstack (React) Query](https://tanstack.com/query/latest) to query the Medusa server. Tanstack Query provides features like asynchronous state management and optimized caching. In the `queryFn` function that executes the query, you use the JS SDK to send a request to the [Get Product API Route](https://docs.medusajs.com/api/admin#products_getproductsid), passing `+brand.*` in the `fields` query parameter to retrieve the product's brand.
+
+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.
+
+You then render a section that shows the brand's name. In admin customizations, use components from the [Medusa UI package](https://docs.medusajs.com/ui/index.html.md) to maintain a consistent user interface and design in the dashboard.
 
 ***
 
-## 5. Add Module to Medusa's Configurations
+## Test it Out
 
-To start using your module, you must add it to Medusa's configurations in `medusa-config.ts`.
+To test out your widget, start the Medusa application:
 
-The object passed to `defineConfig` in `medusa-config.ts` accepts a `modules` property, whose value is an array of modules to add to the application. So, add the following in `medusa-config.ts`:
-
-```ts title="medusa-config.ts"
-module.exports = defineConfig({
-  // ...
-  modules: [
-    {
-      resolve: "./src/modules/brand",
-    },
-  ],
-})
+```bash npm2yarn
+npm run dev
 ```
 
-The Brand Module is now added to your Medusa application. You'll start using it in the [next chapter](https://docs.medusajs.com/learn/customization/custom-features/workflow/index.html.md).
+Then, open the admin dashboard at `http://localhost:9000/app`. After you log in, open the page of a product that has a brand. You'll see a new section at the top showing the brand's name.
+
+![The widget is added as the first section of the product details page.](https://res.cloudinary.com/dza7lstvk/image/upload/v1733414415/Medusa%20Book/Screenshot_2024-12-05_at_5.59.25_PM_y85m14.png)
 
 ***
 
-## 6. Generate and Run Migrations
+## Admin Components Guides
 
-A migration is a TypeScript or JavaScript file that defines database changes made by a module. Migrations ensure that your module is re-usable and removes friction when working in a team, making it easy to reflect changes across team members' databases.
+When building your widget, you may need more complicated components. For example, you may add a form to the above widget to set the product's brand.
 
-Learn more about migrations in [this chapter](https://docs.medusajs.com/learn/fundamentals/modules#5-generate-migrations/index.html.md).
-
-[Medusa's CLI tool](https://docs.medusajs.com/resources/medusa-cli/index.html.md) allows you to generate migration files for your module, then run those migrations to reflect the changes in the database. So, run the following commands in your Medusa application's directory:
-
-```bash
-npx medusa db:generate brand
-npx medusa db:migrate
-```
-
-The `db:generate` command accepts as an argument the name of the module to generate the migrations for, and the `db:migrate` command runs all migrations that haven't been run yet in the Medusa application.
+The [Admin Components guides](https://docs.medusajs.com/resources/admin-components/index.html.md) show you how to build and use common components in the Medusa Admin, such as forms, tables, JSON data viewer, and more. The components in the guides also follow the Medusa Admin's design convention.
 
 ***
 
-## Next Step: Create Brand Workflow
+## Next Chapter: Add UI Route for Brands
 
-The Brand Module now creates a `brand` table in the database and provides a class to manage its records.
-
-In the next chapter, you'll implement the functionality to create a brand in a workflow. You'll then use that workflow in a later chapter to expose an endpoint that allows admin users to create a brand.
+In the next chapter, you'll add a UI route that displays the list of brands in your application and allows admin users.
 
 
 # Guide: Schedule Syncing Brands from Third-Party
@@ -6763,6 +6534,640 @@ By following the previous chapters, you utilized the Medusa Framework and orches
 With Medusa, you can integrate any service from your commerce ecosystem with ease. You don't have to set up separate applications to manage your different customizations, or worry about data inconsistency across systems. Your efforts only go into implementing the business logic that ties your systems together.
 
 
+# Guide: Integrate Third-Party Brand System
+
+In the previous chapters, you've created a [Brand Module](https://docs.medusajs.com/learn/customization/custom-features/module/index.html.md) that adds brands to your application. In this chapter, you'll integrate a dummy Content-Management System (CMS) in a new module. The module's service will provide methods to retrieve and manage brands in the CMS. You'll later use this service to sync data from and to the CMS.
+
+Learn more about modules in [this chapter](https://docs.medusajs.com/learn/fundamentals/modules/index.html.md).
+
+## 1. Create Module Directory
+
+You'll integrate the third-party system in a new CMS Module. So, create the directory `src/modules/cms` that will hold the module's resources.
+
+![Directory structure after adding the directory for the CMS Module](https://res.cloudinary.com/dza7lstvk/image/upload/v1733492447/Medusa%20Book/cms-dir-overview-1_gasguk.jpg)
+
+***
+
+## 2. Create Module Service
+
+Next, you'll create the module's service. It will provide methods to connect and perform actions with the third-party system.
+
+Create the CMS Module's service at `src/modules/cms/service.ts` with the following content:
+
+![Directory structure after adding the CMS Module's service](https://res.cloudinary.com/dza7lstvk/image/upload/v1733492583/Medusa%20Book/cms-dir-overview-2_zwcwh3.jpg)
+
+```ts title="src/modules/cms/service.ts" highlights={serviceHighlights}
+import { Logger, ConfigModule } from "@medusajs/framework/types"
+
+export type ModuleOptions = {
+  apiKey: string
+}
+
+type InjectedDependencies = {
+  logger: Logger
+  configModule: ConfigModule
+}
+
+class CmsModuleService {
+  private options_: ModuleOptions
+  private logger_: Logger
+
+  constructor({ logger }: InjectedDependencies, options: ModuleOptions) {
+    this.logger_ = logger
+    this.options_ = options
+
+    // TODO initialize SDK
+  }
+}
+
+export default CmsModuleService
+```
+
+You create a `CmsModuleService` that will hold the methods to connect to the third-party CMS. A service's constructor accepts two parameters:
+
+1. The module's container. Since a module is [isolated](https://docs.medusajs.com/learn/fundamentals/modules/isolation/index.html.md), it has a [local container](https://docs.medusajs.com/learn/fundamentals/modules/container/index.html.md) different than the Medusa container you use in other customizations. This container holds Framework tools like the [Logger utility](https://docs.medusajs.com/learn/debugging-and-testing/logging/index.html.md) and resources within the module.
+2. Options passed to the module when it's later added in Medusa's configurations. These options are useful to pass secret keys or configurations that ensure your module is re-usable across applications. For the CMS Module, you accept the API key to connect to the dummy CMS as an option.
+
+When integrating a third-party system that has a Node.js SDK or client, you can initialize that client in the constructor to be used in the service's methods.
+
+### Integration Methods
+
+Next, you'll add methods that simulate sending requests to a third-party CMS. You'll use these methods later to sync brands from and to the CMS.
+
+Add the following methods in the `CmsModuleService`:
+
+```ts title="src/modules/cms/service.ts" highlights={methodsHighlights}
+export class CmsModuleService {
+  // ...
+
+  // a dummy method to simulate sending a request,
+  // in a realistic scenario, you'd use an SDK, fetch, or axios clients
+  private async sendRequest(url: string, method: string, data?: any) {
+    this.logger_.info(`Sending a ${method} request to ${url}.`)
+    this.logger_.info(`Request Data: ${JSON.stringify(data, null, 2)}`)
+    this.logger_.info(`API Key: ${JSON.stringify(this.options_.apiKey, null, 2)}`)
+  }
+
+  async createBrand(brand: Record<string, unknown>) {
+    await this.sendRequest("/brands", "POST", brand)
+  }
+
+  async deleteBrand(id: string) {
+    await this.sendRequest(`/brands/${id}`, "DELETE")
+  }
+
+  async retrieveBrands(): Promise<Record<string, unknown>[]> {
+    await this.sendRequest("/brands", "GET")
+
+    return []
+  }
+}
+```
+
+The `sendRequest` method sends requests to the third-party CMS. Since this guide isn't using a real CMS, it only simulates the sending by logging messages in the terminal.
+
+You also add three methods that use the `sendRequest` method:
+
+- `createBrand` that creates a brand in the third-party system.
+- `deleteBrand` that deletes the brand in the third-party system.
+- `retrieveBrands` to retrieve a brand from the third-party system.
+
+***
+
+## 3. Export Module Definition
+
+After creating the module's service, you'll export the module definition indicating the module's name and service.
+
+Create the file `src/modules/cms/index.ts` with the following content:
+
+![Directory structure of the Medusa application after adding the module definition file](https://res.cloudinary.com/dza7lstvk/image/upload/v1733492991/Medusa%20Book/cms-dir-overview-3_b0byks.jpg)
+
+```ts title="src/modules/cms/index.ts"
+import { Module } from "@medusajs/framework/utils"
+import CmsModuleService from "./service"
+
+export const CMS_MODULE = "cms"
+
+export default Module(CMS_MODULE, {
+  service: CmsModuleService,
+})
+```
+
+You use `Module` from the Modules SDK to export the module's defintion, indicating that the module's name is `cms` and its service is `CmsModuleService`.
+
+***
+
+## 4. Add Module to Medusa's Configurations
+
+Finally, add the module to the Medusa configurations at `medusa-config.ts`:
+
+```ts title="medusa-config.ts"
+module.exports = defineConfig({
+  // ...
+  modules: [
+    // ...
+    {
+      resolve: "./src/modules/cms",
+      options: {
+        apiKey: process.env.CMS_API_KEY,
+      },
+    },
+  ], 
+})
+```
+
+The object passed in `modules` accept an `options` property, whose value is an object of options to pass to the module. These are the options you receive in the `CmsModuleService`'s constructor.
+
+You can add the `CMS_API_KEY` environment variable to `.env`:
+
+```bash
+CMS_API_KEY=123
+```
+
+***
+
+## Next Steps: Sync Brand From Medusa to CMS
+
+You can now use the CMS Module's service to perform actions on the third-party CMS.
+
+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: 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.
+
+Some API routes, including the [Create Product API route](https://docs.medusajs.com/api/admin#products_postproducts), accept an `additional_data` request body parameter. This parameter can hold custom data that's passed to the [hooks](https://docs.medusajs.com/learn/fundamentals/workflows/workflow-hooks/index.html.md) of the workflow executed in the API route, allowing you to consume those hooks and perform actions with the custom data.
+
+So, in this chapter, to extend the create product flow and associate a brand with a product, you will:
+
+- Consume the [productsCreated](https://docs.medusajs.com/resources/references/medusa-workflows/createProductsWorkflow#productsCreated/index.html.md) hook of the [createProductsWorkflow](https://docs.medusajs.com/resources/references/medusa-workflows/createProductsWorkflow/index.html.md), which is executed within the workflow after the product is created. You'll link the product with the brand passed in the `additional_data` parameter.
+- Extend the Create Product API route to allow passing a brand ID in `additional_data`.
+
+To learn more about the `additional_data` property and the API routes that accept additional data, refer to [this chapter](https://docs.medusajs.com/learn/fundamentals/api-routes/additional-data/index.html.md).
+
+### Prerequisites
+
+- [Brand Module](https://docs.medusajs.com/learn/customization/custom-features/module/index.html.md)
+- [Defined link between the Brand and Product data models.](https://docs.medusajs.com/learn/customization/extend-features/define-link/index.html.md)
+
+***
+
+## 1. Consume the productsCreated Hook
+
+A workflow hook is a point in a workflow where you can inject a step to perform a custom functionality. Consuming a workflow hook allows you to extend the features of a workflow and, consequently, the API route that uses it.
+
+Learn more about the workflow hooks in [this chapter](https://docs.medusajs.com/learn/fundamentals/workflows/workflow-hooks/index.html.md).
+
+The [createProductsWorkflow](https://docs.medusajs.com/resources/references/medusa-workflows/createProductsWorkflow/index.html.md) used in the [Create Product API route](https://docs.medusajs.com/api/admin#products_postproducts) has a `productsCreated` hook that runs after the product is created. You'll consume this hook to link the created product with the brand specified in the request parameters.
+
+To consume the `productsCreated` hook, create the file `src/workflows/hooks/created-product.ts` with the following content:
+
+![Directory structure after creating the hook's file.](https://res.cloudinary.com/dza7lstvk/image/upload/v1733384338/Medusa%20Book/brands-hook-dir-overview_ltwr5h.jpg)
+
+```ts title="src/workflows/hooks/created-product.ts" highlights={hook1Highlights}
+import { createProductsWorkflow } from "@medusajs/medusa/core-flows"
+import { StepResponse } from "@medusajs/framework/workflows-sdk"
+import { Modules } from "@medusajs/framework/utils"
+import { LinkDefinition } from "@medusajs/framework/types"
+import { BRAND_MODULE } from "../../modules/brand"
+import BrandModuleService from "../../modules/brand/service"
+
+createProductsWorkflow.hooks.productsCreated(
+  (async ({ products, additional_data }, { container }) => {
+    if (!additional_data?.brand_id) {
+      return new StepResponse([], [])
+    }
+
+    const brandModuleService: BrandModuleService = container.resolve(
+      BRAND_MODULE
+    )
+    // if the brand doesn't exist, an error is thrown.
+    await brandModuleService.retrieveBrand(additional_data.brand_id as string)
+
+    // TODO link brand to product
+  })
+)
+```
+
+Workflows have a special `hooks` property to access its hooks and consume them. Each hook, such as `productsCreated`, accepts a step function as a parameter. The step function accepts the following parameters:
+
+1. An object having an `additional_data` property, which is the custom data passed in the request body under `additional_data`. The object will also have properties passed from the workflow to the hook, which in this case is the `products` property that holds an array of the created products.
+2. An object of properties related to the step's context. It has a `container` property whose value is the [Medusa container](https://docs.medusajs.com/learn/fundamentals/medusa-container/index.html.md) to resolve Framework and commerce tools.
+
+In the step, if a brand ID is passed in `additional_data`, you resolve the Brand Module's service and use its generated `retrieveBrand` method to retrieve the brand by its ID. The `retrieveBrand` method will throw an error if the brand doesn't exist.
+
+### Link Brand to Product
+
+Next, you want to create a link between the created products and the brand. To do so, you use Link, which is a class from the Modules SDK that provides methods to manage linked records.
+
+Learn more about Link in [this chapter](https://docs.medusajs.com/learn/fundamentals/module-links/link/index.html.md).
+
+To use Link in the `productsCreated` hook, replace the `TODO` with the following:
+
+```ts title="src/workflows/hooks/created-product.ts" highlights={hook2Highlights}
+const link = container.resolve("link")
+const logger = container.resolve("logger")
+
+const links: LinkDefinition[] = []
+
+for (const product of products) {
+  links.push({
+    [Modules.PRODUCT]: {
+      product_id: product.id,
+    },
+    [BRAND_MODULE]: {
+      brand_id: additional_data.brand_id,
+    },
+  })
+}
+
+await link.create(links)
+
+logger.info("Linked brand to products")
+
+return new StepResponse(links, links)
+```
+
+You resolve Link from the container. Then you loop over the created products to assemble an array of links to be created. After that, you pass the array of links to Link's `create` method, which will link the product and brand records.
+
+Each property in the link object is the name of a module, and its value is an object having a `{model_name}_id` property, where `{model_name}` is the snake-case name of the module's data model. Its value is the ID of the record to be linked. The link object's properties must be set in the same order as the link configurations passed to `defineLink`.
+
+![Diagram showcasing how the order of defining a link affects creating the link](https://res.cloudinary.com/dza7lstvk/image/upload/v1733386156/Medusa%20Book/remote-link-brand-product-exp_fhjmg4.jpg)
+
+Finally, you return an instance of `StepResponse` returning the created links.
+
+### Dismiss Links in Compensation
+
+You can pass as a second parameter of the hook a compensation function that undoes what the step did. It receives as a first parameter the returned `StepResponse`'s second parameter, and the step context object as a second parameter.
+
+To undo creating the links in the hook, pass the following compensation function as a second parameter to `productsCreated`:
+
+```ts title="src/workflows/hooks/created-product.ts"
+createProductsWorkflow.hooks.productsCreated(
+  // ...
+  (async (links, { container }) => {
+    if (!links?.length) {
+      return
+    }
+
+    const link = container.resolve("link")
+
+    await link.dismiss(links)
+  })
+)
+```
+
+In the compensation function, if the `links` parameter isn't empty, you resolve Link from the container and use its `dismiss` method. This method removes a link between two records. It accepts the same parameter as the `create` method.
+
+***
+
+## 2. Configure Additional Data Validation
+
+Now that you've consumed the `productsCreated` hook, you want to configure the `/admin/products` API route that creates a new product to accept a brand ID in its `additional_data` parameter.
+
+You configure the properties accepted in `additional_data` in the `src/api/middlewares.ts` that exports middleware configurations. So, create the file (or, if already existing, add to the file) `src/api/middlewares.ts` the following content:
+
+![Directory structure after adding the middelwares file](https://res.cloudinary.com/dza7lstvk/image/upload/v1733386868/Medusa%20Book/brands-middleware-dir-overview_uczos1.jpg)
+
+```ts title="src/api/middlewares.ts"
+import { defineMiddlewares } from "@medusajs/framework/http"
+import { z } from "zod"
+
+// ...
+
+export default defineMiddlewares({
+  routes: [
+    // ...
+    {
+      matcher: "/admin/products",
+      method: ["POST"],
+      additionalDataValidator: {
+        brand_id: z.string().optional(),
+      },
+    },
+  ],
+})
+```
+
+Objects in `routes` accept an `additionalDataValidator` property that configures the validation rules for custom properties passed in the `additional_data` request parameter. It accepts an object whose keys are custom property names, and their values are validation rules created using [Zod](https://zod.dev/).
+
+So, `POST` requests sent to `/admin/products` can now pass the ID of a brand in the `brand_id` property of `additional_data`.
+
+***
+
+## Test it Out
+
+To test it out, first, retrieve the authentication token of your admin user by sending a `POST` request to `/auth/user/emailpass`:
+
+```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 in the request body with your user's credentials.
+
+Then, send a `POST` request to `/admin/products` to create a product, and pass in the `additional_data` parameter a brand's ID:
+
+```bash
+curl -X POST 'http://localhost:9000/admin/products' \
+-H 'Content-Type: application/json' \
+-H 'Authorization: Bearer {token}' \
+--data '{
+    "title": "Product 1",
+    "options": [
+      {
+        "title": "Default option",
+        "values": ["Default option value"]
+      }
+    ],
+    "shipping_profile_id": "{shipping_profile_id}",
+    "additional_data": {
+        "brand_id": "{brand_id}"
+    }
+}'
+```
+
+Make sure to replace `{token}` with the token you received from the previous request, `shipping_profile_id` with the ID of a shipping profile in your application, and `{brand_id}` with the ID of a brand in your application. You can retrieve the ID of a shipping profile either from the Medusa Admin, or the [List Shipping Profiles API route](https://docs.medusajs.com/api/admin#shipping-profiles_getshippingprofiles).
+
+The request creates a product and returns it.
+
+In the Medusa application's logs, you'll find the message `Linked brand to products`, indicating that the workflow hook handler ran and linked the brand to the products.
+
+***
+
+## Next Steps: Query Linked Brands and Products
+
+Now that you've extending the create-product flow to link a brand to it, you want to retrieve the brand details of a product. You'll learn how to do so in the next chapter.
+
+
+# Guide: Define Module Link Between Brand and Product
+
+In this chapter, you'll learn how to define a module link between a brand defined in the [custom Brand Module](https://docs.medusajs.com/learn/customization/custom-features/module/index.html.md), and a product defined in the [Product Module](https://docs.medusajs.com/resources/commerce-modules/product/index.html.md) that's available in your Medusa application out-of-the-box.
+
+Modules are [isolated](https://docs.medusajs.com/learn/fundamentals/modules/isolation/index.html.md) from other resources, ensuring that they're integrated into the Medusa application without side effects. However, you may need to associate data models of different modules, or you're trying to extend data models from Commerce Modules with custom properties. To do that, you define module links.
+
+A module link forms an association between two data models of different modules while maintaining module isolation. You can then manage and query linked records of the data models using Medusa's Modules SDK.
+
+In this chapter, you'll define a module link between the `Brand` data model of the Brand Module, and the `Product` data model of the Product Module. In later chapters, you'll manage and retrieve linked product and brand records.
+
+Learn more about module links in [this chapters](https://docs.medusajs.com/learn/fundamentals/module-links/index.html.md).
+
+### Prerequisites
+
+- [Brand Module having a Brand data model](https://docs.medusajs.com/learn/customization/custom-features/module/index.html.md)
+
+## 1. Define Link
+
+Links are defined in a TypeScript or JavaScript file under the `src/links` directory. The file defines and exports the link using `defineLink` from the Modules SDK.
+
+So, to define a link between the `Product` and `Brand` models, create the file `src/links/product-brand.ts` with the following content:
+
+![The directory structure of the Medusa application after adding the link.](https://res.cloudinary.com/dza7lstvk/image/upload/v1733329897/Medusa%20Book/brands-link-dir-overview_t1rhlp.jpg)
+
+```ts title="src/links/product-brand.ts" highlights={highlights}
+import BrandModule from "../modules/brand"
+import ProductModule from "@medusajs/medusa/product"
+import { defineLink } from "@medusajs/framework/utils"
+
+export default defineLink(
+  {
+    linkable: ProductModule.linkable.product,
+    isList: true,
+  },
+  BrandModule.linkable.brand
+)
+```
+
+You import each module's definition object from the `index.ts` file of the module's directory. Each module object has a special `linkable` property that holds the data models' link configurations.
+
+The `defineLink` function accepts two parameters of the same type, which is either:
+
+- The data model's link configuration, which you access from the Module's `linkable` property;
+- Or an object that has two properties:
+  - `linkable`: the data model's link configuration, which you access from the Module's `linkable` property.
+  - `isList`: A boolean indicating whether many records of the data model can be linked to the other model.
+
+So, in the above code snippet, you define a link between the `Product` and `Brand` data models. Since a brand can be associated with multiple products, you enable `isList` in the `Product` model's object.
+
+***
+
+## 2. Sync the Link to the Database
+
+A module link is represented in the database as a table that stores the IDs of linked records. So, after defining the link, run the following command to create the module link's table in the database:
+
+```bash
+npx medusa db:migrate
+```
+
+This command reflects migrations on the database and syncs module links, which creates a table for the `product-brand` link.
+
+You can also run the `npx medusa db:sync-links` to just sync module links without running migrations.
+
+***
+
+## Next Steps: Extend Create Product Flow
+
+In the next chapter, you'll extend Medusa's workflow and API route that create a product to allow associating a brand with a product. You'll also learn how to link brand and product records.
+
+
+# Guide: 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.
+
+## Arrow Functions
+
+Widget and UI route components must be created as arrow functions.
+
+```ts highlights={arrowHighlights}
+// Don't
+function ProductWidget() {
+  // ...
+}
+
+// Do
+const ProductWidget = () => {
+  // ...
+}
+```
+
+***
+
+## Widget Zone
+
+A widget zone's value must be wrapped in double or single quotes. It can't be a template literal or a variable.
+
+```ts highlights={zoneHighlights}
+// Don't
+export const config = defineWidgetConfig({
+  zone: `product.details.before`,
+})
+
+// Don't
+const ZONE = "product.details.after"
+export const config = defineWidgetConfig({
+  zone: ZONE,
+})
+
+// Do
+export const config = defineWidgetConfig({
+  zone: "product.details.before",
+})
+```
+
+
 # Seed Data with Custom CLI Script
 
 In this chapter, you'll learn how to seed data using a custom CLI script.
@@ -6951,165 +7356,6 @@ 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.
 
 
-# Guide: Integrate Third-Party Brand System
-
-In the previous chapters, you've created a [Brand Module](https://docs.medusajs.com/learn/customization/custom-features/module/index.html.md) that adds brands to your application. In this chapter, you'll integrate a dummy Content-Management System (CMS) in a new module. The module's service will provide methods to retrieve and manage brands in the CMS. You'll later use this service to sync data from and to the CMS.
-
-Learn more about modules in [this chapter](https://docs.medusajs.com/learn/fundamentals/modules/index.html.md).
-
-## 1. Create Module Directory
-
-You'll integrate the third-party system in a new CMS Module. So, create the directory `src/modules/cms` that will hold the module's resources.
-
-![Directory structure after adding the directory for the CMS Module](https://res.cloudinary.com/dza7lstvk/image/upload/v1733492447/Medusa%20Book/cms-dir-overview-1_gasguk.jpg)
-
-***
-
-## 2. Create Module Service
-
-Next, you'll create the module's service. It will provide methods to connect and perform actions with the third-party system.
-
-Create the CMS Module's service at `src/modules/cms/service.ts` with the following content:
-
-![Directory structure after adding the CMS Module's service](https://res.cloudinary.com/dza7lstvk/image/upload/v1733492583/Medusa%20Book/cms-dir-overview-2_zwcwh3.jpg)
-
-```ts title="src/modules/cms/service.ts" highlights={serviceHighlights}
-import { Logger, ConfigModule } from "@medusajs/framework/types"
-
-export type ModuleOptions = {
-  apiKey: string
-}
-
-type InjectedDependencies = {
-  logger: Logger
-  configModule: ConfigModule
-}
-
-class CmsModuleService {
-  private options_: ModuleOptions
-  private logger_: Logger
-
-  constructor({ logger }: InjectedDependencies, options: ModuleOptions) {
-    this.logger_ = logger
-    this.options_ = options
-
-    // TODO initialize SDK
-  }
-}
-
-export default CmsModuleService
-```
-
-You create a `CmsModuleService` that will hold the methods to connect to the third-party CMS. A service's constructor accepts two parameters:
-
-1. The module's container. Since a module is [isolated](https://docs.medusajs.com/learn/fundamentals/modules/isolation/index.html.md), it has a [local container](https://docs.medusajs.com/learn/fundamentals/modules/container/index.html.md) different than the Medusa container you use in other customizations. This container holds Framework tools like the [Logger utility](https://docs.medusajs.com/learn/debugging-and-testing/logging/index.html.md) and resources within the module.
-2. Options passed to the module when it's later added in Medusa's configurations. These options are useful to pass secret keys or configurations that ensure your module is re-usable across applications. For the CMS Module, you accept the API key to connect to the dummy CMS as an option.
-
-When integrating a third-party system that has a Node.js SDK or client, you can initialize that client in the constructor to be used in the service's methods.
-
-### Integration Methods
-
-Next, you'll add methods that simulate sending requests to a third-party CMS. You'll use these methods later to sync brands from and to the CMS.
-
-Add the following methods in the `CmsModuleService`:
-
-```ts title="src/modules/cms/service.ts" highlights={methodsHighlights}
-export class CmsModuleService {
-  // ...
-
-  // a dummy method to simulate sending a request,
-  // in a realistic scenario, you'd use an SDK, fetch, or axios clients
-  private async sendRequest(url: string, method: string, data?: any) {
-    this.logger_.info(`Sending a ${method} request to ${url}.`)
-    this.logger_.info(`Request Data: ${JSON.stringify(data, null, 2)}`)
-    this.logger_.info(`API Key: ${JSON.stringify(this.options_.apiKey, null, 2)}`)
-  }
-
-  async createBrand(brand: Record<string, unknown>) {
-    await this.sendRequest("/brands", "POST", brand)
-  }
-
-  async deleteBrand(id: string) {
-    await this.sendRequest(`/brands/${id}`, "DELETE")
-  }
-
-  async retrieveBrands(): Promise<Record<string, unknown>[]> {
-    await this.sendRequest("/brands", "GET")
-
-    return []
-  }
-}
-```
-
-The `sendRequest` method sends requests to the third-party CMS. Since this guide isn't using a real CMS, it only simulates the sending by logging messages in the terminal.
-
-You also add three methods that use the `sendRequest` method:
-
-- `createBrand` that creates a brand in the third-party system.
-- `deleteBrand` that deletes the brand in the third-party system.
-- `retrieveBrands` to retrieve a brand from the third-party system.
-
-***
-
-## 3. Export Module Definition
-
-After creating the module's service, you'll export the module definition indicating the module's name and service.
-
-Create the file `src/modules/cms/index.ts` with the following content:
-
-![Directory structure of the Medusa application after adding the module definition file](https://res.cloudinary.com/dza7lstvk/image/upload/v1733492991/Medusa%20Book/cms-dir-overview-3_b0byks.jpg)
-
-```ts title="src/modules/cms/index.ts"
-import { Module } from "@medusajs/framework/utils"
-import CmsModuleService from "./service"
-
-export const CMS_MODULE = "cms"
-
-export default Module(CMS_MODULE, {
-  service: CmsModuleService,
-})
-```
-
-You use `Module` from the Modules SDK to export the module's defintion, indicating that the module's name is `cms` and its service is `CmsModuleService`.
-
-***
-
-## 4. Add Module to Medusa's Configurations
-
-Finally, add the module to the Medusa configurations at `medusa-config.ts`:
-
-```ts title="medusa-config.ts"
-module.exports = defineConfig({
-  // ...
-  modules: [
-    // ...
-    {
-      resolve: "./src/modules/cms",
-      options: {
-        apiKey: process.env.CMS_API_KEY,
-      },
-    },
-  ], 
-})
-```
-
-The object passed in `modules` accept an `options` property, whose value is an object of options to pass to the module. These are the options you receive in the `CmsModuleService`'s constructor.
-
-You can add the `CMS_API_KEY` environment variable to `.env`:
-
-```bash
-CMS_API_KEY=123
-```
-
-***
-
-## Next Steps: Sync Brand From Medusa to CMS
-
-You can now use the CMS Module's service to perform actions on the third-party CMS.
-
-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.
-
-
 # Environment Variables in Admin Customizations
 
 In this chapter, you'll learn how to use environment variables in your admin customizations.
@@ -7187,182 +7433,6 @@ When you build the Medusa application, including the Medusa Admin, with the `bui
 For example, the `VITE_MY_API_KEY` environment variable in the example above will be replaced with the actual value during the build process.
 
 
-# Admin Development Constraints
-
-This chapter lists some constraints of admin widgets and UI routes.
-
-## Arrow Functions
-
-Widget and UI route components must be created as arrow functions.
-
-```ts highlights={arrowHighlights}
-// Don't
-function ProductWidget() {
-  // ...
-}
-
-// Do
-const ProductWidget = () => {
-  // ...
-}
-```
-
-***
-
-## Widget Zone
-
-A widget zone's value must be wrapped in double or single quotes. It can't be a template literal or a variable.
-
-```ts highlights={zoneHighlights}
-// Don't
-export const config = defineWidgetConfig({
-  zone: `product.details.before`,
-})
-
-// Don't
-const ZONE = "product.details.after"
-export const config = defineWidgetConfig({
-  zone: ZONE,
-})
-
-// Do
-export const config = defineWidgetConfig({
-  zone: "product.details.before",
-})
-```
-
-
-# Admin 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 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.
@@ -7516,6 +7586,567 @@ 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 Widgets
+
+In this chapter, you’ll learn more about widgets and how to use them.
+
+## What is an Admin Widget?
+
+The Medusa Admin dashboard's pages are customizable to insert widgets of custom content in pre-defined injection zones. You create these widgets as React components that allow admin users to perform custom actions.
+
+For example, you can add a widget on the product details page that allow admin users to sync products to a third-party service.
+
+***
+
+## How to Create a Widget?
+
+### Prerequisites
+
+- [Medusa application installed](https://docs.medusajs.com/learn/installation/index.html.md)
+
+You create a widget in a `.tsx` file under the `src/admin/widgets` directory. The file’s default export must be the widget, which is the React component that renders the custom content. The file must also export the widget’s configurations indicating where to insert the widget.
+
+For example, create the file `src/admin/widgets/product-widget.tsx` with the following content:
+
+![Example of widget file in the application's directory structure](https://res.cloudinary.com/dza7lstvk/image/upload/v1732867137/Medusa%20Book/widget-dir-overview_dqsbct.jpg)
+
+```tsx title="src/admin/widgets/product-widget.tsx" highlights={widgetHighlights}
+import { defineWidgetConfig } from "@medusajs/admin-sdk"
+import { Container, Heading } from "@medusajs/ui"
+
+// The widget
+const ProductWidget = () => {
+  return (
+    <Container className="divide-y p-0">
+      <div className="flex items-center justify-between px-6 py-4">
+        <Heading level="h2">Product Widget</Heading>
+      </div>
+    </Container>
+  )
+}
+
+// The widget's configurations
+export const config = defineWidgetConfig({
+  zone: "product.details.before",
+})
+
+export default ProductWidget
+```
+
+You export the `ProductWidget` component, which shows the heading `Product Widget`. In the widget, you use [Medusa UI](https://docs.medusajs.com/ui/index.html.md), a package that Medusa maintains to allow you to customize the dashboard with the same components used to build it.
+
+To export the widget's configurations, you use `defineWidgetConfig` from the Admin Extension SDK. It accepts as a parameter an object with the `zone` property, whose value is a string or an array of strings, each being the name of the zone to inject the widget into.
+
+In the example above, the widget is injected at the top of a product’s details.
+
+The widget component must be created as an arrow function.
+
+### Test the Widget
+
+To test out the widget, start the Medusa application:
+
+```bash npm2yarn
+npm run dev
+```
+
+Then, open a product’s details page. You’ll find your custom widget at the top of the page.
+
+***
+
+## Props Passed in Detail Pages
+
+Widgets that are injected into a details page receive a `data` prop, which is the main data of the details page.
+
+For example, a widget injected into the `product.details.before` zone receives the product's details in the `data` prop:
+
+```tsx title="src/admin/widgets/product-widget.tsx" highlights={detailHighlights}
+import { defineWidgetConfig } from "@medusajs/admin-sdk"
+import { Container, Heading } from "@medusajs/ui"
+import { 
+  DetailWidgetProps, 
+  AdminProduct,
+} from "@medusajs/framework/types"
+
+// The widget
+const ProductWidget = ({ 
+  data,
+}: DetailWidgetProps<AdminProduct>) => {
+  return (
+    <Container className="divide-y p-0">
+      <div className="flex items-center justify-between px-6 py-4">
+        <Heading level="h2">
+          Product Widget {data.title}
+        </Heading>
+      </div>
+    </Container>
+  )
+}
+
+// The widget's configurations
+export const config = defineWidgetConfig({
+  zone: "product.details.before",
+})
+
+export default ProductWidget
+```
+
+The props type is `DetailWidgetProps`, and it accepts as a type argument the expected type of `data`. For the product details page, it's `AdminProduct`.
+
+***
+
+## Injection Zone
+
+Refer to [this reference](https://docs.medusajs.com/resources/admin-widget-injection-zones/index.html.md) for the full list of injection zones and their props.
+
+***
+
+## Admin Components List
+
+To build admin customizations that match the Medusa Admin's designs and layouts, refer to [this guide](https://docs.medusajs.com/resources/admin-components/index.html.md) to find common components.
+
+
+# Admin Development Tips
+
+In this chapter, you'll find some tips for your admin development.
+
+## Send Requests to API Routes
+
+To send a request to an API route in the Medusa Application, use Medusa's [JS SDK](https://docs.medusajs.com/resources/js-sdk/index.html.md) with [Tanstack Query](https://tanstack.com/query/latest). Both of these tools are installed in your project by default.
+
+Do not install Tanstack Query as that will cause unexpected errors in your development. If you prefer installing it for better auto-completion in your code editor, make sure to install `v5.64.2` as a development dependency.
+
+First, create the file `src/admin/lib/config.ts` to setup the SDK for use in your customizations:
+
+```ts
+import Medusa from "@medusajs/js-sdk"
+
+export const sdk = new Medusa({
+  baseUrl: import.meta.env.VITE_BACKEND_URL || "/",
+  debug: import.meta.env.DEV,
+  auth: {
+    type: "session",
+  },
+})
+```
+
+Notice that you use `import.meta.env` to access environment variables in your customizations, as explained in [this chapter](https://docs.medusajs.com/learn/fundamentals/admin/environment-variables/index.html.md).
+
+Learn more about the JS SDK's configurations [this documentation](https://docs.medusajs.com/resources/js-sdk#js-sdk-configurations/index.html.md).
+
+Then, use the configured SDK with the `useQuery` Tanstack Query hook to send `GET` requests, and `useMutation` hook to send `POST` or `DELETE` requests.
+
+For example:
+
+### Query
+
+```tsx title="src/admin/widgets/product-widget.ts" highlights={queryHighlights}
+import { defineWidgetConfig } from "@medusajs/admin-sdk"
+import { Button, Container } from "@medusajs/ui"
+import { useQuery } from "@tanstack/react-query"
+import { sdk } from "../lib/config"
+import { DetailWidgetProps, HttpTypes } from "@medusajs/framework/types"
+
+const ProductWidget = () => {
+  const { data, isLoading } = useQuery({
+    queryFn: () => sdk.admin.product.list(),
+    queryKey: ["products"],
+  })
+  
+  return (
+    <Container className="divide-y p-0">
+      {isLoading && <span>Loading...</span>}
+      {data?.products && (
+        <ul>
+          {data.products.map((product) => (
+            <li key={product.id}>{product.title}</li>
+          ))}
+        </ul>
+      )}
+    </Container>
+  )
+}
+
+export const config = defineWidgetConfig({
+  zone: "product.list.before",
+})
+
+export default ProductWidget
+```
+
+### Mutation
+
+```tsx title="src/admin/widgets/product-widget.ts" highlights={mutationHighlights}
+import { defineWidgetConfig } from "@medusajs/admin-sdk"
+import { Button, Container } from "@medusajs/ui"
+import { useMutation } from "@tanstack/react-query"
+import { sdk } from "../lib/config"
+import { DetailWidgetProps, HttpTypes } from "@medusajs/framework/types"
+
+const ProductWidget = ({ 
+  data: productData,
+}: DetailWidgetProps<HttpTypes.AdminProduct>) => {
+  const { mutateAsync } = useMutation({
+    mutationFn: (payload: HttpTypes.AdminUpdateProduct) => 
+      sdk.admin.product.update(productData.id, payload),
+    onSuccess: () => alert("updated product"),
+  })
+
+  const handleUpdate = () => {
+    mutateAsync({
+      title: "New Product Title",
+    })
+  }
+  
+  return (
+    <Container className="divide-y p-0">
+      <Button onClick={handleUpdate}>Update Title</Button>
+    </Container>
+  )
+}
+
+export const config = defineWidgetConfig({
+  zone: "product.details.before",
+})
+
+export default ProductWidget
+```
+
+You can also send requests to custom routes as explained in the [JS SDK reference](https://docs.medusajs.com/resources/js-sdk/index.html.md).
+
+### Use Route Loaders for Initial Data
+
+You may need to retrieve data before your component is rendered, or you may need to pass some initial data to your component to be used while data is being fetched. In those cases, you can use a [route loader](https://docs.medusajs.com/learn/fundamentals/admin/routing/index.html.md).
+
+***
+
+## Global Variables in Admin Customizations
+
+In your admin customizations, you can use the following global variables:
+
+- `__BASE__`: The base path of the Medusa Admin, as set in the [admin.path](https://docs.medusajs.com/learn/configurations/medusa-config#path/index.html.md) configuration in `medusa-config.ts`.
+- `__BACKEND_URL__`: The URL to the Medusa backend, as set in the [admin.backendUrl](https://docs.medusajs.com/learn/configurations/medusa-config#backendurl/index.html.md) configuration in `medusa-config.ts`.
+- `__STOREFRONT_URL__`: The URL to the storefront, as set in the [admin.storefrontUrl](https://docs.medusajs.com/learn/configurations/medusa-config#storefrontUrl/index.html.md) configuration in `medusa-config.ts`.
+
+***
+
+## Admin Translations
+
+The Medusa Admin dashboard can be displayed in languages other than English, which is the default. Other languages are added through community contributions.
+
+Learn how to add a new language translation for the Medusa Admin in [this guide](https://docs.medusajs.com/learn/resources/contribution-guidelines/admin-translations/index.html.md).
+
+
+# Pass Additional Data to Medusa's API Route
+
+In this chapter, you'll learn how to pass additional data in requests to Medusa's API Route.
+
+## Why Pass Additional Data?
+
+Some of Medusa's API Routes accept an `additional_data` parameter whose type is an object. The API Route passes the `additional_data` to the workflow, which in turn passes it to its hooks.
+
+This is useful when you have a link from your custom module to a Commerce Module, and you want to perform an additional action when a request is sent to an existing API route.
+
+For example, the [Create Product API Route](https://docs.medusajs.com/api/admin#products_postproducts) accepts an `additional_data` parameter. If you have a data model linked to it, you consume the `productsCreated` hook to create a record of the data model using the custom data and link it to the product.
+
+### API Routes Accepting Additional Data
+
+### API Routes List
+
+- Campaigns
+  - [Create Campaign](https://docs.medusajs.com/api/admin#campaigns_postcampaigns)
+  - [Update Campaign](https://docs.medusajs.com/api/admin#campaigns_postcampaignsid)
+- Cart
+  - [Create Cart](https://docs.medusajs.com/api/store#carts_postcarts)
+  - [Update Cart](https://docs.medusajs.com/api/store#carts_postcartsid)
+- Collections
+  - [Create Collection](https://docs.medusajs.com/api/admin#collections_postcollections)
+  - [Update Collection](https://docs.medusajs.com/api/admin#collections_postcollectionsid)
+- Customers
+  - [Create Customer](https://docs.medusajs.com/api/admin#customers_postcustomers)
+  - [Update Customer](https://docs.medusajs.com/api/admin#customers_postcustomersid)
+  - [Create Address](https://docs.medusajs.com/api/admin#customers_postcustomersidaddresses)
+  - [Update Address](https://docs.medusajs.com/api/admin#customers_postcustomersidaddressesaddress_id)
+- Draft Orders
+  - [Create Draft Order](https://docs.medusajs.com/api/admin#draft-orders_postdraftorders)
+- Orders
+  - [Complete Orders](https://docs.medusajs.com/api/admin#orders_postordersidcomplete)
+  - [Cancel Order's Fulfillment](https://docs.medusajs.com/api/admin#orders_postordersidfulfillmentsfulfillment_idcancel)
+  - [Create Shipment](https://docs.medusajs.com/api/admin#orders_postordersidfulfillmentsfulfillment_idshipments)
+  - [Create Fulfillment](https://docs.medusajs.com/api/admin#orders_postordersidfulfillments)
+- Products
+  - [Create Product](https://docs.medusajs.com/api/admin#products_postproducts)
+  - [Update Product](https://docs.medusajs.com/api/admin#products_postproductsid)
+  - [Create Product Variant](https://docs.medusajs.com/api/admin#products_postproductsidvariants)
+  - [Update Product Variant](https://docs.medusajs.com/api/admin#products_postproductsidvariantsvariant_id)
+  - [Create Product Option](https://docs.medusajs.com/api/admin#products_postproductsidoptions)
+  - [Update Product Option](https://docs.medusajs.com/api/admin#products_postproductsidoptionsoption_id)
+- Product Tags
+  - [Create Product Tag](https://docs.medusajs.com/api/admin#product-tags_postproducttags)
+  - [Update Product Tag](https://docs.medusajs.com/api/admin#product-tags_postproducttagsid)
+- Product Types
+  - [Create Product Type](https://docs.medusajs.com/api/admin#product-types_postproducttypes)
+  - [Update Product Type](https://docs.medusajs.com/api/admin#product-types_postproducttypesid)
+- Promotions
+  - [Create Promotion](https://docs.medusajs.com/api/admin#promotions_postpromotions)
+  - [Update Promotion](https://docs.medusajs.com/api/admin#promotions_postpromotionsid)
+
+***
+
+## How to Pass Additional Data
+
+### 1. Specify Validation of Additional Data
+
+Before passing custom data in the `additional_data` object parameter, you must specify validation rules for the allowed properties in the object.
+
+To do that, use the middleware route object defined in `src/api/middlewares.ts`.
+
+For example, create the file `src/api/middlewares.ts` with the following content:
+
+```ts title="src/api/middlewares.ts"
+import { defineMiddlewares } from "@medusajs/framework/http"
+import { z } from "zod"
+
+export default defineMiddlewares({
+  routes: [
+    {
+      method: "POST",
+      matcher: "/admin/products",
+      additionalDataValidator: {
+        brand: z.string().optional(),
+      },
+    },
+  ],
+})
+```
+
+The middleware route object accepts an optional parameter `additionalDataValidator` whose value is an object of key-value pairs. The keys indicate the name of accepted properties in the `additional_data` parameter, and the value is [Zod](https://zod.dev/) validation rules of the property.
+
+In this example, you indicate that the `additional_data` parameter accepts a `brand` property whose value is an optional string.
+
+Refer to [Zod's documentation](https://zod.dev) for all available validation rules.
+
+### 2. Pass the Additional Data in a Request
+
+You can now pass a `brand` property in the `additional_data` parameter of a request to the Create Product API Route.
+
+For example:
+
+```bash
+curl -X POST 'http://localhost:9000/admin/products' \
+-H 'Content-Type: application/json' \
+-H 'Authorization: Bearer {token}' \
+--data '{
+    "title": "Product 1",
+    "options": [
+      {
+        "title": "Default option",
+        "values": ["Default option value"]
+      }
+    ],
+    "shipping_profile_id": "{shipping_profile_id}",
+    "additional_data": {
+        "brand": "Acme"
+    }
+}'
+```
+
+Make sure to replace the `{token}` in the authorization header with an admin user's authentication token, and `{shipping_profile_id}` with an existing shipping profile's ID.
+
+In this request, you pass in the `additional_data` parameter a `brand` property and set its value to `Acme`.
+
+The `additional_data` is then passed to hooks in the `createProductsWorkflow` used by the API route.
+
+***
+
+## Use Additional Data in a Hook
+
+Learn about workflow hooks in [this guide](https://docs.medusajs.com/learn/fundamentals/workflows/workflow-hooks/index.html.md).
+
+Step functions consuming the workflow hook can access the `additional_data` in the first parameter.
+
+For example, consider you want to store the data passed in `additional_data` in the product's `metadata` property.
+
+To do that, create the file `src/workflows/hooks/product-created.ts` with the following content:
+
+```ts title="src/workflows/hooks/product-created.ts"
+import { StepResponse } from "@medusajs/framework/workflows-sdk"
+import { createProductsWorkflow } from "@medusajs/medusa/core-flows"
+import { Modules } from "@medusajs/framework/utils"
+
+createProductsWorkflow.hooks.productsCreated(
+  async ({ products, additional_data }, { container }) => {
+    if (!additional_data?.brand) {
+      return
+    }
+
+    const productModuleService = container.resolve(
+      Modules.PRODUCT
+    )
+
+    await productModuleService.upsertProducts(
+      products.map((product) => ({
+        ...product,
+        metadata: {
+          ...product.metadata,
+          brand: additional_data.brand,
+        },
+      }))
+    )
+
+    return new StepResponse(products, {
+      products,
+      additional_data,
+    })
+  }
+)
+```
+
+This consumes the `productsCreated` hook, which runs after the products are created.
+
+If `brand` is passed in `additional_data`, you resolve the Product Module's main service and use its `upsertProducts` method to update the products, adding the brand to the `metadata` property.
+
+### Compensation Function
+
+Hooks also accept a compensation function as a second parameter to undo the actions made by the step function.
+
+For example, pass the following second parameter to the `productsCreated` hook:
+
+```ts title="src/workflows/hooks/product-created.ts"
+createProductsWorkflow.hooks.productsCreated(
+  async ({ products, additional_data }, { container }) => {
+    // ...
+  },
+  async ({ products, additional_data }, { container }) => {
+    if (!additional_data.brand) {
+      return
+    }
+
+    const productModuleService = container.resolve(
+      Modules.PRODUCT
+    )
+
+    await productModuleService.upsertProducts(
+      products
+    )
+  }
+)
+```
+
+This updates the products to their original state before adding the brand to their `metadata` property.
+
+
+# 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`.
+
+
 # Admin UI Routes
 
 In this chapter, you’ll learn how to create a UI route in the admin dashboard.
@@ -7752,195 +8383,1453 @@ 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 Widgets
+# HTTP Methods
 
-In this chapter, you’ll learn more about widgets and how to use them.
+In this chapter, you'll learn about how to add new API routes for each HTTP method.
 
-## What is an Admin Widget?
+## HTTP Method Handler
 
-The Medusa Admin dashboard's pages are customizable to insert widgets of custom content in pre-defined injection zones. You create these widgets as React components that allow admin users to perform custom actions.
+An API route is created for every HTTP method you export a handler function for in a route file.
 
-For example, you can add a widget on the product details page that allow admin users to sync products to a third-party service.
+Allowed HTTP methods are: `GET`, `POST`, `DELETE`, `PUT`, `PATCH`, `OPTIONS`, and `HEAD`.
+
+For example, create the file `src/api/hello-world/route.ts` with the following content:
+
+```ts title="src/api/hello-world/route.ts"
+import type {
+  MedusaRequest,
+  MedusaResponse,
+} from "@medusajs/framework/http"
+
+export const GET = async (
+  req: MedusaRequest,
+  res: MedusaResponse
+) => {
+  res.json({
+    message: "[GET] Hello world!",
+  })
+}
+
+export const POST = async (
+  req: MedusaRequest,
+  res: MedusaResponse
+) => {
+  res.json({
+    message: "[POST] Hello world!",
+  })
+}
+```
+
+This adds two API Routes:
+
+- A `GET` route at `http://localhost:9000/hello-world`.
+- A `POST` route at `http://localhost:9000/hello-world`.
+
+
+# Middlewares
+
+In this chapter, you’ll learn about middlewares and how to create them.
+
+## What is a Middleware?
+
+A middleware is a function executed when a request is sent to an API Route. It's executed before the route handler function.
+
+Middlewares are used to guard API routes, parse request content types other than `application/json`, manipulate request data, and more.
+
+As Medusa's server is based on Express, you can use any [Express middleware](https://expressjs.com/en/resources/middleware.html).
+
+### Middleware Types
+
+There are two types of middlewares:
+
+1. Global Middleware: A middleware that applies to all routes matching a specified pattern.
+2. Route Middleware: A middleware that applies to routes matching a specified pattern and HTTP method(s).
+
+These middlewares generally have the same definition and usage, but they differ in the routes they apply to. You'll learn how to create both types in the following sections.
 
 ***
 
-## How to Create a Widget?
+## How to Create a Global Middleware?
 
-### Prerequisites
+Middlewares of all types are defined in the special file `src/api/middlewares.ts`. Use the `defineMiddlewares` function from the Medusa Framework to define the middlewares, and export its value.
 
-- [Medusa application installed](https://docs.medusajs.com/learn/installation/index.html.md)
+For example:
 
-You create a widget in a `.tsx` file under the `src/admin/widgets` directory. The file’s default export must be the widget, which is the React component that renders the custom content. The file must also export the widget’s configurations indicating where to insert the widget.
+```ts title="src/api/middlewares.ts"
+import { 
+  defineMiddlewares,
+  MedusaNextFunction, 
+  MedusaRequest, 
+  MedusaResponse, 
+} from "@medusajs/framework/http"
 
-For example, create the file `src/admin/widgets/product-widget.tsx` with the following content:
+export default defineMiddlewares({
+  routes: [
+    {
+      matcher: "/custom*",
+      middlewares: [
+        (
+          req: MedusaRequest, 
+          res: MedusaResponse, 
+          next: MedusaNextFunction
+        ) => {
+          console.log("Received a request!")
 
-![Example of widget file in the application's directory structure](https://res.cloudinary.com/dza7lstvk/image/upload/v1732867137/Medusa%20Book/widget-dir-overview_dqsbct.jpg)
-
-```tsx title="src/admin/widgets/product-widget.tsx" highlights={widgetHighlights}
-import { defineWidgetConfig } from "@medusajs/admin-sdk"
-import { Container, Heading } from "@medusajs/ui"
-
-// The widget
-const ProductWidget = () => {
-  return (
-    <Container className="divide-y p-0">
-      <div className="flex items-center justify-between px-6 py-4">
-        <Heading level="h2">Product Widget</Heading>
-      </div>
-    </Container>
-  )
-}
-
-// The widget's configurations
-export const config = defineWidgetConfig({
-  zone: "product.details.before",
+          next()
+        },
+      ],
+    },
+  ],
 })
-
-export default ProductWidget
 ```
 
-You export the `ProductWidget` component, which shows the heading `Product Widget`. In the widget, you use [Medusa UI](https://docs.medusajs.com/ui/index.html.md), a package that Medusa maintains to allow you to customize the dashboard with the same components used to build it.
+The `defineMiddlewares` function accepts a middleware configurations object that has the property `routes`. `routes`'s value is an array of middleware route objects, each having the following properties:
 
-To export the widget's configurations, you use `defineWidgetConfig` from the Admin Extension SDK. It accepts as a parameter an object with the `zone` property, whose value is a string or an array of strings, each being the name of the zone to inject the widget into.
+- `matcher`: a string or regular expression indicating the API route path to apply the middleware on. The regular expression must be compatible with [path-to-regexp](https://github.com/pillarjs/path-to-regexp).
+- `middlewares`: An array of global and route middleware functions.
 
-In the example above, the widget is injected at the top of a product’s details.
+In the example above, you define a global middleware that logs the message `Received a request!` whenever a request is sent to an API route path starting with `/custom`.
 
-The widget component must be created as an arrow function.
+### Test the Global Middleware
 
-### Test the Widget
+To test the middleware:
 
-To test out the widget, start the Medusa application:
+1. Start the application:
 
 ```bash npm2yarn
 npm run dev
 ```
 
-Then, open a product’s details page. You’ll find your custom widget at the top of the page.
-
-***
-
-## Props Passed in Detail Pages
-
-Widgets that are injected into a details page receive a `data` prop, which is the main data of the details page.
-
-For example, a widget injected into the `product.details.before` zone receives the product's details in the `data` prop:
-
-```tsx title="src/admin/widgets/product-widget.tsx" highlights={detailHighlights}
-import { defineWidgetConfig } from "@medusajs/admin-sdk"
-import { Container, Heading } from "@medusajs/ui"
-import { 
-  DetailWidgetProps, 
-  AdminProduct,
-} from "@medusajs/framework/types"
-
-// The widget
-const ProductWidget = ({ 
-  data,
-}: DetailWidgetProps<AdminProduct>) => {
-  return (
-    <Container className="divide-y p-0">
-      <div className="flex items-center justify-between px-6 py-4">
-        <Heading level="h2">
-          Product Widget {data.title}
-        </Heading>
-      </div>
-    </Container>
-  )
-}
-
-// The widget's configurations
-export const config = defineWidgetConfig({
-  zone: "product.details.before",
-})
-
-export default ProductWidget
-```
-
-The props type is `DetailWidgetProps`, and it accepts as a type argument the expected type of `data`. For the product details page, it's `AdminProduct`.
-
-***
-
-## Injection Zone
-
-Refer to [this reference](https://docs.medusajs.com/resources/admin-widget-injection-zones/index.html.md) for the full list of injection zones and their props.
-
-***
-
-## Admin Components List
-
-To build admin customizations that match the Medusa Admin's designs and layouts, refer to [this guide](https://docs.medusajs.com/resources/admin-components/index.html.md) to find common components.
-
-
-# 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:
+2. Send a request to any API route starting with `/custom`.
+3. See the following message in the terminal:
 
 ```bash
-npx medusa db:generate custom_module
-npx medusa db:migrate
+Received a request!
 ```
 
-The first command generates the migration under the `migrations` directory of your module's directory, and the second reflects it on the database.
+***
+
+## How to Create a Route Middleware?
+
+In the previous section, you learned how to create a global middleware. You define the route middleware in the same way in `src/api/middlewares.ts`, but you specify an additional property `method` in the middleware route object. Its value is one or more HTTP methods to apply the middleware to.
+
+For example:
+
+```ts title="src/api/middlewares.ts" highlights={highlights} collapsibleLines="1-7" expandButtonLabel="Show Imports"
+import { 
+  MedusaNextFunction, 
+  MedusaRequest, 
+  MedusaResponse, 
+  defineMiddlewares,
+} from "@medusajs/framework/http"
+
+export default defineMiddlewares({
+  routes: [
+    {
+      matcher: "/custom*",
+      method: ["POST", "PUT"],
+      middlewares: [
+        (
+          req: MedusaRequest, 
+          res: MedusaResponse, 
+          next: MedusaNextFunction
+        ) => {
+          console.log("Received a request!")
+
+          next()
+        },
+      ],
+    },
+  ],
+})
+```
+
+This example applies the middleware only when a `POST` or `PUT` request is sent to an API route path starting with `/custom`, changing the middleware from a global middleware to a route middleware.
+
+### Test the Route Middleware
+
+To test the middleware:
+
+1. Start the application:
+
+```bash npm2yarn
+npm run dev
+```
+
+2. Send a `POST` request to any API route starting with `/custom`.
+3. See the following message in the terminal:
+
+```bash
+Received a request!
+```
+
+***
+
+## When to Use Middlewares
+
+- You want to protect API routes by a custom condition.
+- You're modifying the request body.
+
+***
+
+## Middleware Function Parameters
+
+The middleware function accepts three parameters:
+
+1. A request object of type `MedusaRequest`.
+2. A response object of type `MedusaResponse`.
+3. A function of type `MedusaNextFunction` that executes the next middleware in the stack.
+
+You must call the `next` function in the middleware. Otherwise, other middlewares and the API route handler won’t execute.
+
+***
+
+## Middleware for Routes with Path Parameters
+
+To indicate a path parameter in a middleware's `matcher` pattern, use the format `:{param-name}`.
+
+For example:
+
+```ts title="src/api/middlewares.ts" collapsibleLines="1-7" expandMoreLabel="Show Imports" highlights={pathParamHighlights}
+import { 
+  MedusaNextFunction, 
+  MedusaRequest, 
+  MedusaResponse, 
+  defineMiddlewares,
+} from "@medusajs/framework/http"
+
+export default defineMiddlewares({
+  routes: [
+    {
+      matcher: "/custom/:id",
+      middlewares: [
+        // ...
+      ],
+    },
+  ],
+})
+```
+
+This applies a middleware to the routes defined in the file `src/api/custom/[id]/route.ts`.
+
+***
+
+## Request URLs with Trailing Backslashes
+
+A middleware whose `matcher` pattern doesn't end with a backslash won't be applied for requests to URLs with a trailing backslash.
+
+For example, consider you have the following middleware:
+
+```ts title="src/api/middlewares.ts" collapsibleLines="1-7" expandMoreLabel="Show Imports"
+import { 
+  MedusaNextFunction, 
+  MedusaRequest, 
+  MedusaResponse, 
+  defineMiddlewares,
+} from "@medusajs/framework/http"
+
+export default defineMiddlewares({
+  routes: [
+    {
+      matcher: "/custom",
+      middlewares: [
+        (
+          req: MedusaRequest, 
+          res: MedusaResponse, 
+          next: MedusaNextFunction
+        ) => {
+          console.log("Received a request!")
+
+          next()
+        },
+      ],
+    },
+  ],
+})
+```
+
+If you send a request to `http://localhost:9000/custom`, the middleware will run.
+
+However, if you send a request to `http://localhost:9000/custom/`, the middleware won't run.
+
+In general, avoid adding trailing backslashes when sending requests to API routes.
+
+***
+
+## Middlewares and Route Ordering
+
+The ordering explained in this section was added in [Medusa v2.6](https://github.com/medusajs/medusa/releases/tag/v2.6)
+
+The Medusa application registers middlewares and API route handlers in the following order:
+
+1. Global middlewares in the following order:
+   1. Global middleware defined in the Medusa's core.
+   2. Global middleware defined in the plugins (in the order the plugins are registered in).
+   3. Global middleware you define in the application.
+2. Route middlewares in the following order:
+   1. Route middleware defined in the Medusa's core.
+   2. Route middleware defined in the plugins (in the order the plugins are registered in).
+   3. Route middleware you define in the application.
+3. API routes in the following order:
+   1. API routes defined in the Medusa's core.
+   2. API routes defined in the plugins (in the order the plugins are registered in).
+   3. API routes you define in the application.
+
+### Middlewares Sorting
+
+On top of the previous ordering, Medusa sorts global and route middlewares based on their matcher pattern in the following order:
+
+1. Wildcard matchers. For example, `/custom*`.
+2. Regex matchers. For example, `/custom/(products|collections)`.
+3. Static matchers without parameters. For example, `/custom`.
+4. Static matchers with parameters. For example, `/custom/:id`.
+
+For example, if you have the following middlewares:
+
+```ts title="src/api/middlewares.ts"
+export default defineMiddlewares({
+  routes: [
+    {
+      matcher: "/custom/:id",
+      middlewares: [/* ... */],
+    },
+    {
+      matcher: "/custom",
+      middlewares: [/* ... */],
+    },
+    {
+      matcher: "/custom*",
+      method: ["GET"],
+      middlewares: [/* ... */],
+    },
+    {
+      matcher: "/custom/:id",
+      method: ["GET"],
+      middlewares: [/* ... */],
+    },
+  ],
+})
+```
+
+The global middlewares are sorted into the following order before they're registered:
+
+1. Global middleware `/custom`.
+2. Global middleware `/custom/:id`.
+
+And the route middlewares are sorted into the following order before they're registered:
+
+1. Route middleware `/custom*`.
+2. Route middleware `/custom/:id`.
+
+Then, the middlwares are registered in the order mentioned earlier, with global middlewares first, then the route middlewares.
+
+### Middlewares and Route Execution Order
+
+When a request is sent to an API route, the global middlewares are executed first, then the route middlewares, and finally the route handler.
+
+For example, consider you have the following middlewares:
+
+```ts title="src/api/middlewares.ts"
+export default defineMiddlewares({
+  routes: [
+    {
+      matcher: "/custom",
+      middlewares: [
+        (req, res, next) => {
+          console.log("Global middleware")
+          next()
+        },
+      ],
+    },
+    {
+      matcher: "/custom",
+      method: ["GET"],
+      middlewares: [
+        (req, res, next) => {
+          console.log("Route middleware")
+          next()
+        },
+      ],
+    },
+  ],
+})
+```
+
+When you send a request to `/custom` route, the following messages are logged in the terminal:
+
+```bash
+Global middleware
+Route middleware
+Hello from custom! # message logged from API route handler
+```
+
+The global middleware runs first, then the route middleware, and finally the route handler, assuming that it logs the message `Hello from custom!`.
+
+***
+
+## Overriding Middlewares
+
+A middleware can not override an existing middleware. Instead, middlewares are added to the end of the middleware stack.
+
+For example, if you define a custom validation middleware, such as `validateAndTransformBody`, on an existing route, then both the original and the custom validation middleware will run.
+
+
+# API Route Parameters
+
+In this chapter, you’ll learn about path, query, and request body parameters.
+
+## Path Parameters
+
+To create an API route that accepts a path parameter, create a directory within the route file's path whose name is of the format `[param]`.
+
+For example, to create an API Route at the path `/hello-world/:id`, where `:id` is a path parameter, create the file `src/api/hello-world/[id]/route.ts` with the following content:
+
+```ts title="src/api/hello-world/[id]/route.ts" highlights={singlePathHighlights}
+import type {
+  MedusaRequest,
+  MedusaResponse,
+} from "@medusajs/framework/http"
+
+export const GET = async (
+  req: MedusaRequest,
+  res: MedusaResponse
+) => {
+  res.json({
+    message: `[GET] Hello ${req.params.id}!`,
+  })
+}
+```
+
+The `MedusaRequest` object has a `params` property. `params` holds the path parameters in key-value pairs.
+
+### Multiple Path Parameters
+
+To create an API route that accepts multiple path parameters, create within the file's path multiple directories whose names are of the format `[param]`.
+
+For example, to create an API route at `/hello-world/:id/name/:name`, create the file `src/api/hello-world/[id]/name/[name]/route.ts` with the following content:
+
+```ts title="src/api/hello-world/[id]/name/[name]/route.ts" highlights={multiplePathHighlights}
+import type {
+  MedusaRequest,
+  MedusaResponse,
+} from "@medusajs/framework/http"
+
+export const GET = async (
+  req: MedusaRequest,
+  res: MedusaResponse
+) => {
+  res.json({
+    message: `[GET] Hello ${
+      req.params.id
+    } - ${req.params.name}!`,
+  })
+}
+```
+
+You access the `id` and `name` path parameters using the `req.params` property.
+
+***
+
+## Query Parameters
+
+You can access all query parameters in the `query` property of the `MedusaRequest` object. `query` is an object of key-value pairs, where the key is a query parameter's name, and the value is its value.
+
+For example:
+
+```ts title="src/api/hello-world/route.ts" highlights={queryHighlights}
+import type {
+  MedusaRequest,
+  MedusaResponse,
+} from "@medusajs/framework/http"
+
+export const GET = async (
+  req: MedusaRequest,
+  res: MedusaResponse
+) => {
+  res.json({
+    message: `Hello ${req.query.name}`,
+  })
+}
+```
+
+The value of `req.query.name` is the value passed in `?name=John`, for example.
+
+### Validate Query Parameters
+
+You can apply validation rules on received query parameters to ensure they match specified rules and types.
+
+Learn more in [this documentation](https://docs.medusajs.com/learn/fundamentals/api-routes/validation#how-to-validate-request-query-paramters/index.html.md).
+
+***
+
+## Request Body Parameters
+
+The Medusa application parses the body of any request having a JSON, URL-encoded, or text request content types. The request body parameters are set in the `MedusaRequest`'s `body` property.
+
+Learn more about configuring body parsing in [this guide](https://docs.medusajs.com/learn/fundamentals/api-routes/parse-body/index.html.md).
+
+For example:
+
+```ts title="src/api/hello-world/route.ts" highlights={bodyHighlights}
+import type {
+  MedusaRequest,
+  MedusaResponse,
+} from "@medusajs/framework/http"
+
+type HelloWorldReq = {
+  name: string
+}
+
+export const POST = async (
+  req: MedusaRequest<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.
+
+## Default Body Parser Configuration
+
+The Medusa application configures the body parser by default to parse JSON, URL-encoded, and text request content types. You can parse other data types by adding the relevant [Express middleware](https://expressjs.com/en/guide/using-middleware.html) or preserve the raw body data by configuring the body parser, which is useful for webhook requests.
+
+This chapter shares some examples of configuring the body parser for different data types or use cases.
+
+***
+
+## Preserve Raw Body Data for Webhooks
+
+If your API route receives webhook requests, you might want to preserve the raw body data. To do this, you can configure the body parser to parse the raw body data and store it in the `req.rawBody` property.
+
+To do that, create the file `src/api/middlewares.ts` with the following content:
+
+```ts title="src/api/middlewares.ts" highlights={preserveHighlights}
+import { defineMiddlewares } from "@medusajs/framework/http"
+
+export default defineMiddlewares({
+  routes: [
+    {
+      method: ["POST"],
+      bodyParser: { preserveRawBody: true },
+      matcher: "/custom",
+    },
+  ],
+})
+```
+
+The middleware route object passed to `routes` accepts a `bodyParser` property whose value is an object of configuration for the default body parser. By enabling the `preserveRawBody` property, the raw body data is preserved and stored in the `req.rawBody` property.
+
+Learn more about [middlewares](https://docs.medusajs.com/learn/fundamentals/api-routes/middlewares/index.html.md).
+
+You can then access the raw body data in your API route handler:
+
+```ts title="src/api/custom/route.ts"
+import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
+
+export async function POST(
+  req: MedusaRequest,
+  res: MedusaResponse
+) {
+  console.log(req.rawBody)
+
+  // TODO use raw body
+}
+```
+
+***
+
+## Configure Request Body Size Limit
+
+By default, the body parser limits the request body size to `100kb`. If a request body exceeds that size, the Medusa application throws an error.
+
+You can configure the body parser to accept larger request bodies by setting the `sizeLimit` property of the `bodyParser` object in a middleware route object. For example:
+
+```ts title="src/api/middlewares.ts" highlights={sizeLimitHighlights}
+import { defineMiddlewares } from "@medusajs/framework/http"
+
+export default defineMiddlewares({
+  routes: [
+    {
+      method: ["POST"],
+      bodyParser: { sizeLimit: "2mb" },
+      matcher: "/custom",
+    },
+  ],
+})
+```
+
+The `sizeLimit` property accepts one of the following types of values:
+
+- A string representing the size limit in bytes (For example, `100kb`, `2mb`, `5gb`). It is passed to the [bytes](https://www.npmjs.com/package/bytes) library to parse the size.
+- A number representing the size limit in bytes. For example, `1024` for 1kb.
+
+***
+
+## Configure File Uploads
+
+To accept file uploads in your API routes, you can configure the [Express Multer middleware](https://expressjs.com/en/resources/middleware/multer.html) on your route.
+
+The `multer` package is available through the `@medusajs/medusa` package, so you don't need to install it. However, for better typing support, install the `@types/multer` package as a development dependency:
+
+```bash npm2yarn
+npm install --save-dev @types/multer
+```
+
+Then, to configure file upload for your route, create the file `src/api/middlewares.ts` with the following content:
+
+```ts title="src/api/middlewares.ts" highlights={uploadHighlights}
+import { defineMiddlewares } from "@medusajs/framework/http"
+import multer from "multer"
+
+const upload = multer({ storage: multer.memoryStorage() })
+
+export default defineMiddlewares({
+  routes: [
+    {
+      method: ["POST"],
+      matcher: "/custom",
+      middlewares: [
+        // @ts-ignore
+        upload.array("files"),
+      ],
+    },
+  ],
+})
+```
+
+In the example above, you configure the `multer` middleware to store the uploaded files in memory. Then, you apply the `upload.array("files")` middleware to the route to accept file uploads. By using the `array` method, you accept multiple file uploads with the same `files` field name.
+
+You can then access the uploaded files in your API route handler:
+
+```ts title="src/api/custom/route.ts"
+import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
+
+export async function POST(
+  req: MedusaRequest,
+  res: MedusaResponse
+) {
+  const files = req.files as Express.Multer.File[]
+
+  // TODO handle files
+}
+```
+
+The uploaded files are stored in the `req.files` property as an array of Multer file objects that have properties like `filename` and `mimetype`.
+
+### Uploading Files using File Module Provider
+
+The recommended way to upload the files to storage using the configured [File Module Provider](https://docs.medusajs.com/resources/infrastructure-modules/file/index.html.md) is to use the [uploadFilesWorkflow](https://docs.medusajs.com/resources/references/medusa-workflows/uploadFilesWorkflow/index.html.md):
+
+```ts title="src/api/custom/route.ts"
+import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
+import { MedusaError } from "@medusajs/framework/utils"
+import { uploadFilesWorkflow } from "@medusajs/medusa/core-flows"
+
+export async function POST(
+  req: MedusaRequest,
+  res: MedusaResponse
+) {
+  const files = req.files as Express.Multer.File[]
+
+  if (!files?.length) {
+    throw new MedusaError(
+      MedusaError.Types.INVALID_DATA,
+      "No files were uploaded"
+    )
+  }
+
+  const { result } = await uploadFilesWorkflow(req.scope).run({
+    input: {
+      files: files?.map((f) => ({
+        filename: f.originalname,
+        mimeType: f.mimetype,
+        content: f.buffer.toString("binary"),
+        access: "public",
+      })),
+    },
+  })
+
+  res.status(200).json({ files: result })
+}
+```
+
+Check out the [uploadFilesWorkflow reference](https://docs.medusajs.com/resources/references/medusa-workflows/uploadFilesWorkflow/index.html.md) for details on the expected input and output of the workflow.
+
+
+# Protected Routes
+
+In this chapter, you’ll learn how to create protected routes.
+
+## What is a Protected Route?
+
+A protected route is a route that requires requests to be user-authenticated before performing the route's functionality. Otherwise, the request fails, and the user is prevented access.
+
+***
+
+## Default Protected Routes
+
+Medusa applies an authentication guard on routes starting with `/admin`, including custom API routes.
+
+Requests to `/admin` must be user-authenticated to access the route.
+
+Refer to the API Reference for [Admin](https://docs.medusajs.com/api/admin#authentication) and [Store](https://docs.medusajs.com/api/store#authentication) authentication methods.
+
+***
+
+## Protect Custom API Routes
+
+To protect custom API Routes to only allow authenticated customer or admin users, use the `authenticate` middleware from the Medusa Framework.
+
+For example:
+
+```ts title="src/api/middlewares.ts" highlights={highlights}
+import { 
+  defineMiddlewares,
+  authenticate,
+} from "@medusajs/framework/http"
+
+export default defineMiddlewares({
+  routes: [
+    {
+      matcher: "/custom/admin*",
+      middlewares: [authenticate("user", ["session", "bearer", "api-key"])],
+    },
+    {
+      matcher: "/custom/customer*",
+      middlewares: [authenticate("customer", ["session", "bearer"])],
+    },
+  ],
+})
+```
+
+The `authenticate` middleware function accepts three parameters:
+
+1. The type of user authenticating. Use `user` for authenticating admin users, and `customer` for authenticating customers. You can also pass `*` to allow all types of users, or pass an array of actor types.
+2. An array of types of authentication methods allowed. Both `user` and `customer` scopes support `session` and `bearer`. The `admin` scope also supports the `api-key` authentication method.
+3. An optional object of configurations accepting the following properties:
+   - `allowUnauthenticated`: (default: `false`) A boolean indicating whether authentication is required. For example, you may have an API route where you want to access the logged-in customer if available, but guest customers can still access it too.
+   - `allowUnregistered` (default: `false`): A boolean indicating if unregistered users should be allowed access. This is useful when you want to allow users who aren’t registered to access certain routes.
+
+### Example: Custom Actor Type
+
+For example, to require authentication of a custom actor type `manager` to an API route:
+
+```ts title="src/api/middlewares.ts"
+import { 
+  defineMiddlewares,
+  authenticate,
+} from "@medusajs/framework/http"
+
+export default defineMiddlewares({
+  routes: [
+    {
+      matcher: "/manager*",
+      middlewares: [authenticate("manager", ["session", "bearer"])],
+    },
+  ],
+})
+```
+
+Refer to the [Custom Actor-Type Guide](https://docs.medusajs.com/resources/commerce-modules/auth/create-actor-type/index.html.md) for detailed explanation on how to create a custom actor type and apply authentication middlewares.
+
+### Example: Allow Multiple Actor Types
+
+To allow multiple actor types to access an API route, pass an array of actor types to the `authenticate` middleware:
+
+```ts title="src/api/middlewares.ts"
+import { 
+  defineMiddlewares,
+  authenticate,
+} from "@medusajs/framework/http"
+
+export default defineMiddlewares({
+  routes: [
+    {
+      matcher: "/custom*",
+      middlewares: [authenticate(["user", "customer"], ["session", "bearer"])],
+    },
+  ],
+})
+```
+
+***
+
+## Authentication Opt-Out
+
+To disable the authentication guard on custom routes under the `/admin` path prefix, export an `AUTHENTICATE` variable in the route file with its value set to `false`.
+
+For example:
+
+```ts title="src/api/admin/custom/route.ts" highlights={[["15"]]}
+import type { 
+  AuthenticatedMedusaRequest, 
+  MedusaResponse,
+} from "@medusajs/framework/http"
+
+export const GET = async (
+  req: AuthenticatedMedusaRequest, 
+  res: MedusaResponse
+) => {
+  res.json({
+    message: "Hello",
+  })
+}
+
+export const AUTHENTICATE = false
+```
+
+Now, any request sent to the `/admin/custom` API route is allowed, regardless if the admin user is authenticated.
+
+***
+
+## Authenticated Request Type
+
+To access the authentication details in an API route, such as the logged-in user's ID, set the type of the first request parameter to `AuthenticatedMedusaRequest`. It extends `MedusaRequest`.
+
+The `auth_context.actor_id` property of `AuthenticatedMedusaRequest` holds the ID of the authenticated user or customer. If there isn't any authenticated user or customer, `auth_context` is `undefined`.
+
+If you opt-out of authentication in a route as mentioned in the [previous section](#authentication-opt-out), you can't access the authenticated user or customer anymore. Use the [authenticate middleware](#protect-custom-api-routes) instead.
+
+### Retrieve Logged-In Customer's Details
+
+You can access the logged-in customer’s ID in all API routes starting with `/store` using the `auth_context.actor_id` property of the `AuthenticatedMedusaRequest` object.
+
+For example:
+
+```ts title="src/api/store/custom/route.ts" highlights={[["19", "req.auth_context.actor_id", "Access the logged-in customer's ID."]]} collapsibleLines="1-7" expandButtonLabel="Show Imports"
+import type {
+  AuthenticatedMedusaRequest,
+  MedusaResponse,
+} from "@medusajs/framework/http"
+import { Modules } from "@medusajs/framework/utils"
+import { ICustomerModuleService } from "@medusajs/framework/types"
+
+export const GET = async (
+  req: AuthenticatedMedusaRequest,
+  res: MedusaResponse
+) => {
+  if (req.auth_context?.actor_id) {
+    // retrieve customer
+    const customerModuleService: ICustomerModuleService = req.scope.resolve(
+      Modules.CUSTOMER
+    )
+
+    const customer = await customerModuleService.retrieveCustomer(
+      req.auth_context.actor_id
+    )
+  }
+
+  // ...
+}
+```
+
+In this example, you resolve the Customer Module's main service, then use it to retrieve the logged-in customer, if available.
+
+### Retrieve Logged-In Admin User's Details
+
+You can access the logged-in admin user’s ID in all API Routes starting with `/admin` using the `auth_context.actor_id` property of the `AuthenticatedMedusaRequest` object.
+
+For example:
+
+```ts title="src/api/admin/custom/route.ts" highlights={[["17", "req.auth_context.actor_id", "Access the logged-in admin user's ID."]]} collapsibleLines="1-7" expandButtonLabel="Show Imports"
+import type {
+  AuthenticatedMedusaRequest,
+  MedusaResponse,
+} from "@medusajs/framework/http"
+import { Modules } from "@medusajs/framework/utils"
+import { IUserModuleService } from "@medusajs/framework/types"
+
+export const GET = async (
+  req: AuthenticatedMedusaRequest,
+  res: MedusaResponse
+) => {
+  const userModuleService: IUserModuleService = req.scope.resolve(
+    Modules.USER
+  )
+
+  const user = await userModuleService.retrieveUser(
+    req.auth_context.actor_id
+  )
+
+  // ...
+}
+```
+
+In the route handler, you resolve the User Module's main service, then use it to retrieve the logged-in admin user.
+
+
+# API Route Response
+
+In this chapter, you'll learn how to send a response in your API route.
+
+## Send a JSON Response
+
+To send a JSON response, use the `json` method of the `MedusaResponse` object passed as the second parameter of your API route handler.
+
+For example:
+
+```ts title="src/api/custom/route.ts" highlights={jsonHighlights}
+import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
+
+export const GET = async (
+  req: MedusaRequest,
+  res: MedusaResponse
+) => {
+  res.json({
+    message: "Hello, World!",
+  })
+}
+```
+
+This API route returns the following JSON object:
+
+```json
+{
+  "message": "Hello, World!"
+}
+```
+
+***
+
+## Set Response Status Code
+
+By default, setting the JSON data using the `json` method returns a response with a `200` status code.
+
+To change the status code, use the `status` method of the `MedusaResponse` object.
+
+For example:
+
+```ts title="src/api/custom/route.ts" highlights={statusHighlight}
+import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
+
+export const GET = async (
+  req: MedusaRequest,
+  res: MedusaResponse
+) => {
+  res.status(201).json({
+    message: "Hello, World!",
+  })
+}
+```
+
+The response of this API route has the status code `201`.
+
+***
+
+## Change Response Content Type
+
+To return response data other than a JSON object, use the `writeHead` method of the `MedusaResponse` object. It allows you to set the response headers, including the content type.
+
+For example, to create an API route that returns an event stream:
+
+```ts highlights={streamHighlights}
+import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
+
+export const GET = async (
+  req: MedusaRequest,
+  res: MedusaResponse
+) => {
+  res.writeHead(200, {
+    "Content-Type": "text/event-stream",
+    "Cache-Control": "no-cache",
+    Connection: "keep-alive",
+  })
+
+  const interval = setInterval(() => {
+    res.write("Streaming data...\n")
+  }, 3000)
+
+  req.on("end", () => {
+    clearInterval(interval)
+    res.end()
+  })
+}
+```
+
+The `writeHead` method accepts two parameters:
+
+1. The first one is the response's status code.
+2. The second is an object of key-value pairs to set the headers of the response.
+
+This API route opens a stream by setting the `Content-Type` in the header to `text/event-stream`. It then simulates a stream by creating an interval that writes the stream data every three seconds.
+
+***
+
+## Do More with Responses
+
+The `MedusaResponse` type is based on [Express's Response](https://expressjs.com/en/api.html#res). Refer to their API reference for other uses of responses.
+
+
+# Retrieve Custom Links from Medusa's API Route
+
+In this chapter, you'll learn how to retrieve custom data models linked to existing Medusa data models from Medusa's API routes.
+
+## Why Retrieve Custom Linked Data Models?
+
+Often, you'll link custom data models to existing Medusa data models to implement custom features or expand on existing ones.
+
+For example, to add brands for products, you can create a `Brand` data model in a Brand Module, then [define a link](https://docs.medusajs.com/learn/fundamentals/module-links/index.html.md) to the [Product Module](https://docs.medusajs.com/resources/commerce-modules/product/index.html.md)'s `Product` data model.
+
+When you implement this customization, you might need to retrieve the brand of a product using the existing [Get Product API Route](https://docs.medusajs.com/api/admin#products_getproductsid). You can do this by passing the linked data model's name in the `fields` query parameter of the API route.
+
+***
+
+## How to Retrieve Custom Linked Data Models Using `fields`?
+
+Most of Medusa's API routes accept a `fields` query parameter that allows you to specify the fields and relations to retrieve in the resource, such as a product.
+
+For example, to retrieve the brand of a product, you can pass the `brand` field in the `fields` query parameter of the [Get Product API Route](https://docs.medusajs.com/api/admin#products_getproductsid):
+
+```bash
+curl 'http://localhost:9000/admin/products/{id}?fields=*brand' \
+-H 'Authorization: Bearer {access_token}'
+```
+
+The `fields` query parameter accepts a comma-separated list of fields and relations to retrieve. To learn more about using the `fields` query parameter, refer to the [API Reference](https://docs.medusajs.com/api/store#select-fields-and-relations).
+
+By prefixing `brand` with an asterisk (`*`), you retrieve all the default fields of the product, including the `brand` field. If you don't include the `*` prefix, the response will only include the product's brand.
+
+***
+
+## API Routes that Restrict Retrievable Fields
+
+Some of Medusa's API routes restrict the fields and relations you can retrieve, which means you can't pass your custom linked data models in the `fields` query parameter. Medusa makes this restriction to ensure the API routes are performant and secure.
+
+The API routes that restrict the fields and relations you can retrieve are:
+
+- [Customer Store API Routes](https://docs.medusajs.com/api/store#customers)
+- [Customer Admin API Routes](https://docs.medusajs.com/api/admin#customers)
+- [Product Category Admin API Routes](https://docs.medusajs.com/api/admin#product-categories)
+
+### How to Override Allowed Fields and Relations
+
+For these routes, you need to override the allowed fields and relations to be retrieved. You can do this by adding a [middleware](https://docs.medusajs.com/learn/fundamentals/api-routes/middlewares/index.html.md) to those routes.
+
+For example, to allow retrieving the `b2b_company` of a customer using the [Get Customer Admin API Route](https://docs.medusajs.com/api/admin#customers_getcustomersid), create the file `src/api/middlewares.ts` with the following content:
+
+Learn how to create a middleware in the [Middlewares](https://docs.medusajs.com/learn/fundamentals/api-routes/middlewares/index.html.md) chapter.
+
+```ts title="src/api/middlewares.ts" highlights={highlights}
+import { defineMiddlewares } from "@medusajs/medusa";
+
+export default defineMiddlewares({
+  routes: [
+    {
+      matcher: "/store/customers/me",
+      method: "GET",
+      middlewares: [
+        (req, res, next) => {
+          req.allowed?.push("b2b_company");
+          next();
+        },
+      ],
+    },
+  ],
+});
+```
+
+In this example, you apply a middleware to the [Get Customer Admin API Route](https://docs.medusajs.com/api/admin#customers_getcustomersid).
+
+The request object passed to middlewares has an `allowed` property that contains the fields and relations that can be retrieved. So, you modify the `allowed` array to include the `b2b_company` field.
+
+You can now retrieve the `b2b_company` field using the `fields` query parameter of the [Get Customer Admin API Route](https://docs.medusajs.com/api/admin#customers_getcustomersid):
+
+```bash
+curl 'http://localhost:9000/admin/customers/{id}?fields=*b2b_company' \
+-H 'Authorization: Bearer {access_token}'
+```
+
+In this example, you retrieve the `b2b_company` relation of the customer using the `fields` query parameter.
+
+
+# Request Body and Query Parameter Validation
+
+In this chapter, you'll learn how to validate request body and query parameters in your custom API route.
+
+## Request Validation
+
+Consider you're creating a `POST` API route at `/custom`. It accepts two parameters `a` and `b` that are required numbers, and returns their sum.
+
+Medusa provides two middlewares to validate the request body and query paramters of incoming requests to your custom API routes:
+
+- `validateAndTransformBody` to validate the request's body parameters against a schema.
+- `validateAndTransformQuery` to validate the request's query parameters against a schema.
+
+Both middlewares accept a [Zod](https://zod.dev/) schema as a parameter, which gives you flexibility in how you define your validation schema with complex rules.
+
+The next steps explain how to add request body and query parameter validation to the API route mentioned earlier.
+
+***
+
+## How to Validate Request Body
+
+### Step 1: Create Validation Schema
+
+Medusa uses [Zod](https://zod.dev/) to create validation schemas. These schemas are then used to validate incoming request bodies or query parameters.
+
+To create a validation schema with Zod, create a `validators.ts` file in any `src/api` subfolder. This file holds Zod schemas for each of your API routes.
+
+For example, create the file `src/api/custom/validators.ts` with the following content:
+
+```ts title="src/api/custom/validators.ts"
+import { z } from "zod"
+
+export const PostStoreCustomSchema = z.object({
+  a: z.number(),
+  b: z.number(),
+})
+```
+
+The `PostStoreCustomSchema` variable is a Zod schema that indicates the request body is valid if:
+
+1. It's an object.
+2. It has a property `a` that is a required number.
+3. It has a property `b` that is a required number.
+
+### Step 2: Add Request Body Validation Middleware
+
+To use this schema for validating the body parameters of requests to `/custom`, use the `validateAndTransformBody` middleware provided by `@medusajs/framework/http`. It accepts the Zod schema as a parameter.
+
+For example, create the file `src/api/middlewares.ts` with the following content:
+
+```ts title="src/api/middlewares.ts"
+import { 
+  defineMiddlewares,
+  validateAndTransformBody,
+} from "@medusajs/framework/http"
+import { PostStoreCustomSchema } from "./custom/validators"
+
+export default defineMiddlewares({
+  routes: [
+    {
+      matcher: "/custom",
+      method: "POST",
+      middlewares: [
+        validateAndTransformBody(PostStoreCustomSchema),
+      ],
+    },
+  ],
+})
+```
+
+This applies the `validateAndTransformBody` middleware on `POST` requests to `/custom`. It uses the `PostStoreCustomSchema` as the validation schema.
+
+#### How the Validation Works
+
+If a request's body parameters don't pass the validation, the `validateAndTransformBody` middleware throws an error indicating the validation errors.
+
+If a request's body parameters are validated successfully, the middleware sets the validated body parameters in the `validatedBody` property of `MedusaRequest`.
+
+### Step 3: Use Validated Body in API Route
+
+In your API route, consume the validated body using the `validatedBody` property of `MedusaRequest`.
+
+For example, create the file `src/api/custom/route.ts` with the following content:
+
+```ts title="src/api/custom/route.ts" highlights={routeHighlights}
+import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
+import { z } from "zod"
+import { PostStoreCustomSchema } from "./validators"
+
+type PostStoreCustomSchemaType = z.infer<
+  typeof PostStoreCustomSchema
+>
+
+export const POST = async (
+  req: MedusaRequest<PostStoreCustomSchemaType>,
+  res: MedusaResponse
+) => {
+  res.json({
+    sum: req.validatedBody.a + req.validatedBody.b,
+  })
+}
+```
+
+In the API route, you use the `validatedBody` property of `MedusaRequest` to access the values of the `a` and `b` properties.
+
+To pass the request body's type as a type parameter to `MedusaRequest`, use Zod's `infer` type that accepts the type of a schema as a parameter.
+
+### Test it Out
+
+To test out the validation, send a `POST` request to `/custom` passing `a` and `b` body parameters. You can try sending incorrect request body parameters to test out the validation.
+
+For example, if you omit the `a` parameter, you'll receive a `400` response code with the following response data:
+
+```json
+{
+  "type": "invalid_data",
+  "message": "Invalid request: Field 'a' is required"
+}
+```
+
+***
+
+## How to Validate Request Query Parameters
+
+The steps to validate the request query parameters are the similar to that of [validating the body](#how-to-validate-request-body).
+
+### Step 1: Create Validation Schema
+
+The first step is to create a schema with Zod with the rules of the accepted query parameters.
+
+Consider that the API route accepts two query parameters `a` and `b` that are numbers, similar to the previous section.
+
+Create the file `src/api/custom/validators.ts` with the following content:
+
+```ts title="src/api/custom/validators.ts"
+import { z } from "zod"
+
+export const PostStoreCustomSchema = z.object({
+  a: z.preprocess(
+      (val) => {
+        if (val && typeof val === "string") {
+          return parseInt(val)
+        }
+        return val
+      },
+      z
+        .number()
+    ),
+  b: z.preprocess(
+    (val) => {
+      if (val && typeof val === "string") {
+        return parseInt(val)
+      }
+      return val
+    },
+    z
+      .number()
+  ),
+})
+```
+
+Since a query parameter's type is originally a string or array of strings, you have to use Zod's `preprocess` method to validate other query types, such as numbers.
+
+For both `a` and `b`, you transform the query parameter's value to an integer first if it's a string, then, you check that the resulting value is a number.
+
+### Step 2: Add Request Query Validation Middleware
+
+Next, you'll use the schema to validate incoming requests' query parameters to the `/custom` API route.
+
+Add the `validateAndTransformQuery` middleware to the API route in the file `src/api/middlewares.ts`:
+
+```ts title="src/api/middlewares.ts"
+import { 
+  validateAndTransformQuery,
+  defineMiddlewares,
+} from "@medusajs/framework/http"
+import { PostStoreCustomSchema } from "./custom/validators"
+
+export default defineMiddlewares({
+  routes: [
+    {
+      matcher: "/custom",
+      method: "POST",
+      middlewares: [
+        validateAndTransformQuery(
+          PostStoreCustomSchema,
+          {}
+        ),
+      ],
+    },
+  ],
+})
+```
+
+The `validateAndTransformQuery` accepts two parameters:
+
+- The first one is the Zod schema to validate the query parameters against.
+- The second one is an object of options for retrieving data using Query, which you can learn more about in [this chapter](https://docs.medusajs.com/learn/fundamentals/module-links/query/index.html.md).
+
+#### How the Validation Works
+
+If a request's query parameters don't pass the validation, the `validateAndTransformQuery` middleware throws an error indicating the validation errors.
+
+If a request's query parameters are validated successfully, the middleware sets the validated query parameters in the `validatedQuery` property of `MedusaRequest`.
+
+### Step 3: Use Validated Query in API Route
+
+Finally, use the validated query in the API route. The `MedusaRequest` parameter has a `validatedQuery` parameter that you can use to access the validated parameters.
+
+For example, create the file `src/api/custom/route.ts` with the following content:
+
+```ts title="src/api/custom/route.ts"
+import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
+
+export const GET = async (
+  req: MedusaRequest,
+  res: MedusaResponse
+) => {
+  const a = req.validatedQuery.a as number
+  const b = req.validatedQuery.b as number
+
+  res.json({
+    sum: a + b,
+  })
+}
+```
+
+In the API route, you use the `validatedQuery` property of `MedusaRequest` to access the values of the `a` and `b` properties as numbers, then return in the response their sum.
+
+### Test it Out
+
+To test out the validation, send a `POST` request to `/custom` with `a` and `b` query parameters. You can try sending incorrect query parameters to see how the validation works.
+
+For example, if you omit the `a` parameter, you'll receive a `400` response code with the following response data:
+
+```json
+{
+  "type": "invalid_data",
+  "message": "Invalid request: Field 'a' is required"
+}
+```
+
+***
+
+## Learn More About Validation Schemas
+
+To see different examples and learn more about creating a validation schema, refer to [Zod's documentation](https://zod.dev).
+
+
+# Throwing and Handling Errors
+
+In this guide, you'll learn how to throw errors in your Medusa application, how it affects an API route's response, and how to change the default error handler of your Medusa application.
+
+## Throw MedusaError
+
+When throwing an error in your API routes, middlewares, workflows, or any customization, throw a `MedusaError` from the Medusa Framework.
+
+The Medusa application's API route error handler then wraps your thrown error in a uniform object and returns it in the response.
+
+For example:
+
+```ts
+import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
+import { MedusaError } from "@medusajs/framework/utils"
+
+export const GET = async (
+  req: MedusaRequest,
+  res: MedusaResponse
+) => {
+  if (!req.query.q) {
+    throw new MedusaError(
+      MedusaError.Types.INVALID_DATA,
+      "The `q` query parameter is required."
+    )
+  }
+
+  // ...
+}
+```
+
+The `MedusaError` class accepts in its constructor two parameters:
+
+1. The first is the error's type. `MedusaError` has a static property `Types` that you can use. `Types` is an enum whose possible values are explained in the next section.
+2. The second is the message to show in the error response.
+
+### Error Object in Response
+
+The error object returned in the response has two properties:
+
+- `type`: The error's type.
+- `message`: The error message, if available.
+- `code`: A common snake-case code. Its values can be:
+  - `invalid_request_error` for the `DUPLICATE_ERROR` type.
+  - `api_error`:  for the `DB_ERROR` type.
+  - `invalid_state_error` for `CONFLICT` error type.
+  - `unknown_error` for any unidentified error type.
+  - For other error types, this property won't be available unless you provide a code as a third parameter to the `MedusaError` constructor.
+
+### MedusaError Types
+
+|Type|Description|Status Code|
+|---|---|---|---|---|
+|\`DB\_ERROR\`|Indicates a database error.|\`500\`|
+|\`DUPLICATE\_ERROR\`|Indicates a duplicate of a record already exists. For example, when trying to create a customer whose email is registered by another customer.|\`422\`|
+|\`INVALID\_ARGUMENT\`|Indicates an error that occurred due to incorrect arguments or other unexpected state.|\`500\`|
+|\`INVALID\_DATA\`|Indicates a validation error.|\`400\`|
+|\`UNAUTHORIZED\`|Indicates that a user is not authorized to perform an action or access a route.|\`401\`|
+|\`NOT\_FOUND\`|Indicates that the requested resource, such as a route or a record, isn't found.|\`404\`|
+|\`NOT\_ALLOWED\`|Indicates that an operation isn't allowed.|\`400\`|
+|\`CONFLICT\`|Indicates that a request conflicts with another previous or ongoing request. The error message in this case is ignored for a default message.|\`409\`|
+|\`PAYMENT\_AUTHORIZATION\_ERROR\`|Indicates an error has occurred while authorizing a payment.|\`422\`|
+|Other error types|Any other error type results in an |\`500\`|
+
+***
+
+## Override Error Handler
+
+The `defineMiddlewares` function used to apply middlewares on routes accepts an `errorHandler` in its object parameter. Use it to override the default error handler for API routes.
+
+This error handler will also be used for errors thrown in Medusa's API routes and resources.
+
+For example, create `src/api/middlewares.ts` with the following:
+
+```ts title="src/api/middlewares.ts" collapsibleLines="1-8" expandMoreLabel="Show Imports"
+import { 
+  defineMiddlewares, 
+  MedusaNextFunction, 
+  MedusaRequest, 
+  MedusaResponse,
+} from "@medusajs/framework/http"
+import { MedusaError } from "@medusajs/framework/utils"
+
+export default defineMiddlewares({
+  errorHandler: (
+    error: MedusaError | any, 
+    req: MedusaRequest, 
+    res: MedusaResponse, 
+    next: MedusaNextFunction
+  ) => {
+    res.status(400).json({
+      error: "Something happened.",
+    })
+  },
+})
+```
+
+The `errorHandler` property's value is a function that accepts four parameters:
+
+1. The error thrown. Its type can be `MedusaError` or any other thrown error type.
+2. A request object of type `MedusaRequest`.
+3. A response object of type `MedusaResponse`.
+4. A function of type MedusaNextFunction that executes the next middleware in the stack.
+
+This example overrides Medusa's default error handler with a handler that always returns a `400` status code with the same message.
 
 
 # Data Model Database Index
@@ -8055,6 +9944,78 @@ export default MyCustom
 This creates a unique composite index on the `name` and `age` properties.
 
 
+# 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.
@@ -8095,519 +10056,6 @@ class BlogModuleService extends MedusaService({ Post }) {
 ```
 
 
-# Manage Relationships
-
-In this chapter, you'll learn how to manage relationships between data models when creating, updating, or retrieving records using the module's main service.
-
-## Manage One-to-One Relationship
-
-### BelongsTo Side of One-to-One
-
-When you create a record of a data model that belongs to another through a one-to-one relation, pass the ID of the other data model's record in the `{relation}_id` property, where `{relation}` is the name of the relation property.
-
-For example, assuming you have the [User and Email data models from the previous chapter](https://docs.medusajs.com/learn/fundamentals/data-models/relationships#one-to-one-relationship/index.html.md), set an email's user ID as follows:
-
-```ts highlights={belongsHighlights}
-// when creating an email
-const email = await helloModuleService.createEmails({
-  // other properties...
-  user_id: "123",
-})
-
-// when updating an email
-const email = await helloModuleService.updateEmails({
-  id: "321",
-  // other properties...
-  user_id: "123",
-})
-```
-
-In the example above, you pass the `user_id` property when creating or updating an email to specify the user it belongs to.
-
-### HasOne Side
-
-When you create a record of a data model that has one of another, pass the ID of the other data model's record in the relation property.
-
-For example, assuming you have the [User and Email data models from the previous chapter](https://docs.medusajs.com/learn/fundamentals/data-models/relationships#one-to-one-relationship/index.html.md), set a user's email ID as follows:
-
-```ts highlights={hasOneHighlights}
-// when creating a user
-const user = await helloModuleService.createUsers({
-  // other properties...
-  email: "123",
-})
-
-// when updating a user
-const user = await helloModuleService.updateUsers({
-  id: "321",
-  // other properties...
-  email: "123",
-})
-```
-
-In the example above, you pass the `email` property when creating or updating a user to specify the email it has.
-
-***
-
-## Manage One-to-Many Relationship
-
-In a one-to-many relationship, you can only manage the associations from the `belongsTo` side.
-
-When you create a record of the data model on the `belongsTo` side, pass the ID of the other data model's record in the `{relation}_id` property, where `{relation}` is the name of the relation property.
-
-For example, assuming you have the [Product and Store data models from the previous chapter](https://docs.medusajs.com/learn/fundamentals/data-models/relationships#one-to-many-relationship/index.html.md), set a product's store ID as follows:
-
-```ts highlights={manyBelongsHighlights}
-// when creating a product
-const product = await helloModuleService.createProducts({
-  // other properties...
-  store_id: "123",
-})
-
-// when updating a product
-const product = await helloModuleService.updateProducts({
-  id: "321",
-  // other properties...
-  store_id: "123",
-})
-```
-
-In the example above, you pass the `store_id` property when creating or updating a product to specify the store it belongs to.
-
-***
-
-## Manage Many-to-Many Relationship
-
-If your many-to-many relation is represented with a [pivotEntity](https://docs.medusajs.com/learn/fundamentals/data-models/relationships#many-to-many-with-custom-columns/index.html.md), refer to [this section](#manage-many-to-many-relationship-with-pivotentity) instead.
-
-### Create Associations
-
-When you create a record of a data model that has a many-to-many relationship to another data model, pass an array of IDs of the other data model's records in the relation property.
-
-For example, assuming you have the [Order and Product data models from the previous chapter](https://docs.medusajs.com/learn/fundamentals/data-models/relationships#many-to-many-relationship/index.html.md), set the association between products and orders as follows:
-
-```ts highlights={manyHighlights}
-// when creating a product
-const product = await helloModuleService.createProducts({
-  // other properties...
-  orders: ["123", "321"],
-})
-
-// when creating an order
-const order = await helloModuleService.createOrders({
-  id: "321",
-  // other properties...
-  products: ["123", "321"],
-})
-```
-
-In the example above, you pass the `orders` property when you create a product, and you pass the `products` property when you create an order.
-
-### Update Associations
-
-When you use the `update` methods generated by the service factory, you also pass an array of IDs as the relation property's value to add new associated records.
-
-However, this removes any existing associations to records whose IDs aren't included in the array.
-
-For example, assuming you have the [Order and Product data models from the previous chapter](https://docs.medusajs.com/learn/fundamentals/data-models/relationships#many-to-many-relationship/index.html.md), you update the product's related orders as so:
-
-```ts
-const product = await helloModuleService.updateProducts({
-  id: "123",
-  // other properties...
-  orders: ["321"],
-})
-```
-
-If the product was associated with an order, and you don't include that order's ID in the `orders` array, the association between the product and order is removed.
-
-So, to add a new association without removing existing ones, retrieve the product first to pass its associated orders when updating the product:
-
-```ts highlights={updateAssociationHighlights}
-const product = await helloModuleService.retrieveProduct(
-  "123",
-  {
-    relations: ["orders"],
-  }
-)
-
-const updatedProduct = await helloModuleService.updateProducts({
-  id: product.id,
-  // other properties...
-  orders: [
-    ...product.orders.map((order) => order.id),
-    "321",
-  ],
-})
-```
-
-This keeps existing associations between the product and orders, and adds a new one.
-
-***
-
-## Manage Many-to-Many Relationship with pivotEntity
-
-If your many-to-many relation is represented without a [pivotEntity](https://docs.medusajs.com/learn/fundamentals/data-models/relationships#many-to-many-with-custom-columns/index.html.md), refer to [this section](#manage-many-to-many-relationship) instead.
-
-If you have a many-to-many relation with a `pivotEntity` specified, make sure to pass the data model representing the pivot table to [MedusaService](https://docs.medusajs.com/learn/fundamentals/modules/service-factory/index.html.md) that your module's service extends.
-
-For example, assuming you have the [Order, Product, and OrderProduct models from the previous chapter](https://docs.medusajs.com/learn/fundamentals/data-models/relationships#many-to-many-with-custom-columns/index.html.md), add `OrderProduct` to `MedusaService`'s object parameter:
-
-```ts highlights={["4"]}
-class BlogModuleService extends MedusaService({
-  Order,
-  Product,
-  OrderProduct,
-}) {}
-```
-
-This will generate Create, Read, Update and Delete (CRUD) methods for the `OrderProduct` data model, which you can use to create relations between orders and products and manage the extra columns in the pivot table.
-
-For example:
-
-```ts
-// create order-product association
-const orderProduct = await blogModuleService.createOrderProducts({
-  order_id: "123",
-  product_id: "123",
-  metadata: {
-    test: true,
-  },
-})
-
-// update order-product association
-const orderProduct = await blogModuleService.updateOrderProducts({
-  id: "123",
-  metadata: {
-    test: false,
-  },
-})
-
-// delete order-product association
-await blogModuleService.deleteOrderProducts("123")
-```
-
-Since the `OrderProduct` data model belongs to the `Order` and `Product` data models, you can set its order and product as explained in the [one-to-many relationship section](#manage-one-to-many-relationship) using `order_id` and `product_id`.
-
-Refer to the [service factory reference](https://docs.medusajs.com/resources/service-factory-reference/index.html.md) for a full list of generated methods and their usages.
-
-***
-
-## Retrieve Records of Relation
-
-The `list`, `listAndCount`, and `retrieve` methods of a module's main service accept as a second parameter an object of options.
-
-To retrieve the records associated with a data model's records through a relationship, pass in the second parameter object a `relations` property whose value is an array of relationship names.
-
-For example, assuming you have the [Order and Product data models from the previous chapter](https://docs.medusajs.com/learn/fundamentals/data-models/relationships#many-to-many-relationship/index.html.md), you retrieve a product's orders as follows:
-
-```ts highlights={retrieveHighlights}
-const product = await blogModuleService.retrieveProducts(
-  "123",
-  {
-    relations: ["orders"],
-  }
-)
-```
-
-In the example above, the retrieved product has an `orders` property, whose value is an array of orders associated with the product.
-
-
-# Data Model Relationships
-
-In this chapter, you’ll learn how to define relationships between data models in your module.
-
-## What is a Relationship Property?
-
-A relationship property defines an association in the database between two models. It's created using the Data Model Language (DML) methods, such as `hasOne` or `belongsTo`.
-
-When you generate a migration for these data models, the migrations include foreign key columns or pivot tables, based on the relationship's type.
-
-You want to create a relation between data models in the same module.
-
-You want to create a relationship between data models in different modules. Use module links instead.
-
-***
-
-## One-to-One Relationship
-
-A one-to-one relationship indicates that one record of a data model belongs to or is associated with another.
-
-To define a one-to-one relationship, create relationship properties in the data models using the following methods:
-
-1. `hasOne`: indicates that the model has one record of the specified model.
-2. `belongsTo`: indicates that the model belongs to one record of the specified model.
-
-For example:
-
-```ts highlights={oneToOneHighlights}
-import { model } from "@medusajs/framework/utils"
-
-const User = model.define("user", {
-  id: model.id().primaryKey(),
-  email: model.hasOne(() => Email),
-})
-
-const Email = model.define("email", {
-  id: model.id().primaryKey(),
-  user: model.belongsTo(() => User, {
-    mappedBy: "email",
-  }),
-})
-```
-
-In the example above, a user has one email, and an email belongs to one user.
-
-The `hasOne` and `belongsTo` methods accept a function as the first parameter. The function returns the associated data model.
-
-The `belongsTo` method also requires passing as a second parameter an object with the property `mappedBy`. Its value is the name of the relationship property in the other data model.
-
-### Optional Relationship
-
-To make the relationship optional on the `hasOne` or `belongsTo` side, use the `nullable` method on either property as explained in [this chapter](https://docs.medusajs.com/learn/fundamentals/data-models/properties#make-property-optional/index.html.md).
-
-### One-sided One-to-One Relationship
-
-If the one-to-one relationship is only defined on one side, pass `undefined` to the `mappedBy` property in the `belongsTo` method.
-
-For example:
-
-```ts highlights={oneToOneUndefinedHighlights}
-import { model } from "@medusajs/framework/utils"
-
-const User = model.define("user", {
-  id: model.id().primaryKey(),
-})
-
-const Email = model.define("email", {
-  id: model.id().primaryKey(),
-  user: model.belongsTo(() => User, {
-    mappedBy: undefined,
-  }),
-})
-```
-
-### One-to-One Relationship in the Database
-
-When you generate the migrations of data models that have a one-to-one relationship, the migration adds to the table of the data model that has the `belongsTo` property:
-
-1. A column of the format `{relation_name}_id` to store the ID of the record of the related data model. For example, the `email` table will have a `user_id` column.
-2. A foreign key on the `{relation_name}_id` column to the table of the related data model.
-
-![Diagram illustrating the relation between user and email records in the database](https://res.cloudinary.com/dza7lstvk/image/upload/v1726733492/Medusa%20Book/one-to-one_cj5np3.jpg)
-
-***
-
-## One-to-Many Relationship
-
-A one-to-many relationship indicates that one record of a data model has many records of another data model.
-
-To define a one-to-many relationship, create relationship properties in the data models using the following methods:
-
-1. `hasMany`: indicates that the model has more than one record of the specified model.
-2. `belongsTo`: indicates that the model belongs to one record of the specified model.
-
-For example:
-
-```ts highlights={oneToManyHighlights}
-import { model } from "@medusajs/framework/utils"
-
-const Store = model.define("store", {
-  id: model.id().primaryKey(),
-  products: model.hasMany(() => Product),
-})
-
-const Product = model.define("product", {
-  id: model.id().primaryKey(),
-  store: model.belongsTo(() => Store, {
-    mappedBy: "products",
-  }),
-})
-```
-
-In this example, a store has many products, but a product belongs to one store.
-
-### Optional Relationship
-
-To make the relationship optional on the `belongsTo` side, use the `nullable` method on the property as explained in [this chapter](https://docs.medusajs.com/learn/fundamentals/data-models/properties#make-property-optional/index.html.md).
-
-### One-to-Many Relationship in the Database
-
-When you generate the migrations of data models that have a one-to-many relationship, the migration adds to the table of the data model that has the `belongsTo` property:
-
-1. A column of the format `{relation_name}_id` to store the ID of the record of the related data model. For example, the `product` table will have a `store_id` column.
-2. A foreign key on the `{relation_name}_id` column to the table of the related data model.
-
-![Diagram illustrating the relation between a store and product records in the database](https://res.cloudinary.com/dza7lstvk/image/upload/v1726733937/Medusa%20Book/one-to-many_d6wtcw.jpg)
-
-***
-
-## Many-to-Many Relationship
-
-A many-to-many relationship indicates that many records of a data model can be associated with many records of another data model.
-
-To define a many-to-many relationship, create relationship properties in the data models using the `manyToMany` method.
-
-For example:
-
-```ts highlights={manyToManyHighlights}
-import { model } from "@medusajs/framework/utils"
-
-const Order = model.define("order", {
-  id: model.id().primaryKey(),
-  products: model.manyToMany(() => Product, {
-    mappedBy: "orders",
-    pivotTable: "order_product",
-    joinColumn: "order_id",
-    inverseJoinColumn: "product_id",
-  }),
-})
-
-const Product = model.define("product", {
-  id: model.id().primaryKey(),
-  orders: model.manyToMany(() => Order, {
-    mappedBy: "products",
-  }),
-})
-```
-
-The `manyToMany` method accepts two parameters:
-
-1. A function that returns the associated data model.
-2. An object of optional configuration. Only one of the data models in the relation can define the `pivotTable`, `joinColumn`, and `inverseJoinColumn` configurations, and it's considered the owner data model. The object can accept the following properties:
-   - `mappedBy`: The name of the relationship property in the other data model. If not set, the property's name is inferred from the associated data model's name.
-   - `pivotTable`: The name of the pivot table created in the database for the many-to-many relation. If not set, the pivot table is inferred by combining the names of the data models' tables in alphabetical order, separating them by `_`, and pluralizing the last name. For example, `order_products`.
-   - `joinColumn`: The name of the column in the pivot table that points to the owner model's primary key.
-   - `inverseJoinColumn`: The name of the column in the pivot table that points to the owned model's primary key.
-
-The `pivotTable`, `joinColumn`, and `inverseJoinColumn` properties are only available after [Medusa v2.0.7](https://github.com/medusajs/medusa/releases/tag/v2.0.7).
-
-Following [Medusa v2.1.0](https://github.com/medusajs/medusa/releases/tag/v2.1.0), if `pivotTable`, `joinColumn`, and `inverseJoinColumn` aren't specified on either model, the owner is decided based on alphabetical order. So, in the example above, the `Order` data model would be the owner.
-
-In this example, an order is associated with many products, and a product is associated with many orders. Since the `pivotTable`, `joinColumn`, and `inverseJoinColumn` configurations are defined on the order, it's considered the owner data model.
-
-### Many-to-Many Relationship in the Database
-
-When you generate the migrations of data models that have a many-to-many relationship, the migration adds a new pivot table. Its name is either the name you specify in the `pivotTable` configuration or the inferred name combining the names of the data models' tables in alphabetical order, separating them by `_`, and pluralizing the last name. For example, `order_products`.
-
-The pivot table has a column with the name `{data_model}_id` for each of the data model's tables. It also has foreign keys on each of these columns to their respective tables.
-
-The pivot table has columns with foreign keys pointing to the primary key of the associated tables. The column's name is either:
-
-- The value of the `joinColumn` configuration for the owner table, and the `inverseJoinColumn` configuration for the owned table;
-- Or the inferred name `{table_name}_id`.
-
-![Diagram illustrating the relation between order and product records in the database](https://res.cloudinary.com/dza7lstvk/image/upload/v1726734269/Medusa%20Book/many-to-many_fzy5pq.jpg)
-
-### Many-To-Many with Custom Columns
-
-To add custom columns to the pivot table between two data models having a many-to-many relationship, you must define a new data model that represents the pivot table.
-
-For example:
-
-```ts highlights={manyToManyColumnHighlights}
-import { model } from "@medusajs/framework/utils"
-
-export const Order = model.define("order_test", {
-  id: model.id().primaryKey(),
-  products: model.manyToMany(() => Product, {
-    pivotEntity: () => OrderProduct,
-  }),
-})
-
-export const Product = model.define("product_test", {
-  id: model.id().primaryKey(),
-  orders: model.manyToMany(() => Order),
-})
-
-export const OrderProduct = model.define("orders_products", {
-  id: model.id().primaryKey(),
-  order: model.belongsTo(() => Order, {
-    mappedBy: "products",
-  }),
-  product: model.belongsTo(() => Product, {
-    mappedBy: "orders",
-  }),
-  metadata: model.json().nullable(),
-})
-```
-
-The `Order` and `Product` data models have a many-to-many relationship. To add extra columns to the created pivot table, you pass a `pivotEntity` option to the `products` relation in `Order` (since `Order` is the owner). The value of `pivotEntity` is a function that returns the data model representing the pivot table.
-
-The `OrderProduct` model defines, aside from the ID, the following properties:
-
-- `order`: A relation that indicates this model belongs to the `Order` data model. You set the `mappedBy` option to the many-to-many relation's name in the `Order` data model.
-- `product`: A relation that indicates this model belongs to the `Product` data model. You set the `mappedBy` option to the many-to-many relation's name in the `Product` data model.
-- `metadata`: An extra column to add to the pivot table of type `json`. You can add other columns as well to the model.
-
-***
-
-## Set Relationship Name in the Other Model
-
-The relationship property methods accept as a second parameter an object of options. The `mappedBy` property defines the name of the relationship in the other data model.
-
-This is useful if the relationship property’s name is different from that of the associated data model.
-
-As seen in previous examples, the `mappedBy` option is required for the `belongsTo` method.
-
-For example:
-
-```ts highlights={relationNameHighlights}
-import { model } from "@medusajs/framework/utils"
-
-const User = model.define("user", {
-  id: model.id().primaryKey(),
-  email: model.hasOne(() => Email, {
-    mappedBy: "owner",
-  }),
-})
-
-const Email = model.define("email", {
-  id: model.id().primaryKey(),
-  owner: model.belongsTo(() => User, {
-    mappedBy: "email",
-  }),
-})
-```
-
-In this example, you specify in the `User` data model’s relationship property that the name of the relationship in the `Email` data model is `owner`.
-
-***
-
-## Cascades
-
-When an operation is performed on a data model, such as record deletion, the relationship cascade specifies what related data model records should be affected by it.
-
-For example, if a store is deleted, its products should also be deleted.
-
-The `cascades` method used on a data model configures which child records an operation is cascaded to.
-
-For example:
-
-```ts highlights={highlights}
-import { model } from "@medusajs/framework/utils"
-
-const Store = model.define("store", {
-  id: model.id().primaryKey(),
-  products: model.hasMany(() => Product),
-})
-.cascades({
-  delete: ["products"],
-})
-
-const Product = model.define("product", {
-  id: model.id().primaryKey(),
-  store: model.belongsTo(() => Store, {
-    mappedBy: "products",
-  }),
-})
-```
-
-The `cascades` method accepts an object. Its key is the operation’s name, such as `delete`. The value is an array of relationship property names that the operation is cascaded to.
-
-In the example above, when a store is deleted, its associated products are also deleted.
-
-
 # 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.
@@ -8960,6 +10408,224 @@ const posts = await blogModuleService.listPosts({
 This retrieves records that include `New Products` in their `title` property.
 
 
+# Manage Relationships
+
+In this chapter, you'll learn how to manage relationships between data models when creating, updating, or retrieving records using the module's main service.
+
+## Manage One-to-One Relationship
+
+### BelongsTo Side of One-to-One
+
+When you create a record of a data model that belongs to another through a one-to-one relation, pass the ID of the other data model's record in the `{relation}_id` property, where `{relation}` is the name of the relation property.
+
+For example, assuming you have the [User and Email data models from the previous chapter](https://docs.medusajs.com/learn/fundamentals/data-models/relationships#one-to-one-relationship/index.html.md), set an email's user ID as follows:
+
+```ts highlights={belongsHighlights}
+// when creating an email
+const email = await helloModuleService.createEmails({
+  // other properties...
+  user_id: "123",
+})
+
+// when updating an email
+const email = await helloModuleService.updateEmails({
+  id: "321",
+  // other properties...
+  user_id: "123",
+})
+```
+
+In the example above, you pass the `user_id` property when creating or updating an email to specify the user it belongs to.
+
+### HasOne Side
+
+When you create a record of a data model that has one of another, pass the ID of the other data model's record in the relation property.
+
+For example, assuming you have the [User and Email data models from the previous chapter](https://docs.medusajs.com/learn/fundamentals/data-models/relationships#one-to-one-relationship/index.html.md), set a user's email ID as follows:
+
+```ts highlights={hasOneHighlights}
+// when creating a user
+const user = await helloModuleService.createUsers({
+  // other properties...
+  email: "123",
+})
+
+// when updating a user
+const user = await helloModuleService.updateUsers({
+  id: "321",
+  // other properties...
+  email: "123",
+})
+```
+
+In the example above, you pass the `email` property when creating or updating a user to specify the email it has.
+
+***
+
+## Manage One-to-Many Relationship
+
+In a one-to-many relationship, you can only manage the associations from the `belongsTo` side.
+
+When you create a record of the data model on the `belongsTo` side, pass the ID of the other data model's record in the `{relation}_id` property, where `{relation}` is the name of the relation property.
+
+For example, assuming you have the [Product and Store data models from the previous chapter](https://docs.medusajs.com/learn/fundamentals/data-models/relationships#one-to-many-relationship/index.html.md), set a product's store ID as follows:
+
+```ts highlights={manyBelongsHighlights}
+// when creating a product
+const product = await helloModuleService.createProducts({
+  // other properties...
+  store_id: "123",
+})
+
+// when updating a product
+const product = await helloModuleService.updateProducts({
+  id: "321",
+  // other properties...
+  store_id: "123",
+})
+```
+
+In the example above, you pass the `store_id` property when creating or updating a product to specify the store it belongs to.
+
+***
+
+## Manage Many-to-Many Relationship
+
+If your many-to-many relation is represented with a [pivotEntity](https://docs.medusajs.com/learn/fundamentals/data-models/relationships#many-to-many-with-custom-columns/index.html.md), refer to [this section](#manage-many-to-many-relationship-with-pivotentity) instead.
+
+### Create Associations
+
+When you create a record of a data model that has a many-to-many relationship to another data model, pass an array of IDs of the other data model's records in the relation property.
+
+For example, assuming you have the [Order and Product data models from the previous chapter](https://docs.medusajs.com/learn/fundamentals/data-models/relationships#many-to-many-relationship/index.html.md), set the association between products and orders as follows:
+
+```ts highlights={manyHighlights}
+// when creating a product
+const product = await helloModuleService.createProducts({
+  // other properties...
+  orders: ["123", "321"],
+})
+
+// when creating an order
+const order = await helloModuleService.createOrders({
+  id: "321",
+  // other properties...
+  products: ["123", "321"],
+})
+```
+
+In the example above, you pass the `orders` property when you create a product, and you pass the `products` property when you create an order.
+
+### Update Associations
+
+When you use the `update` methods generated by the service factory, you also pass an array of IDs as the relation property's value to add new associated records.
+
+However, this removes any existing associations to records whose IDs aren't included in the array.
+
+For example, assuming you have the [Order and Product data models from the previous chapter](https://docs.medusajs.com/learn/fundamentals/data-models/relationships#many-to-many-relationship/index.html.md), you update the product's related orders as so:
+
+```ts
+const product = await helloModuleService.updateProducts({
+  id: "123",
+  // other properties...
+  orders: ["321"],
+})
+```
+
+If the product was associated with an order, and you don't include that order's ID in the `orders` array, the association between the product and order is removed.
+
+So, to add a new association without removing existing ones, retrieve the product first to pass its associated orders when updating the product:
+
+```ts highlights={updateAssociationHighlights}
+const product = await helloModuleService.retrieveProduct(
+  "123",
+  {
+    relations: ["orders"],
+  }
+)
+
+const updatedProduct = await helloModuleService.updateProducts({
+  id: product.id,
+  // other properties...
+  orders: [
+    ...product.orders.map((order) => order.id),
+    "321",
+  ],
+})
+```
+
+This keeps existing associations between the product and orders, and adds a new one.
+
+***
+
+## Manage Many-to-Many Relationship with pivotEntity
+
+If your many-to-many relation is represented without a [pivotEntity](https://docs.medusajs.com/learn/fundamentals/data-models/relationships#many-to-many-with-custom-columns/index.html.md), refer to [this section](#manage-many-to-many-relationship) instead.
+
+If you have a many-to-many relation with a `pivotEntity` specified, make sure to pass the data model representing the pivot table to [MedusaService](https://docs.medusajs.com/learn/fundamentals/modules/service-factory/index.html.md) that your module's service extends.
+
+For example, assuming you have the [Order, Product, and OrderProduct models from the previous chapter](https://docs.medusajs.com/learn/fundamentals/data-models/relationships#many-to-many-with-custom-columns/index.html.md), add `OrderProduct` to `MedusaService`'s object parameter:
+
+```ts highlights={["4"]}
+class BlogModuleService extends MedusaService({
+  Order,
+  Product,
+  OrderProduct,
+}) {}
+```
+
+This will generate Create, Read, Update and Delete (CRUD) methods for the `OrderProduct` data model, which you can use to create relations between orders and products and manage the extra columns in the pivot table.
+
+For example:
+
+```ts
+// create order-product association
+const orderProduct = await blogModuleService.createOrderProducts({
+  order_id: "123",
+  product_id: "123",
+  metadata: {
+    test: true,
+  },
+})
+
+// update order-product association
+const orderProduct = await blogModuleService.updateOrderProducts({
+  id: "123",
+  metadata: {
+    test: false,
+  },
+})
+
+// delete order-product association
+await blogModuleService.deleteOrderProducts("123")
+```
+
+Since the `OrderProduct` data model belongs to the `Order` and `Product` data models, you can set its order and product as explained in the [one-to-many relationship section](#manage-one-to-many-relationship) using `order_id` and `product_id`.
+
+Refer to the [service factory reference](https://docs.medusajs.com/resources/service-factory-reference/index.html.md) for a full list of generated methods and their usages.
+
+***
+
+## Retrieve Records of Relation
+
+The `list`, `listAndCount`, and `retrieve` methods of a module's main service accept as a second parameter an object of options.
+
+To retrieve the records associated with a data model's records through a relationship, pass in the second parameter object a `relations` property whose value is an array of relationship names.
+
+For example, assuming you have the [Order and Product data models from the previous chapter](https://docs.medusajs.com/learn/fundamentals/data-models/relationships#many-to-many-relationship/index.html.md), you retrieve a product's orders as follows:
+
+```ts highlights={retrieveHighlights}
+const product = await blogModuleService.retrieveProducts(
+  "123",
+  {
+    relations: ["orders"],
+  }
+)
+```
+
+In the example above, the retrieved product has an `orders` property, whose value is an array of orders associated with the product.
+
+
 # Migrations
 
 In this chapter, you'll learn what a migration is and how to generate a migration or write it manually.
@@ -9058,1562 +10724,6 @@ So, always rollback the migration before deleting it.
 To learn more about the Medusa CLI's database commands, refer to [this CLI reference](https://docs.medusajs.com/resources/medusa-cli/commands/db/index.html.md).
 
 
-# Pass Additional Data to Medusa's API Route
-
-In this chapter, you'll learn how to pass additional data in requests to Medusa's API Route.
-
-## Why Pass Additional Data?
-
-Some of Medusa's API Routes accept an `additional_data` parameter whose type is an object. The API Route passes the `additional_data` to the workflow, which in turn passes it to its hooks.
-
-This is useful when you have a link from your custom module to a Commerce Module, and you want to perform an additional action when a request is sent to an existing API route.
-
-For example, the [Create Product API Route](https://docs.medusajs.com/api/admin#products_postproducts) accepts an `additional_data` parameter. If you have a data model linked to it, you consume the `productsCreated` hook to create a record of the data model using the custom data and link it to the product.
-
-### API Routes Accepting Additional Data
-
-### API Routes List
-
-- Campaigns
-  - [Create Campaign](https://docs.medusajs.com/api/admin#campaigns_postcampaigns)
-  - [Update Campaign](https://docs.medusajs.com/api/admin#campaigns_postcampaignsid)
-- Cart
-  - [Create Cart](https://docs.medusajs.com/api/store#carts_postcarts)
-  - [Update Cart](https://docs.medusajs.com/api/store#carts_postcartsid)
-- Collections
-  - [Create Collection](https://docs.medusajs.com/api/admin#collections_postcollections)
-  - [Update Collection](https://docs.medusajs.com/api/admin#collections_postcollectionsid)
-- Customers
-  - [Create Customer](https://docs.medusajs.com/api/admin#customers_postcustomers)
-  - [Update Customer](https://docs.medusajs.com/api/admin#customers_postcustomersid)
-  - [Create Address](https://docs.medusajs.com/api/admin#customers_postcustomersidaddresses)
-  - [Update Address](https://docs.medusajs.com/api/admin#customers_postcustomersidaddressesaddress_id)
-- Draft Orders
-  - [Create Draft Order](https://docs.medusajs.com/api/admin#draft-orders_postdraftorders)
-- Orders
-  - [Complete Orders](https://docs.medusajs.com/api/admin#orders_postordersidcomplete)
-  - [Cancel Order's Fulfillment](https://docs.medusajs.com/api/admin#orders_postordersidfulfillmentsfulfillment_idcancel)
-  - [Create Shipment](https://docs.medusajs.com/api/admin#orders_postordersidfulfillmentsfulfillment_idshipments)
-  - [Create Fulfillment](https://docs.medusajs.com/api/admin#orders_postordersidfulfillments)
-- Products
-  - [Create Product](https://docs.medusajs.com/api/admin#products_postproducts)
-  - [Update Product](https://docs.medusajs.com/api/admin#products_postproductsid)
-  - [Create Product Variant](https://docs.medusajs.com/api/admin#products_postproductsidvariants)
-  - [Update Product Variant](https://docs.medusajs.com/api/admin#products_postproductsidvariantsvariant_id)
-  - [Create Product Option](https://docs.medusajs.com/api/admin#products_postproductsidoptions)
-  - [Update Product Option](https://docs.medusajs.com/api/admin#products_postproductsidoptionsoption_id)
-- Product Tags
-  - [Create Product Tag](https://docs.medusajs.com/api/admin#product-tags_postproducttags)
-  - [Update Product Tag](https://docs.medusajs.com/api/admin#product-tags_postproducttagsid)
-- Product Types
-  - [Create Product Type](https://docs.medusajs.com/api/admin#product-types_postproducttypes)
-  - [Update Product Type](https://docs.medusajs.com/api/admin#product-types_postproducttypesid)
-- Promotions
-  - [Create Promotion](https://docs.medusajs.com/api/admin#promotions_postpromotions)
-  - [Update Promotion](https://docs.medusajs.com/api/admin#promotions_postpromotionsid)
-
-***
-
-## How to Pass Additional Data
-
-### 1. Specify Validation of Additional Data
-
-Before passing custom data in the `additional_data` object parameter, you must specify validation rules for the allowed properties in the object.
-
-To do that, use the middleware route object defined in `src/api/middlewares.ts`.
-
-For example, create the file `src/api/middlewares.ts` with the following content:
-
-```ts title="src/api/middlewares.ts"
-import { defineMiddlewares } from "@medusajs/framework/http"
-import { z } from "zod"
-
-export default defineMiddlewares({
-  routes: [
-    {
-      method: "POST",
-      matcher: "/admin/products",
-      additionalDataValidator: {
-        brand: z.string().optional(),
-      },
-    },
-  ],
-})
-```
-
-The middleware route object accepts an optional parameter `additionalDataValidator` whose value is an object of key-value pairs. The keys indicate the name of accepted properties in the `additional_data` parameter, and the value is [Zod](https://zod.dev/) validation rules of the property.
-
-In this example, you indicate that the `additional_data` parameter accepts a `brand` property whose value is an optional string.
-
-Refer to [Zod's documentation](https://zod.dev) for all available validation rules.
-
-### 2. Pass the Additional Data in a Request
-
-You can now pass a `brand` property in the `additional_data` parameter of a request to the Create Product API Route.
-
-For example:
-
-```bash
-curl -X POST 'http://localhost:9000/admin/products' \
--H 'Content-Type: application/json' \
--H 'Authorization: Bearer {token}' \
---data '{
-    "title": "Product 1",
-    "options": [
-      {
-        "title": "Default option",
-        "values": ["Default option value"]
-      }
-    ],
-    "shipping_profile_id": "{shipping_profile_id}",
-    "additional_data": {
-        "brand": "Acme"
-    }
-}'
-```
-
-Make sure to replace the `{token}` in the authorization header with an admin user's authentication token, and `{shipping_profile_id}` with an existing shipping profile's ID.
-
-In this request, you pass in the `additional_data` parameter a `brand` property and set its value to `Acme`.
-
-The `additional_data` is then passed to hooks in the `createProductsWorkflow` used by the API route.
-
-***
-
-## Use Additional Data in a Hook
-
-Learn about workflow hooks in [this guide](https://docs.medusajs.com/learn/fundamentals/workflows/workflow-hooks/index.html.md).
-
-Step functions consuming the workflow hook can access the `additional_data` in the first parameter.
-
-For example, consider you want to store the data passed in `additional_data` in the product's `metadata` property.
-
-To do that, create the file `src/workflows/hooks/product-created.ts` with the following content:
-
-```ts title="src/workflows/hooks/product-created.ts"
-import { StepResponse } from "@medusajs/framework/workflows-sdk"
-import { createProductsWorkflow } from "@medusajs/medusa/core-flows"
-import { Modules } from "@medusajs/framework/utils"
-
-createProductsWorkflow.hooks.productsCreated(
-  async ({ products, additional_data }, { container }) => {
-    if (!additional_data?.brand) {
-      return
-    }
-
-    const productModuleService = container.resolve(
-      Modules.PRODUCT
-    )
-
-    await productModuleService.upsertProducts(
-      products.map((product) => ({
-        ...product,
-        metadata: {
-          ...product.metadata,
-          brand: additional_data.brand,
-        },
-      }))
-    )
-
-    return new StepResponse(products, {
-      products,
-      additional_data,
-    })
-  }
-)
-```
-
-This consumes the `productsCreated` hook, which runs after the products are created.
-
-If `brand` is passed in `additional_data`, you resolve the Product Module's main service and use its `upsertProducts` method to update the products, adding the brand to the `metadata` property.
-
-### Compensation Function
-
-Hooks also accept a compensation function as a second parameter to undo the actions made by the step function.
-
-For example, pass the following second parameter to the `productsCreated` hook:
-
-```ts title="src/workflows/hooks/product-created.ts"
-createProductsWorkflow.hooks.productsCreated(
-  async ({ products, additional_data }, { container }) => {
-    // ...
-  },
-  async ({ products, additional_data }, { container }) => {
-    if (!additional_data.brand) {
-      return
-    }
-
-    const productModuleService = container.resolve(
-      Modules.PRODUCT
-    )
-
-    await productModuleService.upsertProducts(
-      products
-    )
-  }
-)
-```
-
-This updates the products to their original state before adding the brand to their `metadata` property.
-
-
-# Throwing and Handling Errors
-
-In this guide, you'll learn how to throw errors in your Medusa application, how it affects an API route's response, and how to change the default error handler of your Medusa application.
-
-## Throw MedusaError
-
-When throwing an error in your API routes, middlewares, workflows, or any customization, throw a `MedusaError` from the Medusa Framework.
-
-The Medusa application's API route error handler then wraps your thrown error in a uniform object and returns it in the response.
-
-For example:
-
-```ts
-import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
-import { MedusaError } from "@medusajs/framework/utils"
-
-export const GET = async (
-  req: MedusaRequest,
-  res: MedusaResponse
-) => {
-  if (!req.query.q) {
-    throw new MedusaError(
-      MedusaError.Types.INVALID_DATA,
-      "The `q` query parameter is required."
-    )
-  }
-
-  // ...
-}
-```
-
-The `MedusaError` class accepts in its constructor two parameters:
-
-1. The first is the error's type. `MedusaError` has a static property `Types` that you can use. `Types` is an enum whose possible values are explained in the next section.
-2. The second is the message to show in the error response.
-
-### Error Object in Response
-
-The error object returned in the response has two properties:
-
-- `type`: The error's type.
-- `message`: The error message, if available.
-- `code`: A common snake-case code. Its values can be:
-  - `invalid_request_error` for the `DUPLICATE_ERROR` type.
-  - `api_error`:  for the `DB_ERROR` type.
-  - `invalid_state_error` for `CONFLICT` error type.
-  - `unknown_error` for any unidentified error type.
-  - For other error types, this property won't be available unless you provide a code as a third parameter to the `MedusaError` constructor.
-
-### MedusaError Types
-
-|Type|Description|Status Code|
-|---|---|---|---|---|
-|\`DB\_ERROR\`|Indicates a database error.|\`500\`|
-|\`DUPLICATE\_ERROR\`|Indicates a duplicate of a record already exists. For example, when trying to create a customer whose email is registered by another customer.|\`422\`|
-|\`INVALID\_ARGUMENT\`|Indicates an error that occurred due to incorrect arguments or other unexpected state.|\`500\`|
-|\`INVALID\_DATA\`|Indicates a validation error.|\`400\`|
-|\`UNAUTHORIZED\`|Indicates that a user is not authorized to perform an action or access a route.|\`401\`|
-|\`NOT\_FOUND\`|Indicates that the requested resource, such as a route or a record, isn't found.|\`404\`|
-|\`NOT\_ALLOWED\`|Indicates that an operation isn't allowed.|\`400\`|
-|\`CONFLICT\`|Indicates that a request conflicts with another previous or ongoing request. The error message in this case is ignored for a default message.|\`409\`|
-|\`PAYMENT\_AUTHORIZATION\_ERROR\`|Indicates an error has occurred while authorizing a payment.|\`422\`|
-|Other error types|Any other error type results in an |\`500\`|
-
-***
-
-## Override Error Handler
-
-The `defineMiddlewares` function used to apply middlewares on routes accepts an `errorHandler` in its object parameter. Use it to override the default error handler for API routes.
-
-This error handler will also be used for errors thrown in Medusa's API routes and resources.
-
-For example, create `src/api/middlewares.ts` with the following:
-
-```ts title="src/api/middlewares.ts" collapsibleLines="1-8" expandMoreLabel="Show Imports"
-import { 
-  defineMiddlewares, 
-  MedusaNextFunction, 
-  MedusaRequest, 
-  MedusaResponse,
-} from "@medusajs/framework/http"
-import { MedusaError } from "@medusajs/framework/utils"
-
-export default defineMiddlewares({
-  errorHandler: (
-    error: MedusaError | any, 
-    req: MedusaRequest, 
-    res: MedusaResponse, 
-    next: MedusaNextFunction
-  ) => {
-    res.status(400).json({
-      error: "Something happened.",
-    })
-  },
-})
-```
-
-The `errorHandler` property's value is a function that accepts four parameters:
-
-1. The error thrown. Its type can be `MedusaError` or any other thrown error type.
-2. A request object of type `MedusaRequest`.
-3. A response object of type `MedusaResponse`.
-4. A function of type MedusaNextFunction that executes the next middleware in the stack.
-
-This example overrides Medusa's default error handler with a handler that always returns a `400` status code with the same message.
-
-
-# Middlewares
-
-In this chapter, you’ll learn about middlewares and how to create them.
-
-## What is a Middleware?
-
-A middleware is a function executed when a request is sent to an API Route. It's executed before the route handler function.
-
-Middlewares are used to guard API routes, parse request content types other than `application/json`, manipulate request data, and more.
-
-As Medusa's server is based on Express, you can use any [Express middleware](https://expressjs.com/en/resources/middleware.html).
-
-### Middleware Types
-
-There are two types of middlewares:
-
-1. Global Middleware: A middleware that applies to all routes matching a specified pattern.
-2. Route Middleware: A middleware that applies to routes matching a specified pattern and HTTP method(s).
-
-These middlewares generally have the same definition and usage, but they differ in the routes they apply to. You'll learn how to create both types in the following sections.
-
-***
-
-## How to Create a Global Middleware?
-
-Middlewares of all types are defined in the special file `src/api/middlewares.ts`. Use the `defineMiddlewares` function from the Medusa Framework to define the middlewares, and export its value.
-
-For example:
-
-```ts title="src/api/middlewares.ts"
-import { 
-  defineMiddlewares,
-  MedusaNextFunction, 
-  MedusaRequest, 
-  MedusaResponse, 
-} from "@medusajs/framework/http"
-
-export default defineMiddlewares({
-  routes: [
-    {
-      matcher: "/custom*",
-      middlewares: [
-        (
-          req: MedusaRequest, 
-          res: MedusaResponse, 
-          next: MedusaNextFunction
-        ) => {
-          console.log("Received a request!")
-
-          next()
-        },
-      ],
-    },
-  ],
-})
-```
-
-The `defineMiddlewares` function accepts a middleware configurations object that has the property `routes`. `routes`'s value is an array of middleware route objects, each having the following properties:
-
-- `matcher`: a string or regular expression indicating the API route path to apply the middleware on. The regular expression must be compatible with [path-to-regexp](https://github.com/pillarjs/path-to-regexp).
-- `middlewares`: An array of global and route middleware functions.
-
-In the example above, you define a global middleware that logs the message `Received a request!` whenever a request is sent to an API route path starting with `/custom`.
-
-### Test the Global Middleware
-
-To test the middleware:
-
-1. Start the application:
-
-```bash npm2yarn
-npm run dev
-```
-
-2. Send a request to any API route starting with `/custom`.
-3. See the following message in the terminal:
-
-```bash
-Received a request!
-```
-
-***
-
-## How to Create a Route Middleware?
-
-In the previous section, you learned how to create a global middleware. You define the route middleware in the same way in `src/api/middlewares.ts`, but you specify an additional property `method` in the middleware route object. Its value is one or more HTTP methods to apply the middleware to.
-
-For example:
-
-```ts title="src/api/middlewares.ts" highlights={highlights} collapsibleLines="1-7" expandButtonLabel="Show Imports"
-import { 
-  MedusaNextFunction, 
-  MedusaRequest, 
-  MedusaResponse, 
-  defineMiddlewares,
-} from "@medusajs/framework/http"
-
-export default defineMiddlewares({
-  routes: [
-    {
-      matcher: "/custom*",
-      method: ["POST", "PUT"],
-      middlewares: [
-        (
-          req: MedusaRequest, 
-          res: MedusaResponse, 
-          next: MedusaNextFunction
-        ) => {
-          console.log("Received a request!")
-
-          next()
-        },
-      ],
-    },
-  ],
-})
-```
-
-This example applies the middleware only when a `POST` or `PUT` request is sent to an API route path starting with `/custom`, changing the middleware from a global middleware to a route middleware.
-
-### Test the Route Middleware
-
-To test the middleware:
-
-1. Start the application:
-
-```bash npm2yarn
-npm run dev
-```
-
-2. Send a `POST` request to any API route starting with `/custom`.
-3. See the following message in the terminal:
-
-```bash
-Received a request!
-```
-
-***
-
-## When to Use Middlewares
-
-- You want to protect API routes by a custom condition.
-- You're modifying the request body.
-
-***
-
-## Middleware Function Parameters
-
-The middleware function accepts three parameters:
-
-1. A request object of type `MedusaRequest`.
-2. A response object of type `MedusaResponse`.
-3. A function of type `MedusaNextFunction` that executes the next middleware in the stack.
-
-You must call the `next` function in the middleware. Otherwise, other middlewares and the API route handler won’t execute.
-
-***
-
-## Middleware for Routes with Path Parameters
-
-To indicate a path parameter in a middleware's `matcher` pattern, use the format `:{param-name}`.
-
-For example:
-
-```ts title="src/api/middlewares.ts" collapsibleLines="1-7" expandMoreLabel="Show Imports" highlights={pathParamHighlights}
-import { 
-  MedusaNextFunction, 
-  MedusaRequest, 
-  MedusaResponse, 
-  defineMiddlewares,
-} from "@medusajs/framework/http"
-
-export default defineMiddlewares({
-  routes: [
-    {
-      matcher: "/custom/:id",
-      middlewares: [
-        // ...
-      ],
-    },
-  ],
-})
-```
-
-This applies a middleware to the routes defined in the file `src/api/custom/[id]/route.ts`.
-
-***
-
-## Request URLs with Trailing Backslashes
-
-A middleware whose `matcher` pattern doesn't end with a backslash won't be applied for requests to URLs with a trailing backslash.
-
-For example, consider you have the following middleware:
-
-```ts title="src/api/middlewares.ts" collapsibleLines="1-7" expandMoreLabel="Show Imports"
-import { 
-  MedusaNextFunction, 
-  MedusaRequest, 
-  MedusaResponse, 
-  defineMiddlewares,
-} from "@medusajs/framework/http"
-
-export default defineMiddlewares({
-  routes: [
-    {
-      matcher: "/custom",
-      middlewares: [
-        (
-          req: MedusaRequest, 
-          res: MedusaResponse, 
-          next: MedusaNextFunction
-        ) => {
-          console.log("Received a request!")
-
-          next()
-        },
-      ],
-    },
-  ],
-})
-```
-
-If you send a request to `http://localhost:9000/custom`, the middleware will run.
-
-However, if you send a request to `http://localhost:9000/custom/`, the middleware won't run.
-
-In general, avoid adding trailing backslashes when sending requests to API routes.
-
-***
-
-## Middlewares and Route Ordering
-
-The ordering explained in this section was added in [Medusa v2.6](https://github.com/medusajs/medusa/releases/tag/v2.6)
-
-The Medusa application registers middlewares and API route handlers in the following order:
-
-1. Global middlewares in the following order:
-   1. Global middleware defined in the Medusa's core.
-   2. Global middleware defined in the plugins (in the order the plugins are registered in).
-   3. Global middleware you define in the application.
-2. Route middlewares in the following order:
-   1. Route middleware defined in the Medusa's core.
-   2. Route middleware defined in the plugins (in the order the plugins are registered in).
-   3. Route middleware you define in the application.
-3. API routes in the following order:
-   1. API routes defined in the Medusa's core.
-   2. API routes defined in the plugins (in the order the plugins are registered in).
-   3. API routes you define in the application.
-
-### Middlewares Sorting
-
-On top of the previous ordering, Medusa sorts global and route middlewares based on their matcher pattern in the following order:
-
-1. Wildcard matchers. For example, `/custom*`.
-2. Regex matchers. For example, `/custom/(products|collections)`.
-3. Static matchers without parameters. For example, `/custom`.
-4. Static matchers with parameters. For example, `/custom/:id`.
-
-For example, if you have the following middlewares:
-
-```ts title="src/api/middlewares.ts"
-export default defineMiddlewares({
-  routes: [
-    {
-      matcher: "/custom/:id",
-      middlewares: [/* ... */],
-    },
-    {
-      matcher: "/custom",
-      middlewares: [/* ... */],
-    },
-    {
-      matcher: "/custom*",
-      method: ["GET"],
-      middlewares: [/* ... */],
-    },
-    {
-      matcher: "/custom/:id",
-      method: ["GET"],
-      middlewares: [/* ... */],
-    },
-  ],
-})
-```
-
-The global middlewares are sorted into the following order before they're registered:
-
-1. Global middleware `/custom`.
-2. Global middleware `/custom/:id`.
-
-And the route middlewares are sorted into the following order before they're registered:
-
-1. Route middleware `/custom*`.
-2. Route middleware `/custom/:id`.
-
-Then, the middlwares are registered in the order mentioned earlier, with global middlewares first, then the route middlewares.
-
-### Middlewares and Route Execution Order
-
-When a request is sent to an API route, the global middlewares are executed first, then the route middlewares, and finally the route handler.
-
-For example, consider you have the following middlewares:
-
-```ts title="src/api/middlewares.ts"
-export default defineMiddlewares({
-  routes: [
-    {
-      matcher: "/custom",
-      middlewares: [
-        (req, res, next) => {
-          console.log("Global middleware")
-          next()
-        },
-      ],
-    },
-    {
-      matcher: "/custom",
-      method: ["GET"],
-      middlewares: [
-        (req, res, next) => {
-          console.log("Route middleware")
-          next()
-        },
-      ],
-    },
-  ],
-})
-```
-
-When you send a request to `/custom` route, the following messages are logged in the terminal:
-
-```bash
-Global middleware
-Route middleware
-Hello from custom! # message logged from API route handler
-```
-
-The global middleware runs first, then the route middleware, and finally the route handler, assuming that it logs the message `Hello from custom!`.
-
-***
-
-## Overriding Middlewares
-
-A middleware can not override an existing middleware. Instead, middlewares are added to the end of the middleware stack.
-
-For example, if you define a custom validation middleware, such as `validateAndTransformBody`, on an existing route, then both the original and the custom validation middleware will run.
-
-
-# HTTP Methods
-
-In this chapter, you'll learn about how to add new API routes for each HTTP method.
-
-## HTTP Method Handler
-
-An API route is created for every HTTP method you export a handler function for in a route file.
-
-Allowed HTTP methods are: `GET`, `POST`, `DELETE`, `PUT`, `PATCH`, `OPTIONS`, and `HEAD`.
-
-For example, create the file `src/api/hello-world/route.ts` with the following content:
-
-```ts title="src/api/hello-world/route.ts"
-import type {
-  MedusaRequest,
-  MedusaResponse,
-} from "@medusajs/framework/http"
-
-export const GET = async (
-  req: MedusaRequest,
-  res: MedusaResponse
-) => {
-  res.json({
-    message: "[GET] Hello world!",
-  })
-}
-
-export const POST = async (
-  req: MedusaRequest,
-  res: MedusaResponse
-) => {
-  res.json({
-    message: "[POST] Hello world!",
-  })
-}
-```
-
-This adds two API Routes:
-
-- A `GET` route at `http://localhost:9000/hello-world`.
-- A `POST` route at `http://localhost:9000/hello-world`.
-
-
-# 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`.
-
-
-# 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).
-
-
-# Protected Routes
-
-In this chapter, you’ll learn how to create protected routes.
-
-## What is a Protected Route?
-
-A protected route is a route that requires requests to be user-authenticated before performing the route's functionality. Otherwise, the request fails, and the user is prevented access.
-
-***
-
-## Default Protected Routes
-
-Medusa applies an authentication guard on routes starting with `/admin`, including custom API routes.
-
-Requests to `/admin` must be user-authenticated to access the route.
-
-Refer to the API Reference for [Admin](https://docs.medusajs.com/api/admin#authentication) and [Store](https://docs.medusajs.com/api/store#authentication) authentication methods.
-
-***
-
-## Protect Custom API Routes
-
-To protect custom API Routes to only allow authenticated customer or admin users, use the `authenticate` middleware from the Medusa Framework.
-
-For example:
-
-```ts title="src/api/middlewares.ts" highlights={highlights}
-import { 
-  defineMiddlewares,
-  authenticate,
-} from "@medusajs/framework/http"
-
-export default defineMiddlewares({
-  routes: [
-    {
-      matcher: "/custom/admin*",
-      middlewares: [authenticate("user", ["session", "bearer", "api-key"])],
-    },
-    {
-      matcher: "/custom/customer*",
-      middlewares: [authenticate("customer", ["session", "bearer"])],
-    },
-  ],
-})
-```
-
-The `authenticate` middleware function accepts three parameters:
-
-1. The type of user authenticating. Use `user` for authenticating admin users, and `customer` for authenticating customers. You can also pass `*` to allow all types of users, or pass an array of actor types.
-2. An array of types of authentication methods allowed. Both `user` and `customer` scopes support `session` and `bearer`. The `admin` scope also supports the `api-key` authentication method.
-3. An optional object of configurations accepting the following properties:
-   - `allowUnauthenticated`: (default: `false`) A boolean indicating whether authentication is required. For example, you may have an API route where you want to access the logged-in customer if available, but guest customers can still access it too.
-   - `allowUnregistered` (default: `false`): A boolean indicating if unregistered users should be allowed access. This is useful when you want to allow users who aren’t registered to access certain routes.
-
-### Example: Custom Actor Type
-
-For example, to require authentication of a custom actor type `manager` to an API route:
-
-```ts title="src/api/middlewares.ts"
-import { 
-  defineMiddlewares,
-  authenticate,
-} from "@medusajs/framework/http"
-
-export default defineMiddlewares({
-  routes: [
-    {
-      matcher: "/manager*",
-      middlewares: [authenticate("manager", ["session", "bearer"])],
-    },
-  ],
-})
-```
-
-Refer to the [Custom Actor-Type Guide](https://docs.medusajs.com/resources/commerce-modules/auth/create-actor-type/index.html.md) for detailed explanation on how to create a custom actor type and apply authentication middlewares.
-
-### Example: Allow Multiple Actor Types
-
-To allow multiple actor types to access an API route, pass an array of actor types to the `authenticate` middleware:
-
-```ts title="src/api/middlewares.ts"
-import { 
-  defineMiddlewares,
-  authenticate,
-} from "@medusajs/framework/http"
-
-export default defineMiddlewares({
-  routes: [
-    {
-      matcher: "/custom*",
-      middlewares: [authenticate(["user", "customer"], ["session", "bearer"])],
-    },
-  ],
-})
-```
-
-***
-
-## Authentication Opt-Out
-
-To disable the authentication guard on custom routes under the `/admin` path prefix, export an `AUTHENTICATE` variable in the route file with its value set to `false`.
-
-For example:
-
-```ts title="src/api/admin/custom/route.ts" highlights={[["15"]]}
-import type { 
-  AuthenticatedMedusaRequest, 
-  MedusaResponse,
-} from "@medusajs/framework/http"
-
-export const GET = async (
-  req: AuthenticatedMedusaRequest, 
-  res: MedusaResponse
-) => {
-  res.json({
-    message: "Hello",
-  })
-}
-
-export const AUTHENTICATE = false
-```
-
-Now, any request sent to the `/admin/custom` API route is allowed, regardless if the admin user is authenticated.
-
-***
-
-## Authenticated Request Type
-
-To access the authentication details in an API route, such as the logged-in user's ID, set the type of the first request parameter to `AuthenticatedMedusaRequest`. It extends `MedusaRequest`.
-
-The `auth_context.actor_id` property of `AuthenticatedMedusaRequest` holds the ID of the authenticated user or customer. If there isn't any authenticated user or customer, `auth_context` is `undefined`.
-
-If you opt-out of authentication in a route as mentioned in the [previous section](#authentication-opt-out), you can't access the authenticated user or customer anymore. Use the [authenticate middleware](#protect-custom-api-routes) instead.
-
-### Retrieve Logged-In Customer's Details
-
-You can access the logged-in customer’s ID in all API routes starting with `/store` using the `auth_context.actor_id` property of the `AuthenticatedMedusaRequest` object.
-
-For example:
-
-```ts title="src/api/store/custom/route.ts" highlights={[["19", "req.auth_context.actor_id", "Access the logged-in customer's ID."]]} collapsibleLines="1-7" expandButtonLabel="Show Imports"
-import type {
-  AuthenticatedMedusaRequest,
-  MedusaResponse,
-} from "@medusajs/framework/http"
-import { Modules } from "@medusajs/framework/utils"
-import { ICustomerModuleService } from "@medusajs/framework/types"
-
-export const GET = async (
-  req: AuthenticatedMedusaRequest,
-  res: MedusaResponse
-) => {
-  if (req.auth_context?.actor_id) {
-    // retrieve customer
-    const customerModuleService: ICustomerModuleService = req.scope.resolve(
-      Modules.CUSTOMER
-    )
-
-    const customer = await customerModuleService.retrieveCustomer(
-      req.auth_context.actor_id
-    )
-  }
-
-  // ...
-}
-```
-
-In this example, you resolve the Customer Module's main service, then use it to retrieve the logged-in customer, if available.
-
-### Retrieve Logged-In Admin User's Details
-
-You can access the logged-in admin user’s ID in all API Routes starting with `/admin` using the `auth_context.actor_id` property of the `AuthenticatedMedusaRequest` object.
-
-For example:
-
-```ts title="src/api/admin/custom/route.ts" highlights={[["17", "req.auth_context.actor_id", "Access the logged-in admin user's ID."]]} collapsibleLines="1-7" expandButtonLabel="Show Imports"
-import type {
-  AuthenticatedMedusaRequest,
-  MedusaResponse,
-} from "@medusajs/framework/http"
-import { Modules } from "@medusajs/framework/utils"
-import { IUserModuleService } from "@medusajs/framework/types"
-
-export const GET = async (
-  req: AuthenticatedMedusaRequest,
-  res: MedusaResponse
-) => {
-  const userModuleService: IUserModuleService = req.scope.resolve(
-    Modules.USER
-  )
-
-  const user = await userModuleService.retrieveUser(
-    req.auth_context.actor_id
-  )
-
-  // ...
-}
-```
-
-In the route handler, you resolve the User Module's main service, then use it to retrieve the logged-in admin user.
-
-
-# Configure Request Body Parser
-
-In this chapter, you'll learn how to configure the request body parser for your API routes.
-
-## Default Body Parser Configuration
-
-The Medusa application configures the body parser by default to parse JSON, URL-encoded, and text request content types. You can parse other data types by adding the relevant [Express middleware](https://expressjs.com/en/guide/using-middleware.html) or preserve the raw body data by configuring the body parser, which is useful for webhook requests.
-
-This chapter shares some examples of configuring the body parser for different data types or use cases.
-
-***
-
-## Preserve Raw Body Data for Webhooks
-
-If your API route receives webhook requests, you might want to preserve the raw body data. To do this, you can configure the body parser to parse the raw body data and store it in the `req.rawBody` property.
-
-To do that, create the file `src/api/middlewares.ts` with the following content:
-
-```ts title="src/api/middlewares.ts" highlights={preserveHighlights}
-import { defineMiddlewares } from "@medusajs/framework/http"
-
-export default defineMiddlewares({
-  routes: [
-    {
-      method: ["POST"],
-      bodyParser: { preserveRawBody: true },
-      matcher: "/custom",
-    },
-  ],
-})
-```
-
-The middleware route object passed to `routes` accepts a `bodyParser` property whose value is an object of configuration for the default body parser. By enabling the `preserveRawBody` property, the raw body data is preserved and stored in the `req.rawBody` property.
-
-Learn more about [middlewares](https://docs.medusajs.com/learn/fundamentals/api-routes/middlewares/index.html.md).
-
-You can then access the raw body data in your API route handler:
-
-```ts title="src/api/custom/route.ts"
-import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
-
-export async function POST(
-  req: MedusaRequest,
-  res: MedusaResponse
-) {
-  console.log(req.rawBody)
-
-  // TODO use raw body
-}
-```
-
-***
-
-## Configure Request Body Size Limit
-
-By default, the body parser limits the request body size to `100kb`. If a request body exceeds that size, the Medusa application throws an error.
-
-You can configure the body parser to accept larger request bodies by setting the `sizeLimit` property of the `bodyParser` object in a middleware route object. For example:
-
-```ts title="src/api/middlewares.ts" highlights={sizeLimitHighlights}
-import { defineMiddlewares } from "@medusajs/framework/http"
-
-export default defineMiddlewares({
-  routes: [
-    {
-      method: ["POST"],
-      bodyParser: { sizeLimit: "2mb" },
-      matcher: "/custom",
-    },
-  ],
-})
-```
-
-The `sizeLimit` property accepts one of the following types of values:
-
-- A string representing the size limit in bytes (For example, `100kb`, `2mb`, `5gb`). It is passed to the [bytes](https://www.npmjs.com/package/bytes) library to parse the size.
-- A number representing the size limit in bytes. For example, `1024` for 1kb.
-
-***
-
-## Configure File Uploads
-
-To accept file uploads in your API routes, you can configure the [Express Multer middleware](https://expressjs.com/en/resources/middleware/multer.html) on your route.
-
-The `multer` package is available through the `@medusajs/medusa` package, so you don't need to install it. However, for better typing support, install the `@types/multer` package as a development dependency:
-
-```bash npm2yarn
-npm install --save-dev @types/multer
-```
-
-Then, to configure file upload for your route, create the file `src/api/middlewares.ts` with the following content:
-
-```ts title="src/api/middlewares.ts" highlights={uploadHighlights}
-import { defineMiddlewares } from "@medusajs/framework/http"
-import multer from "multer"
-
-const upload = multer({ storage: multer.memoryStorage() })
-
-export default defineMiddlewares({
-  routes: [
-    {
-      method: ["POST"],
-      matcher: "/custom",
-      middlewares: [
-        // @ts-ignore
-        upload.array("files"),
-      ],
-    },
-  ],
-})
-```
-
-In the example above, you configure the `multer` middleware to store the uploaded files in memory. Then, you apply the `upload.array("files")` middleware to the route to accept file uploads. By using the `array` method, you accept multiple file uploads with the same `files` field name.
-
-You can then access the uploaded files in your API route handler:
-
-```ts title="src/api/custom/route.ts"
-import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
-
-export async function POST(
-  req: MedusaRequest,
-  res: MedusaResponse
-) {
-  const files = req.files as Express.Multer.File[]
-
-  // TODO handle files
-}
-```
-
-The uploaded files are stored in the `req.files` property as an array of Multer file objects that have properties like `filename` and `mimetype`.
-
-### Uploading Files using File Module Provider
-
-The recommended way to upload the files to storage using the configured [File Module Provider](https://docs.medusajs.com/resources/infrastructure-modules/file/index.html.md) is to use the [uploadFilesWorkflow](https://docs.medusajs.com/resources/references/medusa-workflows/uploadFilesWorkflow/index.html.md):
-
-```ts title="src/api/custom/route.ts"
-import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
-import { MedusaError } from "@medusajs/framework/utils"
-import { uploadFilesWorkflow } from "@medusajs/medusa/core-flows"
-
-export async function POST(
-  req: MedusaRequest,
-  res: MedusaResponse
-) {
-  const files = req.files as Express.Multer.File[]
-
-  if (!files?.length) {
-    throw new MedusaError(
-      MedusaError.Types.INVALID_DATA,
-      "No files were uploaded"
-    )
-  }
-
-  const { result } = await uploadFilesWorkflow(req.scope).run({
-    input: {
-      files: files?.map((f) => ({
-        filename: f.originalname,
-        mimeType: f.mimetype,
-        content: f.buffer.toString("binary"),
-        access: "public",
-      })),
-    },
-  })
-
-  res.status(200).json({ files: result })
-}
-```
-
-Check out the [uploadFilesWorkflow reference](https://docs.medusajs.com/resources/references/medusa-workflows/uploadFilesWorkflow/index.html.md) for details on the expected input and output of the workflow.
-
-
-# API Route Response
-
-In this chapter, you'll learn how to send a response in your API route.
-
-## Send a JSON Response
-
-To send a JSON response, use the `json` method of the `MedusaResponse` object passed as the second parameter of your API route handler.
-
-For example:
-
-```ts title="src/api/custom/route.ts" highlights={jsonHighlights}
-import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
-
-export const GET = async (
-  req: MedusaRequest,
-  res: MedusaResponse
-) => {
-  res.json({
-    message: "Hello, World!",
-  })
-}
-```
-
-This API route returns the following JSON object:
-
-```json
-{
-  "message": "Hello, World!"
-}
-```
-
-***
-
-## Set Response Status Code
-
-By default, setting the JSON data using the `json` method returns a response with a `200` status code.
-
-To change the status code, use the `status` method of the `MedusaResponse` object.
-
-For example:
-
-```ts title="src/api/custom/route.ts" highlights={statusHighlight}
-import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
-
-export const GET = async (
-  req: MedusaRequest,
-  res: MedusaResponse
-) => {
-  res.status(201).json({
-    message: "Hello, World!",
-  })
-}
-```
-
-The response of this API route has the status code `201`.
-
-***
-
-## Change Response Content Type
-
-To return response data other than a JSON object, use the `writeHead` method of the `MedusaResponse` object. It allows you to set the response headers, including the content type.
-
-For example, to create an API route that returns an event stream:
-
-```ts highlights={streamHighlights}
-import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
-
-export const GET = async (
-  req: MedusaRequest,
-  res: MedusaResponse
-) => {
-  res.writeHead(200, {
-    "Content-Type": "text/event-stream",
-    "Cache-Control": "no-cache",
-    Connection: "keep-alive",
-  })
-
-  const interval = setInterval(() => {
-    res.write("Streaming data...\n")
-  }, 3000)
-
-  req.on("end", () => {
-    clearInterval(interval)
-    res.end()
-  })
-}
-```
-
-The `writeHead` method accepts two parameters:
-
-1. The first one is the response's status code.
-2. The second is an object of key-value pairs to set the headers of the response.
-
-This API route opens a stream by setting the `Content-Type` in the header to `text/event-stream`. It then simulates a stream by creating an interval that writes the stream data every three seconds.
-
-***
-
-## Do More with Responses
-
-The `MedusaResponse` type is based on [Express's Response](https://expressjs.com/en/api.html#res). Refer to their API reference for other uses of responses.
-
-
-# Retrieve Custom Links from Medusa's API Route
-
-In this chapter, you'll learn how to retrieve custom data models linked to existing Medusa data models from Medusa's API routes.
-
-## Why Retrieve Custom Linked Data Models?
-
-Often, you'll link custom data models to existing Medusa data models to implement custom features or expand on existing ones.
-
-For example, to add brands for products, you can create a `Brand` data model in a Brand Module, then [define a link](https://docs.medusajs.com/learn/fundamentals/module-links/index.html.md) to the [Product Module](https://docs.medusajs.com/resources/commerce-modules/product/index.html.md)'s `Product` data model.
-
-When you implement this customization, you might need to retrieve the brand of a product using the existing [Get Product API Route](https://docs.medusajs.com/api/admin#products_getproductsid). You can do this by passing the linked data model's name in the `fields` query parameter of the API route.
-
-***
-
-## How to Retrieve Custom Linked Data Models Using `fields`?
-
-Most of Medusa's API routes accept a `fields` query parameter that allows you to specify the fields and relations to retrieve in the resource, such as a product.
-
-For example, to retrieve the brand of a product, you can pass the `brand` field in the `fields` query parameter of the [Get Product API Route](https://docs.medusajs.com/api/admin#products_getproductsid):
-
-```bash
-curl 'http://localhost:9000/admin/products/{id}?fields=*brand' \
--H 'Authorization: Bearer {access_token}'
-```
-
-The `fields` query parameter accepts a comma-separated list of fields and relations to retrieve. To learn more about using the `fields` query parameter, refer to the [API Reference](https://docs.medusajs.com/api/store#select-fields-and-relations).
-
-By prefixing `brand` with an asterisk (`*`), you retrieve all the default fields of the product, including the `brand` field. If you don't include the `*` prefix, the response will only include the product's brand.
-
-***
-
-## API Routes that Restrict Retrievable Fields
-
-Some of Medusa's API routes restrict the fields and relations you can retrieve, which means you can't pass your custom linked data models in the `fields` query parameter. Medusa makes this restriction to ensure the API routes are performant and secure.
-
-The API routes that restrict the fields and relations you can retrieve are:
-
-- [Customer Store API Routes](https://docs.medusajs.com/api/store#customers)
-- [Customer Admin API Routes](https://docs.medusajs.com/api/admin#customers)
-- [Product Category Admin API Routes](https://docs.medusajs.com/api/admin#product-categories)
-
-### How to Override Allowed Fields and Relations
-
-For these routes, you need to override the allowed fields and relations to be retrieved. You can do this by adding a [middleware](https://docs.medusajs.com/learn/fundamentals/api-routes/middlewares/index.html.md) to those routes.
-
-For example, to allow retrieving the `b2b_company` of a customer using the [Get Customer Admin API Route](https://docs.medusajs.com/api/admin#customers_getcustomersid), create the file `src/api/middlewares.ts` with the following content:
-
-Learn how to create a middleware in the [Middlewares](https://docs.medusajs.com/learn/fundamentals/api-routes/middlewares/index.html.md) chapter.
-
-```ts title="src/api/middlewares.ts" highlights={highlights}
-import { defineMiddlewares } from "@medusajs/medusa";
-
-export default defineMiddlewares({
-  routes: [
-    {
-      matcher: "/store/customers/me",
-      method: "GET",
-      middlewares: [
-        (req, res, next) => {
-          req.allowed?.push("b2b_company");
-          next();
-        },
-      ],
-    },
-  ],
-});
-```
-
-In this example, you apply a middleware to the [Get Customer Admin API Route](https://docs.medusajs.com/api/admin#customers_getcustomersid).
-
-The request object passed to middlewares has an `allowed` property that contains the fields and relations that can be retrieved. So, you modify the `allowed` array to include the `b2b_company` field.
-
-You can now retrieve the `b2b_company` field using the `fields` query parameter of the [Get Customer Admin API Route](https://docs.medusajs.com/api/admin#customers_getcustomersid):
-
-```bash
-curl 'http://localhost:9000/admin/customers/{id}?fields=*b2b_company' \
--H 'Authorization: Bearer {access_token}'
-```
-
-In this example, you retrieve the `b2b_company` relation of the customer using the `fields` query parameter.
-
-
-# Event Data Payload
-
-In this chapter, you'll learn how subscribers receive an event's data payload.
-
-## Access Event's Data Payload
-
-When events are emitted, they’re emitted with a data payload.
-
-The object that the subscriber function receives as a parameter has an `event` property, which is an object holding the event payload in a `data` property with additional context.
-
-For example:
-
-```ts title="src/subscribers/product-created.ts" highlights={highlights} collapsibleLines="1-5" expandButtonLabel="Show Imports"
-import type {
-  SubscriberArgs,
-  SubscriberConfig,
-} from "@medusajs/framework"
-
-export default async function productCreateHandler({
-  event,
-}: SubscriberArgs<{ id: string }>) {
-  const productId = event.data.id
-  console.log(`The product ${productId} was created`)
-}
-
-export const config: SubscriberConfig = {
-  event: "product.created",
-}
-```
-
-The `event` object has the following properties:
-
-- data: (\`object\`) The data payload of the event. Its properties are different for each event.
-- name: (string) The name of the triggered event.
-- metadata: (\`object\`) Additional data and context of the emitted event.
-
-This logs the product ID received in the `product.created` event’s data payload to the console.
-
-{/* ---
-
-## List of Events with Data Payload
-
-Refer to [this reference](!resources!/events-reference) for a full list of events emitted by Medusa and their data payloads. */}
-
-
 # Emit Workflow and Service Events
 
 In this chapter, you'll learn about event types and how to emit an event in a service or workflow.
@@ -10782,6 +10892,51 @@ If you execute the `performAction` method of your service, the event is emitted
 Any subscribers listening to the event are also executed.
 
 
+# Event Data Payload
+
+In this chapter, you'll learn how subscribers receive an event's data payload.
+
+## Access Event's Data Payload
+
+When events are emitted, they’re emitted with a data payload.
+
+The object that the subscriber function receives as a parameter has an `event` property, which is an object holding the event payload in a `data` property with additional context.
+
+For example:
+
+```ts title="src/subscribers/product-created.ts" highlights={highlights} collapsibleLines="1-5" expandButtonLabel="Show Imports"
+import type {
+  SubscriberArgs,
+  SubscriberConfig,
+} from "@medusajs/framework"
+
+export default async function productCreateHandler({
+  event,
+}: SubscriberArgs<{ id: string }>) {
+  const productId = event.data.id
+  console.log(`The product ${productId} was created`)
+}
+
+export const config: SubscriberConfig = {
+  event: "product.created",
+}
+```
+
+The `event` object has the following properties:
+
+- data: (\`object\`) The data payload of the event. Its properties are different for each event.
+- name: (string) The name of the triggered event.
+- metadata: (\`object\`) Additional data and context of the emitted event.
+
+This logs the product ID received in the `product.created` event’s data payload to the console.
+
+{/* ---
+
+## List of Events with Data Payload
+
+Refer to [this reference](!resources!/events-reference) for a full list of events emitted by Medusa and their data payloads. */}
+
+
 # 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.
@@ -10940,316 +11095,6 @@ await link.create({
 ```
 
 
-# Request Body and Query Parameter Validation
-
-In this chapter, you'll learn how to validate request body and query parameters in your custom API route.
-
-## Request Validation
-
-Consider you're creating a `POST` API route at `/custom`. It accepts two parameters `a` and `b` that are required numbers, and returns their sum.
-
-Medusa provides two middlewares to validate the request body and query paramters of incoming requests to your custom API routes:
-
-- `validateAndTransformBody` to validate the request's body parameters against a schema.
-- `validateAndTransformQuery` to validate the request's query parameters against a schema.
-
-Both middlewares accept a [Zod](https://zod.dev/) schema as a parameter, which gives you flexibility in how you define your validation schema with complex rules.
-
-The next steps explain how to add request body and query parameter validation to the API route mentioned earlier.
-
-***
-
-## How to Validate Request Body
-
-### Step 1: Create Validation Schema
-
-Medusa uses [Zod](https://zod.dev/) to create validation schemas. These schemas are then used to validate incoming request bodies or query parameters.
-
-To create a validation schema with Zod, create a `validators.ts` file in any `src/api` subfolder. This file holds Zod schemas for each of your API routes.
-
-For example, create the file `src/api/custom/validators.ts` with the following content:
-
-```ts title="src/api/custom/validators.ts"
-import { z } from "zod"
-
-export const PostStoreCustomSchema = z.object({
-  a: z.number(),
-  b: z.number(),
-})
-```
-
-The `PostStoreCustomSchema` variable is a Zod schema that indicates the request body is valid if:
-
-1. It's an object.
-2. It has a property `a` that is a required number.
-3. It has a property `b` that is a required number.
-
-### Step 2: Add Request Body Validation Middleware
-
-To use this schema for validating the body parameters of requests to `/custom`, use the `validateAndTransformBody` middleware provided by `@medusajs/framework/http`. It accepts the Zod schema as a parameter.
-
-For example, create the file `src/api/middlewares.ts` with the following content:
-
-```ts title="src/api/middlewares.ts"
-import { 
-  defineMiddlewares,
-  validateAndTransformBody,
-} from "@medusajs/framework/http"
-import { PostStoreCustomSchema } from "./custom/validators"
-
-export default defineMiddlewares({
-  routes: [
-    {
-      matcher: "/custom",
-      method: "POST",
-      middlewares: [
-        validateAndTransformBody(PostStoreCustomSchema),
-      ],
-    },
-  ],
-})
-```
-
-This applies the `validateAndTransformBody` middleware on `POST` requests to `/custom`. It uses the `PostStoreCustomSchema` as the validation schema.
-
-#### How the Validation Works
-
-If a request's body parameters don't pass the validation, the `validateAndTransformBody` middleware throws an error indicating the validation errors.
-
-If a request's body parameters are validated successfully, the middleware sets the validated body parameters in the `validatedBody` property of `MedusaRequest`.
-
-### Step 3: Use Validated Body in API Route
-
-In your API route, consume the validated body using the `validatedBody` property of `MedusaRequest`.
-
-For example, create the file `src/api/custom/route.ts` with the following content:
-
-```ts title="src/api/custom/route.ts" highlights={routeHighlights}
-import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
-import { z } from "zod"
-import { PostStoreCustomSchema } from "./validators"
-
-type PostStoreCustomSchemaType = z.infer<
-  typeof PostStoreCustomSchema
->
-
-export const POST = async (
-  req: MedusaRequest<PostStoreCustomSchemaType>,
-  res: MedusaResponse
-) => {
-  res.json({
-    sum: req.validatedBody.a + req.validatedBody.b,
-  })
-}
-```
-
-In the API route, you use the `validatedBody` property of `MedusaRequest` to access the values of the `a` and `b` properties.
-
-To pass the request body's type as a type parameter to `MedusaRequest`, use Zod's `infer` type that accepts the type of a schema as a parameter.
-
-### Test it Out
-
-To test out the validation, send a `POST` request to `/custom` passing `a` and `b` body parameters. You can try sending incorrect request body parameters to test out the validation.
-
-For example, if you omit the `a` parameter, you'll receive a `400` response code with the following response data:
-
-```json
-{
-  "type": "invalid_data",
-  "message": "Invalid request: Field 'a' is required"
-}
-```
-
-***
-
-## How to Validate Request Query Parameters
-
-The steps to validate the request query parameters are the similar to that of [validating the body](#how-to-validate-request-body).
-
-### Step 1: Create Validation Schema
-
-The first step is to create a schema with Zod with the rules of the accepted query parameters.
-
-Consider that the API route accepts two query parameters `a` and `b` that are numbers, similar to the previous section.
-
-Create the file `src/api/custom/validators.ts` with the following content:
-
-```ts title="src/api/custom/validators.ts"
-import { z } from "zod"
-
-export const PostStoreCustomSchema = z.object({
-  a: z.preprocess(
-      (val) => {
-        if (val && typeof val === "string") {
-          return parseInt(val)
-        }
-        return val
-      },
-      z
-        .number()
-    ),
-  b: z.preprocess(
-    (val) => {
-      if (val && typeof val === "string") {
-        return parseInt(val)
-      }
-      return val
-    },
-    z
-      .number()
-  ),
-})
-```
-
-Since a query parameter's type is originally a string or array of strings, you have to use Zod's `preprocess` method to validate other query types, such as numbers.
-
-For both `a` and `b`, you transform the query parameter's value to an integer first if it's a string, then, you check that the resulting value is a number.
-
-### Step 2: Add Request Query Validation Middleware
-
-Next, you'll use the schema to validate incoming requests' query parameters to the `/custom` API route.
-
-Add the `validateAndTransformQuery` middleware to the API route in the file `src/api/middlewares.ts`:
-
-```ts title="src/api/middlewares.ts"
-import { 
-  validateAndTransformQuery,
-  defineMiddlewares,
-} from "@medusajs/framework/http"
-import { PostStoreCustomSchema } from "./custom/validators"
-
-export default defineMiddlewares({
-  routes: [
-    {
-      matcher: "/custom",
-      method: "POST",
-      middlewares: [
-        validateAndTransformQuery(
-          PostStoreCustomSchema,
-          {}
-        ),
-      ],
-    },
-  ],
-})
-```
-
-The `validateAndTransformQuery` accepts two parameters:
-
-- The first one is the Zod schema to validate the query parameters against.
-- The second one is an object of options for retrieving data using Query, which you can learn more about in [this chapter](https://docs.medusajs.com/learn/fundamentals/module-links/query/index.html.md).
-
-#### How the Validation Works
-
-If a request's query parameters don't pass the validation, the `validateAndTransformQuery` middleware throws an error indicating the validation errors.
-
-If a request's query parameters are validated successfully, the middleware sets the validated query parameters in the `validatedQuery` property of `MedusaRequest`.
-
-### Step 3: Use Validated Query in API Route
-
-Finally, use the validated query in the API route. The `MedusaRequest` parameter has a `validatedQuery` parameter that you can use to access the validated parameters.
-
-For example, create the file `src/api/custom/route.ts` with the following content:
-
-```ts title="src/api/custom/route.ts"
-import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
-
-export const GET = async (
-  req: MedusaRequest,
-  res: MedusaResponse
-) => {
-  const a = req.validatedQuery.a as number
-  const b = req.validatedQuery.b as number
-
-  res.json({
-    sum: a + b,
-  })
-}
-```
-
-In the API route, you use the `validatedQuery` property of `MedusaRequest` to access the values of the `a` and `b` properties as numbers, then return in the response their sum.
-
-### Test it Out
-
-To test out the validation, send a `POST` request to `/custom` with `a` and `b` query parameters. You can try sending incorrect query parameters to see how the validation works.
-
-For example, if you omit the `a` parameter, you'll receive a `400` response code with the following response data:
-
-```json
-{
-  "type": "invalid_data",
-  "message": "Invalid request: Field 'a' is required"
-}
-```
-
-***
-
-## Learn More About Validation Schemas
-
-To see different examples and learn more about creating a validation schema, refer to [Zod's documentation](https://zod.dev).
-
-
-# Module Link Direction
-
-In this chapter, you'll learn about the difference in module link directions, and which to use based on your use case.
-
-The details in this chapter don't apply to [Read-Only Module Links](https://docs.medusajs.com/learn/fundamentals/module-links/read-only/index.html.md). Refer to the [Read-Only Module Links chapter](https://docs.medusajs.com/learn/fundamentals/module-links/read-only/index.html.md) for more information on read-only links and their direction.
-
-## Link Direction
-
-The module link's direction depends on the order you pass the data model configuration parameters to `defineLink`.
-
-For example, the following defines a link from the Blog Module's `post` data model to the Product Module's `product` data model:
-
-```ts
-export default defineLink(
-  BlogModule.linkable.post,
-  ProductModule.linkable.product
-)
-```
-
-Whereas the following defines a link from the Product Module's `product` data model to the Blog Module's `post` data model:
-
-```ts
-export default defineLink(
-  ProductModule.linkable.product,
-  BlogModule.linkable.post
-)
-```
-
-The above links are two different links that serve different purposes.
-
-***
-
-## Which Link Direction to Use?
-
-### Extend Data Models
-
-If you're adding a link to a data model to extend it and add new fields, define the link from the main data model to the custom data model.
-
-For example, consider you want to add a `subtitle` custom field to the `product` data model. To do that, you define a `Subtitle` data model in your module, then define a link from the `Product` data model to it:
-
-```ts
-export default defineLink(
-  ProductModule.linkable.product,
-  BlogModule.linkable.subtitle
-)
-```
-
-### Associate Data Models
-
-If you're linking data models to indicate an association between them, define the link from the custom data model to the main data model.
-
-For example, consider you have `Post` data model representing a blog post, and you want to associate a blog post with a product. To do that, define a link from the `Post` data model to `Product`:
-
-```ts
-export default defineLink(
-  BlogModule.linkable.post,
-  ProductModule.linkable.product
-)
-```
-
-
 # Link
 
 In this chapter, you’ll learn what Link is and how to use it to manage links.
@@ -11454,737 +11299,66 @@ await link.restore({
 ```
 
 
-# Query Context
+# Module Link Direction
 
-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 about the difference in module link directions, and which to use based on your use case.
 
-## What is Query Context?
+The details in this chapter don't apply to [Read-Only Module Links](https://docs.medusajs.com/learn/fundamentals/module-links/read-only/index.html.md). Refer to the [Read-Only Module Links chapter](https://docs.medusajs.com/learn/fundamentals/module-links/read-only/index.html.md) for more information on read-only links and their direction.
 
-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.
+## Link Direction
 
-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).
+The module link's direction depends on the order you pass the data model configuration parameters to `defineLink`.
 
-***
+For example, the following defines a link from the Blog Module's `post` data model to the Product Module's `product` data model:
 
-## How to Use Query Context
+```ts
+export default defineLink(
+  BlogModule.linkable.post,
+  ProductModule.linkable.product
+)
+```
 
-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:
+Whereas the following defines a link from the Product Module's `product` data model to the Blog Module's `post` data model:
 
 ```ts
-const { data } = await query.graph({
-  entity: "post",
-  fields: ["*"],
-  context: QueryContext({
-    lang: "es",
-  }),
-})
-```
-
-In this example, you pass in the context a `lang` property whose value is `es`.
-
-Then, to handle the context while retrieving records of the data model, in the associated module's service you override the generated `list` method of the data model.
-
-For example, continuing the example above, you can override the `listPosts` method of the Blog Module's service to handle the context:
-
-```ts highlights={highlights2}
-import { MedusaContext, MedusaService } from "@medusajs/framework/utils"
-import { Context, FindConfig } from "@medusajs/framework/types"
-import Post from "./models/post"
-import Author from "./models/author"
-
-class BlogModuleService extends MedusaService({
-  Post,
-  Author,
-}){
-  // @ts-ignore
-  async listPosts(
-    filters?: any, 
-    config?: FindConfig<any> | undefined, 
-    @MedusaContext() sharedContext?: Context | undefined
-  ) {
-    const context = filters.context ?? {}
-    delete filters.context
-
-    let posts = await super.listPosts(filters, config, sharedContext)
-
-    if (context.lang === "es") {
-      posts = posts.map((post) => {
-        return {
-          ...post,
-          title: post.title + " en español",
-        }
-      })
-    }
-
-    return posts
-  }
-}
-
-export default BlogModuleService
-```
-
-In the above example, you override the generated `listPosts` method. This method receives as a first parameter the filters passed to the query, but it also includes a `context` property that holds the context passed to the query.
-
-You extract the context from `filters`, then retrieve the posts using the parent's `listPosts` method. After that, if the language is set in the context, you transform the titles of the posts.
-
-All posts returned will now have their titles appended with "en español".
-
-Learn more about the generated `list` method in [this reference](https://docs.medusajs.com/resources/service-factory-reference/methods/list/index.html.md).
-
-### Using Pagination with Query
-
-If you pass pagination fields to `query.graph`, you must also override the `listAndCount` method in the service.
-
-For example, following along with the previous example, you must override the `listAndCountPosts` method of the Blog Module's service:
-
-```ts
-import { MedusaContext, MedusaService } from "@medusajs/framework/utils"
-import { Context, FindConfig } from "@medusajs/framework/types"
-import Post from "./models/post"
-import Author from "./models/author"
-
-class BlogModuleService extends MedusaService({
-  Post,
-  Author,
-}){
-  // @ts-ignore
-  async listAndCountPosts(
-    filters?: any, 
-    config?: FindConfig<any> | undefined, 
-    @MedusaContext() sharedContext?: Context | undefined
-  ) {
-    const context = filters.context ?? {}
-    delete filters.context
-
-    const result = await super.listAndCountPosts(
-      filters, 
-      config, 
-      sharedContext
-    )
-
-    if (context.lang === "es") {
-      result.posts = posts.map((post) => {
-        return {
-          ...post,
-          title: post.title + " en español",
-        }
-      })
-    }
-
-    return result
-  }
-}
-
-export default BlogModuleService
-```
-
-Now, the `listAndCountPosts` method will handle the context passed to `query.graph` when you pass pagination fields. You can also move the logic to transform the posts' titles to a separate method and call it from both `listPosts` and `listAndCountPosts`.
-
-***
-
-## Passing Query Context to Related Data Models
-
-If you're retrieving a data model and you want to pass context to its associated model in the same module, you can pass them as part of `QueryContext`'s parameter, then handle them in the same `list` method.
-
-For linked data models, check out the [next section](#passing-query-context-to-linked-data-models).
-
-For example, to pass a context for the post's authors:
-
-```ts highlights={highlights3}
-const { data } = await query.graph({
-  entity: "post",
-  fields: ["*"],
-  context: QueryContext({
-    lang: "es",
-    author: QueryContext({
-      lang: "es",
-    }),
-  }),
-})
-```
-
-Then, in the `listPosts` method, you can handle the context for the post's authors:
-
-```ts highlights={highlights4}
-import { MedusaContext, MedusaService } from "@medusajs/framework/utils"
-import { Context, FindConfig } from "@medusajs/framework/types"
-import Post from "./models/post"
-import Author from "./models/author"
-
-class BlogModuleService extends MedusaService({
-  Post,
-  Author,
-}){
-  // @ts-ignore
-  async listPosts(
-    filters?: any, 
-    config?: FindConfig<any> | undefined, 
-    @MedusaContext() sharedContext?: Context | undefined
-  ) {
-    const context = filters.context ?? {}
-    delete filters.context
-
-    let posts = await super.listPosts(filters, config, sharedContext)
-
-    const isPostLangEs = context.lang === "es"
-    const isAuthorLangEs = context.author?.lang === "es"
-
-    if (isPostLangEs || isAuthorLangEs) {
-      posts = posts.map((post) => {
-        return {
-          ...post,
-          title: isPostLangEs ? post.title + " en español" : post.title,
-          author: {
-            ...post.author,
-            name: isAuthorLangEs ? post.author.name + " en español" : post.author.name,
-          },
-        }
-      })
-    }
-
-    return posts
-  }
-}
-
-export default BlogModuleService
-```
-
-The context in `filters` will also have the context for `author`, which you can use to make transformations to the post's authors.
-
-***
-
-## Passing Query Context to Linked Data Models
-
-If you're retrieving a data model and you want to pass context to a linked model in a different module, pass to the `context` property an object instead, where its keys are the linked model's name and the values are the context for that linked model.
-
-For example, consider the Product Module's `Product` data model is linked to the Blog Module's `Post` data model. You can pass context to the `Post` data model while retrieving products like so:
-
-```ts highlights={highlights5}
-const { data } = await query.graph({
-  entity: "product",
-  fields: ["*", "post.*"],
-  context: {
-    post: QueryContext({
-      lang: "es",
-    }),
-  },
-})
-```
-
-In this example, you retrieve products and their associated posts. You also pass a context for `post`, indicating the customer's language.
-
-To handle the context, you override the generated `listPosts` method of the Blog Module as explained [previously](#how-to-use-query-context).
-
-
-# Read-Only Module Link
-
-In this chapter, you’ll learn what a read-only module link is and how to define one.
-
-## What is a Read-Only Module Link?
-
-Consider a scenario where you need to access related records from another module, but don't want the overhead of managing or storing the links between them. This can include cases where you're working with external data models not stored in your Medusa database, such as third-party systems.
-
-In those cases, instead of defining a [Module Link](https://docs.medusajs.com/learn/fundamentals/module-links/index.html.md) whose linked records must be stored in a link table in the database, you can use a read-only module link. A read-only module link builds a virtual relation from one data model to another in a different module without creating a link table in the database. Instead, the linked record's ID is stored in the first data model's field.
-
-For example, Medusa creates a read-only module link from the `Cart` data model of the [Cart Module](https://docs.medusajs.com/resources/commerce-modules/cart/index.html.md) to the `Customer` data model of the [Customer Module](https://docs.medusajs.com/resources/commerce-modules/customer/index.html.md). This link allows you to access the details of the cart's customer without managing the link. Instead, the customer's ID is stored in the `Cart` data model.
-
-![Diagram illustrating the read-only module link from cart to customer](https://res.cloudinary.com/dza7lstvk/image/upload/v1742212508/Medusa%20Book/cart-customer_w6vk59.jpg)
-
-***
-
-## How to Define a Read-Only Module Link
-
-The `defineLink` function accepts an optional third-parameter object that can hold additional configurations for the module link.
-
-If you're not familiar with the `defineLink` function, refer to the [Module Links chapter](https://docs.medusajs.com/learn/fundamentals/module-links/index.html.md) for more information.
-
-To make the module link read-only, pass the `readOnly` property as `true`. You must also set in the link configuration of the first data model a `field` property that specifies the data model's field where the linked record's ID is stored.
-
-For example:
-
-```ts highlights={highlights}
-import BlogModule from "../modules/blog"
-import ProductModule from "@medusajs/medusa/product"
-import { defineLink } from "@medusajs/framework/utils"
-
 export default defineLink(
-  {
-    linkable: BlogModule.linkable.post,
-    field: "product_id",
-  },
   ProductModule.linkable.product,
-  {
-    readOnly: true,
-  }
+  BlogModule.linkable.post
 )
 ```
 
-In this example, you define a read-only module link from the Blog Module's `post` data model to the Product Module's `product` data model. You do that by:
-
-- Passing an object as a first parameter that accepts the linkable configuration and the field where the linked record's ID is stored.
-- Setting the `readOnly` property to `true` in the third parameter.
-
-Unlike the stored module link, Medusa will not create a table in the database for this link. Instead, Medusa uses the ID stored in the specified field of the first data model to retrieve the linked record.
+The above links are two different links that serve different purposes.
 
 ***
 
-## Retrieve Read-Only Linked Record
+## Which Link Direction to Use?
 
-[Query](https://docs.medusajs.com/learn/fundamentals/module-links/query/index.html.md) allows you to retrieve records linked through a read-only module link.
+### Extend Data Models
 
-For example, assuming you have the module link created in [the above section](#how-to-define-a-read-only-module-link), you can retrieve a post and its linked product as follows:
+If you're adding a link to a data model to extend it and add new fields, define the link from the main data model to the custom data model.
+
+For example, consider you want to add a `subtitle` custom field to the `product` data model. To do that, you define a `Subtitle` data model in your module, then define a link from the `Product` data model to it:
 
 ```ts
-const { result } = await query.graph({
-  entity: "post",
-  fields: ["id", "product.*"],
-  filters: {
-    id: "post_123",
-  },
-})
-```
-
-In the above example, you retrieve a post and its linked product. Medusa will use the ID of the product in the post's `product_id` field to determine which product should be retrieved.
-
-***
-
-## Read-Only Module Link Direction
-
-A read-only module is uni-directional. So, you can only retrieve the linked record from the first data model. If you need to access the linked record from the second data model, you must define another read-only module link in the opposite direction.
-
-In the `blog` -> `product` example, you can access a post's product, but you can't access a product's posts. You would have to define another read-only module link from `product` to `blog` to access a product's posts.
-
-***
-
-## Inverse Read-Only Module Link
-
-An inverse read-only module link is a read-only module link that allows you to access the linked record based on the ID stored in the second data model.
-
-For example, consider you want to access a product's posts. You can define a read-only module link from the Product Module's `product` data model to the Blog Module's `post` data model:
-
-```ts
-import BlogModule from "../modules/blog"
-import ProductModule from "@medusajs/medusa/product"
-import { defineLink } from "@medusajs/framework/utils"
-
 export default defineLink(
-  {
-    linkable: ProductModule.linkable.product,
-    field: "id",
-  },
-  {
-    ...BlogModule.linkable.post.id,
-    primaryKey: "product_id",
-  },
-  {
-    readOnly: true,
-  }
-)
-```
-
-In the above example, you define a read-only module link from the Product Module's `product` data model to the Blog Module's `post` data model. This link allows you to access a product's posts.
-
-Since you can't add a `post_id` field to the `product` data model, you must:
-
-1. Set the `field` property in the first data model's link configuration to the product's ID field.
-2. Spread the `BlogModule.linkable.post.id` object in the second parameter object and set the `primaryKey` property to the field in the `post` data model that holds the product's ID.
-
-You can now retrieve a product and its linked posts:
-
-```ts
-const { result } = await query.graph({
-  entity: "product",
-  fields: ["id", "post.*"],
-  filters: {
-    id: "prod_123",
-  },
-})
-```
-
-***
-
-## One-to-One or One-to-Many?
-
-When you retrieve the linked record through a read-only module link, the retrieved data may be an object (one-to-one) or an array of objects (one-to-many) based on different criteria.
-
-|Scenario|Relation Type|
-|---|---|---|
-|The first data model's |One-to-one relation|
-|The first data model's |One-to-many relation|
-|The read-only module link is inversed.|One-to-many relation if multiple records in the second data model have the same ID of the first data model. Otherwise, one-to-one relation.|
-
-### One-to-One Relation
-
-Consider the first read-only module link you defined in this chapter:
-
-```ts
-import BlogModule from "../modules/blog"
-import ProductModule from "@medusajs/medusa/product"
-
-export default defineLink(
-  {
-    linkable: BlogModule.linkable.post,
-    field: "product_id",
-  },
   ProductModule.linkable.product,
-  {
-    readOnly: true,
-  }
+  BlogModule.linkable.subtitle
 )
 ```
 
-Since the `product_id` field of a post stores the ID of a single product, the link is a one-to-one relation. When querying a post, you'll get a single product object:
+### Associate Data Models
 
-```json title="Example Data"
-[
-  {
-    "id": "post_123",
-    "product_id": "prod_123",
-    "product": {
-      "id": "prod_123",
-      // ...
-    }
-  }
-]
-```
+If you're linking data models to indicate an association between them, define the link from the custom data model to the main data model.
 
-### One-to-Many Relation
-
-Consider the read-only module link from the `post` data model uses an array of product IDs:
+For example, consider you have `Post` data model representing a blog post, and you want to associate a blog post with a product. To do that, define a link from the `Post` data model to `Product`:
 
 ```ts
-import BlogModule from "../modules/blog"
-import ProductModule from "@medusajs/medusa/product"
-
 export default defineLink(
-  {
-    linkable: BlogModule.linkable.post,
-    field: "product_ids",
-  },
-  ProductModule.linkable.product,
-  {
-    readOnly: true,
-  }
+  BlogModule.linkable.post,
+  ProductModule.linkable.product
 )
 ```
 
-Where `product_ids` in the `post` data model is an array of strings. In this case, the link would be a one-to-many relation. So, an array of products would be returned when querying a post:
-
-```json title="Example Data"
-[
-  {
-    "id": "post_123",
-    "product_ids": ["prod_123", "prod_124"],
-    "product": [
-      {
-        "id": "prod_123",
-        // ...
-      },
-      {
-        "id": "prod_124",
-        // ...
-      }
-    ]
-  }
-]
-```
-
-### Relation with Inversed Read-Only Link
-
-If you define an inversed read-only module link where the ID of the linked record is stored in the second data model, the link can be either one-to-one or one-to-many based on the number of records in the second data model that have the same ID of the first data model.
-
-For example, consider the `product` -> `post` link you defined in an earlier section:
-
-```ts
-import BlogModule from "../modules/blog"
-import ProductModule from "@medusajs/medusa/product"
-import { defineLink } from "@medusajs/framework/utils"
-
-export default defineLink(
-  {
-    linkable: ProductModule.linkable.product,
-    field: "id",
-  },
-  {
-    ...BlogModule.linkable.post.id,
-    primaryKey: "product_id",
-  },
-  {
-    readOnly: true,
-  }
-)
-```
-
-In the above snippet, the ID of the product is stored in the `post`'s `product_id` string field.
-
-When you retrieve the post of a product, it may be a post object, or an array of post objects if multiple posts are linked to the product:
-
-```json title="Example Data"
-[
-  {
-    "id": "prod_123",
-    "post": {
-      "id": "post_123",
-      "product_id": "prod_123"
-      // ...
-    }
-  },
-  {
-    "id": "prod_321",
-    "post": [
-      {
-        "id": "post_123",
-        "product_id": "prod_321"
-        // ...
-      },
-      {
-        "id": "post_124",
-        "product_id": "prod_321"
-        // ...
-      }
-    ]
-  }
-]
-```
-
-If, however, you use an array field in `post`, the relation would always be one-to-many:
-
-```json title="Example Data"
-[
-  {
-    "id": "prod_123",
-    "post": [
-      {
-        "id": "post_123",
-        "product_id": "prod_123"
-        // ...
-      }
-    ]
-  }
-]
-```
-
-#### Force One-to-Many Relation
-
-Alternatively, you can force a one-to-many relation by setting `isList` to `true` in the first data model's link configuration. For example:
-
-```ts
-import BlogModule from "../modules/blog"
-import ProductModule from "@medusajs/medusa/product"
-import { defineLink } from "@medusajs/framework/utils"
-
-export default defineLink(
-  {
-    linkable: ProductModule.linkable.product,
-    field: "id",
-    isList: true,
-  },
-  {
-    ...BlogModule.linkable.post.id,
-    primaryKey: "product_id",
-  },
-  {
-    readOnly: true,
-  }
-)
-```
-
-In this case, the relation would always be one-to-many, even if only one post is linked to a product:
-
-```json title="Example Data"
-[
-  {
-    "id": "prod_123",
-    "post": [
-      {
-        "id": "post_123",
-        "product_id": "prod_123"
-        // ...
-      }
-    ]
-  }
-]
-```
-
-***
-
-## Example: Read-Only Module Link for Virtual Data Models
-
-Read-only module links are most useful when working with data models that aren't stored in your Medusa database. For example, data that is stored in a third-party system. In those cases, you can define a read-only module link between a data model in Medusa and the data model in the external system, facilitating the retrieval of the linked data.
-
-To define the read-only module link to a virtual data model, you must:
-
-1. Create a `list` method in the custom module's service. This method retrieves the linked records filtered by the ID(s) of the first data model.
-   - You can also create a `listAndCount` method to retrieve the related records with pagination.
-2. Define the read-only module link from the first data model to the virtual data model.
-3. Use Query to retrieve the first data model and its linked records from the virtual data model.
-
-For example, consider you have a third-party Content-Management System (CMS) that you're integrating with Medusa, and you want to retrieve the posts in the CMS associated with a product in Medusa.
-
-To do that, first, create a CMS Module having the following service:
-
-Refer to the [Modules chapter](https://docs.medusajs.com/learn/fundamentals/modules/index.html.md) to learn how to create a module and its service.
-
-```ts title="src/modules/cms/service.ts"
-import { FindConfig } from "@medusajs/framework/types"
-
-type CmsModuleOptions = {
-  apiKey: string
-}
-
-export default class CmsModuleService {
-  private client
-
-  constructor({}, options: CmsModuleOptions) {
-    this.client = new Client(options)
-  }
-
-  async list(
-    filter: {
-      id: string | string[]
-    }
-  ) {
-    return this.client.getPosts(filter)
-    /**
-     - Example of returned data:
-     - 
-     - [
-     -   {
-     -     "id": "post_123",
-     -     "product_id": "prod_321"
-     -   },
-     -   {
-     -     "id": "post_456",
-     -     "product_id": "prod_654"
-     -   }
-     - ]
-    */
-  }
-
-  // To retrieve with pagination
-  async listAndCount(
-    filter: {
-      id: string | string[]
-    },
-    config?: FindConfig<any> | undefined, 
-  ) {
-    return this.client.getPosts(filter, {
-      limit: config?.take,
-      offset: config?.skip,
-    })
-    /**
-     - Example of returned data:
-     - 
-     - {
-     -   count: 2,
-     -   data: [
-     -     {
-     -       "id": "post_123",
-     -       "product_id": "prod_321"
-     -     },
-     -     {
-     -       "id": "post_456",
-     -       "product_id": "prod_654"
-     -     }
-     -   ]
-     - }
-    */
-  }
-}
-```
-
-The above service initializes a client, assuming your CMS has an SDK that allows you to retrieve posts.
-
-The service must have a `list` method to be part of the read-only module link. This method accepts the ID(s) of the products to retrieve their associated posts. The posts must include the product's ID in a field, such as `product_id`.
-
-You can also create a `listAndCount` method to retrieve the posts with pagination. This method is called if you pass [pagination parameters to Query](https://docs.medusajs.com/learn/fundamentals/module-links/query#apply-pagination/index.html.md).
-
-Next, define a read-only module link from the Product Module to the CMS Module:
-
-```ts title="src/links/product-cms.ts"
-import { defineLink } from "@medusajs/framework/utils"
-import ProductModule from "@medusajs/medusa/product"
-import { CMS_MODULE } from "../modules/cms"
-
-export default defineLink(
-  {
-    linkable: ProductModule.linkable.product,
-    field: "id",
-  },
-  {
-    linkable: {
-      serviceName: CMS_MODULE,
-      alias: "cms_post",
-      primaryKey: "product_id",
-    },
-  },
-  {
-    readOnly: true,
-  }
-)
-```
-
-To define the read-only module link, you must pass to `defineLink`:
-
-1. The first parameter: an object with the linkable configuration of the data model in Medusa, and the fields that will be passed as a filter to the CMS service. For example, if you want to filter by product title instead, you can pass `title` instead of `id`.
-2. The second parameter: an object with the linkable configuration of the virtual data model in the CMS. This object must have the following properties:
-   - `serviceName`: The name of the service, which is the CMS Module's name. Medusa uses this name to resolve the module's service from the [Medusa container](https://docs.medusajs.com/learn/fundamentals/medusa-container/index.html.md).
-   - `alias`: The alias to use when querying the linked records. You'll see how that works in a bit.
-   - `primaryKey`: The field in the CMS data model that holds the ID of a product.
-3. The third parameter: an object with the `readOnly` property set to `true`.
-
-Now, you can use Query to retrieve a product and its linked post from the CMS:
-
-```ts
-const { data } = await query.graph({
-  entity: "product",
-  fields: ["id", "cms_post.*"],
-})
-```
-
-In the above example, each product that has a CMS post with the `product_id` field set to the product's ID will be retrieved:
-
-```json title="Example Data"
-[
-  {
-    "id": "prod_123",
-    "cms_post": {
-      "id": "post_123",
-      "product_id": "prod_123",
-      // ...
-    }
-  }
-]
-```
-
-If multiple posts have their `product_id` set to a product's ID, an array of posts is returned instead:
-
-```json title="Example Data"
-[
-  {
-    "id": "prod_123",
-    "cms_post": [
-      {
-        "id": "post_123",
-        "product_id": "prod_123",
-        // ...
-      },
-      {
-        "id": "post_124",
-        "product_id": "prod_123",
-        // ...
-      }
-    ]
-  }
-]
-```
-
-[Sanity Integration Tutorial](https://docs.medusajs.com/resources/integrations/guides/sanity/index.html.md).
-
 
 # Query
 
@@ -12742,6 +11916,232 @@ 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
+
+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).
+
+
 # Create a Plugin
 
 In this chapter, you'll learn how to create a Medusa plugin and publish it.
@@ -13176,6 +12576,807 @@ npm publish
 This will publish an updated version of your plugin under a new version.
 
 
+# Read-Only Module Link
+
+In this chapter, you’ll learn what a read-only module link is and how to define one.
+
+## What is a Read-Only Module Link?
+
+Consider a scenario where you need to access related records from another module, but don't want the overhead of managing or storing the links between them. This can include cases where you're working with external data models not stored in your Medusa database, such as third-party systems.
+
+In those cases, instead of defining a [Module Link](https://docs.medusajs.com/learn/fundamentals/module-links/index.html.md) whose linked records must be stored in a link table in the database, you can use a read-only module link. A read-only module link builds a virtual relation from one data model to another in a different module without creating a link table in the database. Instead, the linked record's ID is stored in the first data model's field.
+
+For example, Medusa creates a read-only module link from the `Cart` data model of the [Cart Module](https://docs.medusajs.com/resources/commerce-modules/cart/index.html.md) to the `Customer` data model of the [Customer Module](https://docs.medusajs.com/resources/commerce-modules/customer/index.html.md). This link allows you to access the details of the cart's customer without managing the link. Instead, the customer's ID is stored in the `Cart` data model.
+
+![Diagram illustrating the read-only module link from cart to customer](https://res.cloudinary.com/dza7lstvk/image/upload/v1742212508/Medusa%20Book/cart-customer_w6vk59.jpg)
+
+***
+
+## How to Define a Read-Only Module Link
+
+The `defineLink` function accepts an optional third-parameter object that can hold additional configurations for the module link.
+
+If you're not familiar with the `defineLink` function, refer to the [Module Links chapter](https://docs.medusajs.com/learn/fundamentals/module-links/index.html.md) for more information.
+
+To make the module link read-only, pass the `readOnly` property as `true`. You must also set in the link configuration of the first data model a `field` property that specifies the data model's field where the linked record's ID is stored.
+
+For example:
+
+```ts highlights={highlights}
+import BlogModule from "../modules/blog"
+import ProductModule from "@medusajs/medusa/product"
+import { defineLink } from "@medusajs/framework/utils"
+
+export default defineLink(
+  {
+    linkable: BlogModule.linkable.post,
+    field: "product_id",
+  },
+  ProductModule.linkable.product,
+  {
+    readOnly: true,
+  }
+)
+```
+
+In this example, you define a read-only module link from the Blog Module's `post` data model to the Product Module's `product` data model. You do that by:
+
+- Passing an object as a first parameter that accepts the linkable configuration and the field where the linked record's ID is stored.
+- Setting the `readOnly` property to `true` in the third parameter.
+
+Unlike the stored module link, Medusa will not create a table in the database for this link. Instead, Medusa uses the ID stored in the specified field of the first data model to retrieve the linked record.
+
+***
+
+## Retrieve Read-Only Linked Record
+
+[Query](https://docs.medusajs.com/learn/fundamentals/module-links/query/index.html.md) allows you to retrieve records linked through a read-only module link.
+
+For example, assuming you have the module link created in [the above section](#how-to-define-a-read-only-module-link), you can retrieve a post and its linked product as follows:
+
+```ts
+const { result } = await query.graph({
+  entity: "post",
+  fields: ["id", "product.*"],
+  filters: {
+    id: "post_123",
+  },
+})
+```
+
+In the above example, you retrieve a post and its linked product. Medusa will use the ID of the product in the post's `product_id` field to determine which product should be retrieved.
+
+***
+
+## Read-Only Module Link Direction
+
+A read-only module is uni-directional. So, you can only retrieve the linked record from the first data model. If you need to access the linked record from the second data model, you must define another read-only module link in the opposite direction.
+
+In the `blog` -> `product` example, you can access a post's product, but you can't access a product's posts. You would have to define another read-only module link from `product` to `blog` to access a product's posts.
+
+***
+
+## Inverse Read-Only Module Link
+
+An inverse read-only module link is a read-only module link that allows you to access the linked record based on the ID stored in the second data model.
+
+For example, consider you want to access a product's posts. You can define a read-only module link from the Product Module's `product` data model to the Blog Module's `post` data model:
+
+```ts
+import BlogModule from "../modules/blog"
+import ProductModule from "@medusajs/medusa/product"
+import { defineLink } from "@medusajs/framework/utils"
+
+export default defineLink(
+  {
+    linkable: ProductModule.linkable.product,
+    field: "id",
+  },
+  {
+    ...BlogModule.linkable.post.id,
+    primaryKey: "product_id",
+  },
+  {
+    readOnly: true,
+  }
+)
+```
+
+In the above example, you define a read-only module link from the Product Module's `product` data model to the Blog Module's `post` data model. This link allows you to access a product's posts.
+
+Since you can't add a `post_id` field to the `product` data model, you must:
+
+1. Set the `field` property in the first data model's link configuration to the product's ID field.
+2. Spread the `BlogModule.linkable.post.id` object in the second parameter object and set the `primaryKey` property to the field in the `post` data model that holds the product's ID.
+
+You can now retrieve a product and its linked posts:
+
+```ts
+const { result } = await query.graph({
+  entity: "product",
+  fields: ["id", "post.*"],
+  filters: {
+    id: "prod_123",
+  },
+})
+```
+
+***
+
+## One-to-One or One-to-Many?
+
+When you retrieve the linked record through a read-only module link, the retrieved data may be an object (one-to-one) or an array of objects (one-to-many) based on different criteria.
+
+|Scenario|Relation Type|
+|---|---|---|
+|The first data model's |One-to-one relation|
+|The first data model's |One-to-many relation|
+|The read-only module link is inversed.|One-to-many relation if multiple records in the second data model have the same ID of the first data model. Otherwise, one-to-one relation.|
+
+### One-to-One Relation
+
+Consider the first read-only module link you defined in this chapter:
+
+```ts
+import BlogModule from "../modules/blog"
+import ProductModule from "@medusajs/medusa/product"
+
+export default defineLink(
+  {
+    linkable: BlogModule.linkable.post,
+    field: "product_id",
+  },
+  ProductModule.linkable.product,
+  {
+    readOnly: true,
+  }
+)
+```
+
+Since the `product_id` field of a post stores the ID of a single product, the link is a one-to-one relation. When querying a post, you'll get a single product object:
+
+```json title="Example Data"
+[
+  {
+    "id": "post_123",
+    "product_id": "prod_123",
+    "product": {
+      "id": "prod_123",
+      // ...
+    }
+  }
+]
+```
+
+### One-to-Many Relation
+
+Consider the read-only module link from the `post` data model uses an array of product IDs:
+
+```ts
+import BlogModule from "../modules/blog"
+import ProductModule from "@medusajs/medusa/product"
+
+export default defineLink(
+  {
+    linkable: BlogModule.linkable.post,
+    field: "product_ids",
+  },
+  ProductModule.linkable.product,
+  {
+    readOnly: true,
+  }
+)
+```
+
+Where `product_ids` in the `post` data model is an array of strings. In this case, the link would be a one-to-many relation. So, an array of products would be returned when querying a post:
+
+```json title="Example Data"
+[
+  {
+    "id": "post_123",
+    "product_ids": ["prod_123", "prod_124"],
+    "product": [
+      {
+        "id": "prod_123",
+        // ...
+      },
+      {
+        "id": "prod_124",
+        // ...
+      }
+    ]
+  }
+]
+```
+
+### Relation with Inversed Read-Only Link
+
+If you define an inversed read-only module link where the ID of the linked record is stored in the second data model, the link can be either one-to-one or one-to-many based on the number of records in the second data model that have the same ID of the first data model.
+
+For example, consider the `product` -> `post` link you defined in an earlier section:
+
+```ts
+import BlogModule from "../modules/blog"
+import ProductModule from "@medusajs/medusa/product"
+import { defineLink } from "@medusajs/framework/utils"
+
+export default defineLink(
+  {
+    linkable: ProductModule.linkable.product,
+    field: "id",
+  },
+  {
+    ...BlogModule.linkable.post.id,
+    primaryKey: "product_id",
+  },
+  {
+    readOnly: true,
+  }
+)
+```
+
+In the above snippet, the ID of the product is stored in the `post`'s `product_id` string field.
+
+When you retrieve the post of a product, it may be a post object, or an array of post objects if multiple posts are linked to the product:
+
+```json title="Example Data"
+[
+  {
+    "id": "prod_123",
+    "post": {
+      "id": "post_123",
+      "product_id": "prod_123"
+      // ...
+    }
+  },
+  {
+    "id": "prod_321",
+    "post": [
+      {
+        "id": "post_123",
+        "product_id": "prod_321"
+        // ...
+      },
+      {
+        "id": "post_124",
+        "product_id": "prod_321"
+        // ...
+      }
+    ]
+  }
+]
+```
+
+If, however, you use an array field in `post`, the relation would always be one-to-many:
+
+```json title="Example Data"
+[
+  {
+    "id": "prod_123",
+    "post": [
+      {
+        "id": "post_123",
+        "product_id": "prod_123"
+        // ...
+      }
+    ]
+  }
+]
+```
+
+#### Force One-to-Many Relation
+
+Alternatively, you can force a one-to-many relation by setting `isList` to `true` in the first data model's link configuration. For example:
+
+```ts
+import BlogModule from "../modules/blog"
+import ProductModule from "@medusajs/medusa/product"
+import { defineLink } from "@medusajs/framework/utils"
+
+export default defineLink(
+  {
+    linkable: ProductModule.linkable.product,
+    field: "id",
+    isList: true,
+  },
+  {
+    ...BlogModule.linkable.post.id,
+    primaryKey: "product_id",
+  },
+  {
+    readOnly: true,
+  }
+)
+```
+
+In this case, the relation would always be one-to-many, even if only one post is linked to a product:
+
+```json title="Example Data"
+[
+  {
+    "id": "prod_123",
+    "post": [
+      {
+        "id": "post_123",
+        "product_id": "prod_123"
+        // ...
+      }
+    ]
+  }
+]
+```
+
+***
+
+## Example: Read-Only Module Link for Virtual Data Models
+
+Read-only module links are most useful when working with data models that aren't stored in your Medusa database. For example, data that is stored in a third-party system. In those cases, you can define a read-only module link between a data model in Medusa and the data model in the external system, facilitating the retrieval of the linked data.
+
+To define the read-only module link to a virtual data model, you must:
+
+1. Create a `list` method in the custom module's service. This method retrieves the linked records filtered by the ID(s) of the first data model.
+   - You can also create a `listAndCount` method to retrieve the related records with pagination.
+2. Define the read-only module link from the first data model to the virtual data model.
+3. Use Query to retrieve the first data model and its linked records from the virtual data model.
+
+For example, consider you have a third-party Content-Management System (CMS) that you're integrating with Medusa, and you want to retrieve the posts in the CMS associated with a product in Medusa.
+
+To do that, first, create a CMS Module having the following service:
+
+Refer to the [Modules chapter](https://docs.medusajs.com/learn/fundamentals/modules/index.html.md) to learn how to create a module and its service.
+
+```ts title="src/modules/cms/service.ts"
+import { FindConfig } from "@medusajs/framework/types"
+
+type CmsModuleOptions = {
+  apiKey: string
+}
+
+export default class CmsModuleService {
+  private client
+
+  constructor({}, options: CmsModuleOptions) {
+    this.client = new Client(options)
+  }
+
+  async list(
+    filter: {
+      id: string | string[]
+    }
+  ) {
+    return this.client.getPosts(filter)
+    /**
+     - Example of returned data:
+     - 
+     - [
+     -   {
+     -     "id": "post_123",
+     -     "product_id": "prod_321"
+     -   },
+     -   {
+     -     "id": "post_456",
+     -     "product_id": "prod_654"
+     -   }
+     - ]
+    */
+  }
+
+  // To retrieve with pagination
+  async listAndCount(
+    filter: {
+      id: string | string[]
+    },
+    config?: FindConfig<any> | undefined, 
+  ) {
+    return this.client.getPosts(filter, {
+      limit: config?.take,
+      offset: config?.skip,
+    })
+    /**
+     - Example of returned data:
+     - 
+     - {
+     -   count: 2,
+     -   data: [
+     -     {
+     -       "id": "post_123",
+     -       "product_id": "prod_321"
+     -     },
+     -     {
+     -       "id": "post_456",
+     -       "product_id": "prod_654"
+     -     }
+     -   ]
+     - }
+    */
+  }
+}
+```
+
+The above service initializes a client, assuming your CMS has an SDK that allows you to retrieve posts.
+
+The service must have a `list` method to be part of the read-only module link. This method accepts the ID(s) of the products to retrieve their associated posts. The posts must include the product's ID in a field, such as `product_id`.
+
+You can also create a `listAndCount` method to retrieve the posts with pagination. This method is called if you pass [pagination parameters to Query](https://docs.medusajs.com/learn/fundamentals/module-links/query#apply-pagination/index.html.md).
+
+Next, define a read-only module link from the Product Module to the CMS Module:
+
+```ts title="src/links/product-cms.ts"
+import { defineLink } from "@medusajs/framework/utils"
+import ProductModule from "@medusajs/medusa/product"
+import { CMS_MODULE } from "../modules/cms"
+
+export default defineLink(
+  {
+    linkable: ProductModule.linkable.product,
+    field: "id",
+  },
+  {
+    linkable: {
+      serviceName: CMS_MODULE,
+      alias: "cms_post",
+      primaryKey: "product_id",
+    },
+  },
+  {
+    readOnly: true,
+  }
+)
+```
+
+To define the read-only module link, you must pass to `defineLink`:
+
+1. The first parameter: an object with the linkable configuration of the data model in Medusa, and the fields that will be passed as a filter to the CMS service. For example, if you want to filter by product title instead, you can pass `title` instead of `id`.
+2. The second parameter: an object with the linkable configuration of the virtual data model in the CMS. This object must have the following properties:
+   - `serviceName`: The name of the service, which is the CMS Module's name. Medusa uses this name to resolve the module's service from the [Medusa container](https://docs.medusajs.com/learn/fundamentals/medusa-container/index.html.md).
+   - `alias`: The alias to use when querying the linked records. You'll see how that works in a bit.
+   - `primaryKey`: The field in the CMS data model that holds the ID of a product.
+3. The third parameter: an object with the `readOnly` property set to `true`.
+
+Now, you can use Query to retrieve a product and its linked post from the CMS:
+
+```ts
+const { data } = await query.graph({
+  entity: "product",
+  fields: ["id", "cms_post.*"],
+})
+```
+
+In the above example, each product that has a CMS post with the `product_id` field set to the product's ID will be retrieved:
+
+```json title="Example Data"
+[
+  {
+    "id": "prod_123",
+    "cms_post": {
+      "id": "post_123",
+      "product_id": "prod_123",
+      // ...
+    }
+  }
+]
+```
+
+If multiple posts have their `product_id` set to a product's ID, an array of posts is returned instead:
+
+```json title="Example Data"
+[
+  {
+    "id": "prod_123",
+    "cms_post": [
+      {
+        "id": "post_123",
+        "product_id": "prod_123",
+        // ...
+      },
+      {
+        "id": "post_124",
+        "product_id": "prod_123",
+        // ...
+      }
+    ]
+  }
+]
+```
+
+[Sanity Integration Tutorial](https://docs.medusajs.com/resources/integrations/guides/sanity/index.html.md).
+
+
+# Data Model Relationships
+
+In this chapter, you’ll learn how to define relationships between data models in your module.
+
+## What is a Relationship Property?
+
+A relationship property defines an association in the database between two models. It's created using the Data Model Language (DML) methods, such as `hasOne` or `belongsTo`.
+
+When you generate a migration for these data models, the migrations include foreign key columns or pivot tables, based on the relationship's type.
+
+You want to create a relation between data models in the same module.
+
+You want to create a relationship between data models in different modules. Use module links instead.
+
+***
+
+## One-to-One Relationship
+
+A one-to-one relationship indicates that one record of a data model belongs to or is associated with another.
+
+To define a one-to-one relationship, create relationship properties in the data models using the following methods:
+
+1. `hasOne`: indicates that the model has one record of the specified model.
+2. `belongsTo`: indicates that the model belongs to one record of the specified model.
+
+For example:
+
+```ts highlights={oneToOneHighlights}
+import { model } from "@medusajs/framework/utils"
+
+const User = model.define("user", {
+  id: model.id().primaryKey(),
+  email: model.hasOne(() => Email),
+})
+
+const Email = model.define("email", {
+  id: model.id().primaryKey(),
+  user: model.belongsTo(() => User, {
+    mappedBy: "email",
+  }),
+})
+```
+
+In the example above, a user has one email, and an email belongs to one user.
+
+The `hasOne` and `belongsTo` methods accept a function as the first parameter. The function returns the associated data model.
+
+The `belongsTo` method also requires passing as a second parameter an object with the property `mappedBy`. Its value is the name of the relationship property in the other data model.
+
+### Optional Relationship
+
+To make the relationship optional on the `hasOne` or `belongsTo` side, use the `nullable` method on either property as explained in [this chapter](https://docs.medusajs.com/learn/fundamentals/data-models/properties#make-property-optional/index.html.md).
+
+### One-sided One-to-One Relationship
+
+If the one-to-one relationship is only defined on one side, pass `undefined` to the `mappedBy` property in the `belongsTo` method.
+
+For example:
+
+```ts highlights={oneToOneUndefinedHighlights}
+import { model } from "@medusajs/framework/utils"
+
+const User = model.define("user", {
+  id: model.id().primaryKey(),
+})
+
+const Email = model.define("email", {
+  id: model.id().primaryKey(),
+  user: model.belongsTo(() => User, {
+    mappedBy: undefined,
+  }),
+})
+```
+
+### One-to-One Relationship in the Database
+
+When you generate the migrations of data models that have a one-to-one relationship, the migration adds to the table of the data model that has the `belongsTo` property:
+
+1. A column of the format `{relation_name}_id` to store the ID of the record of the related data model. For example, the `email` table will have a `user_id` column.
+2. A foreign key on the `{relation_name}_id` column to the table of the related data model.
+
+![Diagram illustrating the relation between user and email records in the database](https://res.cloudinary.com/dza7lstvk/image/upload/v1726733492/Medusa%20Book/one-to-one_cj5np3.jpg)
+
+***
+
+## One-to-Many Relationship
+
+A one-to-many relationship indicates that one record of a data model has many records of another data model.
+
+To define a one-to-many relationship, create relationship properties in the data models using the following methods:
+
+1. `hasMany`: indicates that the model has more than one record of the specified model.
+2. `belongsTo`: indicates that the model belongs to one record of the specified model.
+
+For example:
+
+```ts highlights={oneToManyHighlights}
+import { model } from "@medusajs/framework/utils"
+
+const Store = model.define("store", {
+  id: model.id().primaryKey(),
+  products: model.hasMany(() => Product),
+})
+
+const Product = model.define("product", {
+  id: model.id().primaryKey(),
+  store: model.belongsTo(() => Store, {
+    mappedBy: "products",
+  }),
+})
+```
+
+In this example, a store has many products, but a product belongs to one store.
+
+### Optional Relationship
+
+To make the relationship optional on the `belongsTo` side, use the `nullable` method on the property as explained in [this chapter](https://docs.medusajs.com/learn/fundamentals/data-models/properties#make-property-optional/index.html.md).
+
+### One-to-Many Relationship in the Database
+
+When you generate the migrations of data models that have a one-to-many relationship, the migration adds to the table of the data model that has the `belongsTo` property:
+
+1. A column of the format `{relation_name}_id` to store the ID of the record of the related data model. For example, the `product` table will have a `store_id` column.
+2. A foreign key on the `{relation_name}_id` column to the table of the related data model.
+
+![Diagram illustrating the relation between a store and product records in the database](https://res.cloudinary.com/dza7lstvk/image/upload/v1726733937/Medusa%20Book/one-to-many_d6wtcw.jpg)
+
+***
+
+## Many-to-Many Relationship
+
+A many-to-many relationship indicates that many records of a data model can be associated with many records of another data model.
+
+To define a many-to-many relationship, create relationship properties in the data models using the `manyToMany` method.
+
+For example:
+
+```ts highlights={manyToManyHighlights}
+import { model } from "@medusajs/framework/utils"
+
+const Order = model.define("order", {
+  id: model.id().primaryKey(),
+  products: model.manyToMany(() => Product, {
+    mappedBy: "orders",
+    pivotTable: "order_product",
+    joinColumn: "order_id",
+    inverseJoinColumn: "product_id",
+  }),
+})
+
+const Product = model.define("product", {
+  id: model.id().primaryKey(),
+  orders: model.manyToMany(() => Order, {
+    mappedBy: "products",
+  }),
+})
+```
+
+The `manyToMany` method accepts two parameters:
+
+1. A function that returns the associated data model.
+2. An object of optional configuration. Only one of the data models in the relation can define the `pivotTable`, `joinColumn`, and `inverseJoinColumn` configurations, and it's considered the owner data model. The object can accept the following properties:
+   - `mappedBy`: The name of the relationship property in the other data model. If not set, the property's name is inferred from the associated data model's name.
+   - `pivotTable`: The name of the pivot table created in the database for the many-to-many relation. If not set, the pivot table is inferred by combining the names of the data models' tables in alphabetical order, separating them by `_`, and pluralizing the last name. For example, `order_products`.
+   - `joinColumn`: The name of the column in the pivot table that points to the owner model's primary key.
+   - `inverseJoinColumn`: The name of the column in the pivot table that points to the owned model's primary key.
+
+The `pivotTable`, `joinColumn`, and `inverseJoinColumn` properties are only available after [Medusa v2.0.7](https://github.com/medusajs/medusa/releases/tag/v2.0.7).
+
+Following [Medusa v2.1.0](https://github.com/medusajs/medusa/releases/tag/v2.1.0), if `pivotTable`, `joinColumn`, and `inverseJoinColumn` aren't specified on either model, the owner is decided based on alphabetical order. So, in the example above, the `Order` data model would be the owner.
+
+In this example, an order is associated with many products, and a product is associated with many orders. Since the `pivotTable`, `joinColumn`, and `inverseJoinColumn` configurations are defined on the order, it's considered the owner data model.
+
+### Many-to-Many Relationship in the Database
+
+When you generate the migrations of data models that have a many-to-many relationship, the migration adds a new pivot table. Its name is either the name you specify in the `pivotTable` configuration or the inferred name combining the names of the data models' tables in alphabetical order, separating them by `_`, and pluralizing the last name. For example, `order_products`.
+
+The pivot table has a column with the name `{data_model}_id` for each of the data model's tables. It also has foreign keys on each of these columns to their respective tables.
+
+The pivot table has columns with foreign keys pointing to the primary key of the associated tables. The column's name is either:
+
+- The value of the `joinColumn` configuration for the owner table, and the `inverseJoinColumn` configuration for the owned table;
+- Or the inferred name `{table_name}_id`.
+
+![Diagram illustrating the relation between order and product records in the database](https://res.cloudinary.com/dza7lstvk/image/upload/v1726734269/Medusa%20Book/many-to-many_fzy5pq.jpg)
+
+### Many-To-Many with Custom Columns
+
+To add custom columns to the pivot table between two data models having a many-to-many relationship, you must define a new data model that represents the pivot table.
+
+For example:
+
+```ts highlights={manyToManyColumnHighlights}
+import { model } from "@medusajs/framework/utils"
+
+export const Order = model.define("order_test", {
+  id: model.id().primaryKey(),
+  products: model.manyToMany(() => Product, {
+    pivotEntity: () => OrderProduct,
+  }),
+})
+
+export const Product = model.define("product_test", {
+  id: model.id().primaryKey(),
+  orders: model.manyToMany(() => Order),
+})
+
+export const OrderProduct = model.define("orders_products", {
+  id: model.id().primaryKey(),
+  order: model.belongsTo(() => Order, {
+    mappedBy: "products",
+  }),
+  product: model.belongsTo(() => Product, {
+    mappedBy: "orders",
+  }),
+  metadata: model.json().nullable(),
+})
+```
+
+The `Order` and `Product` data models have a many-to-many relationship. To add extra columns to the created pivot table, you pass a `pivotEntity` option to the `products` relation in `Order` (since `Order` is the owner). The value of `pivotEntity` is a function that returns the data model representing the pivot table.
+
+The `OrderProduct` model defines, aside from the ID, the following properties:
+
+- `order`: A relation that indicates this model belongs to the `Order` data model. You set the `mappedBy` option to the many-to-many relation's name in the `Order` data model.
+- `product`: A relation that indicates this model belongs to the `Product` data model. You set the `mappedBy` option to the many-to-many relation's name in the `Product` data model.
+- `metadata`: An extra column to add to the pivot table of type `json`. You can add other columns as well to the model.
+
+***
+
+## Set Relationship Name in the Other Model
+
+The relationship property methods accept as a second parameter an object of options. The `mappedBy` property defines the name of the relationship in the other data model.
+
+This is useful if the relationship property’s name is different from that of the associated data model.
+
+As seen in previous examples, the `mappedBy` option is required for the `belongsTo` method.
+
+For example:
+
+```ts highlights={relationNameHighlights}
+import { model } from "@medusajs/framework/utils"
+
+const User = model.define("user", {
+  id: model.id().primaryKey(),
+  email: model.hasOne(() => Email, {
+    mappedBy: "owner",
+  }),
+})
+
+const Email = model.define("email", {
+  id: model.id().primaryKey(),
+  owner: model.belongsTo(() => User, {
+    mappedBy: "email",
+  }),
+})
+```
+
+In this example, you specify in the `User` data model’s relationship property that the name of the relationship in the `Email` data model is `owner`.
+
+***
+
+## Cascades
+
+When an operation is performed on a data model, such as record deletion, the relationship cascade specifies what related data model records should be affected by it.
+
+For example, if a store is deleted, its products should also be deleted.
+
+The `cascades` method used on a data model configures which child records an operation is cascaded to.
+
+For example:
+
+```ts highlights={highlights}
+import { model } from "@medusajs/framework/utils"
+
+const Store = model.define("store", {
+  id: model.id().primaryKey(),
+  products: model.hasMany(() => Product),
+})
+.cascades({
+  delete: ["products"],
+})
+
+const Product = model.define("product", {
+  id: model.id().primaryKey(),
+  store: model.belongsTo(() => Store, {
+    mappedBy: "products",
+  }),
+})
+```
+
+The `cascades` method accepts an object. Its key is the operation’s name, such as `delete`. The value is an array of relationship property names that the operation is cascaded to.
+
+In the example above, when a store is deleted, its associated products are also deleted.
+
+
 # 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.
@@ -13206,6 +13407,1687 @@ So, it'll only execute 3 times, each every minute, then it won't be executed any
 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.
+
+
+# Module Container
+
+In this chapter, you'll learn about the module's container and how to resolve resources in that container.
+
+Since modules are isolated, each module has a local container only used by the resources of that module.
+
+So, resources in the module, such as services or loaders, can only resolve other resources registered in the module's container.
+
+### List of Registered Resources
+
+Find a list of resources or dependencies registered in a module's container in [the Container Resources reference](https://docs.medusajs.com/resources/medusa-container-resources/index.html.md).
+
+***
+
+## Resolve Resources
+
+### Services
+
+A service's constructor accepts as a first parameter an object used to resolve resources registered in the module's container.
+
+For example:
+
+```ts highlights={[["4"], ["10"]]}
+import { Logger } from "@medusajs/framework/types"
+
+type InjectedDependencies = {
+  logger: Logger
+}
+
+export default class BlogModuleService {
+  protected logger_: Logger
+
+  constructor({ logger }: InjectedDependencies) {
+    this.logger_ = logger
+
+    this.logger_.info("[BlogModuleService]: Hello World!")
+  }
+
+  // ...
+}
+```
+
+### Loader
+
+A loader function accepts as a parameter an object having the property `container`. Its value is the module's container used to resolve resources.
+
+For example:
+
+```ts highlights={[["9"]]}
+import {
+  LoaderOptions,
+} from "@medusajs/framework/types"
+import { 
+  ContainerRegistrationKeys,
+} from "@medusajs/framework/utils"
+
+export default async function helloWorldLoader({
+  container,
+}: LoaderOptions) {
+  const logger = container.resolve(ContainerRegistrationKeys.LOGGER)
+
+  logger.info("[helloWorldLoader]: Hello, World!")
+}
+```
+
+
+# Perform Database Operations in a Service
+
+In this chapter, you'll learn how to perform database operations in a module's service.
+
+This chapter is intended for more advanced database use-cases where you need more control over queries and operations. For basic database operations, such as creating or retrieving data of a model, use the [Service Factory](https://docs.medusajs.com/learn/fundamentals/modules/service-factory/index.html.md) instead.
+
+## Run Queries
+
+[MikroORM's entity manager](https://mikro-orm.io/docs/entity-manager) is a class that has methods to run queries on the database and perform operations.
+
+Medusa provides an `InjectManager` decorator from the Modules SDK that injects a service's method with a [forked entity manager](https://mikro-orm.io/docs/identity-map#forking-entity-manager).
+
+So, to run database queries in a service:
+
+1. Add the `InjectManager` decorator to the method.
+2. Add as a last parameter an optional `sharedContext` parameter that has the `MedusaContext` decorator from the Modules SDK. This context holds database-related context, including the manager injected by `InjectManager`
+
+For example, in your service, add the following methods:
+
+```ts highlights={methodsHighlight}
+// other imports...
+import { 
+  InjectManager,
+  MedusaContext,
+} from "@medusajs/framework/utils"
+import { Context } from "@medusajs/framework/types"
+import { EntityManager } from "@mikro-orm/knex"
+
+class BlogModuleService {
+  // ...
+
+  @InjectManager()
+  async getCount(
+    @MedusaContext() sharedContext?: Context<EntityManager>
+  ): Promise<number | undefined> {
+    return await sharedContext?.manager?.count("my_custom")
+  }
+  
+  @InjectManager()
+  async getCountSql(
+    @MedusaContext() sharedContext?: Context<EntityManager>
+  ): Promise<number> {
+    const data = await sharedContext?.manager?.execute(
+      "SELECT COUNT(*) as num FROM my_custom"
+    ) 
+    
+    return parseInt(data?.[0].num || 0)
+  }
+}
+```
+
+You add two methods `getCount` and `getCountSql` that have the `InjectManager` decorator. Each of the methods also accept the `sharedContext` parameter which has the `MedusaContext` decorator.
+
+The entity manager is injected to the `sharedContext.manager` property, which is an instance of [EntityManager from the @mikro-orm/knex package](https://mikro-orm.io/api/knex/class/EntityManager).
+
+You use the manager in the `getCount` method to retrieve the number of records in a table, and in the `getCountSql` to run a PostgreSQL query that retrieves the count.
+
+Refer to [MikroORM's reference](https://mikro-orm.io/api/knex/class/EntityManager) for a full list of the entity manager's methods.
+
+***
+
+## Perform Database Operations
+
+There are two ways to perform database operations in transactional methods:
+
+1. Using the [data model repositories](#perform-database-operations-with-data-model-repositories) in your module.
+2. Using the [transactional entity manager](#perform-database-operations-with-the-transactional-entity-manager) injected into the method's shared context.
+
+For both approaches, you must wrap the method performing the database operations in a transaction.
+
+### Wrap Database Operations in Transactions
+
+When performing database operations without using the [Service Factory](https://docs.medusajs.com/learn/fundamentals/modules/service-factory/index.html.md), you must wrap the method performing the database operations in a transaction.
+
+To wrap database operations in a transaction, you create two methods:
+
+1. A private or protected method that's wrapped in a transaction. To wrap it in a transaction, you use the `InjectTransactionManager` decorator from the Modules SDK.
+2. A public method that calls the transactional method. You use on it the `InjectManager` decorator as explained in the previous section.
+
+Both methods must accept as a last parameter an optional `sharedContext` parameter that has the `MedusaContext` decorator from the Modules SDK. It holds database-related contexts passed through the Medusa application.
+
+For example:
+
+```ts highlights={opHighlights}
+import { 
+  InjectManager,
+  InjectTransactionManager,
+  MedusaContext,
+} from "@medusajs/framework/utils"
+import { Context } from "@medusajs/framework/types"
+import { EntityManager } from "@mikro-orm/knex"
+
+class BlogModuleService {
+  // ...
+  @InjectTransactionManager()
+  protected async update_(
+    input: {
+      id: string,
+      name: string
+    },
+    @MedusaContext() sharedContext?: Context<EntityManager>
+  ): Promise<any> {
+    const transactionManager = sharedContext?.transactionManager
+    
+    // TODO: update the record
+  }
+
+  @InjectManager()
+  async update(
+    input: {
+      id: string,
+      name: string
+    },
+    @MedusaContext() sharedContext?: Context<EntityManager>
+  ) {
+    return await this.update_(input, sharedContext)
+  }
+}
+```
+
+The `BlogModuleService` has two methods:
+
+- A protected `update_` that performs the database operations inside a transaction.
+- A public `update` that executes the transactional protected method.
+
+You can then perform in the transactional method the database operations either using the [data model repository](#perform-database-operations-with-data-model-repositories) or the [transactional entity manager](#perform-database-operations-with-the-transactional-entity-manager).
+
+#### Why Wrap a Transactional Method
+
+The variables in the transactional method (such as `update_`) hold values that are uncommitted to the database. They're only committed once the method finishes execution.
+
+So, if in your method you perform database operations, then use their result to perform other actions, such as connecting to a third-party service, you'll be working with uncommitted data.
+
+By placing only the database operations in a method that has the `InjectTransactionManager` and using it in a wrapper method, the wrapper method receives the committed result of the transactional method.
+
+This is also useful if you perform heavy data normalization outside of the database operations. In that case, you don't hold the transaction for a longer time than needed.
+
+For example, the `update` method may call other methods than `update_` to perform other actions:
+
+```ts
+// other imports...
+import { 
+  InjectManager,
+  InjectTransactionManager,
+  MedusaContext,
+} from "@medusajs/framework/utils"
+import { Context } from "@medusajs/framework/types"
+import { EntityManager } from "@mikro-orm/knex"
+
+class BlogModuleService {
+  // ...
+  @InjectTransactionManager()
+  protected async update_(
+    // ...
+  ): Promise<any> {
+    // ...
+  }
+  @InjectManager()
+  async update(
+    input: {
+      id: string,
+      name: string
+    },
+    @MedusaContext() sharedContext?: Context<EntityManager>
+  ) {
+    const newData = await this.update_(input, sharedContext)
+
+    // example method that sends data to another system
+    await this.sendNewDataToSystem(newData)
+
+    return newData
+  }
+}
+```
+
+In this case, only the `update_` method is wrapped in a transaction. The returned value `newData` holds the committed result, which can be used for other operations, such as passed to a `sendNewDataToSystem` method.
+
+#### Using Methods in Transactional Methods
+
+If your protected transactional method uses other methods that accept a Medusa context, pass the shared context to those methods.
+
+For example:
+
+```ts highlights={anotherMethodHighlights}
+// other imports...
+import { 
+  InjectTransactionManager,
+  MedusaContext,
+} from "@medusajs/framework/utils"
+import { Context } from "@medusajs/framework/types"
+import { EntityManager } from "@mikro-orm/knex"
+
+class BlogModuleService {
+  // ...
+  @InjectTransactionManager()
+  protected async anotherMethod(
+    @MedusaContext() sharedContext?: Context<EntityManager>
+  ) {
+    // ...
+  }
+  
+  @InjectTransactionManager()
+  protected async update_(
+    input: {
+      id: string,
+      name: string
+    },
+    @MedusaContext() sharedContext?: Context<EntityManager>
+  ): Promise<any> {
+    this.anotherMethod(sharedContext)
+  }
+}
+```
+
+You use the `anotherMethod` transactional method in the `update_` transactional method, so you pass it the shared context.
+
+The `anotherMethod` now runs in the same transaction as the `update_` method.
+
+### Perform Database Operations with Data Model Repositories
+
+For every data model in your module, Medusa generates a data model repository that has methods to perform database operations.
+
+For example, if your module has a `Post` model, it has a `postRepository` in the container.
+
+The data model repository is a wrapper around the [entity manager](https://mikro-orm.io/api/knex/class/EntityManager) that provides a higher-level API for performing database operations.
+
+To use the low-level entity manager, use the [transactional entity manager](#perform-database-operations-with-the-transactional-entity-manager) instead.
+
+#### Resolve Data Model Repository
+
+When the Medusa application injects a data model repository into a module's container, it formats the registration name by:
+
+- Taking the data model's name that's passed as the first parameter of `model.define`
+- Lower-casing the first character
+- Suffixing the result with `Repository`.
+
+For example:
+
+- `Post` model: `postRepository`
+- `My_Custom` model: `my_CustomRepository`
+
+So, to resolve a data model repository from a module's container, pass the expected registration name of the repository in the first parameter of the module's constructor (the container).
+
+For example:
+
+### Extending Service Factory
+
+```ts highlights={serviceFactoryRepoHighlights}
+import { MedusaService } from "@medusajs/framework/utils"
+import { InferTypeOf, DAL } from "@medusajs/framework/types"
+import Post from "./models/post"
+
+type Post = InferTypeOf<typeof Post>
+
+type InjectedDependencies = {
+  postRepository: DAL.RepositoryService<Post>
+}
+
+class BlogModuleService extends MedusaService({
+  Post,
+}){
+  protected postRepository_: DAL.RepositoryService<Post>
+
+  constructor({ 
+    postRepository 
+  }: InjectedDependencies) {
+    super(...arguments)
+    this.postRepository_ = postRepository
+  }
+}
+
+export default BlogModuleService
+```
+
+### Without Service Factory
+
+```ts highlights={noServiceFactoryRepoHighlights}
+import { InferTypeOf, DAL } from "@medusajs/framework/types"
+import Post from "./models/post"
+
+type Post = InferTypeOf<typeof Post>
+
+type InjectedDependencies = {
+  postRepository: DAL.RepositoryService<Post>
+}
+
+class BlogModuleService {
+  protected postRepository_: DAL.RepositoryService<Post>
+
+  constructor({ 
+    postRepository 
+  }: InjectedDependencies) {
+    super(...arguments)
+    this.postRepository_ = postRepository
+  }
+}
+
+export default BlogModuleService
+```
+
+You can then use the data model repository in your service to perform database operations.
+
+#### Data Model Repository Methods
+
+A data model repository has methods that allows you to create, update, and delete records, among other operations.
+
+To learn about the methods available in a data model repository, refer to the [Data Model Repository](https://docs.medusajs.com/resources/data-model-repository-reference/index.html.md) reference.
+
+### Perform Database Operations with the Transactional Entity Manager
+
+Your transactional method can use the transactional entity manager injected into the method's shared context to perform database operations. It's an instance of the [MikroORM EntityManager](https://mikro-orm.io/api/knex/class/EntityManager) class.
+
+To use an easier higher-level API focused on each data model, use the [data model repository](#perform-database-operations-with-data-model-repositories) instead.
+
+For example:
+
+```ts highlights={transactionalEntityManagerHighlights}
+import { 
+  InjectManager,
+  InjectTransactionManager,
+  MedusaContext,
+} from "@medusajs/framework/utils"
+import { Context } from "@medusajs/framework/types"
+import { EntityManager } from "@mikro-orm/knex"
+
+class BlogModuleService {
+  // ...
+  @InjectTransactionManager()
+  protected async update_(
+    input: {
+      id: string,
+      name: string
+    },
+    @MedusaContext() sharedContext?: Context<EntityManager>
+  ): Promise<any> {
+    const transactionManager = sharedContext?.transactionManager
+    await transactionManager?.nativeUpdate(
+      "my_custom",
+      {
+        id: input.id,
+      },
+      {
+        name: input.name,
+      }
+    )
+
+    // retrieve again
+    const updatedRecord = await transactionManager?.execute(
+      `SELECT * FROM my_custom WHERE id = '${input.id}'`
+    )
+
+    return updatedRecord
+  }
+
+  @InjectManager()
+  async update(
+    input: {
+      id: string,
+      name: string
+    },
+    @MedusaContext() sharedContext?: Context<EntityManager>
+  ) {
+    return await this.update_(input, sharedContext)
+  }
+}
+```
+
+The `update_` method uses the transactional entity manager injected into the `sharedContext.transactionManager` property to perform the database operations.
+
+Find all available methods in the [MikroORM EntityManager](https://mikro-orm.io/api/knex/class/EntityManager) reference.
+
+***
+
+## Configure Transactions with the Base Repository
+
+To configure the transaction, such as its [isolation level](https://www.postgresql.org/docs/current/transaction-iso.html), use the `baseRepository` class registered in your module's container.
+
+The `baseRepository` is an instance of a repository class that provides methods to create transactions, run database operations, and more.
+
+The `baseRepository` has a `transaction` method that allows you to run a function within a transaction and configure that transaction.
+
+For example, resolve the `baseRepository` in your service's constructor:
+
+### Extending Service Factory
+
+```ts highlights={baseRepoHighlights}
+import { MedusaService } from "@medusajs/framework/utils"
+import Post from "./models/post"
+import { DAL } from "@medusajs/framework/types"
+
+type InjectedDependencies = {
+  baseRepository: DAL.RepositoryService
+}
+
+class BlogModuleService extends MedusaService({
+  Post,
+}){
+  protected baseRepository_: DAL.RepositoryService
+
+  constructor({ baseRepository }: InjectedDependencies) {
+    super(...arguments)
+    this.baseRepository_ = baseRepository
+  }
+}
+
+export default BlogModuleService
+```
+
+### Without Service Factory
+
+```ts highlights={noServiceFactoryBaseRepoHighlights}
+import { DAL } from "@medusajs/framework/types"
+
+type InjectedDependencies = {
+  baseRepository: DAL.RepositoryService
+}
+
+class BlogModuleService {
+  protected baseRepository_: DAL.RepositoryService
+
+  constructor({ baseRepository }: InjectedDependencies) {
+    this.baseRepository_ = baseRepository
+  }
+}
+
+export default BlogModuleService
+```
+
+Then, use it in the service's transactional methods:
+
+```ts highlights={repoHighlights}
+// ...
+import { 
+  InjectManager,
+  InjectTransactionManager,
+  MedusaContext,
+} from "@medusajs/framework/utils"
+import { Context } from "@medusajs/framework/types"
+import { EntityManager } from "@mikro-orm/knex"
+
+class BlogModuleService {
+  // ...
+  @InjectTransactionManager()
+  protected async update_(
+    input: {
+      id: string,
+      name: string
+    },
+    @MedusaContext() sharedContext?: Context<EntityManager>
+  ): Promise<any> {
+    return await this.baseRepository_.transaction(
+      async (transactionManager) => {
+        await transactionManager.nativeUpdate(
+          "my_custom",
+          {
+            id: input.id,
+          },
+          {
+            name: input.name,
+          }
+        )
+
+        // retrieve again
+        const updatedRecord = await transactionManager.execute(
+          `SELECT * FROM my_custom WHERE id = '${input.id}'`
+        )
+
+        return updatedRecord
+      },
+      {
+        transaction: sharedContext?.transactionManager,
+      }
+    )
+  }
+
+  @InjectManager()
+  async update(
+    input: {
+      id: string,
+      name: string
+    },
+    @MedusaContext() sharedContext?: Context<EntityManager>
+  ) {
+    return await this.update_(input, sharedContext)
+  }
+}
+```
+
+The `update_` method uses the `baseRepository_.transaction` method to wrap a function in a transaction.
+
+The function parameter receives a transactional entity manager as a parameter. Use it to perform the database operations.
+
+The `baseRepository_.transaction` method also receives as a second parameter an object of options. You must pass in it the `transaction` property and set its value to the `sharedContext.transactionManager` property so that the function wrapped in the transaction uses the injected transaction manager.
+
+Refer to [MikroORM's reference](https://mikro-orm.io/api/knex/class/EntityManager) for a full list of the entity manager's methods.
+
+### Transaction Options
+
+The second parameter of the `baseRepository_.transaction` method is an object of options that accepts the following properties:
+
+1. `transaction`: Set the transactional entity manager passed to the function. You must provide this option as explained in the previous section.
+
+```ts highlights={[["24"]]}
+// other imports...
+import { EntityManager } from "@mikro-orm/knex"
+import { 
+  InjectTransactionManager,
+  MedusaContext,
+} from "@medusajs/framework/utils"
+import { Context } from "@medusajs/framework/types"
+
+class BlogModuleService {
+  // ...
+  @InjectTransactionManager()
+  async update_(
+    input: {
+      id: string,
+      name: string
+    },
+    @MedusaContext() sharedContext?: Context<EntityManager>
+  ): Promise<any> {
+    return await this.baseRepository_.transaction<EntityManager>(
+      async (transactionManager) => {
+        // ...
+      },
+      {
+        transaction: sharedContext?.transactionManager,
+      }
+    )
+  }
+}
+```
+
+2. `isolationLevel`: Sets the transaction's [isolation level](https://www.postgresql.org/docs/current/transaction-iso.html). Its values can be:
+   - `read committed`
+   - `read uncommitted`
+   - `snapshot`
+   - `repeatable read`
+   - `serializable`
+
+```ts highlights={[["25"]]}
+// other imports...
+import { 
+  InjectTransactionManager,
+  MedusaContext,
+} from "@medusajs/framework/utils"
+import { Context } from "@medusajs/framework/types"
+import { EntityManager } from "@mikro-orm/knex"
+import { IsolationLevel } from "@mikro-orm/core"
+
+class BlogModuleService {
+  // ...
+  @InjectTransactionManager()
+  async update_(
+    input: {
+      id: string,
+      name: string
+    },
+    @MedusaContext() sharedContext?: Context<EntityManager>
+  ): Promise<any> {
+    return await this.baseRepository_.transaction<EntityManager>(
+      async (transactionManager) => {
+        // ...
+      },
+      {
+        isolationLevel: IsolationLevel.READ_COMMITTED,
+      }
+    )
+  }
+}
+```
+
+3. `enableNestedTransactions`: (default: `false`) whether to allow using nested transactions.
+   - If `transaction` is provided and this is disabled, the manager in `transaction` is re-used.
+
+```ts highlights={[["24"]]}
+// other imports...
+import { 
+  InjectTransactionManager,
+  MedusaContext,
+} from "@medusajs/framework/utils"
+import { Context } from "@medusajs/framework/types"
+import { EntityManager } from "@mikro-orm/knex"
+
+class BlogModuleService {
+  // ...
+  @InjectTransactionManager()
+  async update_(
+    input: {
+      id: string,
+      name: string
+    },
+    @MedusaContext() sharedContext?: Context<EntityManager>
+  ): Promise<any> {
+    return await this.baseRepository_.transaction<EntityManager>(
+      async (transactionManager) => {
+        // ...
+      },
+      {
+        enableNestedTransactions: false,
+      }
+    )
+  }
+}
+```
+
+
+# Infrastructure Modules
+
+In this chapter, you’ll learn about Infrastructure Modules.
+
+## What is an Infrastructure Module?
+
+An Infrastructure Module implements features and mechanisms related to the Medusa application’s architecture and infrastructure.
+
+Since modules are interchangeable, you have more control over Medusa’s architecture. For example, you can choose to use Memcached for event handling instead of Redis.
+
+***
+
+## Infrastructure Module Types
+
+There are different Infrastructure Module types including:
+
+![Diagram illustrating how the modules connect to third-party services](https://res.cloudinary.com/dza7lstvk/image/upload/v1727095814/Medusa%20Book/infrastructure-modules_bj9bb9.jpg)
+
+- Cache Module: Defines the caching mechanism or logic to cache computational results.
+- Event Module: Integrates a pub/sub service to handle subscribing to and emitting events.
+- Workflow Engine Module: Integrates a service to store and track workflow executions and steps.
+- File Module: Integrates a storage service to handle uploading and managing files.
+- Notification Module: Integrates a third-party service or defines custom logic to send notifications to users and customers.
+- Locking Module: Integrates a service that manages access to shared resources by multiple processes or threads.
+
+***
+
+## Infrastructure Modules List
+
+Refer to the [Infrastructure Modules reference](https://docs.medusajs.com/resources/infrastructure-modules/index.html.md) for a list of Medusa’s Infrastructure Modules, available modules to install, and how to create an Infrastructure Module.
+
+
+# Loaders
+
+In this chapter, you’ll learn about loaders and how to use them.
+
+## What is a Loader?
+
+When building a commerce application, you'll often need to execute an action the first time the application starts. For example, if your application needs to connect to databases other than Medusa's PostgreSQL database, you might need to establish a connection on application startup.
+
+In Medusa, you can execute an action when the application starts using a loader. A loader is a function exported by a [module](https://docs.medusajs.com/learn/fundamentals/modules/index.html.md), which is a package of business logic for a single domain. When the Medusa application starts, it executes all loaders exported by configured modules.
+
+Loaders are useful to register custom resources, such as database connections, in the [module's container](https://docs.medusajs.com/learn/fundamentals/modules/container/index.html.md), which is similar to the [Medusa container](https://docs.medusajs.com/learn/fundamentals/medusa-container/index.html.md) but includes only [resources available to the module](https://docs.medusajs.com/resources/medusa-container-resources#module-container-resources/index.html.md). Modules are isolated, so they can't access resources outside of them, such as a service in another module.
+
+Medusa isolates modules to ensure that they're re-usable across applications, aren't tightly coupled to other resources, and don't have implications when integrated into the Medusa application. Learn more about why modules are isolated in [this chapter](https://docs.medusajs.com/learn/fundamentals/modules/isolation/index.html.md), and check out [this reference for the list of resources in the module's container](https://docs.medusajs.com/resources/medusa-container-resources#module-container-resources/index.html.md).
+
+***
+
+## How to Create a Loader?
+
+### 1. Implement Loader Function
+
+You create a loader function in a TypeScript or JavaScript file under a module's `loaders` directory.
+
+For example, consider you have a `hello` module, you can create a loader at `src/modules/hello/loaders/hello-world.ts` with the following content:
+
+![Example of loader file in the application's directory structure](https://res.cloudinary.com/dza7lstvk/image/upload/v1732865671/Medusa%20Book/loader-dir-overview_eg6vtu.jpg)
+
+Learn how to create a module in [this chapter](https://docs.medusajs.com/learn/fundamentals/modules/index.html.md).
+
+```ts title="src/modules/hello/loaders/hello-world.ts"
+import {
+  LoaderOptions,
+} from "@medusajs/framework/types"
+
+export default async function helloWorldLoader({
+  container,
+}: LoaderOptions) {
+  const logger = container.resolve("logger")
+
+  logger.info("[HELLO MODULE] Just started the Medusa application!")
+}
+```
+
+The loader file exports an async function, which is the function executed when the application loads.
+
+The function receives an object parameter that has a `container` property, which is the module's container that you can use to resolve resources from. In this example, you resolve the Logger utility to log a message in the terminal.
+
+Find the list of resources in the module's container in [this reference](https://docs.medusajs.com/resources/medusa-container-resources#module-container-resources/index.html.md).
+
+### 2. Export Loader in Module Definition
+
+After implementing the loader, you must export it in the module's definition in the `index.ts` file at the root of the module's directory. Otherwise, the Medusa application will not run it.
+
+So, to export the loader you implemented above in the `hello` module, add the following to `src/modules/hello/index.ts`:
+
+```ts title="src/modules/hello/index.ts"
+// other imports...
+import helloWorldLoader from "./loaders/hello-world"
+
+export default Module("hello", {
+  // ...
+  loaders: [helloWorldLoader],
+})
+```
+
+The second parameter of the `Module` function accepts a `loaders` property whose value is an array of loader functions. The Medusa application will execute these functions when it starts.
+
+### Test the Loader
+
+Assuming your module is [added to Medusa's configuration](https://docs.medusajs.com/learn/fundamentals/modules#4-add-module-to-medusas-configurations/index.html.md), you can test the loader by starting the Medusa application:
+
+```bash npm2yarn
+npm run dev
+```
+
+Then, you'll find the following message logged in the terminal:
+
+```plain
+info:   [HELLO MODULE] Just started the Medusa application!
+```
+
+This indicates that the loader in the `hello` module ran and logged this message.
+
+***
+
+## When are Loaders Executed?
+
+When you start the Medusa application, it executes the loaders of all modules in their registration order.
+
+A loader is executed before the module's main service is instantiated. So, you can use loaders to register in the module's container resources that you want to use in the module's service. For example, you can register a database connection.
+
+Loaders are also useful to only load a module if a certain condition is met. For example, if you try to connect to a database in a loader but the connection fails, you can throw an error in the loader to prevent the module from being loaded. This is useful if your module depends on an external service to work.
+
+***
+
+## Example: Register Custom MongoDB Connection
+
+As mentioned in this chapter's introduction, loaders are most useful when you need to register a custom resource in the module's container to re-use it in other customizations in the module.
+
+Consider your have a MongoDB module that allows you to perform operations on a MongoDB database.
+
+### Prerequisites
+
+- [MongoDB database that you can connect to from a local machine.](https://www.mongodb.com)
+- [Install the MongoDB SDK in your Medusa application.](https://www.mongodb.com/docs/drivers/node/current/quick-start/download-and-install/#install-the-node.js-driver)
+
+To connect to the database, you create the following loader in your module:
+
+```ts title="src/modules/mongo/loaders/connection.ts" highlights={loaderHighlights}
+import { LoaderOptions } from "@medusajs/framework/types"
+import { asValue } from "awilix"
+import { MongoClient } from "mongodb"
+
+type ModuleOptions = {
+  connection_url?: string
+  db_name?: string
+}
+
+export default async function mongoConnectionLoader({
+  container,
+  options,
+}: LoaderOptions<ModuleOptions>) {
+  if (!options.connection_url) {
+    throw new Error(`[MONGO MDOULE]: connection_url option is required.`)
+  }
+  if (!options.db_name) {
+    throw new Error(`[MONGO MDOULE]: db_name option is required.`)
+  }
+  const logger = container.resolve("logger")
+  
+  try {
+    const clientDb = (
+      await (new MongoClient(options.connection_url)).connect()
+    ).db(options.db_name)
+
+    logger.info("Connected to MongoDB")
+
+    container.register(
+      "mongoClient",
+      asValue(clientDb)
+    )
+  } catch (e) {
+    logger.error(
+      `[MONGO MDOULE]: An error occurred while connecting to MongoDB: ${e}`
+    )
+  }
+}
+```
+
+The loader function accepts in its object parameter an `options` property, which is the options passed to the module in Medusa's configurations. For example:
+
+```ts title="medusa-config.ts" highlights={optionHighlights}
+module.exports = defineConfig({
+  // ...
+  modules: [
+    {
+      resolve: "./src/modules/mongo",
+      options: {
+        connection_url: process.env.MONGO_CONNECTION_URL,
+        db_name: process.env.MONGO_DB_NAME,
+      },
+    },
+  ],
+})
+```
+
+Passing options is useful when your module needs informations like connection URLs or API keys, as it ensures your module can be re-usable across applications. For the MongoDB Module, you expect two options:
+
+- `connection_url`: the URL to connect to the MongoDB database.
+- `db_name`: The name of the database to connect to.
+
+In the loader, you check first that these options are set before proceeding. Then, you create an instance of the MongoDB client and connect to the database specified in the options.
+
+After creating the client, you register it in the module's container using the container's `register` method. The method accepts two parameters:
+
+1. The key to register the resource under, which in this case is `mongoClient`. You'll use this name later to resolve the client.
+2. The resource to register in the container, which is the MongoDB client you created. However, you don't pass the resource as-is. Instead, you need to use an `asValue` function imported from the [awilix package](https://github.com/jeffijoe/awilix), which is the package used to implement the container functionality in Medusa.
+
+### Use Custom Registered Resource in Module's Service
+
+After registering the custom MongoDB client in the module's container, you can now resolve and use it in the module's service.
+
+For example:
+
+```ts title="src/modules/mongo/service.ts"
+import type { Db } from "mongodb"
+
+type InjectedDependencies = {
+  mongoClient: Db
+}
+
+export default class MongoModuleService {
+  private mongoClient_: Db
+
+  constructor({ mongoClient }: InjectedDependencies) {
+    this.mongoClient_ = mongoClient
+  }
+
+  async createMovie({ title }: {
+    title: string
+  }) {
+    const moviesCol = this.mongoClient_.collection("movie")
+
+    const insertedMovie = await moviesCol.insertOne({
+      title,
+    })
+
+    const movie = await moviesCol.findOne({
+      _id: insertedMovie.insertedId,
+    })
+
+    return movie
+  }
+
+  async deleteMovie(id: string) {
+    const moviesCol = this.mongoClient_.collection("movie")
+
+    await moviesCol.deleteOne({
+      _id: {
+        equals: id,
+      },
+    })
+  }
+}
+```
+
+The service `MongoModuleService` resolves the `mongoClient` resource you registered in the loader and sets it as a class property. You then use it in the `createMovie` and `deleteMovie` methods, which create and delete a document in a `movie` collection in the MongoDB database, respectively.
+
+Make sure to export the loader in the module's definition in the `index.ts` file at the root directory of the module:
+
+```ts title="src/modules/mongo/index.ts" highlights={[["9"]]}
+import { Module } from "@medusajs/framework/utils"
+import MongoModuleService from "./service"
+import mongoConnectionLoader from "./loaders/connection"
+
+export const MONGO_MODULE = "mongo"
+
+export default Module(MONGO_MODULE, {
+  service: MongoModuleService,
+  loaders: [mongoConnectionLoader],
+})
+```
+
+### Test it Out
+
+You can test the connection out by starting the Medusa application. If it's successful, you'll see the following message logged in the terminal:
+
+```bash
+info:    Connected to MongoDB
+```
+
+You can now resolve the MongoDB Module's main service in your customizations to perform operations on the MongoDB database.
+
+
+# Modules Directory Structure
+
+In this document, you'll learn about the expected files and directories in your module.
+
+![Module Directory Structure Example](https://res.cloudinary.com/dza7lstvk/image/upload/v1714379976/Medusa%20Book/modules-dir-overview_nqq7ne.jpg)
+
+## index.ts
+
+The `index.ts` file in the root of your module's directory is the only required file. It must export the module's definition as explained in a [previous chapter](https://docs.medusajs.com/learn/fundamentals/modules/index.html.md).
+
+***
+
+## service.ts
+
+A module must have a main service. It's created in the `service.ts` file at the root of your module directory as explained in a [previous chapter](https://docs.medusajs.com/learn/fundamentals/modules/index.html.md).
+
+***
+
+## Other Directories
+
+The following directories are optional and their content are explained more in the following chapters:
+
+- `models`: Holds the data models representing tables in the database.
+- `migrations`: Holds the migration files used to reflect changes on the database.
+- `loaders`: Holds the scripts to run on the Medusa application's start-up.
+
+
+# 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.
+
+
+# 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.
+
+
+# Module Options
+
+In this chapter, you’ll learn about passing options to your module from the Medusa application’s configurations and using them in the module’s resources.
+
+## What are Module Options?
+
+A module can receive options to customize or configure its functionality. For example, if you’re creating a module that integrates a third-party service, you’ll want to receive the integration credentials in the options rather than adding them directly in your code.
+
+***
+
+## How to Pass Options to a Module?
+
+To pass options to a module, add an `options` property to the module’s configuration in `medusa-config.ts`.
+
+For example:
+
+```ts title="medusa-config.ts"
+module.exports = defineConfig({
+  // ...
+  modules: [
+    {
+      resolve: "./src/modules/blog",
+      options: {
+        capitalize: true,
+      },
+    },
+  ],
+})
+```
+
+The `options` property’s value is an object. You can pass any properties you want.
+
+### Pass Options to a Module in a Plugin
+
+If your module is part of a plugin, you can pass options to the module in the plugin’s configuration.
+
+For example:
+
+```ts title="medusa-config.ts"
+import { defineConfig } from "@medusajs/framework/utils"
+module.exports = defineConfig({
+  plugins: [
+    {
+      resolve: "@myorg/plugin-name",
+      options: {
+        capitalize: true,
+      },
+    },
+  ],
+})
+```
+
+The `options` property in the plugin configuration is passed to all modules in a plugin.
+
+***
+
+## Access Module Options in Main Service
+
+The module’s main service receives the module options as a second parameter.
+
+For example:
+
+```ts title="src/modules/blog/service.ts" highlights={[["12"], ["14", "options?: ModuleOptions"], ["17"], ["18"], ["19"]]}
+import { MedusaService } from "@medusajs/framework/utils"
+import Post from "./models/post"
+
+// recommended to define type in another file
+type ModuleOptions = {
+  capitalize?: boolean
+}
+
+export default class BlogModuleService extends MedusaService({
+  Post,
+}){
+  protected options_: ModuleOptions
+
+  constructor({}, options?: ModuleOptions) {
+    super(...arguments)
+
+    this.options_ = options || {
+      capitalize: false,
+    }
+  }
+
+  // ...
+}
+```
+
+***
+
+## Access Module Options in Loader
+
+The object that a module’s loaders receive as a parameter has an `options` property holding the module's options.
+
+For example:
+
+```ts title="src/modules/blog/loaders/hello-world.ts" highlights={[["11"], ["12", "ModuleOptions", "The type of expected module options."], ["16"]]}
+import {
+  LoaderOptions,
+} from "@medusajs/framework/types"
+
+// recommended to define type in another file
+type ModuleOptions = {
+  capitalize?: boolean
+}
+
+export default async function helloWorldLoader({
+  options,
+}: LoaderOptions<ModuleOptions>) {
+  
+  console.log(
+    "[BLOG MODULE] Just started the Medusa application!",
+    options
+  )
+}
+```
+
+***
+
+## Validate Module Options
+
+If you expect a certain option and want to throw an error if it's not provided or isn't valid, it's recommended to perform the validation in a loader. The module's service is only instantiated when it's used, whereas the loader runs the when the Medusa application starts.
+
+So, by performing the validation in the loader, you ensure you can throw an error at an early point, rather than when the module is used.
+
+For example, to validate that the Hello Module received an `apiKey` option, create the loader `src/modules/loaders/validate.ts`:
+
+```ts title="src/modules/blog/loaders/validate.ts" 
+import { LoaderOptions } from "@medusajs/framework/types"
+import { MedusaError } from "@medusajs/framework/utils"
+
+// recommended to define type in another file
+type ModuleOptions = {
+  apiKey?: string
+}
+
+export default async function validationLoader({
+  options,
+}: LoaderOptions<ModuleOptions>) {
+  if (!options.apiKey) {
+    throw new MedusaError(
+      MedusaError.Types.INVALID_DATA,
+      "Hello Module requires an apiKey option."
+    )
+  }
+}
+```
+
+Then, export the loader in the module's definition file, as explained in [this chapter](https://docs.medusajs.com/learn/fundamentals/modules/loaders/index.html.md):
+
+```ts title="src/modules/blog/index.ts"
+// other imports...
+import validationLoader from "./loaders/validate"
+
+export const BLOG_MODULE = "blog"
+
+export default Module(BLOG_MODULE, {
+  // ...
+  loaders: [validationLoader],
+})
+```
+
+Now, when the Medusa application starts, the loader will run, validating the module's options and throwing an error if the `apiKey` option is missing.
+
+
+# Service Factory
+
+In this chapter, you’ll learn about what the service factory is and how to use it.
+
+## What is the Service Factory?
+
+Medusa provides a service factory that your module’s main service can extend.
+
+The service factory generates data management methods for your data models in the database, so you don't have to implement these methods manually.
+
+Your service provides data-management functionalities of your data models.
+
+***
+
+## How to Extend the Service Factory?
+
+Medusa provides the service factory as a `MedusaService` function your service extends. The function creates and returns a service class with generated data-management methods.
+
+For example, create the file `src/modules/blog/service.ts` with the following content:
+
+```ts title="src/modules/blog/service.ts" highlights={highlights}
+import { MedusaService } from "@medusajs/framework/utils"
+import Post from "./models/post"
+
+class BlogModuleService extends MedusaService({
+  Post,
+}){
+  // TODO implement custom methods
+}
+
+export default BlogModuleService
+```
+
+### MedusaService Parameters
+
+The `MedusaService` function accepts one parameter, which is an object of data models to generate data-management methods for.
+
+In the example above, since the `BlogModuleService` extends `MedusaService`, it has methods to manage the `Post` data model, such as `createPosts`.
+
+### Generated Methods
+
+The service factory generates methods to manage the records of each of the data models provided in the first parameter in the database.
+
+The method's names are the operation's name, suffixed by the data model's key in the object parameter passed to `MedusaService`.
+
+For example, the following methods are generated for the service above:
+
+Find a complete reference of each of the methods in [this documentation](https://docs.medusajs.com/resources/service-factory-reference/index.html.md)
+
+### listPosts
+
+### listPosts
+
+This method retrieves an array of records based on filters and pagination configurations.
+
+For example:
+
+```ts
+const posts = await blogModuleService
+  .listPosts()
+
+// with filters
+const posts = await blogModuleService
+  .listPosts({
+    id: ["123"]
+  })
+```
+
+### listAndCountPosts
+
+### retrievePost
+
+This method retrieves a record by its ID.
+
+For example:
+
+```ts
+const post = await blogModuleService
+  .retrievePost("123")
+```
+
+### retrievePost
+
+### updatePosts
+
+This method updates and retrieves records of the data model.
+
+For example:
+
+```ts
+const post = await blogModuleService
+  .updatePosts({
+    id: "123",
+    title: "test"
+  })
+
+// update multiple
+const posts = await blogModuleService
+  .updatePosts([
+    {
+      id: "123",
+      title: "test"
+    },
+    {
+      id: "321",
+      title: "test 2"
+    },
+  ])
+
+// use filters
+const posts = await blogModuleService
+  .updatePosts([
+    {
+      selector: {
+        id: ["123", "321"]
+      },
+      data: {
+        title: "test"
+      }
+    },
+  ])
+```
+
+### createPosts
+
+### softDeletePosts
+
+This method soft-deletes records using an array of IDs or an object of filters.
+
+For example:
+
+```ts
+await blogModuleService.softDeletePosts("123")
+
+// soft-delete multiple
+await blogModuleService.softDeletePosts([
+  "123", "321"
+])
+
+// use filters
+await blogModuleService.softDeletePosts({
+  id: ["123", "321"]
+})
+```
+
+### updatePosts
+
+### deletePosts
+
+### softDeletePosts
+
+### restorePosts
+
+### Using a Constructor
+
+If you implement the `constructor` of your service, make sure to call `super` passing it `...arguments`.
+
+For example:
+
+```ts highlights={[["8"]]}
+import { MedusaService } from "@medusajs/framework/utils"
+import Post from "./models/post"
+
+class BlogModuleService extends MedusaService({
+  Post,
+}){
+  constructor() {
+    super(...arguments)
+  }
+}
+
+export default BlogModuleService
+```
+
+
+# Access Workflow Errors
+
+In this chapter, you’ll learn how to access errors that occur during a workflow’s execution.
+
+## How to Access Workflow Errors?
+
+By default, when an error occurs in a workflow, it throws that error, and the execution stops.
+
+You can configure the workflow to return the errors instead so that you can access and handle them differently.
+
+For example:
+
+```ts title="src/api/workflows/route.ts" highlights={highlights} collapsibleLines="1-6" expandButtonLabel="Show Imports"
+import type {
+  MedusaRequest,
+  MedusaResponse,
+} from "@medusajs/framework/http"
+import myWorkflow from "../../../workflows/hello-world"
+
+export async function GET(
+  req: MedusaRequest,
+  res: MedusaResponse
+) {
+  const { result, errors } = await myWorkflow(req.scope)
+    .run({
+	    // ...
+      throwOnError: false,
+    })
+
+  if (errors.length) {
+    return res.send({
+      errors: errors.map((error) => error.error),
+    })
+  }
+
+  res.send(result)
+}
+
+```
+
+The object passed to the `run` method accepts a `throwOnError` property. When disabled, the errors are returned in the `errors` property of `run`'s output.
+
+The value of `errors` is an array of error objects. Each object has an `error` property, whose value is the name or text of the thrown error.
+
+
+# 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
+```
+
+
 # Expose a Workflow Hook
 
 In this chapter, you'll learn how to expose a hook in your workflow.
@@ -13275,51 +15157,6 @@ The hook is available on the workflow's `hooks` property using its name `product
 You invoke the hook, passing a step function (the hook handler) as a parameter.
 
 
-# Access Workflow Errors
-
-In this chapter, you’ll learn how to access errors that occur during a workflow’s execution.
-
-## How to Access Workflow Errors?
-
-By default, when an error occurs in a workflow, it throws that error, and the execution stops.
-
-You can configure the workflow to return the errors instead so that you can access and handle them differently.
-
-For example:
-
-```ts title="src/api/workflows/route.ts" highlights={highlights} collapsibleLines="1-6" expandButtonLabel="Show Imports"
-import type {
-  MedusaRequest,
-  MedusaResponse,
-} from "@medusajs/framework/http"
-import myWorkflow from "../../../workflows/hello-world"
-
-export async function GET(
-  req: MedusaRequest,
-  res: MedusaResponse
-) {
-  const { result, errors } = await myWorkflow(req.scope)
-    .run({
-	    // ...
-      throwOnError: false,
-    })
-
-  if (errors.length) {
-    return res.send({
-      errors: errors.map((error) => error.error),
-    })
-  }
-
-  res.send(result)
-}
-
-```
-
-The object passed to the `run` method accepts a `throwOnError` property. When disabled, the errors are returned in the `errors` property of `run`'s output.
-
-The value of `errors` is an array of error objects. Each object has an `error` property, whose value is the name or text of the thrown error.
-
-
 # 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.
@@ -14211,133 +16048,6 @@ const workflow = createWorkflow(
 In this example, you use when-then to run the `createProductsWorkflow` only if `should_create` (passed in the `input`) is enabled.
 
 
-# Multiple Step Usage in Workflow
-
-In this chapter, you'll learn how to use a step multiple times in a workflow.
-
-## Problem Reusing a Step in a Workflow
-
-In some cases, you may need to use a step multiple times in the same workflow.
-
-The most common example is using the `useQueryGraphStep` multiple times in a workflow to retrieve multiple unrelated data, such as customers and products.
-
-Each workflow step must have a unique ID, which is the ID passed as a first parameter when creating the step:
-
-```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"],
-    })
-  }
-)
-```
-
-The next section explains how to fix this issue to use the same step multiple times in a workflow.
-
-***
-
-## How to Use a Step Multiple Times in a Workflow?
-
-When you execute a step in a workflow, you can chain a `config` method to it to change the step's config.
-
-Use the `config` method to change a step's ID for a single execution.
-
-So, this is the correct way to write the example above:
-
-```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" })
-  }
-)
-```
-
-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.
-
-The first `useQueryGraphStep` usage has the ID `use-query-graph`, and the second `useQueryGraphStep` usage has the ID `fetch-customers`.
-
-
-# Run Workflow Steps in Parallel
-
-In this chapter, you’ll learn how to run workflow steps in parallel.
-
-## parallelize Utility Function
-
-If your workflow has steps that don’t rely on one another’s results, run them in parallel using `parallelize` from the Workflows SDK.
-
-The workflow waits until all steps passed to the `parallelize` function finish executing before continuing to the next step.
-
-For example:
-
-```ts highlights={highlights} collapsibleLines="1-12" expandButtonLabel="Show Imports"
-import {
-  createWorkflow,
-  WorkflowResponse,
-  parallelize,
-} from "@medusajs/framework/workflows-sdk"
-import {
-  createProductStep,
-  getProductStep,
-  createPricesStep,
-  attachProductToSalesChannelStep,
-} from "./steps"
-
-interface WorkflowInput {
-  title: string
-}
-
-const myWorkflow = createWorkflow(
-  "my-workflow", 
-  (input: WorkflowInput) => {
-   const product = createProductStep(input)
-
-   const [prices, productSalesChannel] = parallelize(
-     createPricesStep(product),
-     attachProductToSalesChannelStep(product)
-   )
-
-   const refetchedProduct = getProductStep(product.id)
-
-   return new WorkflowResponse(refetchedProduct)
- }
-)
-```
-
-The `parallelize` function accepts the steps to run in parallel as a parameter.
-
-It returns an array of the steps' results in the same order they're passed to the `parallelize` function.
-
-So, `prices` is the result of `createPricesStep`, and `productSalesChannel` is the result of `attachProductToSalesChannelStep`.
-
-
 # Long-Running Workflows
 
 In this chapter, you’ll learn what a long-running workflow is and how to configure it.
@@ -14633,6 +16343,59 @@ 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.
 
 
+# Run Workflow Steps in Parallel
+
+In this chapter, you’ll learn how to run workflow steps in parallel.
+
+## parallelize Utility Function
+
+If your workflow has steps that don’t rely on one another’s results, run them in parallel using `parallelize` from the Workflows SDK.
+
+The workflow waits until all steps passed to the `parallelize` function finish executing before continuing to the next step.
+
+For example:
+
+```ts highlights={highlights} collapsibleLines="1-12" expandButtonLabel="Show Imports"
+import {
+  createWorkflow,
+  WorkflowResponse,
+  parallelize,
+} from "@medusajs/framework/workflows-sdk"
+import {
+  createProductStep,
+  getProductStep,
+  createPricesStep,
+  attachProductToSalesChannelStep,
+} from "./steps"
+
+interface WorkflowInput {
+  title: string
+}
+
+const myWorkflow = createWorkflow(
+  "my-workflow", 
+  (input: WorkflowInput) => {
+   const product = createProductStep(input)
+
+   const [prices, productSalesChannel] = parallelize(
+     createPricesStep(product),
+     attachProductToSalesChannelStep(product)
+   )
+
+   const refetchedProduct = getProductStep(product.id)
+
+   return new WorkflowResponse(refetchedProduct)
+ }
+)
+```
+
+The `parallelize` function accepts the steps to run in parallel as a parameter.
+
+It returns an array of the steps' results in the same order they're passed to the `parallelize` function.
+
+So, `prices` is the result of `createPricesStep`, and `productSalesChannel` is the result of `attachProductToSalesChannelStep`.
+
+
 # Retry Failed Steps
 
 In this chapter, you’ll learn how to configure steps to allow retrial on failure.
@@ -14756,6 +16519,80 @@ However, since the long-running workflow runs in the background, you won't recei
 Instead, you must subscribe to the workflow's execution using the Workflow Engine Module Service. Learn more about it in [this chapter](https://docs.medusajs.com/learn/fundamentals/workflows/long-running-workflow#access-long-running-workflow-status-and-result/index.html.md).
 
 
+# Multiple Step Usage in Workflow
+
+In this chapter, you'll learn how to use a step multiple times in a workflow.
+
+## Problem Reusing a Step in a Workflow
+
+In some cases, you may need to use a step multiple times in the same workflow.
+
+The most common example is using the `useQueryGraphStep` multiple times in a workflow to retrieve multiple unrelated data, such as customers and products.
+
+Each workflow step must have a unique ID, which is the ID passed as a first parameter when creating the step:
+
+```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"],
+    })
+  }
+)
+```
+
+The next section explains how to fix this issue to use the same step multiple times in a workflow.
+
+***
+
+## How to Use a Step Multiple Times in a Workflow?
+
+When you execute a step in a workflow, you can chain a `config` method to it to change the step's config.
+
+Use the `config` method to change a step's ID for a single execution.
+
+So, this is the correct way to write the example above:
+
+```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" })
+  }
+)
+```
+
+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.
+
+The first `useQueryGraphStep` usage has the ID `use-query-graph`, and the second `useQueryGraphStep` usage has the ID `fetch-customers`.
+
+
 # Store Workflow Executions
 
 In this chapter, you'll learn how to store workflow executions in the database and access them later.
@@ -15106,6 +16943,186 @@ const myWorkflow = createWorkflow(
 ```
 
 
+# Workflow Timeout
+
+In this chapter, you’ll learn how to set a timeout for workflows and steps.
+
+## What is a Workflow Timeout?
+
+By default, a workflow doesn’t have a timeout. It continues execution until it’s finished or an error occurs.
+
+You can configure a workflow’s timeout to indicate how long the workflow can execute. If a workflow's execution time passes the configured timeout, it is failed and an error is thrown.
+
+### Timeout Doesn't Stop Step Execution
+
+Configuring a timeout doesn't stop the execution of a step in progress. The timeout only affects the status of the workflow and its result.
+
+***
+
+## Configure Workflow Timeout
+
+The `createWorkflow` function can accept a configuration object instead of the workflow’s name.
+
+In the configuration object, you pass a `timeout` property, whose value is a number indicating the timeout in seconds.
+
+For example:
+
+```ts title="src/workflows/hello-world.ts" highlights={[["16"]]} collapsibleLines="1-13" expandButtonLabel="Show More"
+import { 
+  createStep,  
+  createWorkflow,
+  WorkflowResponse,
+} from "@medusajs/framework/workflows-sdk"
+
+const step1 = createStep(
+  "step-1",
+  async () => {
+    // ...
+  }
+)
+
+const myWorkflow = createWorkflow({
+  name: "hello-world",
+  timeout: 2, // 2 seconds
+}, function () {
+  const str1 = step1()
+
+  return new WorkflowResponse({
+    message: str1,
+  })
+})
+
+export default myWorkflow
+
+```
+
+This workflow's executions fail if they run longer than two seconds.
+
+A workflow’s timeout error is returned in the `errors` property of the workflow’s execution, as explained in [this chapter](https://docs.medusajs.com/learn/fundamentals/workflows/access-workflow-errors/index.html.md). The error’s name is `TransactionTimeoutError`.
+
+***
+
+## Configure Step Timeout
+
+Alternatively, you can configure the timeout for a step rather than the entire workflow.
+
+As mentioned in the previous section, the timeout doesn't stop the execution of the step. It only affects the step's status and output.
+
+The step’s configuration object accepts a `timeout` property, whose value is a number indicating the timeout in seconds.
+
+For example:
+
+```tsx
+const step1 = createStep(
+  {
+    name: "step-1",
+    timeout: 2, // 2 seconds
+  },
+  async () => {
+    // ...
+  }
+)
+```
+
+This step's executions fail if they run longer than two seconds.
+
+A step’s timeout error is returned in the `errors` property of the workflow’s execution, as explained in [this chapter](https://docs.medusajs.com/learn/fundamentals/workflows/access-workflow-errors/index.html.md). The error’s name is `TransactionStepTimeoutError`.
+
+
+# Translate Medusa Admin
+
+The Medusa Admin supports multiple languages, with the default being English. In this documentation, you'll learn how to contribute to the community by translating the Medusa Admin to a language you're fluent in.
+
+{/* vale docs.We = NO */}
+
+You can contribute either by translating the admin to a new language, or fixing translations for existing languages. As we can't validate every language's translations, some translations may be incorrect. Your contribution is welcome to fix any translation errors you find.
+
+{/* vale docs.We = YES */}
+
+Check out the translated languages either in the admin dashboard's settings or on [GitHub](https://github.com/medusajs/medusa/blob/develop/packages/admin/dashboard/src/i18n/languages.ts).
+
+***
+
+## How to Contribute Translation
+
+1. Clone the [Medusa monorepository](https://github.com/medusajs/medusa) to your local machine:
+
+```bash
+git clone https://github.com/medusajs/medusa.git
+```
+
+If you already have it cloned, make sure to pull the latest changes from the `develop` branch.
+
+2. Install the monorepository's dependencies. Since it's a Yarn workspace, it's highly recommended to use yarn:
+
+```bash
+yarn install
+```
+
+3. Create a branch that you'll use to open the pull request later:
+
+```bash
+git checkout -b feat/translate-<LANGUAGE>
+```
+
+Where `<LANGUAGE>` is your language name. For example, `feat/translate-da`.
+
+4. Translation files are under `packages/admin/dashboard/src/i18n/translations` as JSON files whose names are the ISO-2 name of the language.
+   - If you're adding a new language, copy the file `packages/admin/dashboard/src/i18n/translations/en.json` and paste it with the ISO-2 name for your language. For example, if you're adding Danish translations, copy the `en.json` file and paste it as `packages/admin/dashboard/src/i18n/translations/de.json`.
+   - If you're fixing a translation, find the JSON file of the language under `packages/admin/dashboard/src/i18n/translations`.
+
+5. Start translating the keys in the JSON file (or updating the targeted ones). All keys in the JSON file must be translated, and your PR tests will fail otherwise.
+   - You can check whether the JSON file is valid by running the following command in `packages/admin/dashboard`, replacing `da.json` with the JSON file's name:
+
+```bash title="packages/admin/dashboard"
+yarn i18n:validate da.json
+```
+
+6. After finishing the translation, if you're adding a new language, import its JSON file in `packages/admin/dashboard/src/i18n/translations/index.ts` and add it to the exported object:
+
+```ts title="packages/admin/dashboard/src/i18n/translations/index.ts" highlights={[["2"], ["6"], ["7"], ["8"]]}
+// other imports...
+import da from "./da.json"
+
+export default {
+  // other languages...
+  da: {
+    translation: da,
+  },
+}
+```
+
+The language's key in the object is the ISO-2 name of the language.
+
+7. If you're adding a new language, add it to the file `packages/admin/dashboard/src/i18n/languages.ts`:
+
+```ts title="packages/admin/dashboard/src/i18n/languages.ts" highlights={languageHighlights}
+import { da } from "date-fns/locale"
+// other imports...
+
+export const languages: Language[] = [
+  // other languages...
+  {
+    code: "da",
+    display_name: "Danish",
+    ltr: true,
+    date_locale: da,
+  },
+]
+```
+
+`languages` is an array having the following properties:
+
+- `code`: The ISO-2 name of the language. For example, `da` for Danish.
+- `display_name`: The language's name to be displayed in the admin.
+- `ltr`: Whether the language supports a left-to-right layout. For example, set this to `false` for languages like Arabic.
+- `date_locale`: An instance of the locale imported from the [date-fns/locale](https://date-fns.org/) package.
+
+8. Once you're done, push the changes into your branch and open a pull request on GitHub.
+
+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.
+
+
 # Workflow Hooks
 
 In this chapter, you'll learn what a workflow hook is and how to consume them.
@@ -15230,1876 +17247,6 @@ export async function POST(req: MedusaRequest, res: MedusaResponse) {
 Your hook handler then receives that passed data in the `additional_data` object.
 
 
-# Workflow Timeout
-
-In this chapter, you’ll learn how to set a timeout for workflows and steps.
-
-## What is a Workflow Timeout?
-
-By default, a workflow doesn’t have a timeout. It continues execution until it’s finished or an error occurs.
-
-You can configure a workflow’s timeout to indicate how long the workflow can execute. If a workflow's execution time passes the configured timeout, it is failed and an error is thrown.
-
-### Timeout Doesn't Stop Step Execution
-
-Configuring a timeout doesn't stop the execution of a step in progress. The timeout only affects the status of the workflow and its result.
-
-***
-
-## Configure Workflow Timeout
-
-The `createWorkflow` function can accept a configuration object instead of the workflow’s name.
-
-In the configuration object, you pass a `timeout` property, whose value is a number indicating the timeout in seconds.
-
-For example:
-
-```ts title="src/workflows/hello-world.ts" highlights={[["16"]]} collapsibleLines="1-13" expandButtonLabel="Show More"
-import { 
-  createStep,  
-  createWorkflow,
-  WorkflowResponse,
-} from "@medusajs/framework/workflows-sdk"
-
-const step1 = createStep(
-  "step-1",
-  async () => {
-    // ...
-  }
-)
-
-const myWorkflow = createWorkflow({
-  name: "hello-world",
-  timeout: 2, // 2 seconds
-}, function () {
-  const str1 = step1()
-
-  return new WorkflowResponse({
-    message: str1,
-  })
-})
-
-export default myWorkflow
-
-```
-
-This workflow's executions fail if they run longer than two seconds.
-
-A workflow’s timeout error is returned in the `errors` property of the workflow’s execution, as explained in [this chapter](https://docs.medusajs.com/learn/fundamentals/workflows/access-workflow-errors/index.html.md). The error’s name is `TransactionTimeoutError`.
-
-***
-
-## Configure Step Timeout
-
-Alternatively, you can configure the timeout for a step rather than the entire workflow.
-
-As mentioned in the previous section, the timeout doesn't stop the execution of the step. It only affects the step's status and output.
-
-The step’s configuration object accepts a `timeout` property, whose value is a number indicating the timeout in seconds.
-
-For example:
-
-```tsx
-const step1 = createStep(
-  {
-    name: "step-1",
-    timeout: 2, // 2 seconds
-  },
-  async () => {
-    // ...
-  }
-)
-```
-
-This step's executions fail if they run longer than two seconds.
-
-A step’s timeout error is returned in the `errors` property of the workflow’s execution, as explained in [this chapter](https://docs.medusajs.com/learn/fundamentals/workflows/access-workflow-errors/index.html.md). The error’s name is `TransactionStepTimeoutError`.
-
-
-# Write 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).
-
-
-# Module Container
-
-In this chapter, you'll learn about the module's container and how to resolve resources in that container.
-
-Since modules are isolated, each module has a local container only used by the resources of that module.
-
-So, resources in the module, such as services or loaders, can only resolve other resources registered in the module's container.
-
-### List of Registered Resources
-
-Find a list of resources or dependencies registered in a module's container in [the Container Resources reference](https://docs.medusajs.com/resources/medusa-container-resources/index.html.md).
-
-***
-
-## Resolve Resources
-
-### Services
-
-A service's constructor accepts as a first parameter an object used to resolve resources registered in the module's container.
-
-For example:
-
-```ts highlights={[["4"], ["10"]]}
-import { Logger } from "@medusajs/framework/types"
-
-type InjectedDependencies = {
-  logger: Logger
-}
-
-export default class BlogModuleService {
-  protected logger_: Logger
-
-  constructor({ logger }: InjectedDependencies) {
-    this.logger_ = logger
-
-    this.logger_.info("[BlogModuleService]: Hello World!")
-  }
-
-  // ...
-}
-```
-
-### Loader
-
-A loader function accepts as a parameter an object having the property `container`. Its value is the module's container used to resolve resources.
-
-For example:
-
-```ts highlights={[["9"]]}
-import {
-  LoaderOptions,
-} from "@medusajs/framework/types"
-import { 
-  ContainerRegistrationKeys,
-} from "@medusajs/framework/utils"
-
-export default async function helloWorldLoader({
-  container,
-}: LoaderOptions) {
-  const logger = container.resolve(ContainerRegistrationKeys.LOGGER)
-
-  logger.info("[helloWorldLoader]: Hello, World!")
-}
-```
-
-
-# Perform Database Operations in a Service
-
-In this chapter, you'll learn how to perform database operations in a module's service.
-
-This chapter is intended for more advanced database use-cases where you need more control over queries and operations. For basic database operations, such as creating or retrieving data of a model, use the [Service Factory](https://docs.medusajs.com/learn/fundamentals/modules/service-factory/index.html.md) instead.
-
-## Run Queries
-
-[MikroORM's entity manager](https://mikro-orm.io/docs/entity-manager) is a class that has methods to run queries on the database and perform operations.
-
-Medusa provides an `InjectManager` decorator from the Modules SDK that injects a service's method with a [forked entity manager](https://mikro-orm.io/docs/identity-map#forking-entity-manager).
-
-So, to run database queries in a service:
-
-1. Add the `InjectManager` decorator to the method.
-2. Add as a last parameter an optional `sharedContext` parameter that has the `MedusaContext` decorator from the Modules SDK. This context holds database-related context, including the manager injected by `InjectManager`
-
-For example, in your service, add the following methods:
-
-```ts highlights={methodsHighlight}
-// other imports...
-import { 
-  InjectManager,
-  MedusaContext,
-} from "@medusajs/framework/utils"
-import { Context } from "@medusajs/framework/types"
-import { EntityManager } from "@mikro-orm/knex"
-
-class BlogModuleService {
-  // ...
-
-  @InjectManager()
-  async getCount(
-    @MedusaContext() sharedContext?: Context<EntityManager>
-  ): Promise<number | undefined> {
-    return await sharedContext?.manager?.count("my_custom")
-  }
-  
-  @InjectManager()
-  async getCountSql(
-    @MedusaContext() sharedContext?: Context<EntityManager>
-  ): Promise<number> {
-    const data = await sharedContext?.manager?.execute(
-      "SELECT COUNT(*) as num FROM my_custom"
-    ) 
-    
-    return parseInt(data?.[0].num || 0)
-  }
-}
-```
-
-You add two methods `getCount` and `getCountSql` that have the `InjectManager` decorator. Each of the methods also accept the `sharedContext` parameter which has the `MedusaContext` decorator.
-
-The entity manager is injected to the `sharedContext.manager` property, which is an instance of [EntityManager from the @mikro-orm/knex package](https://mikro-orm.io/api/knex/class/EntityManager).
-
-You use the manager in the `getCount` method to retrieve the number of records in a table, and in the `getCountSql` to run a PostgreSQL query that retrieves the count.
-
-Refer to [MikroORM's reference](https://mikro-orm.io/api/knex/class/EntityManager) for a full list of the entity manager's methods.
-
-***
-
-## Execute Operations in Transactions
-
-To wrap database operations in a transaction, you create two methods:
-
-1. A private or protected method that's wrapped in a transaction. To wrap it in a transaction, you use the `InjectTransactionManager` decorator from the Modules SDK.
-2. A public method that calls the transactional method. You use on it the `InjectManager` decorator as explained in the previous section.
-
-Both methods must accept as a last parameter an optional `sharedContext` parameter that has the `MedusaContext` decorator from the Modules SDK. It holds database-related contexts passed through the Medusa application.
-
-For example:
-
-```ts highlights={opHighlights}
-import { 
-  InjectManager,
-  InjectTransactionManager,
-  MedusaContext,
-} from "@medusajs/framework/utils"
-import { Context } from "@medusajs/framework/types"
-import { EntityManager } from "@mikro-orm/knex"
-
-class BlogModuleService {
-  // ...
-  @InjectTransactionManager()
-  protected async update_(
-    input: {
-      id: string,
-      name: string
-    },
-    @MedusaContext() sharedContext?: Context<EntityManager>
-  ): Promise<any> {
-    const transactionManager = sharedContext?.transactionManager
-    await transactionManager?.nativeUpdate(
-      "my_custom",
-      {
-        id: input.id,
-      },
-      {
-        name: input.name,
-      }
-    )
-
-    // retrieve again
-    const updatedRecord = await transactionManager?.execute(
-      `SELECT * FROM my_custom WHERE id = '${input.id}'`
-    )
-
-    return updatedRecord
-  }
-
-  @InjectManager()
-  async update(
-    input: {
-      id: string,
-      name: string
-    },
-    @MedusaContext() sharedContext?: Context<EntityManager>
-  ) {
-    return await this.update_(input, sharedContext)
-  }
-}
-```
-
-The `BlogModuleService` has two methods:
-
-- A protected `update_` that performs the database operations inside a transaction.
-- A public `update` that executes the transactional protected method.
-
-The shared context's `transactionManager` property holds the transactional entity manager (injected by `InjectTransactionManager`) that you use to perform database operations.
-
-Refer to [MikroORM's reference](https://mikro-orm.io/api/knex/class/EntityManager) for a full list of the entity manager's methods.
-
-### Why Wrap a Transactional Method
-
-The variables in the transactional method (for example, `update_`) hold values that are uncommitted to the database. They're only committed once the method finishes execution.
-
-So, if in your method you perform database operations, then use their result to perform other actions, such as connecting to a third-party service, you'll be working with uncommitted data.
-
-By placing only the database operations in a method that has the `InjectTransactionManager` and using it in a wrapper method, the wrapper method receives the committed result of the transactional method.
-
-This is also useful if you perform heavy data normalization outside of the database operations. In that case, you don't hold the transaction for a longer time than needed.
-
-For example, the `update` method could be changed to the following:
-
-```ts
-// other imports...
-import { 
-  InjectManager,
-  InjectTransactionManager,
-  MedusaContext,
-} from "@medusajs/framework/utils"
-import { Context } from "@medusajs/framework/types"
-import { EntityManager } from "@mikro-orm/knex"
-
-class BlogModuleService {
-  // ...
-  @InjectTransactionManager()
-  protected async update_(
-    // ...
-  ): Promise<any> {
-    // ...
-  }
-  @InjectManager()
-  async update(
-    input: {
-      id: string,
-      name: string
-    },
-    @MedusaContext() sharedContext?: Context<EntityManager>
-  ) {
-    const newData = await this.update_(input, sharedContext)
-
-    // example method that sends data to another system
-    await this.sendNewDataToSystem(newData)
-
-    return newData
-  }
-}
-```
-
-In this case, only the `update_` method is wrapped in a transaction. The returned value `newData` holds the committed result, which can be used for other operations, such as passed to a `sendNewDataToSystem` method.
-
-### Using Methods in Transactional Methods
-
-If your transactional method uses other methods that accept a Medusa context, pass the shared context to those methods.
-
-For example:
-
-```ts
-// other imports...
-import { 
-  InjectTransactionManager,
-  MedusaContext,
-} from "@medusajs/framework/utils"
-import { Context } from "@medusajs/framework/types"
-import { EntityManager } from "@mikro-orm/knex"
-
-class BlogModuleService {
-  // ...
-  @InjectTransactionManager()
-  protected async anotherMethod(
-    @MedusaContext() sharedContext?: Context<EntityManager>
-  ) {
-    // ...
-  }
-  
-  @InjectTransactionManager()
-  protected async update_(
-    input: {
-      id: string,
-      name: string
-    },
-    @MedusaContext() sharedContext?: Context<EntityManager>
-  ): Promise<any> {
-    this.anotherMethod(sharedContext)
-  }
-}
-```
-
-You use the `anotherMethod` transactional method in the `update_` transactional method, so you pass it the shared context.
-
-The `anotherMethod` now runs in the same transaction as the `update_` method.
-
-***
-
-## Configure Transactions
-
-To configure the transaction, such as its [isolation level](https://www.postgresql.org/docs/current/transaction-iso.html), use the `baseRepository` dependency registered in your module's container.
-
-The `baseRepository` is an instance of a repository class that provides methods to create transactions, run database operations, and more.
-
-The `baseRepository` has a `transaction` method that allows you to run a function within a transaction and configure that transaction.
-
-For example, resolve the `baseRepository` in your service's constructor:
-
-### Extending Service Factory
-
-```ts highlights={[["14"]]}
-import { MedusaService } from "@medusajs/framework/utils"
-import Post from "./models/post"
-import { DAL } from "@medusajs/framework/types"
-
-type InjectedDependencies = {
-  baseRepository: DAL.RepositoryService
-}
-
-class BlogModuleService extends MedusaService({
-  Post,
-}){
-  protected baseRepository_: DAL.RepositoryService
-
-  constructor({ baseRepository }: InjectedDependencies) {
-    super(...arguments)
-    this.baseRepository_ = baseRepository
-  }
-}
-
-export default BlogModuleService
-```
-
-### Without Service Factory
-
-```ts highlights={[["10"]]}
-import { DAL } from "@medusajs/framework/types"
-
-type InjectedDependencies = {
-  baseRepository: DAL.RepositoryService
-}
-
-class BlogModuleService {
-  protected baseRepository_: DAL.RepositoryService
-
-  constructor({ baseRepository }: InjectedDependencies) {
-    this.baseRepository_ = baseRepository
-  }
-}
-
-export default BlogModuleService
-```
-
-Then, add the following method that uses it:
-
-```ts highlights={repoHighlights}
-// ...
-import { 
-  InjectManager,
-  InjectTransactionManager,
-  MedusaContext,
-} from "@medusajs/framework/utils"
-import { Context } from "@medusajs/framework/types"
-import { EntityManager } from "@mikro-orm/knex"
-
-class BlogModuleService {
-  // ...
-  @InjectTransactionManager()
-  protected async update_(
-    input: {
-      id: string,
-      name: string
-    },
-    @MedusaContext() sharedContext?: Context<EntityManager>
-  ): Promise<any> {
-    return await this.baseRepository_.transaction(
-      async (transactionManager) => {
-        await transactionManager.nativeUpdate(
-          "my_custom",
-          {
-            id: input.id,
-          },
-          {
-            name: input.name,
-          }
-        )
-
-        // retrieve again
-        const updatedRecord = await transactionManager.execute(
-          `SELECT * FROM my_custom WHERE id = '${input.id}'`
-        )
-
-        return updatedRecord
-      },
-      {
-        transaction: sharedContext?.transactionManager,
-      }
-    )
-  }
-
-  @InjectManager()
-  async update(
-    input: {
-      id: string,
-      name: string
-    },
-    @MedusaContext() sharedContext?: Context<EntityManager>
-  ) {
-    return await this.update_(input, sharedContext)
-  }
-}
-```
-
-The `update_` method uses the `baseRepository_.transaction` method to wrap a function in a transaction.
-
-The function parameter receives a transactional entity manager as a parameter. Use it to perform the database operations.
-
-The `baseRepository_.transaction` method also receives as a second parameter an object of options. You must pass in it the `transaction` property and set its value to the `sharedContext.transactionManager` property so that the function wrapped in the transaction uses the injected transaction manager.
-
-Refer to [MikroORM's reference](https://mikro-orm.io/api/knex/class/EntityManager) for a full list of the entity manager's methods.
-
-### Transaction Options
-
-The second parameter of the `baseRepository_.transaction` method is an object of options that accepts the following properties:
-
-1. `transaction`: Set the transactional entity manager passed to the function. You must provide this option as explained in the previous section.
-
-```ts highlights={[["16"]]}
-// other imports...
-import { EntityManager } from "@mikro-orm/knex"
-import { 
-  InjectTransactionManager,
-  MedusaContext,
-} from "@medusajs/framework/utils"
-import { Context } from "@medusajs/framework/types"
-import { EntityManager } from "@mikro-orm/knex"
-
-class BlogModuleService {
-  // ...
-  @InjectTransactionManager()
-  async update_(
-    input: {
-      id: string,
-      name: string
-    },
-    @MedusaContext() sharedContext?: Context<EntityManager>
-  ): Promise<any> {
-    return await this.baseRepository_.transaction<EntityManager>(
-      async (transactionManager) => {
-        // ...
-      },
-      {
-        transaction: sharedContext?.transactionManager,
-      }
-    )
-  }
-}
-```
-
-2. `isolationLevel`: Sets the transaction's [isolation level](https://www.postgresql.org/docs/current/transaction-iso.html). Its values can be:
-   - `read committed`
-   - `read uncommitted`
-   - `snapshot`
-   - `repeatable read`
-   - `serializable`
-
-```ts highlights={[["19"]]}
-// other imports...
-import { 
-  InjectTransactionManager,
-  MedusaContext,
-} from "@medusajs/framework/utils"
-import { Context } from "@medusajs/framework/types"
-import { EntityManager } from "@mikro-orm/knex"
-import { IsolationLevel } from "@mikro-orm/core"
-
-class BlogModuleService {
-  // ...
-  @InjectTransactionManager()
-  async update_(
-    input: {
-      id: string,
-      name: string
-    },
-    @MedusaContext() sharedContext?: Context<EntityManager>
-  ): Promise<any> {
-    return await this.baseRepository_.transaction<EntityManager>(
-      async (transactionManager) => {
-        // ...
-      },
-      {
-        isolationLevel: IsolationLevel.READ_COMMITTED,
-      }
-    )
-  }
-}
-```
-
-3. `enableNestedTransactions`: (default: `false`) whether to allow using nested transactions.
-   - If `transaction` is provided and this is disabled, the manager in `transaction` is re-used.
-
-```ts highlights={[["16"]]}
-// other imports...
-import { 
-  InjectTransactionManager,
-  MedusaContext,
-} from "@medusajs/framework/utils"
-import { Context } from "@medusajs/framework/types"
-import { EntityManager } from "@mikro-orm/knex"
-
-class BlogModuleService {
-  // ...
-  @InjectTransactionManager()
-  async update_(
-    input: {
-      id: string,
-      name: string
-    },
-    @MedusaContext() sharedContext?: Context<EntityManager>
-  ): Promise<any> {
-    return await this.baseRepository_.transaction<EntityManager>(
-      async (transactionManager) => {
-        // ...
-      },
-      {
-        enableNestedTransactions: false,
-      }
-    )
-  }
-}
-```
-
-
-# Infrastructure Modules
-
-In this chapter, you’ll learn about Infrastructure Modules.
-
-## What is an Infrastructure Module?
-
-An Infrastructure Module implements features and mechanisms related to the Medusa application’s architecture and infrastructure.
-
-Since modules are interchangeable, you have more control over Medusa’s architecture. For example, you can choose to use Memcached for event handling instead of Redis.
-
-***
-
-## Infrastructure Module Types
-
-There are different Infrastructure Module types including:
-
-![Diagram illustrating how the modules connect to third-party services](https://res.cloudinary.com/dza7lstvk/image/upload/v1727095814/Medusa%20Book/infrastructure-modules_bj9bb9.jpg)
-
-- Cache Module: Defines the caching mechanism or logic to cache computational results.
-- Event Module: Integrates a pub/sub service to handle subscribing to and emitting events.
-- Workflow Engine Module: Integrates a service to store and track workflow executions and steps.
-- File Module: Integrates a storage service to handle uploading and managing files.
-- Notification Module: Integrates a third-party service or defines custom logic to send notifications to users and customers.
-- Locking Module: Integrates a service that manages access to shared resources by multiple processes or threads.
-
-***
-
-## Infrastructure Modules List
-
-Refer to the [Infrastructure Modules reference](https://docs.medusajs.com/resources/infrastructure-modules/index.html.md) for a list of Medusa’s Infrastructure Modules, available modules to install, and how to create an Infrastructure Module.
-
-
-# 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 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.
-
-
-# Loaders
-
-In this chapter, you’ll learn about loaders and how to use them.
-
-## What is a Loader?
-
-When building a commerce application, you'll often need to execute an action the first time the application starts. For example, if your application needs to connect to databases other than Medusa's PostgreSQL database, you might need to establish a connection on application startup.
-
-In Medusa, you can execute an action when the application starts using a loader. A loader is a function exported by a [module](https://docs.medusajs.com/learn/fundamentals/modules/index.html.md), which is a package of business logic for a single domain. When the Medusa application starts, it executes all loaders exported by configured modules.
-
-Loaders are useful to register custom resources, such as database connections, in the [module's container](https://docs.medusajs.com/learn/fundamentals/modules/container/index.html.md), which is similar to the [Medusa container](https://docs.medusajs.com/learn/fundamentals/medusa-container/index.html.md) but includes only [resources available to the module](https://docs.medusajs.com/resources/medusa-container-resources#module-container-resources/index.html.md). Modules are isolated, so they can't access resources outside of them, such as a service in another module.
-
-Medusa isolates modules to ensure that they're re-usable across applications, aren't tightly coupled to other resources, and don't have implications when integrated into the Medusa application. Learn more about why modules are isolated in [this chapter](https://docs.medusajs.com/learn/fundamentals/modules/isolation/index.html.md), and check out [this reference for the list of resources in the module's container](https://docs.medusajs.com/resources/medusa-container-resources#module-container-resources/index.html.md).
-
-***
-
-## How to Create a Loader?
-
-### 1. Implement Loader Function
-
-You create a loader function in a TypeScript or JavaScript file under a module's `loaders` directory.
-
-For example, consider you have a `hello` module, you can create a loader at `src/modules/hello/loaders/hello-world.ts` with the following content:
-
-![Example of loader file in the application's directory structure](https://res.cloudinary.com/dza7lstvk/image/upload/v1732865671/Medusa%20Book/loader-dir-overview_eg6vtu.jpg)
-
-Learn how to create a module in [this chapter](https://docs.medusajs.com/learn/fundamentals/modules/index.html.md).
-
-```ts title="src/modules/hello/loaders/hello-world.ts"
-import {
-  LoaderOptions,
-} from "@medusajs/framework/types"
-
-export default async function helloWorldLoader({
-  container,
-}: LoaderOptions) {
-  const logger = container.resolve("logger")
-
-  logger.info("[HELLO MODULE] Just started the Medusa application!")
-}
-```
-
-The loader file exports an async function, which is the function executed when the application loads.
-
-The function receives an object parameter that has a `container` property, which is the module's container that you can use to resolve resources from. In this example, you resolve the Logger utility to log a message in the terminal.
-
-Find the list of resources in the module's container in [this reference](https://docs.medusajs.com/resources/medusa-container-resources#module-container-resources/index.html.md).
-
-### 2. Export Loader in Module Definition
-
-After implementing the loader, you must export it in the module's definition in the `index.ts` file at the root of the module's directory. Otherwise, the Medusa application will not run it.
-
-So, to export the loader you implemented above in the `hello` module, add the following to `src/modules/hello/index.ts`:
-
-```ts title="src/modules/hello/index.ts"
-// other imports...
-import helloWorldLoader from "./loaders/hello-world"
-
-export default Module("hello", {
-  // ...
-  loaders: [helloWorldLoader],
-})
-```
-
-The second parameter of the `Module` function accepts a `loaders` property whose value is an array of loader functions. The Medusa application will execute these functions when it starts.
-
-### Test the Loader
-
-Assuming your module is [added to Medusa's configuration](https://docs.medusajs.com/learn/fundamentals/modules#4-add-module-to-medusas-configurations/index.html.md), you can test the loader by starting the Medusa application:
-
-```bash npm2yarn
-npm run dev
-```
-
-Then, you'll find the following message logged in the terminal:
-
-```plain
-info:   [HELLO MODULE] Just started the Medusa application!
-```
-
-This indicates that the loader in the `hello` module ran and logged this message.
-
-***
-
-## When are Loaders Executed?
-
-When you start the Medusa application, it executes the loaders of all modules in their registration order.
-
-A loader is executed before the module's main service is instantiated. So, you can use loaders to register in the module's container resources that you want to use in the module's service. For example, you can register a database connection.
-
-Loaders are also useful to only load a module if a certain condition is met. For example, if you try to connect to a database in a loader but the connection fails, you can throw an error in the loader to prevent the module from being loaded. This is useful if your module depends on an external service to work.
-
-***
-
-## Example: Register Custom MongoDB Connection
-
-As mentioned in this chapter's introduction, loaders are most useful when you need to register a custom resource in the module's container to re-use it in other customizations in the module.
-
-Consider your have a MongoDB module that allows you to perform operations on a MongoDB database.
-
-### Prerequisites
-
-- [MongoDB database that you can connect to from a local machine.](https://www.mongodb.com)
-- [Install the MongoDB SDK in your Medusa application.](https://www.mongodb.com/docs/drivers/node/current/quick-start/download-and-install/#install-the-node.js-driver)
-
-To connect to the database, you create the following loader in your module:
-
-```ts title="src/modules/mongo/loaders/connection.ts" highlights={loaderHighlights}
-import { LoaderOptions } from "@medusajs/framework/types"
-import { asValue } from "awilix"
-import { MongoClient } from "mongodb"
-
-type ModuleOptions = {
-  connection_url?: string
-  db_name?: string
-}
-
-export default async function mongoConnectionLoader({
-  container,
-  options,
-}: LoaderOptions<ModuleOptions>) {
-  if (!options.connection_url) {
-    throw new Error(`[MONGO MDOULE]: connection_url option is required.`)
-  }
-  if (!options.db_name) {
-    throw new Error(`[MONGO MDOULE]: db_name option is required.`)
-  }
-  const logger = container.resolve("logger")
-  
-  try {
-    const clientDb = (
-      await (new MongoClient(options.connection_url)).connect()
-    ).db(options.db_name)
-
-    logger.info("Connected to MongoDB")
-
-    container.register(
-      "mongoClient",
-      asValue(clientDb)
-    )
-  } catch (e) {
-    logger.error(
-      `[MONGO MDOULE]: An error occurred while connecting to MongoDB: ${e}`
-    )
-  }
-}
-```
-
-The loader function accepts in its object parameter an `options` property, which is the options passed to the module in Medusa's configurations. For example:
-
-```ts title="medusa-config.ts" highlights={optionHighlights}
-module.exports = defineConfig({
-  // ...
-  modules: [
-    {
-      resolve: "./src/modules/mongo",
-      options: {
-        connection_url: process.env.MONGO_CONNECTION_URL,
-        db_name: process.env.MONGO_DB_NAME,
-      },
-    },
-  ],
-})
-```
-
-Passing options is useful when your module needs informations like connection URLs or API keys, as it ensures your module can be re-usable across applications. For the MongoDB Module, you expect two options:
-
-- `connection_url`: the URL to connect to the MongoDB database.
-- `db_name`: The name of the database to connect to.
-
-In the loader, you check first that these options are set before proceeding. Then, you create an instance of the MongoDB client and connect to the database specified in the options.
-
-After creating the client, you register it in the module's container using the container's `register` method. The method accepts two parameters:
-
-1. The key to register the resource under, which in this case is `mongoClient`. You'll use this name later to resolve the client.
-2. The resource to register in the container, which is the MongoDB client you created. However, you don't pass the resource as-is. Instead, you need to use an `asValue` function imported from the [awilix package](https://github.com/jeffijoe/awilix), which is the package used to implement the container functionality in Medusa.
-
-### Use Custom Registered Resource in Module's Service
-
-After registering the custom MongoDB client in the module's container, you can now resolve and use it in the module's service.
-
-For example:
-
-```ts title="src/modules/mongo/service.ts"
-import type { Db } from "mongodb"
-
-type InjectedDependencies = {
-  mongoClient: Db
-}
-
-export default class MongoModuleService {
-  private mongoClient_: Db
-
-  constructor({ mongoClient }: InjectedDependencies) {
-    this.mongoClient_ = mongoClient
-  }
-
-  async createMovie({ title }: {
-    title: string
-  }) {
-    const moviesCol = this.mongoClient_.collection("movie")
-
-    const insertedMovie = await moviesCol.insertOne({
-      title,
-    })
-
-    const movie = await moviesCol.findOne({
-      _id: insertedMovie.insertedId,
-    })
-
-    return movie
-  }
-
-  async deleteMovie(id: string) {
-    const moviesCol = this.mongoClient_.collection("movie")
-
-    await moviesCol.deleteOne({
-      _id: {
-        equals: id,
-      },
-    })
-  }
-}
-```
-
-The service `MongoModuleService` resolves the `mongoClient` resource you registered in the loader and sets it as a class property. You then use it in the `createMovie` and `deleteMovie` methods, which create and delete a document in a `movie` collection in the MongoDB database, respectively.
-
-Make sure to export the loader in the module's definition in the `index.ts` file at the root directory of the module:
-
-```ts title="src/modules/mongo/index.ts" highlights={[["9"]]}
-import { Module } from "@medusajs/framework/utils"
-import MongoModuleService from "./service"
-import mongoConnectionLoader from "./loaders/connection"
-
-export const MONGO_MODULE = "mongo"
-
-export default Module(MONGO_MODULE, {
-  service: MongoModuleService,
-  loaders: [mongoConnectionLoader],
-})
-```
-
-### Test it Out
-
-You can test the connection out by starting the Medusa application. If it's successful, you'll see the following message logged in the terminal:
-
-```bash
-info:    Connected to MongoDB
-```
-
-You can now resolve the MongoDB Module's main service in your customizations to perform operations on the MongoDB database.
-
-
-# Modules Directory Structure
-
-In this document, you'll learn about the expected files and directories in your module.
-
-![Module Directory Structure Example](https://res.cloudinary.com/dza7lstvk/image/upload/v1714379976/Medusa%20Book/modules-dir-overview_nqq7ne.jpg)
-
-## index.ts
-
-The `index.ts` file in the root of your module's directory is the only required file. It must export the module's definition as explained in a [previous chapter](https://docs.medusajs.com/learn/fundamentals/modules/index.html.md).
-
-***
-
-## service.ts
-
-A module must have a main service. It's created in the `service.ts` file at the root of your module directory as explained in a [previous chapter](https://docs.medusajs.com/learn/fundamentals/modules/index.html.md).
-
-***
-
-## Other Directories
-
-The following directories are optional and their content are explained more in the following chapters:
-
-- `models`: Holds the data models representing tables in the database.
-- `migrations`: Holds the migration files used to reflect changes on the database.
-- `loaders`: Holds the scripts to run on the Medusa application's start-up.
-
-
-# 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.
-
-## What are Module Options?
-
-A module can receive options to customize or configure its functionality. For example, if you’re creating a module that integrates a third-party service, you’ll want to receive the integration credentials in the options rather than adding them directly in your code.
-
-***
-
-## How to Pass Options to a Module?
-
-To pass options to a module, add an `options` property to the module’s configuration in `medusa-config.ts`.
-
-For example:
-
-```ts title="medusa-config.ts"
-module.exports = defineConfig({
-  // ...
-  modules: [
-    {
-      resolve: "./src/modules/blog",
-      options: {
-        capitalize: true,
-      },
-    },
-  ],
-})
-```
-
-The `options` property’s value is an object. You can pass any properties you want.
-
-### Pass Options to a Module in a Plugin
-
-If your module is part of a plugin, you can pass options to the module in the plugin’s configuration.
-
-For example:
-
-```ts title="medusa-config.ts"
-import { defineConfig } from "@medusajs/framework/utils"
-module.exports = defineConfig({
-  plugins: [
-    {
-      resolve: "@myorg/plugin-name",
-      options: {
-        capitalize: true,
-      },
-    },
-  ],
-})
-```
-
-The `options` property in the plugin configuration is passed to all modules in a plugin.
-
-***
-
-## Access Module Options in Main Service
-
-The module’s main service receives the module options as a second parameter.
-
-For example:
-
-```ts title="src/modules/blog/service.ts" highlights={[["12"], ["14", "options?: ModuleOptions"], ["17"], ["18"], ["19"]]}
-import { MedusaService } from "@medusajs/framework/utils"
-import Post from "./models/post"
-
-// recommended to define type in another file
-type ModuleOptions = {
-  capitalize?: boolean
-}
-
-export default class BlogModuleService extends MedusaService({
-  Post,
-}){
-  protected options_: ModuleOptions
-
-  constructor({}, options?: ModuleOptions) {
-    super(...arguments)
-
-    this.options_ = options || {
-      capitalize: false,
-    }
-  }
-
-  // ...
-}
-```
-
-***
-
-## Access Module Options in Loader
-
-The object that a module’s loaders receive as a parameter has an `options` property holding the module's options.
-
-For example:
-
-```ts title="src/modules/blog/loaders/hello-world.ts" highlights={[["11"], ["12", "ModuleOptions", "The type of expected module options."], ["16"]]}
-import {
-  LoaderOptions,
-} from "@medusajs/framework/types"
-
-// recommended to define type in another file
-type ModuleOptions = {
-  capitalize?: boolean
-}
-
-export default async function helloWorldLoader({
-  options,
-}: LoaderOptions<ModuleOptions>) {
-  
-  console.log(
-    "[BLOG MODULE] Just started the Medusa application!",
-    options
-  )
-}
-```
-
-***
-
-## Validate Module Options
-
-If you expect a certain option and want to throw an error if it's not provided or isn't valid, it's recommended to perform the validation in a loader. The module's service is only instantiated when it's used, whereas the loader runs the when the Medusa application starts.
-
-So, by performing the validation in the loader, you ensure you can throw an error at an early point, rather than when the module is used.
-
-For example, to validate that the Hello Module received an `apiKey` option, create the loader `src/modules/loaders/validate.ts`:
-
-```ts title="src/modules/blog/loaders/validate.ts" 
-import { LoaderOptions } from "@medusajs/framework/types"
-import { MedusaError } from "@medusajs/framework/utils"
-
-// recommended to define type in another file
-type ModuleOptions = {
-  apiKey?: string
-}
-
-export default async function validationLoader({
-  options,
-}: LoaderOptions<ModuleOptions>) {
-  if (!options.apiKey) {
-    throw new MedusaError(
-      MedusaError.Types.INVALID_DATA,
-      "Hello Module requires an apiKey option."
-    )
-  }
-}
-```
-
-Then, export the loader in the module's definition file, as explained in [this chapter](https://docs.medusajs.com/learn/fundamentals/modules/loaders/index.html.md):
-
-```ts title="src/modules/blog/index.ts"
-// other imports...
-import validationLoader from "./loaders/validate"
-
-export const BLOG_MODULE = "blog"
-
-export default Module(BLOG_MODULE, {
-  // ...
-  loaders: [validationLoader],
-})
-```
-
-Now, when the Medusa application starts, the loader will run, validating the module's options and throwing an error if the `apiKey` option is missing.
-
-
-# Translate Medusa Admin
-
-The Medusa Admin supports multiple languages, with the default being English. In this documentation, you'll learn how to contribute to the community by translating the Medusa Admin to a language you're fluent in.
-
-{/* vale docs.We = NO */}
-
-You can contribute either by translating the admin to a new language, or fixing translations for existing languages. As we can't validate every language's translations, some translations may be incorrect. Your contribution is welcome to fix any translation errors you find.
-
-{/* vale docs.We = YES */}
-
-Check out the translated languages either in the admin dashboard's settings or on [GitHub](https://github.com/medusajs/medusa/blob/develop/packages/admin/dashboard/src/i18n/languages.ts).
-
-***
-
-## How to Contribute Translation
-
-1. Clone the [Medusa monorepository](https://github.com/medusajs/medusa) to your local machine:
-
-```bash
-git clone https://github.com/medusajs/medusa.git
-```
-
-If you already have it cloned, make sure to pull the latest changes from the `develop` branch.
-
-2. Install the monorepository's dependencies. Since it's a Yarn workspace, it's highly recommended to use yarn:
-
-```bash
-yarn install
-```
-
-3. Create a branch that you'll use to open the pull request later:
-
-```bash
-git checkout -b feat/translate-<LANGUAGE>
-```
-
-Where `<LANGUAGE>` is your language name. For example, `feat/translate-da`.
-
-4. Translation files are under `packages/admin/dashboard/src/i18n/translations` as JSON files whose names are the ISO-2 name of the language.
-   - If you're adding a new language, copy the file `packages/admin/dashboard/src/i18n/translations/en.json` and paste it with the ISO-2 name for your language. For example, if you're adding Danish translations, copy the `en.json` file and paste it as `packages/admin/dashboard/src/i18n/translations/de.json`.
-   - If you're fixing a translation, find the JSON file of the language under `packages/admin/dashboard/src/i18n/translations`.
-
-5. Start translating the keys in the JSON file (or updating the targeted ones). All keys in the JSON file must be translated, and your PR tests will fail otherwise.
-   - You can check whether the JSON file is valid by running the following command in `packages/admin/dashboard`, replacing `da.json` with the JSON file's name:
-
-```bash title="packages/admin/dashboard"
-yarn i18n:validate da.json
-```
-
-6. After finishing the translation, if you're adding a new language, import its JSON file in `packages/admin/dashboard/src/i18n/translations/index.ts` and add it to the exported object:
-
-```ts title="packages/admin/dashboard/src/i18n/translations/index.ts" highlights={[["2"], ["6"], ["7"], ["8"]]}
-// other imports...
-import da from "./da.json"
-
-export default {
-  // other languages...
-  da: {
-    translation: da,
-  },
-}
-```
-
-The language's key in the object is the ISO-2 name of the language.
-
-7. If you're adding a new language, add it to the file `packages/admin/dashboard/src/i18n/languages.ts`:
-
-```ts title="packages/admin/dashboard/src/i18n/languages.ts" highlights={languageHighlights}
-import { da } from "date-fns/locale"
-// other imports...
-
-export const languages: Language[] = [
-  // other languages...
-  {
-    code: "da",
-    display_name: "Danish",
-    ltr: true,
-    date_locale: da,
-  },
-]
-```
-
-`languages` is an array having the following properties:
-
-- `code`: The ISO-2 name of the language. For example, `da` for Danish.
-- `display_name`: The language's name to be displayed in the admin.
-- `ltr`: Whether the language supports a left-to-right layout. For example, set this to `false` for languages like Arabic.
-- `date_locale`: An instance of the locale imported from the [date-fns/locale](https://date-fns.org/) package.
-
-8. Once you're done, push the changes into your branch and open a pull request on GitHub.
-
-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.
-
-
-# Service Factory
-
-In this chapter, you’ll learn about what the service factory is and how to use it.
-
-## What is the Service Factory?
-
-Medusa provides a service factory that your module’s main service can extend.
-
-The service factory generates data management methods for your data models in the database, so you don't have to implement these methods manually.
-
-Your service provides data-management functionalities of your data models.
-
-***
-
-## How to Extend the Service Factory?
-
-Medusa provides the service factory as a `MedusaService` function your service extends. The function creates and returns a service class with generated data-management methods.
-
-For example, create the file `src/modules/blog/service.ts` with the following content:
-
-```ts title="src/modules/blog/service.ts" highlights={highlights}
-import { MedusaService } from "@medusajs/framework/utils"
-import Post from "./models/post"
-
-class BlogModuleService extends MedusaService({
-  Post,
-}){
-  // TODO implement custom methods
-}
-
-export default BlogModuleService
-```
-
-### MedusaService Parameters
-
-The `MedusaService` function accepts one parameter, which is an object of data models to generate data-management methods for.
-
-In the example above, since the `BlogModuleService` extends `MedusaService`, it has methods to manage the `Post` data model, such as `createPosts`.
-
-### Generated Methods
-
-The service factory generates methods to manage the records of each of the data models provided in the first parameter in the database.
-
-The method's names are the operation's name, suffixed by the data model's key in the object parameter passed to `MedusaService`.
-
-For example, the following methods are generated for the service above:
-
-Find a complete reference of each of the methods in [this documentation](https://docs.medusajs.com/resources/service-factory-reference/index.html.md)
-
-### listPosts
-
-### listPosts
-
-This method retrieves an array of records based on filters and pagination configurations.
-
-For example:
-
-```ts
-const posts = await blogModuleService
-  .listPosts()
-
-// with filters
-const posts = await blogModuleService
-  .listPosts({
-    id: ["123"]
-  })
-```
-
-### listAndCountPosts
-
-### retrievePost
-
-This method retrieves a record by its ID.
-
-For example:
-
-```ts
-const post = await blogModuleService
-  .retrievePost("123")
-```
-
-### retrievePost
-
-### updatePosts
-
-This method updates and retrieves records of the data model.
-
-For example:
-
-```ts
-const post = await blogModuleService
-  .updatePosts({
-    id: "123",
-    title: "test"
-  })
-
-// update multiple
-const posts = await blogModuleService
-  .updatePosts([
-    {
-      id: "123",
-      title: "test"
-    },
-    {
-      id: "321",
-      title: "test 2"
-    },
-  ])
-
-// use filters
-const posts = await blogModuleService
-  .updatePosts([
-    {
-      selector: {
-        id: ["123", "321"]
-      },
-      data: {
-        title: "test"
-      }
-    },
-  ])
-```
-
-### createPosts
-
-### softDeletePosts
-
-This method soft-deletes records using an array of IDs or an object of filters.
-
-For example:
-
-```ts
-await blogModuleService.softDeletePosts("123")
-
-// soft-delete multiple
-await blogModuleService.softDeletePosts([
-  "123", "321"
-])
-
-// use filters
-await blogModuleService.softDeletePosts({
-  id: ["123", "321"]
-})
-```
-
-### updatePosts
-
-### deletePosts
-
-### softDeletePosts
-
-### restorePosts
-
-### Using a Constructor
-
-If you implement the `constructor` of your service, make sure to call `super` passing it `...arguments`.
-
-For example:
-
-```ts highlights={[["8"]]}
-import { MedusaService } from "@medusajs/framework/utils"
-import Post from "./models/post"
-
-class BlogModuleService extends MedusaService({
-  Post,
-}){
-  constructor() {
-    super(...arguments)
-  }
-}
-
-export default BlogModuleService
-```
-
-
 # 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.
@@ -17364,207 +17511,6 @@ 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.
-
-### Prerequisites
-
-- [Testing Tools Setup](https://docs.medusajs.com/learn/debugging-and-testing/testing-tools/index.html.md)
-
-## Write Integration Test for Workflow
-
-Consider you have the following workflow defined at `src/workflows/hello-world.ts`:
-
-```ts title="src/workflows/hello-world.ts"
-import {
-  createWorkflow,
-  createStep,
-  StepResponse,
-  WorkflowResponse,
-} from "@medusajs/framework/workflows-sdk"
-
-const step1 = createStep("step-1", () => {
-  return new StepResponse("Hello, World!")
-})
-
-export const helloWorldWorkflow = createWorkflow(
-  "hello-world-workflow",
-  () => {
-    const message = step1()
-
-    return new WorkflowResponse(message)
-  }
-)
-```
-
-To write a test for this workflow, create the file `integration-tests/http/workflow.spec.ts` with the following content:
-
-```ts title="integration-tests/http/workflow.spec.ts"
-import { medusaIntegrationTestRunner } from "@medusajs/test-utils"
-import { helloWorldWorkflow } from "../../src/workflows/hello-world"
-
-medusaIntegrationTestRunner({
-  testSuite: ({ getContainer }) => {
-    describe("Test hello-world workflow", () => {
-      it("returns message", async () => {
-        const { result } = await helloWorldWorkflow(getContainer())
-          .run()
-
-        expect(result).toEqual("Hello, World!")
-      })
-    })
-  },
-})
-
-jest.setTimeout(60 * 1000)
-```
-
-You use the `medusaIntegrationTestRunner` to write an integration test for the workflow. The test pases if the workflow returns the string `"Hello, World!"`.
-
-### Jest Timeout
-
-Since your tests connect to the database and perform actions that require more time than the typical tests, make sure to increase the timeout in your test:
-
-```ts title="integration-tests/http/custom-routes.spec.ts"
-// in your test's file
-jest.setTimeout(60 * 1000)
-```
-
-***
-
-## Run Test
-
-Run the following command to run your tests:
-
-```bash npm2yarn
-npm run test:integration
-```
-
-If you don't have a `test:integration` script in `package.json`, refer to the [Medusa Testing Tools chapter](https://docs.medusajs.com/learn/debugging-and-testing/testing-tools#add-test-commands/index.html.md).
-
-This runs your Medusa application and runs the tests available under the `integrations/http` directory.
-
-***
-
-## Test That a Workflow Throws an Error
-
-You might want to test that a workflow throws an error in certain cases. To test this:
-
-- Disable the `throwOnError` option when executing the workflow.
-- Use the returned `errors` property to check what errors were thrown.
-
-For example, if you have a step that throws this error:
-
-```ts title="src/workflows/hello-world.ts"
-import { MedusaError } from "@medusajs/framework/utils"
-import { createStep } from "@medusajs/framework/workflows-sdk"
-
-const step1 = createStep("step-1", () => {
-  throw new MedusaError(MedusaError.Types.NOT_FOUND, "Item doesn't exist")
-})
-```
-
-You can write the following test to ensure that the workflow throws that error:
-
-```ts title="integration-tests/http/workflow.spec.ts"
-import { medusaIntegrationTestRunner } from "@medusajs/test-utils"
-import { helloWorldWorkflow } from "../../src/workflows/hello-world"
-
-medusaIntegrationTestRunner({
-  testSuite: ({ getContainer }) => {
-    describe("Test hello-world workflow", () => {
-      it("returns message", async () => {
-        const { errors } = await helloWorldWorkflow(getContainer())
-          .run({
-            throwOnError: false,
-          })
-
-        expect(errors.length).toBeGreaterThan(0)
-        expect(errors[0].error.message).toBe("Item doesn't exist")
-      })
-    })
-  },
-})
-
-jest.setTimeout(60 * 1000)
-```
-
-The `errors` property contains an array of errors thrown during the execution of the workflow. Each error item has an `error` object, being the error thrown.
-
-If you threw a `MedusaError`, then you can check the error message in `errors[0].error.message`.
-
-
-# Example: Integration Tests for a Module
-
-In this chapter, find an example of writing an integration test for a module using [moduleIntegrationTestRunner](https://docs.medusajs.com/learn/debugging-and-testing/testing-tools/modules-tests/index.html.md) from Medusa's Testing Framework.
-
-### Prerequisites
-
-- [Testing Tools Setup](https://docs.medusajs.com/learn/debugging-and-testing/testing-tools/index.html.md)
-
-## Write Integration Test for Module
-
-Consider a `blog` module with a `BlogModuleService` that has a `getMessage` method:
-
-```ts title="src/modules/blog/service.ts"
-import { MedusaService } from "@medusajs/framework/utils"
-import MyCustom from "./models/my-custom"
-
-class BlogModuleService extends MedusaService({
-  MyCustom,
-}){
-  getMessage(): string {
-    return "Hello, World!"
-  }
-}
-
-export default BlogModuleService
-```
-
-To create an integration test for the method, create the file `src/modules/blog/__tests__/service.spec.ts` with the following content:
-
-```ts title="src/modules/blog/__tests__/service.spec.ts"
-import { moduleIntegrationTestRunner } from "@medusajs/test-utils"
-import { BLOG_MODULE } from ".."
-import BlogModuleService from "../service"
-import MyCustom from "../models/my-custom"
-
-moduleIntegrationTestRunner<BlogModuleService>({
-  moduleName: BLOG_MODULE,
-  moduleModels: [MyCustom],
-  resolve: "./src/modules/blog",
-  testSuite: ({ service }) => {
-    describe("BlogModuleService", () => {
-      it("says hello world", () => {
-        const message = service.getMessage()
-
-        expect(message).toEqual("Hello, World!")
-      })
-    })
-  },
-})
-
-jest.setTimeout(60 * 1000)
-```
-
-You use the `moduleIntegrationTestRunner` function to add tests for the `blog` module. You have one test that passes if the `getMessage` method returns the `"Hello, World!"` string.
-
-***
-
-## Run Test
-
-Run the following command to run your module integration tests:
-
-```bash npm2yarn
-npm run test:integration:modules
-```
-
-If you don't have a `test:integration:modules` script in `package.json`, refer to the [Medusa Testing Tools chapter](https://docs.medusajs.com/learn/debugging-and-testing/testing-tools#add-test-commands/index.html.md).
-
-This runs your Medusa application and runs the tests available in any `__tests__` directory under the `src/modules` directory.
-
-
 # Example: Write Integration Tests for API Routes
 
 In this chapter, you'll learn how to write integration tests for API routes using [medusaIntegrationTestRunner](https://docs.medusajs.com/learn/debugging-and-testing/testing-tools/integration-tests/index.html.md) from Medusa's Testing Framework.
@@ -18134,6 +18080,207 @@ const response = await api.post(`/custom`, form, {
 ```
 
 
+# Example: Write Integration Tests for Workflows
+
+In this chapter, you'll learn how to write integration tests for workflows using [medusaIntegrationTestRunner](https://docs.medusajs.com/learn/debugging-and-testing/testing-tools/integration-tests/index.html.md) from Medusa's Testing Framwork.
+
+### Prerequisites
+
+- [Testing Tools Setup](https://docs.medusajs.com/learn/debugging-and-testing/testing-tools/index.html.md)
+
+## Write Integration Test for Workflow
+
+Consider you have the following workflow defined at `src/workflows/hello-world.ts`:
+
+```ts title="src/workflows/hello-world.ts"
+import {
+  createWorkflow,
+  createStep,
+  StepResponse,
+  WorkflowResponse,
+} from "@medusajs/framework/workflows-sdk"
+
+const step1 = createStep("step-1", () => {
+  return new StepResponse("Hello, World!")
+})
+
+export const helloWorldWorkflow = createWorkflow(
+  "hello-world-workflow",
+  () => {
+    const message = step1()
+
+    return new WorkflowResponse(message)
+  }
+)
+```
+
+To write a test for this workflow, create the file `integration-tests/http/workflow.spec.ts` with the following content:
+
+```ts title="integration-tests/http/workflow.spec.ts"
+import { medusaIntegrationTestRunner } from "@medusajs/test-utils"
+import { helloWorldWorkflow } from "../../src/workflows/hello-world"
+
+medusaIntegrationTestRunner({
+  testSuite: ({ getContainer }) => {
+    describe("Test hello-world workflow", () => {
+      it("returns message", async () => {
+        const { result } = await helloWorldWorkflow(getContainer())
+          .run()
+
+        expect(result).toEqual("Hello, World!")
+      })
+    })
+  },
+})
+
+jest.setTimeout(60 * 1000)
+```
+
+You use the `medusaIntegrationTestRunner` to write an integration test for the workflow. The test pases if the workflow returns the string `"Hello, World!"`.
+
+### Jest Timeout
+
+Since your tests connect to the database and perform actions that require more time than the typical tests, make sure to increase the timeout in your test:
+
+```ts title="integration-tests/http/custom-routes.spec.ts"
+// in your test's file
+jest.setTimeout(60 * 1000)
+```
+
+***
+
+## Run Test
+
+Run the following command to run your tests:
+
+```bash npm2yarn
+npm run test:integration
+```
+
+If you don't have a `test:integration` script in `package.json`, refer to the [Medusa Testing Tools chapter](https://docs.medusajs.com/learn/debugging-and-testing/testing-tools#add-test-commands/index.html.md).
+
+This runs your Medusa application and runs the tests available under the `integrations/http` directory.
+
+***
+
+## Test That a Workflow Throws an Error
+
+You might want to test that a workflow throws an error in certain cases. To test this:
+
+- Disable the `throwOnError` option when executing the workflow.
+- Use the returned `errors` property to check what errors were thrown.
+
+For example, if you have a step that throws this error:
+
+```ts title="src/workflows/hello-world.ts"
+import { MedusaError } from "@medusajs/framework/utils"
+import { createStep } from "@medusajs/framework/workflows-sdk"
+
+const step1 = createStep("step-1", () => {
+  throw new MedusaError(MedusaError.Types.NOT_FOUND, "Item doesn't exist")
+})
+```
+
+You can write the following test to ensure that the workflow throws that error:
+
+```ts title="integration-tests/http/workflow.spec.ts"
+import { medusaIntegrationTestRunner } from "@medusajs/test-utils"
+import { helloWorldWorkflow } from "../../src/workflows/hello-world"
+
+medusaIntegrationTestRunner({
+  testSuite: ({ getContainer }) => {
+    describe("Test hello-world workflow", () => {
+      it("returns message", async () => {
+        const { errors } = await helloWorldWorkflow(getContainer())
+          .run({
+            throwOnError: false,
+          })
+
+        expect(errors.length).toBeGreaterThan(0)
+        expect(errors[0].error.message).toBe("Item doesn't exist")
+      })
+    })
+  },
+})
+
+jest.setTimeout(60 * 1000)
+```
+
+The `errors` property contains an array of errors thrown during the execution of the workflow. Each error item has an `error` object, being the error thrown.
+
+If you threw a `MedusaError`, then you can check the error message in `errors[0].error.message`.
+
+
+# Example: Integration Tests for a Module
+
+In this chapter, find an example of writing an integration test for a module using [moduleIntegrationTestRunner](https://docs.medusajs.com/learn/debugging-and-testing/testing-tools/modules-tests/index.html.md) from Medusa's Testing Framework.
+
+### Prerequisites
+
+- [Testing Tools Setup](https://docs.medusajs.com/learn/debugging-and-testing/testing-tools/index.html.md)
+
+## Write Integration Test for Module
+
+Consider a `blog` module with a `BlogModuleService` that has a `getMessage` method:
+
+```ts title="src/modules/blog/service.ts"
+import { MedusaService } from "@medusajs/framework/utils"
+import MyCustom from "./models/my-custom"
+
+class BlogModuleService extends MedusaService({
+  MyCustom,
+}){
+  getMessage(): string {
+    return "Hello, World!"
+  }
+}
+
+export default BlogModuleService
+```
+
+To create an integration test for the method, create the file `src/modules/blog/__tests__/service.spec.ts` with the following content:
+
+```ts title="src/modules/blog/__tests__/service.spec.ts"
+import { moduleIntegrationTestRunner } from "@medusajs/test-utils"
+import { BLOG_MODULE } from ".."
+import BlogModuleService from "../service"
+import MyCustom from "../models/my-custom"
+
+moduleIntegrationTestRunner<BlogModuleService>({
+  moduleName: BLOG_MODULE,
+  moduleModels: [MyCustom],
+  resolve: "./src/modules/blog",
+  testSuite: ({ service }) => {
+    describe("BlogModuleService", () => {
+      it("says hello world", () => {
+        const message = service.getMessage()
+
+        expect(message).toEqual("Hello, World!")
+      })
+    })
+  },
+})
+
+jest.setTimeout(60 * 1000)
+```
+
+You use the `moduleIntegrationTestRunner` function to add tests for the `blog` module. You have one test that passes if the `getMessage` method returns the `"Hello, World!"` string.
+
+***
+
+## Run Test
+
+Run the following command to run your module integration tests:
+
+```bash npm2yarn
+npm run test:integration:modules
+```
+
+If you don't have a `test:integration:modules` script in `package.json`, refer to the [Medusa Testing Tools chapter](https://docs.medusajs.com/learn/debugging-and-testing/testing-tools#add-test-commands/index.html.md).
+
+This runs your Medusa application and runs the tests available in any `__tests__` directory under the `src/modules` directory.
+
+
 # Commerce Modules
 
 In this section of the documentation, you'll find guides and references related to Medusa's Commerce Modules.
@@ -18464,277 +18611,6 @@ Learn more about workflows in [this documentation](https://docs.medusajs.com/doc
 ***
 
 
-# Auth Module
-
-In this section of the documentation, you will find resources to learn more about the Auth Module and how to use it in your application.
-
-Medusa has auth related features available out-of-the-box through the Auth Module. A [module](https://docs.medusajs.com/docs/learn/fundamentals/modules/index.html.md) is a standalone package that provides features for a single domain. Each of Medusa's commerce features are placed in Commerce Modules, such as this Auth Module.
-
-Learn more about why modules are isolated in [this documentation](https://docs.medusajs.com/docs/learn/fundamentals/modules/isolation/index.html.md).
-
-## Auth Features
-
-- [Basic User Authentication](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/auth/authentication-route#1-basic-authentication-flow/index.html.md): Authenticate users using their email and password credentials.
-- [Third-Party and Social Authentication](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/auth/authentication-route#2-third-party-service-authenticate-flow/index.html.md): Authenticate users using third-party services and social platforms, such as [Google](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/auth/auth-providers/google/index.html.md) and [GitHub](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/auth/auth-providers/github/index.html.md).
-- [Authenticate Custom Actor Types](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/auth/create-actor-type/index.html.md): Create custom user or actor types, such as managers, authenticate them in your application, and guard routes based on the custom user types.
-- [Custom Authentication Providers](https://docs.medusajs.com/references/auth/provider/index.html.md): Integrate third-party services with custom authentication providors.
-
-***
-
-## How to Use the Auth Module
-
-In your Medusa application, you build flows around Commerce Modules. A flow is built as a [Workflow](https://docs.medusajs.com/docs/learn/fundamentals/workflows/index.html.md), which is a special function composed of a series of steps that guarantees data consistency and reliable roll-back mechanism.
-
-You can build custom workflows and steps. You can also re-use Medusa's workflows and steps, which are provided by the `@medusajs/medusa/core-flows` package.
-
-For example:
-
-```ts title="src/workflows/authenticate-user.ts" highlights={highlights}
-import { 
-  createWorkflow, 
-  WorkflowResponse,
-  createStep,
-  StepResponse,
-} from "@medusajs/framework/workflows-sdk"
-import { Modules, MedusaError } from "@medusajs/framework/utils"
-import { MedusaRequest } from "@medusajs/framework/http"
-import { AuthenticationInput } from "@medusajs/framework/types"
-
-type Input = {
-  req: MedusaRequest
-}
-
-const authenticateUserStep = createStep(
-  "authenticate-user",
-  async ({ req }: Input, { container }) => {
-    const authModuleService = container.resolve(Modules.AUTH)
-
-    const { success, authIdentity, error } = await authModuleService
-      .authenticate(
-        "emailpass",
-       {
-          url: req.url,
-          headers: req.headers,
-          query: req.query,
-          body: req.body,
-          authScope: "admin", // or custom actor type
-          protocol: req.protocol,
-        } as AuthenticationInput
-      )
-
-    if (!success) {
-      // incorrect authentication details
-      throw new MedusaError(
-        MedusaError.Types.UNAUTHORIZED,
-        error || "Incorrect authentication details"
-      )
-    }
-
-    return new StepResponse({ authIdentity }, authIdentity?.id)
-  },
-  async (authIdentityId, { container }) => {
-    if (!authIdentityId) {
-      return
-    }
-    
-    const authModuleService = container.resolve(Modules.AUTH)
-
-    await authModuleService.deleteAuthIdentities([authIdentityId])
-  }
-)
-
-export const authenticateUserWorkflow = createWorkflow(
-  "authenticate-user",
-  (input: Input) => {
-    const { authIdentity } = authenticateUserStep(input)
-
-    return new WorkflowResponse({
-      authIdentity,
-    })
-  }
-)
-```
-
-You can then execute the workflow in your custom API routes, scheduled jobs, or subscribers:
-
-```ts title="API Route" highlights={[["11"], ["12"]]} collapsibleLines="1-6" expandButtonLabel="Show Imports"
-import type {
-  MedusaRequest,
-  MedusaResponse,
-} from "@medusajs/framework/http"
-import { authenticateUserWorkflow } from "../../workflows/authenticate-user"
-
-export async function GET(
-  req: MedusaRequest,
-  res: MedusaResponse
-) {
-  const { result } = await authenticateUserWorkflow(req.scope)
-    .run({
-      req,
-    })
-
-  res.send(result)
-}
-```
-
-Learn more about workflows in [this documentation](https://docs.medusajs.com/docs/learn/fundamentals/workflows/index.html.md).
-
-***
-
-## Configure Auth Module
-
-The Auth Module accepts options for further configurations. Refer to [this documentation](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/auth/module-options/index.html.md) for details on the module's options.
-
-***
-
-## Providers
-
-Medusa provides the following authentication providers out-of-the-box. You can use them to authenticate admin users, customers, or custom actor types.
-
-***
-
-
-# Customer Module
-
-In this section of the documentation, you will find resources to learn more about the Customer Module and how to use it in your application.
-
-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).
-
-***
-
-
 # Currency Module
 
 In this section of the documentation, you will find resources to learn more about the Currency Module and how to use it in your application.
@@ -18883,6 +18759,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.
+
+***
+
+
 # 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.
@@ -19349,6 +19355,147 @@ 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).
+
+***
+
+
 # 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.
@@ -20103,6 +20250,143 @@ Learn more about workflows in [this documentation](https://docs.medusajs.com/doc
 ***
 
 
+# Stock Location Module
+
+In this section of the documentation, you will find resources to learn more about the Stock Location Module and how to use it in your application.
+
+Refer to the [Medusa Admin User Guide](https://docs.medusajs.com/user-guide/settings/locations-and-shipping/index.html.md) to learn how to manage stock locations using the dashboard.
+
+Medusa has stock location related features available out-of-the-box through the Stock Location Module. A [module](https://docs.medusajs.com/docs/learn/fundamentals/modules/index.html.md) is a standalone package that provides features for a single domain. Each of Medusa's commerce features are placed in Commerce Modules, such as this Stock Location Module.
+
+Learn more about why modules are isolated in [this documentation](https://docs.medusajs.com/docs/learn/fundamentals/modules/isolation/index.html.md).
+
+## Stock Location Features
+
+- [Stock Location Management](https://docs.medusajs.com/references/stock-location-next/models/index.html.md): Store and manage stock locations. Medusa links stock locations with data models of other modules that require a location, such as the [Inventory Module's InventoryLevel](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/stock-location/links-to-other-modules/index.html.md).
+- [Address Management](https://docs.medusajs.com/references/stock-location-next/models/StockLocationAddress/index.html.md): Manage the address of each stock location.
+
+***
+
+## How to Use Stock Location Module's Service
+
+In your Medusa application, you build flows around Commerce Modules. A flow is built as a [Workflow](https://docs.medusajs.com/docs/learn/fundamentals/workflows/index.html.md), which is a special function composed of a series of steps that guarantees data consistency and reliable roll-back mechanism.
+
+You can build custom workflows and steps. You can also re-use Medusa's workflows and steps, which are provided by the `@medusajs/medusa/core-flows` package.
+
+For example:
+
+```ts title="src/workflows/create-stock-location.ts" highlights={highlights}
+import { 
+  createWorkflow, 
+  WorkflowResponse,
+  createStep,
+  StepResponse,
+} from "@medusajs/framework/workflows-sdk"
+import { Modules } from "@medusajs/framework/utils"
+
+const createStockLocationStep = createStep(
+  "create-stock-location",
+  async ({}, { container }) => {
+    const stockLocationModuleService = container.resolve(Modules.STOCK_LOCATION)
+
+    const stockLocation = await stockLocationModuleService.createStockLocations({
+      name: "Warehouse 1",
+    })
+
+    return new StepResponse({ stockLocation }, stockLocation.id)
+  },
+  async (stockLocationId, { container }) => {
+    if (!stockLocationId) {
+      return
+    }
+    const stockLocationModuleService = container.resolve(Modules.STOCK_LOCATION)
+
+    await stockLocationModuleService.deleteStockLocations([stockLocationId])
+  }
+)
+
+export const createStockLocationWorkflow = createWorkflow(
+  "create-stock-location",
+  () => {
+    const { stockLocation } = createStockLocationStep()
+
+    return new WorkflowResponse({ stockLocation })
+  }
+)
+```
+
+You can then execute the workflow in your custom API routes, scheduled jobs, or subscribers:
+
+### API Route
+
+```ts title="src/api/workflow/route.ts" highlights={[["11"], ["12"]]} collapsibleLines="1-6" expandButtonLabel="Show Imports"
+import type {
+  MedusaRequest,
+  MedusaResponse,
+} from "@medusajs/framework/http"
+import { createStockLocationWorkflow } from "../../workflows/create-stock-location"
+
+export async function GET(
+  req: MedusaRequest,
+  res: MedusaResponse
+) {
+  const { result } = await createStockLocationWorkflow(req.scope)
+    .run()
+
+  res.send(result)
+}
+```
+
+### Subscriber
+
+```ts title="src/subscribers/user-created.ts" highlights={[["11"], ["12"]]} collapsibleLines="1-6" expandButtonLabel="Show Imports"
+import {
+  type SubscriberConfig,
+  type SubscriberArgs,
+} from "@medusajs/framework"
+import { createStockLocationWorkflow } from "../workflows/create-stock-location"
+
+export default async function handleUserCreated({
+  event: { data },
+  container,
+}: SubscriberArgs<{ id: string }>) {
+  const { result } = await createStockLocationWorkflow(container)
+    .run()
+
+  console.log(result)
+}
+
+export const config: SubscriberConfig = {
+  event: "user.created",
+}
+```
+
+### Scheduled Job
+
+```ts title="src/jobs/run-daily.ts" highlights={[["7"], ["8"]]}
+import { MedusaContainer } from "@medusajs/framework/types"
+import { createStockLocationWorkflow } from "../workflows/create-stock-location"
+
+export default async function myCustomJob(
+  container: MedusaContainer
+) {
+  const { result } = await createStockLocationWorkflow(container)
+    .run()
+
+  console.log(result)
+}
+
+export const config = {
+  name: "run-once-a-day",
+  schedule: `0 0 * * *`,
+}
+```
+
+Learn more about workflows in [this documentation](https://docs.medusajs.com/docs/learn/fundamentals/workflows/index.html.md).
+
+***
+
+
 # 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.
@@ -20263,24 +20547,24 @@ Learn more about workflows in [this documentation](https://docs.medusajs.com/doc
 ***
 
 
-# Stock Location Module
+# User 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 User 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/settings/users/index.html.md) to learn how to manage users 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 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).
 
-## Stock Location Features
+## User 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.
+- [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 Stock Location Module's Service
+## 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.
 
@@ -20288,7 +20572,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-user.ts" highlights={highlights}
 import { 
   createWorkflow, 
   WorkflowResponse,
@@ -20297,33 +20581,37 @@ import {
 } from "@medusajs/framework/workflows-sdk"
 import { Modules } from "@medusajs/framework/utils"
 
-const createStockLocationStep = createStep(
-  "create-stock-location",
+const createUserStep = createStep(
+  "create-user",
   async ({}, { container }) => {
-    const stockLocationModuleService = container.resolve(Modules.STOCK_LOCATION)
+    const userModuleService = container.resolve(Modules.USER)
 
-    const stockLocation = await stockLocationModuleService.createStockLocations({
-      name: "Warehouse 1",
+    const user = await userModuleService.createUsers({
+      email: "user@example.com",
+      first_name: "John",
+      last_name: "Smith",
     })
 
-    return new StepResponse({ stockLocation }, stockLocation.id)
+    return new StepResponse({ user }, user.id)
   },
-  async (stockLocationId, { container }) => {
-    if (!stockLocationId) {
+  async (userId, { container }) => {
+    if (!userId) {
       return
     }
-    const stockLocationModuleService = container.resolve(Modules.STOCK_LOCATION)
+    const userModuleService = container.resolve(Modules.USER)
 
-    await stockLocationModuleService.deleteStockLocations([stockLocationId])
+    await userModuleService.deleteUsers([userId])
   }
 )
 
-export const createStockLocationWorkflow = createWorkflow(
-  "create-stock-location",
+export const createUserWorkflow = createWorkflow(
+  "create-user",
   () => {
-    const { stockLocation } = createStockLocationStep()
+    const { user } = createUserStep()
 
-    return new WorkflowResponse({ stockLocation })
+    return new WorkflowResponse({
+      user,
+    })
   }
 )
 ```
@@ -20337,13 +20625,13 @@ import type {
   MedusaRequest,
   MedusaResponse,
 } from "@medusajs/framework/http"
-import { createStockLocationWorkflow } from "../../workflows/create-stock-location"
+import { createUserWorkflow } from "../../workflows/create-user"
 
 export async function GET(
   req: MedusaRequest,
   res: MedusaResponse
 ) {
-  const { result } = await createStockLocationWorkflow(req.scope)
+  const { result } = await createUserWorkflow(req.scope)
     .run()
 
   res.send(result)
@@ -20357,13 +20645,13 @@ import {
   type SubscriberConfig,
   type SubscriberArgs,
 } from "@medusajs/framework"
-import { createStockLocationWorkflow } from "../workflows/create-stock-location"
+import { createUserWorkflow } from "../workflows/create-user"
 
 export default async function handleUserCreated({
   event: { data },
   container,
 }: SubscriberArgs<{ id: string }>) {
-  const { result } = await createStockLocationWorkflow(container)
+  const { result } = await createUserWorkflow(container)
     .run()
 
   console.log(result)
@@ -20378,12 +20666,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 { createUserWorkflow } from "../workflows/create-user"
 
 export default async function myCustomJob(
   container: MedusaContainer
 ) {
-  const { result } = await createStockLocationWorkflow(container)
+  const { result } = await createUserWorkflow(container)
     .run()
 
   console.log(result)
@@ -20399,6 +20687,12 @@ Learn more about workflows in [this documentation](https://docs.medusajs.com/doc
 
 ***
 
+## 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.
+
+***
+
 
 # Tax Module
 
@@ -20685,153 +20979,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.
-
-***
-
-
 # Links between API Key Module and Other Modules
 
 This document showcases the module links defined between the API Key Module and other Commerce Modules.
@@ -21406,6 +21553,81 @@ const { data: carts } = useQueryGraphStep({
 ```
 
 
+# Tax Lines in Cart Module
+
+In this document, you’ll learn about tax lines in a cart and how to retrieve tax lines with the Tax Module.
+
+## What are Tax Lines?
+
+A tax line indicates the tax rate of a line item or a shipping method. The [LineItemTaxLine data model](https://docs.medusajs.com/references/cart/models/LineItemTaxLine/index.html.md) represents a line item’s tax line, and the [ShippingMethodTaxLine data model](https://docs.medusajs.com/references/cart/models/ShippingMethodTaxLine/index.html.md) represents a shipping method’s tax line.
+
+![A diagram showcasing the relation between other data models and the tax line models](https://res.cloudinary.com/dza7lstvk/image/upload/v1711534431/Medusa%20Resources/cart-tax-lines_oheaq6.jpg)
+
+***
+
+## Tax Inclusivity
+
+By default, the tax amount is calculated by taking the tax rate from the line item or shipping method’s amount, and then adding them to the item/method’s subtotal.
+
+However, line items and shipping methods have an `is_tax_inclusive` property that, when enabled, indicates that the item or method’s price already includes taxes.
+
+So, instead of calculating the tax rate and adding it to the item/method’s subtotal, it’s calculated as part of the subtotal.
+
+The following diagram is a simplified showcase of how a subtotal is calculated from the taxes perspective.
+
+![A diagram showing an example of calculating the subtotal of a line item using its taxes](https://res.cloudinary.com/dza7lstvk/image/upload/v1711535295/Medusa%20Resources/cart-tax-inclusive_shpr3t.jpg)
+
+For example, if a line item's amount is `5000`, the tax rate is `10`, and tax inclusivity is enabled, the tax amount is 10% of `5000`, which is `500`, making the unit price of the line item `4500`.
+
+***
+
+## Retrieve Tax Lines
+
+When using the Cart and Tax modules together, you can use the `getTaxLines` method of the Tax Module’s main service. It retrieves the tax lines for a cart’s line items and shipping methods.
+
+```ts
+// retrieve the cart
+const cart = await cartModuleService.retrieveCart("cart_123", {
+  relations: [
+    "items.tax_lines",
+    "shipping_methods.tax_lines",
+    "shipping_address",
+  ],
+})
+
+// retrieve the tax lines
+const taxLines = await taxModuleService.getTaxLines(
+  [
+    ...(cart.items as TaxableItemDTO[]),
+    ...(cart.shipping_methods as TaxableShippingDTO[]),
+  ],
+  {
+    address: {
+      ...cart.shipping_address,
+      country_code:
+        cart.shipping_address.country_code || "us",
+    },
+  }
+)
+```
+
+Then, use the returned tax lines to set the line items and shipping methods’ tax lines:
+
+```ts
+// set line item tax lines
+await cartModuleService.setLineItemTaxLines(
+  cart.id,
+  taxLines.filter((line) => "line_item_id" in line)
+)
+
+// set shipping method tax lines
+await cartModuleService.setLineItemTaxLines(
+  cart.id,
+  taxLines.filter((line) => "shipping_line_id" in line)
+)
+```
+
+
 # Promotions Adjustments in Carts
 
 In this document, you’ll learn how a promotion is applied to a cart’s line items and shipping methods using adjustment lines.
@@ -21524,128 +21746,90 @@ await cartModuleService.setShippingMethodAdjustments(
 ```
 
 
-# Tax Lines in Cart Module
+# API Key Concepts
 
-In this document, you’ll learn about tax lines in a cart and how to retrieve tax lines with the Tax Module.
+In this document, you’ll learn about the different types of API keys, their expiration and verification.
 
-## What are Tax Lines?
+## API Key Types
 
-A tax line indicates the tax rate of a line item or a shipping method. The [LineItemTaxLine data model](https://docs.medusajs.com/references/cart/models/LineItemTaxLine/index.html.md) represents a line item’s tax line, and the [ShippingMethodTaxLine data model](https://docs.medusajs.com/references/cart/models/ShippingMethodTaxLine/index.html.md) represents a shipping method’s tax line.
+There are two types of API keys:
 
-![A diagram showcasing the relation between other data models and the tax line models](https://res.cloudinary.com/dza7lstvk/image/upload/v1711534431/Medusa%20Resources/cart-tax-lines_oheaq6.jpg)
+- `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).
 
 ***
 
-## Tax Inclusivity
+## API Key Expiration
 
-By default, the tax amount is calculated by taking the tax rate from the line item or shipping method’s amount, and then adding them to the item/method’s subtotal.
+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).
 
-However, line items and shipping methods have an `is_tax_inclusive` property that, when enabled, indicates that the item or method’s price already includes taxes.
-
-So, instead of calculating the tax rate and adding it to the item/method’s subtotal, it’s calculated as part of the subtotal.
-
-The following diagram is a simplified showcase of how a subtotal is calculated from the taxes perspective.
-
-![A diagram showing an example of calculating the subtotal of a line item using its taxes](https://res.cloudinary.com/dza7lstvk/image/upload/v1711535295/Medusa%20Resources/cart-tax-inclusive_shpr3t.jpg)
-
-For example, if a line item's amount is `5000`, the tax rate is `10`, and tax inclusivity is enabled, the tax amount is 10% of `5000`, which is `500`, making the unit price of the line item `4500`.
+The associated token is no longer usable or verifiable.
 
 ***
 
-## Retrieve Tax Lines
+## Token Verification
 
-When using the Cart and Tax modules together, you can use the `getTaxLines` method of the Tax Module’s main service. It retrieves the tax lines for a cart’s line items and shipping methods.
+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 Currency Module and Other Modules
+
+This document showcases the module links defined between the Currency Module and other Commerce Modules.
+
+## Summary
+
+The Currency Module has the following links to other modules:
+
+Read-only links are used to query data across modules, but the relations aren't stored in a pivot table in the database.
+
+|First Data Model|Second Data Model|Type|Description|
+|---|---|---|---|
+| in ||Read-only - has one||
+
+***
+
+## Store Module
+
+The Store Module has a `Currency` data model that stores the supported currencies of a store. However, these currencies don't hold all the details of a currency, such as its name or symbol.
+
+Instead, Medusa defines a read-only link between the [Store Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/store/index.html.md)'s `StoreCurrency` data model and the Currency Module's `Currency` data model. Because the link is read-only from the `Store`'s side, you can only retrieve the details of a store's supported currencies, and not the other way around.
+
+### Retrieve with Query
+
+To retrieve the details of a store's currencies with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `supported_currencies.currency.*` in `fields`:
+
+### query.graph
 
 ```ts
-// retrieve the cart
-const cart = await cartModuleService.retrieveCart("cart_123", {
-  relations: [
-    "items.tax_lines",
-    "shipping_methods.tax_lines",
-    "shipping_address",
+const { data: stores } = await query.graph({
+  entity: "store",
+  fields: [
+    "supported_currencies.currency.*",
   ],
 })
 
-// retrieve the tax lines
-const taxLines = await taxModuleService.getTaxLines(
-  [
-    ...(cart.items as TaxableItemDTO[]),
-    ...(cart.shipping_methods as TaxableShippingDTO[]),
-  ],
-  {
-    address: {
-      ...cart.shipping_address,
-      country_code:
-        cart.shipping_address.country_code || "us",
-    },
-  }
-)
+// stores[0].supported_currencies[0].currency
 ```
 
-Then, use the returned tax lines to set the line items and shipping methods’ tax lines:
+### useQueryGraphStep
 
 ```ts
-// set line item tax lines
-await cartModuleService.setLineItemTaxLines(
-  cart.id,
-  taxLines.filter((line) => "line_item_id" in line)
-)
+import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
 
-// set shipping method tax lines
-await cartModuleService.setLineItemTaxLines(
-  cart.id,
-  taxLines.filter((line) => "shipping_line_id" in line)
-)
-```
+// ...
 
-
-# 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"],
-      },
-      // ...
-    },
-    // ...
-  },
+const { data: stores } = useQueryGraphStep({
+  entity: "store",
+  fields: [
+    "supported_currencies.currency.*",
+  ],
 })
+
+// stores[0].supported_currencies[0].currency
 ```
 
-When you specify the `authMethodsPerActor` configuration, it overrides the default. So, if you don't specify any providers for an actor type, users of that actor type can't authenticate with any provider.
-
-***
-
-## How to Create an Auth Module Provider
-
-Refer to [this guide](https://docs.medusajs.com/references/auth/provider/index.html.md) to learn how to create an auth module provider.
-
 
 # Auth Identity and Actor Types
 
@@ -21716,32 +21900,396 @@ For example, if you have a custom module with a `Manager` data model, you can au
 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).
 
 
-# API Key Concepts
+# Auth Providers
 
-In this document, you’ll learn about the different types of API keys, their expiration and verification.
+In this document, you’ll learn how the Auth Module handles authentication using providers.
 
-## API Key Types
+## What's an Auth Module Provider?
 
-There are two types of API keys:
+An auth module provider handles authenticating customers and users, either using custom logic or by integrating a third-party service.
 
-- `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.
+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.
 
-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).
+### 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)
 
 ***
 
-## API Key Expiration
+## Configure Allowed Auth Providers of Actor Types
 
-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).
+By default, users of all actor types can authenticate with all installed auth module providers.
 
-The associated token is no longer usable or verifiable.
+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.
 
 ***
 
-## Token Verification
+## How to Create an Auth Module Provider
 
-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.
+Refer to [this guide](https://docs.medusajs.com/references/auth/provider/index.html.md) to learn how to create an auth module provider.
+
+
+# How to Use Authentication Routes
+
+In this document, you'll learn about the authentication routes and how to use them to create and log-in users, and reset their password.
+
+These routes are added by Medusa's HTTP layer, not the Auth Module.
+
+## Types of Authentication Flows
+
+### 1. Basic Authentication Flow
+
+This authentication flow doesn't require validation with third-party services.
+
+[How to register customer in storefront using basic authentication flow](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/storefront-development/customers/register/index.html.md).
+
+The steps are:
+
+![Diagram showcasing the basic authentication flow between the frontend and the Medusa application](https://res.cloudinary.com/dza7lstvk/image/upload/v1725539370/Medusa%20Resources/basic-auth-routes_pgpjch.jpg)
+
+1. Register the user with the [Register Route](#register-route).
+2. Use the authentication token to create the user with their respective API route.
+   - For example, for customers you would use the [Create Customer API route](https://docs.medusajs.com/api/store#customers_postcustomers).
+   - For admin users, you accept an invite using the [Accept Invite API route](https://docs.medusajs.com/api/admin#invites_postinvitesaccept)
+3. Authenticate the user with the [Auth Route](#login-route).
+
+After registration, you only use the [Auth Route](#login-route) for subsequent authentication.
+
+To handle errors related to existing identities, refer to [this section](#handling-existing-identities).
+
+### 2. Third-Party Service Authenticate Flow
+
+This authentication flow authenticates the user with a third-party service, such as Google.
+
+[How to authenticate customer with a third-party provider in the storefront.](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/storefront-development/customers/third-party-login/index.html.md).
+
+It requires the following steps:
+
+![Diagram showcasing the authentication flow between the frontend, Medusa application, and third-party service](https://res.cloudinary.com/dza7lstvk/image/upload/v1725528159/Medusa%20Resources/Third_Party_Auth_tvf4ng.jpg)
+
+1. Authenticate the user with the [Auth Route](#login-route).
+2. The auth route returns a URL to authenticate with third-party service, such as login with Google. The frontend (such as a storefront), when it receives a `location` property in the response, must redirect to the returned location.
+3. Once the authentication with the third-party service finishes, it redirects back to the frontend with a `code` query parameter. So, make sure your third-party service is configured to redirect to your frontend page after successful authentication.
+4. The frontend sends a request to the [Validate Callback Route](#validate-callback-route) passing it the query parameters received from the third-party service, such as the `code` and `state` query parameters.
+5. If the callback validation is successful, the frontend receives the authentication token.
+6. Decode the received token in the frontend using tools like [react-jwt](https://www.npmjs.com/package/react-jwt).
+   - If the decoded data has an `actor_id` property, then the user is already registered. So, use this token for subsequent authenticated requests.
+   - If not, follow the rest of the steps.
+7. The frontend uses the authentication token to create the user with their respective API route.
+   - For example, for customers you would use the [Create Customer API route](https://docs.medusajs.com/api/store#customers_postcustomers).
+   - For admin users, you accept an invite using the [Accept Invite API route](https://docs.medusajs.com/api/admin#invites_postinvitesaccept)
+8. The frontend sends a request to the [Refresh Token Route](#refresh-token-route) to retrieve a new token with the user information populated.
+
+***
+
+## Register Route
+
+The Medusa application defines an API route at `/auth/{actor_type}/{provider}/register` that creates an auth identity for an actor type, such as a `customer`. It returns a JWT token that you pass to an API route that creates the user.
+
+```bash
+curl -X POST http://localhost:9000/auth/{actor_type}/{providers}/register
+-H 'Content-Type: application/json' \
+--data-raw '{
+  "email": "Whitney_Schultz@gmail.com"
+  // ...
+}'
+```
+
+This API route is useful for providers like `emailpass` that uses custom logic to authenticate a user. For authentication providers that authenticate with third-party services, such as Google, use the [Auth Route](#login-route) instead.
+
+For example, if you're registering a customer, you:
+
+1. Send a request to `/auth/customer/emailpass/register` to retrieve the registration JWT token.
+2. Send a request to the [Create Customer API route](https://docs.medusajs.com/api/store#customers_postcustomers) to create the customer, passing the [JWT token in the header](https://docs.medusajs.com/api/store#authentication).
+
+### Path Parameters
+
+Its path parameters are:
+
+- `{actor_type}`: the actor type of the user you're authenticating. For example, `customer`.
+- `{provider}`: the auth provider to handle the authentication. For example, `emailpass`.
+
+### Request Body Parameters
+
+This route accepts in the request body the data that the specified authentication provider requires to handle authentication.
+
+For example, the EmailPass provider requires an `email` and `password` fields in the request body.
+
+### Response Fields
+
+If the authentication is successful, you'll receive a `token` field in the response body object:
+
+```json
+{
+  "token": "..."
+}
+```
+
+Use that token in the header of subsequent requests to send authenticated requests.
+
+### Handling Existing Identities
+
+An auth identity with the same email may already exist in Medusa. This can happen if:
+
+- Another actor type is using that email. For example, an admin user is trying to register as a customer.
+- The same email belongs to a record of the same actor type. For example, another customer has the same email.
+
+In these scenarios, the Register Route will return an error instead of a token:
+
+```json
+{
+  "type": "unauthorized",
+  "message": "Identity with email already exists"
+}
+```
+
+To handle these scenarios, you can use the [Login Route](#login-route) to validate that the email and password match the existing identity. If so, you can allow the admin user, for example, to register as a customer.
+
+Otherwise, if the email and password don't match the existing identity, such as when the email belongs to another customer, the [Login Route](#login-route) returns an error:
+
+```json
+{
+  "type": "unauthorized",
+  "message": "Invalid email or password"
+}
+```
+
+You can show that error message to the customer.
+
+***
+
+## Login Route
+
+The Medusa application defines an API route at `/auth/{actor_type}/{provider}` that authenticates a user of an actor type. It returns a JWT token that can be passed in [the header of subsequent requests](https://docs.medusajs.com/api/store#authentication) to send authenticated requests.
+
+```bash
+curl -X POST http://localhost:9000/auth/{actor_type}/{providers}
+-H 'Content-Type: application/json' \
+--data-raw '{
+  "email": "Whitney_Schultz@gmail.com"
+  // ...
+}'
+```
+
+For example, if you're authenticating a customer, you send a request to `/auth/customer/emailpass`.
+
+### Path Parameters
+
+Its path parameters are:
+
+- `{actor_type}`: the actor type of the user you're authenticating. For example, `customer`.
+- `{provider}`: the auth provider to handle the authentication. For example, `emailpass`.
+
+### Request Body Parameters
+
+This route accepts in the request body the data that the specified authentication provider requires to handle authentication.
+
+For example, the EmailPass provider requires an `email` and `password` fields in the request body.
+
+#### Overriding Callback URL
+
+For the [GitHub](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/auth/auth-providers/github/index.html.md) and [Google](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/auth/auth-providers/google/index.html.md) providers, you can pass a `callback_url` body parameter that overrides the `callbackUrl` set in the provider's configurations.
+
+This is useful if you want to redirect the user to a different URL after authentication based on their actor type. For example, you can set different `callback_url` for admin users and customers.
+
+### Response Fields
+
+If the authentication is successful, you'll receive a `token` field in the response body object:
+
+```json
+{
+  "token": "..."
+}
+```
+
+Use that token in the header of subsequent requests to send authenticated requests.
+
+If the authentication requires more action with a third-party service, you'll receive a `location` property:
+
+```json
+{
+  "location": "https://..."
+}
+```
+
+Redirect to that URL in the frontend to continue the authentication process with the third-party service.
+
+[How to login Customers using the authentication route](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/storefront-development/customers/login/index.html.md).
+
+***
+
+## Validate Callback Route
+
+The Medusa application defines an API route at `/auth/{actor_type}/{provider}/callback` that's useful for validating the authentication callback or redirect from third-party services like Google.
+
+```bash
+curl -X POST http://localhost:9000/auth/{actor_type}/{providers}/callback?code=123&state=456
+```
+
+Refer to the [third-party authentication flow](#2-third-party-service-authenticate-flow) section to see how this route fits into the authentication flow.
+
+### Path Parameters
+
+Its path parameters are:
+
+- `{actor_type}`: the actor type of the user you're authenticating. For example, `customer`.
+- `{provider}`: the auth provider to handle the authentication. For example, `google`.
+
+### Query Parameters
+
+This route accepts all the query parameters that the third-party service sends to the frontend after the user completes the authentication process, such as the `code` and `state` query parameters.
+
+### Response Fields
+
+If the authentication is successful, you'll receive a `token` field in the response body object:
+
+```json
+{
+  "token": "..."
+}
+```
+
+In your frontend, decode the token using tools like [react-jwt](https://www.npmjs.com/package/react-jwt):
+
+- If the decoded data has an `actor_id` property, the user is already registered. So, use this token for subsequent authenticated requests.
+- If not, use the token in the header of a request that creates the user, such as the [Create Customer API route](https://docs.medusajs.com/api/store#customers_postcustomers).
+
+***
+
+## Refresh Token Route
+
+The Medusa application defines an API route at `/auth/token/refresh` that's useful after authenticating a user with a third-party service to populate the user's token with their new information.
+
+It requires the user's JWT token that they received from the authentication or callback routes.
+
+```bash
+curl -X POST http://localhost:9000/auth/token/refresh \
+-H 'Authorization: Bearer {token}'
+```
+
+### Response Fields
+
+If the token was refreshed successfully, you'll receive a `token` field in the response body object:
+
+```json
+{
+  "token": "..."
+}
+```
+
+Use that token in the header of subsequent requests to send authenticated requests.
+
+***
+
+## Reset Password Routes
+
+To reset a user's password:
+
+1. Generate a token using the [Generate Reset Password Token API route](#generate-reset-password-token-route).
+   - The API route emits the `auth.password_reset` event, passing the token in the payload.
+   - You can create a subscriber, as seen in [this guide](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/auth/reset-password/index.html.md), that listens to the event and send a notification to the user.
+2. Pass the token to the [Reset Password API route](#reset-password-route) to reset the password.
+   - The URL in the user's notification should direct them to a frontend URL, which sends a request to this route.
+
+[Storefront Development: How to Reset a Customer's Password.](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/storefront-development/customers/reset-password/index.html.md)
+
+### Generate Reset Password Token Route
+
+The Medusa application defines an API route at `/auth/{actor_type}/{auth_provider}/reset-password` that emits the `auth.password_reset` event, passing the token in the payload.
+
+```bash
+curl -X POST http://localhost:9000/auth/{actor_type}/{providers}/reset-password
+-H 'Content-Type: application/json' \
+--data-raw '{
+  "identifier": "Whitney_Schultz@gmail.com"
+}'
+```
+
+This API route is useful for providers like `emailpass` that store a user's password and use it for authentication.
+
+#### Path Parameters
+
+Its path parameters are:
+
+- `{actor_type}`: the actor type of the user you're authenticating. For example, `customer`.
+- `{provider}`: the auth provider to handle the authentication. For example, `emailpass`.
+
+#### Request Body Parameters
+
+This route accepts in the request body an object having the following property:
+
+- `identifier`: The user's identifier in the specified auth provider. For example, for the `emailpass` auth provider, you pass the user's email.
+
+#### Response Fields
+
+If the authentication is successful, the request returns a `201` response code.
+
+### Reset Password Route
+
+The Medusa application defines an API route at `/auth/{actor_type}/{auth_provider}/update` that accepts a token and, if valid, updates the user's password.
+
+```bash
+curl -X POST http://localhost:9000/auth/{actor_type}/{providers}/update
+-H 'Content-Type: application/json' \
+-H 'Authorization: Bearer {token}' \
+--data-raw '{
+  "email": "Whitney_Schultz@gmail.com",
+  "password": "supersecret"
+}'
+```
+
+This API route is useful for providers like `emailpass` that store a user's password and use it for logging them in.
+
+#### Path Parameters
+
+Its path parameters are:
+
+- `{actor_type}`: the actor type of the user you're authenticating. For example, `customer`.
+- `{provider}`: the auth provider to handle the authentication. For example, `emailpass`.
+
+#### Pass Token in Authorization Header
+
+Before [Medusa v2.6](https://github.com/medusajs/medusa/releases/tag/v2.6), you passed the token as a query parameter. Now, you must pass it in the `Authorization` header.
+
+In the request's authorization header, you must pass the token generated using the [Generate Reset Password Token route](#generate-reset-password-token-route). You pass it as a bearer token.
+
+### Request Body Parameters
+
+This route accepts in the request body an object that has the data necessary for the provider to update the user's password.
+
+For the `emailpass` provider, you must pass the following properties:
+
+- `email`: The user's email.
+- `password`: The new password.
+
+### Response Fields
+
+If the authentication is successful, the request returns an object with a `success` property set to `true`:
+
+```json
+{
+  "success": "true"
+}
+```
 
 
 # How to Create an Actor Type
@@ -22137,209 +22685,6 @@ In the workflow, you:
 You can use this workflow when deleting a manager, such as in an API route.
 
 
-# How to Handle Password Reset Token Event
-
-In this guide, you'll learn how to handle the `auth.password_reset` event, which is emitted when a request is sent to the [Generate Reset Password Token API route](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/auth/authentication-route#generate-reset-password-token-route/index.html.md).
-
-Refer to this [Medusa Admin User Guide](https://docs.medusajs.com/user-guide/reset-password/index.html.md) to learn how to reset your user admin password using the dashboard.
-
-You'll create a subscriber that listens to the event. When the event is emitted, the subscriber sends an email notification to the user.
-
-### Prerequisites
-
-- [A notification provider module, such as SendGrid](https://docs.medusajs.com/infrastructure-modules/notification/sendgrid/index.html.md)
-
-## 1. Create Subscriber
-
-The first step is to create a subscriber that listens to the `auth.password_reset` and sends the user a notification with instructions to reset their password.
-
-Create the file `src/subscribers/handle-reset.ts` with the following content:
-
-```ts title="src/subscribers/handle-reset.ts" highlights={highlights} collapsibleLines="1-6" expandMoreLabel="Show Imports"
-import {
-  SubscriberArgs,
-  type SubscriberConfig,
-} from "@medusajs/medusa"
-import { Modules } from "@medusajs/framework/utils"
-
-export default async function resetPasswordTokenHandler({
-  event: { data: {
-    entity_id: email,
-    token,
-    actor_type,
-  } },
-  container,
-}: SubscriberArgs<{ entity_id: string, token: string, actor_type: string }>) {
-  const notificationModuleService = container.resolve(
-    Modules.NOTIFICATION
-  )
-
-  const urlPrefix = actor_type === "customer" ? 
-    "https://storefront.com" : 
-    "https://admin.com/app"
-
-  await notificationModuleService.createNotifications({
-    to: email,
-    channel: "email",
-    template: "reset-password-template",
-    data: {
-      // a URL to a frontend application
-      url: `${urlPrefix}/reset-password?token=${token}&email=${email}`,
-    },
-  })
-}
-
-export const config: SubscriberConfig = {
-  event: "auth.password_reset",
-}
-```
-
-You subscribe to the `auth.password_reset` event. The event has a data payload object with the following properties:
-
-- `entity_id`: The identifier of the user. When using the `emailpass` provider, it's the user's email.
-- `token`: The token to reset the user's password.
-- `actor_type`: The user's actor type. For example, if the user is a customer, the `actor_type` is `customer`. If it's an admin user, the `actor_type` is `user`.
-
-This event's payload previously had an `actorType` field. It was renamed to `actor_type` after [Medusa v2.0.7](https://github.com/medusajs/medusa/releases/tag/v2.0.7).
-
-In the subscriber, you:
-
-- Decide the frontend URL based on whether the user is a customer or admin user by checking the value of `actor_type`.
-- Resolve the Notification Module and use its `createNotifications` method to send the notification.
-- You pass to the `createNotifications` method an object having the following properties:
-  - `to`: The identifier to send the notification to, which in this case is the email.
-  - `channel`: The channel to send the notification through, which in this case is email.
-  - `template`: The template ID in the third-party service.
-  - `data`: The data payload to pass to the template. You pass the URL to redirect the user to. You must pass the token and email in the URL so that the frontend can send them later to the Medusa application when reseting the password.
-
-***
-
-## 2. Test it Out: Generate Reset Password Token
-
-To test the subscriber out, send a request to the `/auth/{actor_type}/{auth_provider}/reset-password` API route, replacing `{actor_type}` and `{auth_provider}` with the user's actor type and provider used for authentication respectively.
-
-For example, to generate a reset password token for an admin user using the `emailpass` provider, send the following request:
-
-```bash
-curl --location 'http://localhost:9000/auth/user/emailpass/reset-password' \
---header 'Content-Type: application/json' \
---data-raw '{
-    "identifier": "admin-test@gmail.com"
-}'
-```
-
-In the request body, you must pass an `identifier` parameter. Its value is the user's identifier, which is the email in this case.
-
-If the token is generated successfully, the request returns a response with `201` status code. In the terminal, you'll find the following message indicating that the `auth.password_reset` event was emitted and your subscriber ran:
-
-```plain
-info:    Processing auth.password_reset which has 1 subscribers
-```
-
-The notification is sent to the user with the frontend URL to enter a new password.
-
-***
-
-## Next Steps: Implementing Frontend
-
-In your frontend, you must have a page that accepts `token` and `email` query parameters.
-
-The page shows the user password fields to enter their new password, then submits the new password, token, and email to the [Reset Password Route](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/auth/authentication-route#reset-password-route/index.html.md).
-
-### Examples
-
-- [Storefront Guide: Reset Customer Password](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/storefront-development/customers/reset-password/index.html.md)
-
-
-# Auth Module Options
-
-In this document, you'll learn about the options of the Auth Module.
-
-## providers
-
-The `providers` option is an array of auth module providers.
-
-When the Medusa application starts, these providers are registered and can be used to handle authentication.
-
-By default, the `emailpass` provider is registered to authenticate customers and admin users.
-
-For example:
-
-```ts title="medusa-config.ts"
-import { Modules, ContainerRegistrationKeys } from "@medusajs/framework/utils"
-
-// ...
-
-module.exports = defineConfig({
-  // ...
-  modules: [
-    {
-      resolve: "@medusajs/medusa/auth",
-      dependencies: [Modules.CACHE, ContainerRegistrationKeys.LOGGER],
-      options: {
-        providers: [
-          {
-            resolve: "@medusajs/medusa/auth-emailpass",
-            id: "emailpass",
-            options: {
-              // provider options...
-            },
-          },
-        ],
-      },
-    },
-  ],
-})
-```
-
-The `providers` option is an array of objects that accept the following properties:
-
-- `resolve`: A string indicating the package name of the module provider or the path to it relative to the `src` directory.
-- `id`: A string indicating the provider's unique name or ID.
-- `options`: An optional object of the module provider's options.
-
-***
-
-## Auth CORS
-
-The Medusa application's authentication API routes are defined under the `/auth` prefix that requires setting the `authCors` property of the `http` configuration.
-
-By default, the Medusa application you created will have an `AUTH_CORS` environment variable, which is used as the value of `authCors`.
-
-Refer to [Medusa's configuration guide](https://docs.medusajs.com/docs/learn/configurations/medusa-config#httpauthCors/index.html.md) to learn more about the `authCors` configuration.
-
-***
-
-## authMethodsPerActor Configuration
-
-The Medusa application's configuration accept an `authMethodsPerActor` configuration which restricts the allowed auth providers used with an actor type.
-
-Learn more about the `authMethodsPerActor` configuration in [this guide](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/auth/auth-providers#configure-allowed-auth-providers-of-actor-types/index.html.md).
-
-
-# Customer Accounts
-
-In this document, you’ll learn how registered and unregistered accounts are distinguished in the Medusa application.
-
-Refer to this [Medusa Admin User Guide](https://docs.medusajs.com/user-guide/customers/index.html.md) to learn how to manage customers using the dashboard.
-
-## `has_account` Property
-
-The [Customer data model](https://docs.medusajs.com/references/customer/models/Customer/index.html.md) has a `has_account` property, which is a boolean that indicates whether a customer is registered.
-
-When a guest customer places an order, a new `Customer` record is created with `has_account` set to `false`.
-
-When this or another guest customer registers an account with the same email, a new `Customer` record is created with `has_account` set to `true`.
-
-***
-
-## Email Uniqueness
-
-The above behavior means that two `Customer` records may exist with the same email. However, the main difference is the `has_account` property's value.
-
-So, there can only be one guest customer (having `has_account=false`) and one registered customer (having `has_account=true`) with the same email.
-
-
 # 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.
@@ -22542,582 +22887,184 @@ In the example above, you use the `emailpass` provider, so you have to pass an o
 If the returned `success` property is `true`, the password has reset successfully.
 
 
-# Links between Customer Module and Other Modules
+# Auth Module Options
 
-This document showcases the module links defined between the Customer Module and other Commerce Modules.
+In this document, you'll learn about the options of the Auth Module.
 
-## Summary
+## providers
 
-The Customer Module has the following links to other modules:
+The `providers` option is an array of auth module providers.
 
-Read-only links are used to query data across modules, but the relations aren't stored in a pivot table in the database.
+When the Medusa application starts, these providers are registered and can be used to handle authentication.
 
-|First Data Model|Second Data Model|Type|Description|
-|---|---|---|---|
-|| in |Stored - many-to-many||
-| in ||Read-only - has one||
-| in ||Read-only - has one||
+By default, the `emailpass` provider is registered to authenticate customers and admin users.
 
-***
+For example:
 
-## 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"
+```ts title="medusa-config.ts"
+import { Modules, ContainerRegistrationKeys } from "@medusajs/framework/utils"
 
 // ...
 
-const { data: customers } = useQueryGraphStep({
-  entity: "customer",
-  fields: [
-    "account_holder_link.account_holder.*",
+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...
+            },
+          },
+        ],
+      },
+    },
   ],
 })
-
-// customers[0].account_holder_link?.[0]?.account_holder
 ```
 
-### Manage with Link
+The `providers` option is an array of objects that accept the following properties:
 
-To manage the account holders of a customer, use [Link](https://docs.medusajs.com/docs/learn/fundamentals/module-links/link/index.html.md):
+- `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.
 
-### link.create
+***
 
-```ts
+## Auth CORS
+
+The Medusa application's authentication API routes are defined under the `/auth` prefix that requires setting the `authCors` property of the `http` configuration.
+
+By default, the Medusa application you created will have an `AUTH_CORS` environment variable, which is used as the value of `authCors`.
+
+Refer to [Medusa's configuration guide](https://docs.medusajs.com/docs/learn/configurations/medusa-config#httpauthCors/index.html.md) to learn more about the `authCors` configuration.
+
+***
+
+## authMethodsPerActor Configuration
+
+The Medusa application's configuration accept an `authMethodsPerActor` configuration which restricts the allowed auth providers used with an actor type.
+
+Learn more about the `authMethodsPerActor` configuration in [this guide](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/auth/auth-providers#configure-allowed-auth-providers-of-actor-types/index.html.md).
+
+
+# How to Handle Password Reset Token Event
+
+In this guide, you'll learn how to handle the `auth.password_reset` event, which is emitted when a request is sent to the [Generate Reset Password Token API route](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/auth/authentication-route#generate-reset-password-token-route/index.html.md).
+
+Refer to this [Medusa Admin User Guide](https://docs.medusajs.com/user-guide/reset-password/index.html.md) to learn how to reset your user admin password using the dashboard.
+
+You'll create a subscriber that listens to the event. When the event is emitted, the subscriber sends an email notification to the user.
+
+### Prerequisites
+
+- [A notification provider module, such as SendGrid](https://docs.medusajs.com/infrastructure-modules/notification/sendgrid/index.html.md)
+
+## 1. Create Subscriber
+
+The first step is to create a subscriber that listens to the `auth.password_reset` and sends the user a notification with instructions to reset their password.
+
+Create the file `src/subscribers/handle-reset.ts` with the following content:
+
+```ts title="src/subscribers/handle-reset.ts" highlights={highlights} collapsibleLines="1-6" expandMoreLabel="Show Imports"
+import {
+  SubscriberArgs,
+  type SubscriberConfig,
+} from "@medusajs/medusa"
 import { Modules } from "@medusajs/framework/utils"
 
-// ...
+export default async function resetPasswordTokenHandler({
+  event: { data: {
+    entity_id: email,
+    token,
+    actor_type,
+  } },
+  container,
+}: SubscriberArgs<{ entity_id: string, token: string, actor_type: string }>) {
+  const notificationModuleService = container.resolve(
+    Modules.NOTIFICATION
+  )
 
-await link.create({
-  [Modules.CUSTOMER]: {
-    customer_id: "cus_123",
-  },
-  [Modules.PAYMENT]: {
-    account_holder_id: "acchld_123",
-  },
-})
+  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",
+}
 ```
 
-### createRemoteLinkStep
+You subscribe to the `auth.password_reset` event. The event has a data payload object with the following properties:
 
-```ts
-import { createRemoteLinkStep } from "@medusajs/medusa/core-flows"
+- `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).
 
-createRemoteLinkStep({
-  [Modules.CUSTOMER]: {
-    customer_id: "cus_123",
-  },
-  [Modules.PAYMENT]: {
-    account_holder_id: "acchld_123",
-  },
-})
-```
+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.
 
 ***
 
-## Cart Module
+## 2. Test it Out: Generate Reset Password Token
 
-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.
+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.
 
-### 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
-```
-
-
-# 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.
+For example, to generate a reset password token for an admin user using the `emailpass` provider, send the following request:
 
 ```bash
-curl -X POST http://localhost:9000/auth/{actor_type}/{providers}/register
--H 'Content-Type: application/json' \
+curl --location 'http://localhost:9000/auth/user/emailpass/reset-password' \
+--header 'Content-Type: application/json' \
 --data-raw '{
-  "email": "Whitney_Schultz@gmail.com"
-  // ...
+    "identifier": "admin-test@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.
+In the request body, you must pass an `identifier` parameter. Its value is the user's identifier, which is the email in this case.
 
-For example, if you're registering a customer, you:
+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:
 
-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": "..."
-}
+```plain
+info:    Processing auth.password_reset which has 1 subscribers
 ```
 
-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.
+The notification is sent to the user with the frontend URL to enter a new password.
 
 ***
 
-## Login Route
+## Next Steps: Implementing Frontend
 
-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.
+In your frontend, you must have a page that accepts `token` and `email` query parameters.
 
-```bash
-curl -X POST http://localhost:9000/auth/{actor_type}/{providers}
--H 'Content-Type: application/json' \
---data-raw '{
-  "email": "Whitney_Schultz@gmail.com"
-  // ...
-}'
-```
+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, if you're authenticating a customer, you send a request to `/auth/customer/emailpass`.
+### Examples
 
-### 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"
-}
-```
-
-
-# Links between Currency Module and Other Modules
-
-This document showcases the module links defined between the Currency Module and other Commerce Modules.
-
-## Summary
-
-The Currency Module has the following links to other modules:
-
-Read-only links are used to query data across modules, but the relations aren't stored in a pivot table in the database.
-
-|First Data Model|Second Data Model|Type|Description|
-|---|---|---|---|
-| in ||Read-only - has one||
-
-***
-
-## Store Module
-
-The Store Module has a `Currency` data model that stores the supported currencies of a store. However, these currencies don't hold all the details of a currency, such as its name or symbol.
-
-Instead, Medusa defines a read-only link between the [Store Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/store/index.html.md)'s `StoreCurrency` data model and the Currency Module's `Currency` data model. Because the link is read-only from the `Store`'s side, you can only retrieve the details of a store's supported currencies, and not the other way around.
-
-### Retrieve with Query
-
-To retrieve the details of a store's currencies with [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), pass `supported_currencies.currency.*` in `fields`:
-
-### query.graph
-
-```ts
-const { data: stores } = await query.graph({
-  entity: "store",
-  fields: [
-    "supported_currencies.currency.*",
-  ],
-})
-
-// stores[0].supported_currencies[0].currency
-```
-
-### useQueryGraphStep
-
-```ts
-import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
-
-// ...
-
-const { data: stores } = useQueryGraphStep({
-  entity: "store",
-  fields: [
-    "supported_currencies.currency.*",
-  ],
-})
-
-// stores[0].supported_currencies[0].currency
-```
+- [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
@@ -23651,72 +23598,6 @@ The `providers` option is an array of objects that accept the following properti
 - `options`: An optional object of the module provider's options.
 
 
-# Shipping Option
-
-In this document, you’ll learn about shipping options and their rules.
-
-## What’s a Shipping Option?
-
-A shipping option is a way of shipping an item. Each fulfillment provider provides a set of shipping options. For example, a provider may provide a shipping option for express shipping and another for standard shipping.
-
-When the customer places their order, they choose a shipping option to be used to fulfill their items.
-
-A shipping option is represented by the [ShippingOption data model](https://docs.medusajs.com/references/fulfillment/models/ShippingOption/index.html.md).
-
-***
-
-## Service Zone Restrictions
-
-A shipping option is restricted by a service zone, limiting the locations a shipping option be used in.
-
-For example, a fulfillment provider may have a shipping option that can be used in the United States, and another in Canada.
-
-![A diagram showcasing the relation between shipping options and service zones.](https://res.cloudinary.com/dza7lstvk/image/upload/v1712330831/Medusa%20Resources/shipping-option-service-zone_pobh6k.jpg)
-
-Service zones can be more restrictive, such as restricting to certain cities or province codes.
-
-![A diagram showcasing the relation between shipping options, service zones, and geo zones](https://res.cloudinary.com/dza7lstvk/image/upload/v1712331186/Medusa%20Resources/shipping-option-service-zone-city_m5sxod.jpg)
-
-***
-
-## Shipping Option Rules
-
-You can restrict shipping options by custom rules, such as the item’s weight or the customer’s group.
-
-You can also restrict a shipping option's price based on specific conditions. For example, you can make a shipping option's price free based on the cart's total. Learn more in the Pricing Module's [Price Rules](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/pricing/price-rules#how-to-set-rules-on-a-price/index.html.md) guide.
-
-These rules are represented by the [ShippingOptionRule data model](https://docs.medusajs.com/references/fulfillment/models/ShippingOptionRule/index.html.md). Its properties define the custom rule:
-
-- `attribute`: The name of a property or table that the rule applies to. For example, `customer_group`.
-- `operator`: The operator used in the condition. For example:
-  - To allow multiple values, use the operator `in`, which validates that the provided values are in the rule’s values.
-  - To create a negation condition that considers `value` against the rule, use `nin`, which validates that the provided values aren’t in the rule’s values.
-  - Check out more operators in [this reference](https://docs.medusajs.com/references/fulfillment/types/fulfillment.RuleOperatorType/index.html.md).
-- `value`: One or more values.
-
-![A diagram showcasing the relation between shipping option and shipping option rules.](https://res.cloudinary.com/dza7lstvk/image/upload/v1712331340/Medusa%20Resources/shipping-option-rule_oosopf.jpg)
-
-A shipping option can have multiple rules. For example, you can add rules to a shipping option so that it's available if the customer belongs to the VIP group and the total weight is less than 2000g.
-
-![A diagram showcasing how a shipping option can have multiple rules.](https://res.cloudinary.com/dza7lstvk/image/upload/v1712331462/Medusa%20Resources/shipping-option-rule-2_ylaqdb.jpg)
-
-***
-
-## Shipping Profile and Types
-
-A shipping option belongs to a type. For example, a shipping option’s type may be `express`, while another `standard`. The type is represented by the [ShippingOptionType data model](https://docs.medusajs.com/references/fulfillment/models/ShippingOptionType/index.html.md).
-
-A shipping option also belongs to a shipping profile, as each shipping profile defines the type of items to be shipped in a similar manner.
-
-***
-
-## data Property
-
-When fulfilling an item, you might use a third-party fulfillment provider that requires additional custom data to be passed along from the checkout or order-creation process.
-
-The `ShippingOption` data model has a `data` property. It's an object that stores custom data relevant later when creating and processing a fulfillment.
-
-
 # Inventory Concepts
 
 In this document, you’ll learn about the main concepts in the Inventory Module, and how data is stored and related.
@@ -24350,6 +24231,126 @@ const { data: inventoryLevels } = useQueryGraphStep({
 ```
 
 
+# Shipping Option
+
+In this document, you’ll learn about shipping options and their rules.
+
+## What’s a Shipping Option?
+
+A shipping option is a way of shipping an item. Each fulfillment provider provides a set of shipping options. For example, a provider may provide a shipping option for express shipping and another for standard shipping.
+
+When the customer places their order, they choose a shipping option to be used to fulfill their items.
+
+A shipping option is represented by the [ShippingOption data model](https://docs.medusajs.com/references/fulfillment/models/ShippingOption/index.html.md).
+
+***
+
+## Service Zone Restrictions
+
+A shipping option is restricted by a service zone, limiting the locations a shipping option be used in.
+
+For example, a fulfillment provider may have a shipping option that can be used in the United States, and another in Canada.
+
+![A diagram showcasing the relation between shipping options and service zones.](https://res.cloudinary.com/dza7lstvk/image/upload/v1712330831/Medusa%20Resources/shipping-option-service-zone_pobh6k.jpg)
+
+Service zones can be more restrictive, such as restricting to certain cities or province codes.
+
+![A diagram showcasing the relation between shipping options, service zones, and geo zones](https://res.cloudinary.com/dza7lstvk/image/upload/v1712331186/Medusa%20Resources/shipping-option-service-zone-city_m5sxod.jpg)
+
+***
+
+## Shipping Option Rules
+
+You can restrict shipping options by custom rules, such as the item’s weight or the customer’s group.
+
+You can also restrict a shipping option's price based on specific conditions. For example, you can make a shipping option's price free based on the cart's total. Learn more in the Pricing Module's [Price Rules](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/pricing/price-rules#how-to-set-rules-on-a-price/index.html.md) guide.
+
+These rules are represented by the [ShippingOptionRule data model](https://docs.medusajs.com/references/fulfillment/models/ShippingOptionRule/index.html.md). Its properties define the custom rule:
+
+- `attribute`: The name of a property or table that the rule applies to. For example, `customer_group`.
+- `operator`: The operator used in the condition. For example:
+  - To allow multiple values, use the operator `in`, which validates that the provided values are in the rule’s values.
+  - To create a negation condition that considers `value` against the rule, use `nin`, which validates that the provided values aren’t in the rule’s values.
+  - Check out more operators in [this reference](https://docs.medusajs.com/references/fulfillment/types/fulfillment.RuleOperatorType/index.html.md).
+- `value`: One or more values.
+
+![A diagram showcasing the relation between shipping option and shipping option rules.](https://res.cloudinary.com/dza7lstvk/image/upload/v1712331340/Medusa%20Resources/shipping-option-rule_oosopf.jpg)
+
+A shipping option can have multiple rules. For example, you can add rules to a shipping option so that it's available if the customer belongs to the VIP group and the total weight is less than 2000g.
+
+![A diagram showcasing how a shipping option can have multiple rules.](https://res.cloudinary.com/dza7lstvk/image/upload/v1712331462/Medusa%20Resources/shipping-option-rule-2_ylaqdb.jpg)
+
+***
+
+## Shipping Profile and Types
+
+A shipping option belongs to a type. For example, a shipping option’s type may be `express`, while another `standard`. The type is represented by the [ShippingOptionType data model](https://docs.medusajs.com/references/fulfillment/models/ShippingOptionType/index.html.md).
+
+A shipping option also belongs to a shipping profile, as each shipping profile defines the type of items to be shipped in a similar manner.
+
+***
+
+## data Property
+
+When fulfilling an item, you might use a third-party fulfillment provider that requires additional custom data to be passed along from the checkout or order-creation process.
+
+The `ShippingOption` data model has a `data` property. It's an object that stores custom data relevant later when creating and processing a fulfillment.
+
+
+# Order Claim
+
+In this document, you’ll learn about order claims.
+
+Refer to this [Medusa Admin User Guide](https://docs.medusajs.com/user-guide/orders/claims/index.html.md) to learn how to manage an order's claims using the dashboard.
+
+## What is a Claim?
+
+When a customer receives a defective or incorrect item, the merchant can create a claim to refund or replace the item.
+
+The [OrderClaim data model](https://docs.medusajs.com/references/order/models/OrderClaim/index.html.md) represents a claim.
+
+***
+
+## Claim Type
+
+The `Claim` data model has a `type` property whose value indicates the type of the claim:
+
+- `refund`: the items are returned, and the customer is refunded.
+- `replace`: the items are returned, and the customer receives new items.
+
+***
+
+## Old and Replacement Items
+
+When the claim is created, a return, represented by the [Return data model](https://docs.medusajs.com/references/order/models/Return/index.html.md), is also created to handle receiving the old items from the customer.
+
+Learn more about returns in [this guide](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/order/return/index.html.md).
+
+If the claim’s type is `replace`, replacement items are represented by the [ClaimItem data model](https://docs.medusajs.com/references/order/models/OrderClaimItem/index.html.md).
+
+***
+
+## Claim Shipping Methods
+
+A claim uses shipping methods to send the replacement items to the customer. These methods are represented by the [OrderShippingMethod data model](https://docs.medusajs.com/references/order/models/OrderShippingMethod/index.html.md).
+
+The shipping methods for the returned items are associated with the claim's return, as explained in [this guide](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/order/return#return-shipping-methods/index.html.md).
+
+***
+
+## Claim Refund
+
+If the claim’s type is `refund`, the amount to be refunded is stored in the `refund_amount` property.
+
+The [Transaction data model](https://docs.medusajs.com/references/order/models/OrderTransaction/index.html.md) represents the refunds made for the claim.
+
+***
+
+## How Claims Impact an Order’s Version
+
+When a claim is confirmed, the order’s version is incremented.
+
+
 # Order Concepts
 
 In this document, you’ll learn about orders and related concepts
@@ -24399,6 +24400,59 @@ An order can have multiple transactions. The sum of these transactions must be e
 Learn more about transactions in [this guide](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/order/transactions/index.html.md).
 
 
+# Order 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 Edit
 
 In this document, you'll learn about order edits.
@@ -25171,6 +25225,67 @@ await orderModuleService.setOrderShippingMethodAdjustments(
 ```
 
 
+# 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.
+
+
 # Tax Lines in Order Module
 
 In this document, you’ll learn about tax lines in an order.
@@ -25248,6 +25363,206 @@ 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`.
 
 
+# Customer Accounts
+
+In this document, you’ll learn how registered and unregistered accounts are distinguished in the Medusa application.
+
+Refer to this [Medusa Admin User Guide](https://docs.medusajs.com/user-guide/customers/index.html.md) to learn how to manage customers using the dashboard.
+
+## `has_account` Property
+
+The [Customer data model](https://docs.medusajs.com/references/customer/models/Customer/index.html.md) has a `has_account` property, which is a boolean that indicates whether a customer is registered.
+
+When a guest customer places an order, a new `Customer` record is created with `has_account` set to `false`.
+
+When this or another guest customer registers an account with the same email, a new `Customer` record is created with `has_account` set to `true`.
+
+***
+
+## Email Uniqueness
+
+The above behavior means that two `Customer` records may exist with the same email. However, the main difference is the `has_account` property's value.
+
+So, there can only be one guest customer (having `has_account=false`) and one registered customer (having `has_account=true`) with the same email.
+
+
+# Links between Customer Module and Other Modules
+
+This document showcases the module links defined between the Customer Module and other Commerce Modules.
+
+## 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|
+|---|---|---|---|
+|| in |Stored - many-to-many||
+| in ||Read-only - has one||
+| in ||Read-only - has one||
+
+***
+
+## 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
+```
+
+
 # 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.
@@ -25698,41 +26013,6 @@ The `providers` option is an array of objects that accept the following properti
 - `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.
@@ -26021,6 +26301,41 @@ The `status` property of a payment session indicates its current status. Its val
 - `canceled`: The authorization of the payment session has been canceled.
 
 
+# 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)
+
+
 # Webhook Events
 
 In this document, you’ll learn how the Payment Module supports listening to webhook events.
@@ -26057,195 +26372,188 @@ If the event's details indicate that the payment should be captured, then the [c
 After the payment webhook actions are processed and the payment is authorized or captured, the Medusa application completes the cart associated with the payment's collection if it's not completed yet.
 
 
-# Order Claim
+# Links between Pricing Module and Other Modules
 
-In this document, you’ll learn about order claims.
+This document showcases the module links defined between the Pricing 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 Pricing 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|
+|---|---|---|---|
+| in ||Stored - one-to-one||
+| in ||Stored - one-to-one||
 
 ***
 
-## Claim Type
+## Fulfillment Module
 
-The `Claim` data model has a `type` property whose value indicates the type of the claim:
+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.
 
-- `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 `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",
+  },
+})
+```
 
 ***
 
-## Old and Replacement Items
+## Product 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.
+The Product Module doesn't store or manage the prices of product variants.
 
-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).
+Medusa defines a link between the `ProductVariant` and the `PriceSet`. A product variant’s prices are stored as prices belonging to a price set.
 
-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).
+![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.
 
-## Claim Shipping Methods
+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.
 
-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).
+### Retrieve with Query
 
-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).
+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
 
-## Claim Refund
+```ts
+const { data: priceSets } = await query.graph({
+  entity: "price_set",
+  fields: [
+    "variant.*",
+  ],
+})
 
-If the claim’s type is `refund`, the amount to be refunded is stored in the `refund_amount` property.
+// priceSets[0].variant
+```
 
-The [Transaction data model](https://docs.medusajs.com/references/order/models/OrderTransaction/index.html.md) represents the refunds made for the claim.
+### useQueryGraphStep
 
-***
+```ts
+import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
 
-## How Claims Impact an Order’s Version
+// ...
 
-When a claim is confirmed, the order’s version is incremented.
+const { data: priceSets } = useQueryGraphStep({
+  entity: "price_set",
+  fields: [
+    "variant.*",
+  ],
+})
 
+// priceSets[0].variant
+```
 
-# Order Exchange
+### Manage with Link
 
-In this document, you’ll learn about order exchanges.
+To manage the price set of a variant, use [Link](https://docs.medusajs.com/docs/learn/fundamentals/module-links/link/index.html.md):
 
-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.
+### link.create
 
-## What is an Exchange?
+```ts
+import { Modules } from "@medusajs/framework/utils"
 
-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.
+await link.create({
+  [Modules.PRODUCT]: {
+    variant_id: "variant_123",
+  },
+  [Modules.PRICING]: {
+    price_set_id: "pset_123",
+  },
+})
+```
 
-The [OrderExchange data model](https://docs.medusajs.com/references/order/models/OrderExchange/index.html.md) represents an exchange.
+### createRemoteLinkStep
 
-***
+```ts
+import { Modules } from "@medusajs/framework/utils"
+import { createRemoteLinkStep } from "@medusajs/medusa/core-flows"
 
-## 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 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.
-
-
-# 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.
+createRemoteLinkStep({
+  [Modules.PRODUCT]: {
+    variant_id: "variant_123",
+  },
+  [Modules.PRICING]: {
+    price_set_id: "pset_123",
+  },
+})
+```
 
 
 # Prices Calculation
@@ -26441,6 +26749,74 @@ const price = await pricingModuleService.calculatePrices(
 ### Result
 
 
+# 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
+
+
 # Price Rules
 
 In this Pricing Module guide, you'll learn about price rules for price sets and price lists, and how to add rules to a price.
@@ -26598,256 +26974,27 @@ In this example, the price is only applied if a cart's customer belongs to the c
 These same rules apply to product variant prices as well, or any other resource that has a price.
 
 
-# Links between Pricing Module and Other Modules
+# Pricing Concepts
 
-This document showcases the module links defined between the Pricing Module and other Commerce Modules.
+In this document, you’ll learn about the main concepts in the Pricing Module.
 
-## Summary
+## Price Set
 
-The Pricing Module has the following links to other modules:
+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).
 
-|First Data Model|Second Data Model|Type|Description|
-|---|---|---|---|
-| in ||Stored - one-to-one||
-| in ||Stored - one-to-one||
+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)
 
 ***
 
-## Fulfillment Module
+## Price List
 
-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 [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.
 
-Medusa defines a link between the `PriceSet` and `ShippingOption` data models. A shipping option's price is stored as a price set.
+A price list has optional `start_date` and `end_date` properties that indicate the date range in which a price list can be applied.
 
-![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",
-  },
-})
-```
-
-
-# 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
+Its associated prices are represented by the `Price` data model.
 
 
 # Links between Product Module and Other Modules
@@ -27347,6 +27494,72 @@ By combining configurations of shipment requirements and inventory management, y
 |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.
+- [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).
@@ -27458,72 +27671,6 @@ export interface CampaignBudgetExceededAction {
 Refer to [this reference](https://docs.medusajs.com/references/promotion/interfaces/promotion.CampaignBudgetExceededAction/index.html.md) for details on the object’s properties.
 
 
-# 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.
-- [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).
-
-
 # Application Method
 
 In this document, you'll learn what an application method is.
@@ -28112,6 +28259,253 @@ createRemoteLinkStep({
 ```
 
 
+# Stock Location Concepts
+
+In this document, you’ll learn about the main concepts in the Stock Location Module.
+
+## Stock Location
+
+A stock location, represented by the `StockLocation` data model, represents a location where stock items are kept. For example, a warehouse.
+
+Medusa uses stock locations to provide inventory details, from the Inventory Module, per location.
+
+***
+
+## StockLocationAddress
+
+The `StockLocationAddress` data model belongs to the `StockLocation` data model. It provides more detailed information of the location, such as country code or street address.
+
+
+# Links between Stock Location Module and Other Modules
+
+This document showcases the module links defined between the Stock Location Module and other Commerce Modules.
+
+## Summary
+
+The Stock Location Module has the following links to other modules:
+
+Read-only links are used to query data across modules, but the relations aren't stored in a pivot table in the database.
+
+|First Data Model|Second Data Model|Type|Description|
+|---|---|---|---|
+| in ||Stored - many-to-one||
+| in ||Stored - many-to-many||
+| in ||Read-only - has many||
+| in ||Stored - many-to-many||
+
+***
+
+## 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
 
 In this document, you’ll learn what publishable API keys are and how to use them with sales channels.
@@ -28136,23 +28530,6 @@ The Medusa application infers the associated sales channels and ensures that onl
 To create a publishable API key, either use the [Medusa Admin](https://docs.medusajs.com/user-guide/settings/developer/publishable-api-keys/index.html.md) or the [Admin API Routes](https://docs.medusajs.com/api/admin#publishable-api-keys).
 
 
-# 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 Sales Channel Module and Other Modules
 
 This document showcases the module links defined between the Sales Channel Module and other Commerce Modules.
@@ -28501,233 +28878,120 @@ createRemoteLinkStep({
 ```
 
 
-# Links between Stock Location Module and Other Modules
+# User Module Options
 
-This document showcases the module links defined between the Stock Location Module and other Commerce Modules.
+In this document, you'll learn about the options of the User Module.
 
-## Summary
+## Module Options
 
-The Stock Location Module has the following links to other modules:
+```ts title="medusa-config.ts"
+import { Modules } from "@medusajs/framework/utils"
 
-Read-only links are used to query data across modules, but the relations aren't stored in a pivot table in the database.
+// ...
 
-|First Data Model|Second Data Model|Type|Description|
-|---|---|---|---|
-| in ||Stored - many-to-one||
-| in ||Stored - many-to-many||
-| in ||Read-only - has many||
-| in ||Stored - many-to-many||
+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).
 
 ***
 
-## Fulfillment Module
+## Invite Users
 
-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
+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 { 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",
-  },
+const invite = await userModuleService.createInvites({
+  email: "user@example.com",
 })
 ```
 
-### createRemoteLinkStep
+Later, you can accept the invite and create a new user for them:
 
 ```ts
-import { Modules } from "@medusajs/framework/utils"
-import { createRemoteLinkStep } from "@medusajs/medusa/core-flows"
+const invite =
+  await userModuleService.validateInviteToken("secret_123")
 
-// ...
-
-createRemoteLinkStep({
-  [Modules.STOCK_LOCATION]: {
-    stock_location_id: "sloc_123",
-  },
-  [Modules.FULFILLMENT]: {
-    fulfillment_set_id: "fset_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"])
 ```
 
 ***
 
-## Inventory Module
+## Create Identity with the Auth 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.
+By combining the User and Auth Modules, you can use the Auth Module for authenticating users, and the User Module to manage those users.
 
-### 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
+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 { data: inventoryLevels } = await query.graph({
-  entity: "inventory_level",
-  fields: [
-    "stock_locations.*",
-  ],
+const { success, authIdentity } =
+  await authModuleService.authenticate("emailpass", {
+    // ...
+  })
+
+const [, count] = await userModuleService.listAndCountUsers({
+  email: authIdentity.entity_id,
 })
 
-// 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",
-  },
-})
+if (!count) {
+  const user = await userModuleService.createUsers({
+    email: authIdentity.entity_id,
+  })
+}
 ```
 
 
@@ -28851,6 +29115,21 @@ TODO add once tax provider guide is updated + add module providers match other m
 Refer to [this guide](/modules/tax/provider) to learn more about creating a tax provider. */}
 
 
+# Tax Region
+
+In this document, you’ll learn about tax regions and how to use them with the Region Module.
+
+Refer to this [Medusa Admin User Guide](https://docs.medusajs.com/user-guide/settings/tax-regions/index.html.md) to learn how to manage tax regions using the dashboard.
+
+## What is a Tax Region?
+
+A tax region, represented by the [TaxRegion data model](https://docs.medusajs.com/references/tax/models/TaxRegion/index.html.md), stores tax settings related to a region that your store serves.
+
+Tax regions can inherit settings and rules from a parent tax region.
+
+Each tax region has tax rules and a tax provider.
+
+
 # Tax Rates and Rules
 
 In this document, you’ll learn about tax rates and rules.
@@ -28889,21 +29168,6 @@ These two properties of the data model identify the rule’s target:
 So, to override the default tax rate for product types “Shirt”, you create a tax rate and associate with it a tax rule whose `reference` is `product_type` and `reference_id` the ID of the “Shirt” product type.
 
 
-# Tax Region
-
-In this document, you’ll learn about tax regions and how to use them with the Region Module.
-
-Refer to this [Medusa Admin User Guide](https://docs.medusajs.com/user-guide/settings/tax-regions/index.html.md) to learn how to manage tax regions using the dashboard.
-
-## What is a Tax Region?
-
-A tax region, represented by the [TaxRegion data model](https://docs.medusajs.com/references/tax/models/TaxRegion/index.html.md), stores tax settings related to a region that your store serves.
-
-Tax regions can inherit settings and rules from a parent tax region.
-
-Each tax region has tax rules and a tax provider.
-
-
 # Links between Store Module and Other Modules
 
 This document showcases the module links defined between the Store Module and other Commerce Modules.
@@ -28961,123 +29225,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.
@@ -29140,6 +29287,175 @@ 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.
@@ -29330,175 +29646,6 @@ For the context of the product variant's calculated price, you pass an object to
 Each variant in the retrieved products has a `calculated_price` object. Learn more about its properties in [this Pricing Module guide](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/pricing/price-calculation#returned-price-object/index.html.md).
 
 
-# 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).
-
-
 # Calculate Product Variant Price with Taxes
 
 In this document, you'll learn how to calculate a product variant's price with taxes.
@@ -29686,312 +29833,312 @@ For each product variant, you:
 
 ## Workflows
 
-- [generateResetPasswordTokenWorkflow](https://docs.medusajs.com/references/medusa-workflows/generateResetPasswordTokenWorkflow/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)
-- [updateApiKeysWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateApiKeysWorkflow/index.html.md)
-- [addShippingMethodToCartWorkflow](https://docs.medusajs.com/references/medusa-workflows/addShippingMethodToCartWorkflow/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)
-- [addToCartWorkflow](https://docs.medusajs.com/references/medusa-workflows/addToCartWorkflow/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)
-- [deleteCartCreditLinesWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteCartCreditLinesWorkflow/index.html.md)
-- [createPaymentCollectionForCartWorkflow](https://docs.medusajs.com/references/medusa-workflows/createPaymentCollectionForCartWorkflow/index.html.md)
-- [listShippingOptionsForCartWithPricingWorkflow](https://docs.medusajs.com/references/medusa-workflows/listShippingOptionsForCartWithPricingWorkflow/index.html.md)
-- [listShippingOptionsForCartWorkflow](https://docs.medusajs.com/references/medusa-workflows/listShippingOptionsForCartWorkflow/index.html.md)
-- [refreshCartShippingMethodsWorkflow](https://docs.medusajs.com/references/medusa-workflows/refreshCartShippingMethodsWorkflow/index.html.md)
-- [refreshCartItemsWorkflow](https://docs.medusajs.com/references/medusa-workflows/refreshCartItemsWorkflow/index.html.md)
-- [refreshPaymentCollectionForCartWorkflow](https://docs.medusajs.com/references/medusa-workflows/refreshPaymentCollectionForCartWorkflow/index.html.md)
-- [updateCartPromotionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateCartPromotionsWorkflow/index.html.md)
-- [updateCartWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateCartWorkflow/index.html.md)
-- [transferCartCustomerWorkflow](https://docs.medusajs.com/references/medusa-workflows/transferCartCustomerWorkflow/index.html.md)
-- [updateLineItemInCartWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateLineItemInCartWorkflow/index.html.md)
-- [validateExistingPaymentCollectionStep](https://docs.medusajs.com/references/medusa-workflows/validateExistingPaymentCollectionStep/index.html.md)
-- [updateTaxLinesWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateTaxLinesWorkflow/index.html.md)
-- [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)
-- [createCustomerAccountWorkflow](https://docs.medusajs.com/references/medusa-workflows/createCustomerAccountWorkflow/index.html.md)
-- [removeCustomerAccountWorkflow](https://docs.medusajs.com/references/medusa-workflows/removeCustomerAccountWorkflow/index.html.md)
-- [updateCustomersWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateCustomersWorkflow/index.html.md)
-- [updateCustomerAddressesWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateCustomerAddressesWorkflow/index.html.md)
-- [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)
-- [updateCustomerGroupsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateCustomerGroupsWorkflow/index.html.md)
-- [linkCustomersToCustomerGroupWorkflow](https://docs.medusajs.com/references/medusa-workflows/linkCustomersToCustomerGroupWorkflow/index.html.md)
-- [createDefaultsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createDefaultsWorkflow/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)
 - [batchLinksWorkflow](https://docs.medusajs.com/references/medusa-workflows/batchLinksWorkflow/index.html.md)
 - [createLinksWorkflow](https://docs.medusajs.com/references/medusa-workflows/createLinksWorkflow/index.html.md)
 - [dismissLinksWorkflow](https://docs.medusajs.com/references/medusa-workflows/dismissLinksWorkflow/index.html.md)
 - [updateLinksWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateLinksWorkflow/index.html.md)
-- [batchInventoryItemLevelsWorkflow](https://docs.medusajs.com/references/medusa-workflows/batchInventoryItemLevelsWorkflow/index.html.md)
-- [createInventoryLevelsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createInventoryLevelsWorkflow/index.html.md)
-- [deleteInventoryItemWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteInventoryItemWorkflow/index.html.md)
-- [createInventoryItemsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createInventoryItemsWorkflow/index.html.md)
-- [bulkCreateDeleteLevelsWorkflow](https://docs.medusajs.com/references/medusa-workflows/bulkCreateDeleteLevelsWorkflow/index.html.md)
-- [updateInventoryItemsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateInventoryItemsWorkflow/index.html.md)
-- [updateInventoryLevelsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateInventoryLevelsWorkflow/index.html.md)
-- [deleteInventoryLevelsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteInventoryLevelsWorkflow/index.html.md)
-- [validateInventoryLevelsDelete](https://docs.medusajs.com/references/medusa-workflows/validateInventoryLevelsDelete/index.html.md)
-- [calculateShippingOptionsPricesWorkflow](https://docs.medusajs.com/references/medusa-workflows/calculateShippingOptionsPricesWorkflow/index.html.md)
+- [generateResetPasswordTokenWorkflow](https://docs.medusajs.com/references/medusa-workflows/generateResetPasswordTokenWorkflow/index.html.md)
+- [createApiKeysWorkflow](https://docs.medusajs.com/references/medusa-workflows/createApiKeysWorkflow/index.html.md)
+- [revokeApiKeysWorkflow](https://docs.medusajs.com/references/medusa-workflows/revokeApiKeysWorkflow/index.html.md)
+- [updateApiKeysWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateApiKeysWorkflow/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)
+- [createDefaultsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createDefaultsWorkflow/index.html.md)
+- [addToCartWorkflow](https://docs.medusajs.com/references/medusa-workflows/addToCartWorkflow/index.html.md)
+- [addShippingMethodToCartWorkflow](https://docs.medusajs.com/references/medusa-workflows/addShippingMethodToCartWorkflow/index.html.md)
+- [completeCartWorkflow](https://docs.medusajs.com/references/medusa-workflows/completeCartWorkflow/index.html.md)
+- [confirmVariantInventoryWorkflow](https://docs.medusajs.com/references/medusa-workflows/confirmVariantInventoryWorkflow/index.html.md)
+- [createCartCreditLinesWorkflow](https://docs.medusajs.com/references/medusa-workflows/createCartCreditLinesWorkflow/index.html.md)
+- [createPaymentCollectionForCartWorkflow](https://docs.medusajs.com/references/medusa-workflows/createPaymentCollectionForCartWorkflow/index.html.md)
+- [createCartWorkflow](https://docs.medusajs.com/references/medusa-workflows/createCartWorkflow/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)
+- [listShippingOptionsForCartWorkflow](https://docs.medusajs.com/references/medusa-workflows/listShippingOptionsForCartWorkflow/index.html.md)
+- [listShippingOptionsForCartWithPricingWorkflow](https://docs.medusajs.com/references/medusa-workflows/listShippingOptionsForCartWithPricingWorkflow/index.html.md)
+- [refreshCartShippingMethodsWorkflow](https://docs.medusajs.com/references/medusa-workflows/refreshCartShippingMethodsWorkflow/index.html.md)
+- [refreshPaymentCollectionForCartWorkflow](https://docs.medusajs.com/references/medusa-workflows/refreshPaymentCollectionForCartWorkflow/index.html.md)
+- [transferCartCustomerWorkflow](https://docs.medusajs.com/references/medusa-workflows/transferCartCustomerWorkflow/index.html.md)
+- [updateTaxLinesWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateTaxLinesWorkflow/index.html.md)
+- [updateCartWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateCartWorkflow/index.html.md)
+- [updateCartPromotionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateCartPromotionsWorkflow/index.html.md)
+- [updateLineItemInCartWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateLineItemInCartWorkflow/index.html.md)
+- [validateExistingPaymentCollectionStep](https://docs.medusajs.com/references/medusa-workflows/validateExistingPaymentCollectionStep/index.html.md)
+- [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)
 - [batchShippingOptionRulesWorkflow](https://docs.medusajs.com/references/medusa-workflows/batchShippingOptionRulesWorkflow/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)
-- [createServiceZonesWorkflow](https://docs.medusajs.com/references/medusa-workflows/createServiceZonesWorkflow/index.html.md)
+- [createFulfillmentWorkflow](https://docs.medusajs.com/references/medusa-workflows/createFulfillmentWorkflow/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)
+- [calculateShippingOptionsPricesWorkflow](https://docs.medusajs.com/references/medusa-workflows/calculateShippingOptionsPricesWorkflow/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)
-- [markFulfillmentAsDeliveredWorkflow](https://docs.medusajs.com/references/medusa-workflows/markFulfillmentAsDeliveredWorkflow/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)
+- [deleteServiceZonesWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteServiceZonesWorkflow/index.html.md)
 - [updateShippingOptionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateShippingOptionsWorkflow/index.html.md)
-- [updateServiceZonesWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateServiceZonesWorkflow/index.html.md)
 - [updateShippingProfilesWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateShippingProfilesWorkflow/index.html.md)
 - [validateFulfillmentDeliverabilityStep](https://docs.medusajs.com/references/medusa-workflows/validateFulfillmentDeliverabilityStep/index.html.md)
+- [updateServiceZonesWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateServiceZonesWorkflow/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)
+- [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)
+- [createInventoryLevelsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createInventoryLevelsWorkflow/index.html.md)
+- [deleteInventoryItemWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteInventoryItemWorkflow/index.html.md)
+- [updateInventoryItemsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateInventoryItemsWorkflow/index.html.md)
+- [deleteInventoryLevelsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteInventoryLevelsWorkflow/index.html.md)
+- [validateInventoryLevelsDelete](https://docs.medusajs.com/references/medusa-workflows/validateInventoryLevelsDelete/index.html.md)
+- [updateInventoryLevelsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateInventoryLevelsWorkflow/index.html.md)
 - [acceptInviteWorkflow](https://docs.medusajs.com/references/medusa-workflows/acceptInviteWorkflow/index.html.md)
 - [createInvitesWorkflow](https://docs.medusajs.com/references/medusa-workflows/createInvitesWorkflow/index.html.md)
 - [refreshInviteTokensWorkflow](https://docs.medusajs.com/references/medusa-workflows/refreshInviteTokensWorkflow/index.html.md)
 - [deleteInvitesWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteInvitesWorkflow/index.html.md)
 - [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)
-- [validatePaymentsRefundStep](https://docs.medusajs.com/references/medusa-workflows/validatePaymentsRefundStep/index.html.md)
-- [validateRefundStep](https://docs.medusajs.com/references/medusa-workflows/validateRefundStep/index.html.md)
-- [createPricePreferencesWorkflow](https://docs.medusajs.com/references/medusa-workflows/createPricePreferencesWorkflow/index.html.md)
-- [deletePricePreferencesWorkflow](https://docs.medusajs.com/references/medusa-workflows/deletePricePreferencesWorkflow/index.html.md)
-- [updatePricePreferencesWorkflow](https://docs.medusajs.com/references/medusa-workflows/updatePricePreferencesWorkflow/index.html.md)
-- [createRefundReasonsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createRefundReasonsWorkflow/index.html.md)
+- [batchPriceListPricesWorkflow](https://docs.medusajs.com/references/medusa-workflows/batchPriceListPricesWorkflow/index.html.md)
+- [deletePriceListsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deletePriceListsWorkflow/index.html.md)
+- [createPriceListsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createPriceListsWorkflow/index.html.md)
+- [createPriceListPricesWorkflow](https://docs.medusajs.com/references/medusa-workflows/createPriceListPricesWorkflow/index.html.md)
+- [updatePriceListPricesWorkflow](https://docs.medusajs.com/references/medusa-workflows/updatePriceListPricesWorkflow/index.html.md)
+- [removePriceListPricesWorkflow](https://docs.medusajs.com/references/medusa-workflows/removePriceListPricesWorkflow/index.html.md)
+- [updatePriceListsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updatePriceListsWorkflow/index.html.md)
 - [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)
-- [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)
-- [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)
+- [createCustomerAccountWorkflow](https://docs.medusajs.com/references/medusa-workflows/createCustomerAccountWorkflow/index.html.md)
+- [createCustomersWorkflow](https://docs.medusajs.com/references/medusa-workflows/createCustomersWorkflow/index.html.md)
+- [createCustomerAddressesWorkflow](https://docs.medusajs.com/references/medusa-workflows/createCustomerAddressesWorkflow/index.html.md)
+- [deleteCustomerAddressesWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteCustomerAddressesWorkflow/index.html.md)
+- [deleteCustomersWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteCustomersWorkflow/index.html.md)
+- [updateCustomerAddressesWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateCustomerAddressesWorkflow/index.html.md)
+- [updateCustomersWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateCustomersWorkflow/index.html.md)
+- [removeCustomerAccountWorkflow](https://docs.medusajs.com/references/medusa-workflows/removeCustomerAccountWorkflow/index.html.md)
 - [acceptOrderTransferValidationStep](https://docs.medusajs.com/references/medusa-workflows/acceptOrderTransferValidationStep/index.html.md)
-- [acceptOrderTransferWorkflow](https://docs.medusajs.com/references/medusa-workflows/acceptOrderTransferWorkflow/index.html.md)
 - [addOrderLineItemsWorkflow](https://docs.medusajs.com/references/medusa-workflows/addOrderLineItemsWorkflow/index.html.md)
-- [archiveOrderWorkflow](https://docs.medusajs.com/references/medusa-workflows/archiveOrderWorkflow/index.html.md)
 - [beginClaimOrderValidationStep](https://docs.medusajs.com/references/medusa-workflows/beginClaimOrderValidationStep/index.html.md)
-- [beginClaimOrderWorkflow](https://docs.medusajs.com/references/medusa-workflows/beginClaimOrderWorkflow/index.html.md)
+- [acceptOrderTransferWorkflow](https://docs.medusajs.com/references/medusa-workflows/acceptOrderTransferWorkflow/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)
 - [beginOrderEditOrderWorkflow](https://docs.medusajs.com/references/medusa-workflows/beginOrderEditOrderWorkflow/index.html.md)
-- [beginOrderExchangeValidationStep](https://docs.medusajs.com/references/medusa-workflows/beginOrderExchangeValidationStep/index.html.md)
 - [beginOrderEditValidationStep](https://docs.medusajs.com/references/medusa-workflows/beginOrderEditValidationStep/index.html.md)
 - [beginReceiveReturnValidationStep](https://docs.medusajs.com/references/medusa-workflows/beginReceiveReturnValidationStep/index.html.md)
-- [beginReceiveReturnWorkflow](https://docs.medusajs.com/references/medusa-workflows/beginReceiveReturnWorkflow/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)
-- [cancelBeginOrderClaimWorkflow](https://docs.medusajs.com/references/medusa-workflows/cancelBeginOrderClaimWorkflow/index.html.md)
 - [cancelBeginOrderClaimValidationStep](https://docs.medusajs.com/references/medusa-workflows/cancelBeginOrderClaimValidationStep/index.html.md)
+- [beginReturnOrderValidationStep](https://docs.medusajs.com/references/medusa-workflows/beginReturnOrderValidationStep/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)
 - [cancelBeginOrderExchangeValidationStep](https://docs.medusajs.com/references/medusa-workflows/cancelBeginOrderExchangeValidationStep/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)
+- [cancelBeginOrderEditWorkflow](https://docs.medusajs.com/references/medusa-workflows/cancelBeginOrderEditWorkflow/index.html.md)
 - [cancelClaimValidateOrderStep](https://docs.medusajs.com/references/medusa-workflows/cancelClaimValidateOrderStep/index.html.md)
-- [cancelOrderChangeWorkflow](https://docs.medusajs.com/references/medusa-workflows/cancelOrderChangeWorkflow/index.html.md)
-- [cancelOrderClaimWorkflow](https://docs.medusajs.com/references/medusa-workflows/cancelOrderClaimWorkflow/index.html.md)
+- [cancelExchangeValidateOrder](https://docs.medusajs.com/references/medusa-workflows/cancelExchangeValidateOrder/index.html.md)
 - [cancelOrderExchangeWorkflow](https://docs.medusajs.com/references/medusa-workflows/cancelOrderExchangeWorkflow/index.html.md)
+- [cancelOrderClaimWorkflow](https://docs.medusajs.com/references/medusa-workflows/cancelOrderClaimWorkflow/index.html.md)
+- [cancelOrderChangeWorkflow](https://docs.medusajs.com/references/medusa-workflows/cancelOrderChangeWorkflow/index.html.md)
 - [cancelOrderFulfillmentValidateOrder](https://docs.medusajs.com/references/medusa-workflows/cancelOrderFulfillmentValidateOrder/index.html.md)
 - [cancelOrderFulfillmentWorkflow](https://docs.medusajs.com/references/medusa-workflows/cancelOrderFulfillmentWorkflow/index.html.md)
-- [cancelOrderTransferRequestWorkflow](https://docs.medusajs.com/references/medusa-workflows/cancelOrderTransferRequestWorkflow/index.html.md)
 - [cancelOrderWorkflow](https://docs.medusajs.com/references/medusa-workflows/cancelOrderWorkflow/index.html.md)
+- [cancelRequestReturnValidationStep](https://docs.medusajs.com/references/medusa-workflows/cancelRequestReturnValidationStep/index.html.md)
 - [cancelReceiveReturnValidationStep](https://docs.medusajs.com/references/medusa-workflows/cancelReceiveReturnValidationStep/index.html.md)
 - [cancelReturnReceiveWorkflow](https://docs.medusajs.com/references/medusa-workflows/cancelReturnReceiveWorkflow/index.html.md)
-- [cancelRequestReturnValidationStep](https://docs.medusajs.com/references/medusa-workflows/cancelRequestReturnValidationStep/index.html.md)
 - [cancelReturnRequestWorkflow](https://docs.medusajs.com/references/medusa-workflows/cancelReturnRequestWorkflow/index.html.md)
+- [cancelOrderTransferRequestWorkflow](https://docs.medusajs.com/references/medusa-workflows/cancelOrderTransferRequestWorkflow/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)
-- [cancelTransferOrderRequestValidationStep](https://docs.medusajs.com/references/medusa-workflows/cancelTransferOrderRequestValidationStep/index.html.md)
-- [completeOrderWorkflow](https://docs.medusajs.com/references/medusa-workflows/completeOrderWorkflow/index.html.md)
 - [cancelValidateOrder](https://docs.medusajs.com/references/medusa-workflows/cancelValidateOrder/index.html.md)
+- [beginReceiveReturnWorkflow](https://docs.medusajs.com/references/medusa-workflows/beginReceiveReturnWorkflow/index.html.md)
+- [cancelTransferOrderRequestValidationStep](https://docs.medusajs.com/references/medusa-workflows/cancelTransferOrderRequestValidationStep/index.html.md)
 - [confirmClaimRequestValidationStep](https://docs.medusajs.com/references/medusa-workflows/confirmClaimRequestValidationStep/index.html.md)
-- [confirmClaimRequestWorkflow](https://docs.medusajs.com/references/medusa-workflows/confirmClaimRequestWorkflow/index.html.md)
-- [confirmExchangeRequestValidationStep](https://docs.medusajs.com/references/medusa-workflows/confirmExchangeRequestValidationStep/index.html.md)
+- [completeOrderWorkflow](https://docs.medusajs.com/references/medusa-workflows/completeOrderWorkflow/index.html.md)
 - [confirmExchangeRequestWorkflow](https://docs.medusajs.com/references/medusa-workflows/confirmExchangeRequestWorkflow/index.html.md)
+- [confirmClaimRequestWorkflow](https://docs.medusajs.com/references/medusa-workflows/confirmClaimRequestWorkflow/index.html.md)
 - [confirmOrderEditRequestValidationStep](https://docs.medusajs.com/references/medusa-workflows/confirmOrderEditRequestValidationStep/index.html.md)
 - [confirmOrderEditRequestWorkflow](https://docs.medusajs.com/references/medusa-workflows/confirmOrderEditRequestWorkflow/index.html.md)
-- [confirmReceiveReturnValidationStep](https://docs.medusajs.com/references/medusa-workflows/confirmReceiveReturnValidationStep/index.html.md)
 - [confirmReturnReceiveWorkflow](https://docs.medusajs.com/references/medusa-workflows/confirmReturnReceiveWorkflow/index.html.md)
+- [confirmReceiveReturnValidationStep](https://docs.medusajs.com/references/medusa-workflows/confirmReceiveReturnValidationStep/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)
+- [createAndCompleteReturnOrderWorkflow](https://docs.medusajs.com/references/medusa-workflows/createAndCompleteReturnOrderWorkflow/index.html.md)
 - [createCompleteReturnValidationStep](https://docs.medusajs.com/references/medusa-workflows/createCompleteReturnValidationStep/index.html.md)
+- [confirmExchangeRequestValidationStep](https://docs.medusajs.com/references/medusa-workflows/confirmExchangeRequestValidationStep/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)
-- [confirmReturnRequestValidationStep](https://docs.medusajs.com/references/medusa-workflows/confirmReturnRequestValidationStep/index.html.md)
 - [createOrderChangeActionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createOrderChangeActionsWorkflow/index.html.md)
-- [createOrderEditShippingMethodValidationStep](https://docs.medusajs.com/references/medusa-workflows/createOrderEditShippingMethodValidationStep/index.html.md)
 - [createOrderChangeWorkflow](https://docs.medusajs.com/references/medusa-workflows/createOrderChangeWorkflow/index.html.md)
+- [createExchangeShippingMethodWorkflow](https://docs.medusajs.com/references/medusa-workflows/createExchangeShippingMethodWorkflow/index.html.md)
+- [createOrderEditShippingMethodValidationStep](https://docs.medusajs.com/references/medusa-workflows/createOrderEditShippingMethodValidationStep/index.html.md)
 - [createOrderEditShippingMethodWorkflow](https://docs.medusajs.com/references/medusa-workflows/createOrderEditShippingMethodWorkflow/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)
 - [createOrderPaymentCollectionWorkflow](https://docs.medusajs.com/references/medusa-workflows/createOrderPaymentCollectionWorkflow/index.html.md)
 - [createOrderWorkflow](https://docs.medusajs.com/references/medusa-workflows/createOrderWorkflow/index.html.md)
-- [createOrderShipmentWorkflow](https://docs.medusajs.com/references/medusa-workflows/createOrderShipmentWorkflow/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)
-- [createReturnShippingMethodWorkflow](https://docs.medusajs.com/references/medusa-workflows/createReturnShippingMethodWorkflow/index.html.md)
+- [createOrdersWorkflow](https://docs.medusajs.com/references/medusa-workflows/createOrdersWorkflow/index.html.md)
 - [createShipmentValidateOrder](https://docs.medusajs.com/references/medusa-workflows/createShipmentValidateOrder/index.html.md)
+- [declineOrderTransferRequestWorkflow](https://docs.medusajs.com/references/medusa-workflows/declineOrderTransferRequestWorkflow/index.html.md)
 - [declineOrderChangeWorkflow](https://docs.medusajs.com/references/medusa-workflows/declineOrderChangeWorkflow/index.html.md)
 - [declineTransferOrderRequestValidationStep](https://docs.medusajs.com/references/medusa-workflows/declineTransferOrderRequestValidationStep/index.html.md)
-- [declineOrderTransferRequestWorkflow](https://docs.medusajs.com/references/medusa-workflows/declineOrderTransferRequestWorkflow/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)
-- [dismissItemReturnRequestValidationStep](https://docs.medusajs.com/references/medusa-workflows/dismissItemReturnRequestValidationStep/index.html.md)
+- [createReturnShippingMethodWorkflow](https://docs.medusajs.com/references/medusa-workflows/createReturnShippingMethodWorkflow/index.html.md)
 - [deleteOrderPaymentCollections](https://docs.medusajs.com/references/medusa-workflows/deleteOrderPaymentCollections/index.html.md)
-- [exchangeAddNewItemValidationStep](https://docs.medusajs.com/references/medusa-workflows/exchangeAddNewItemValidationStep/index.html.md)
+- [dismissItemReturnRequestValidationStep](https://docs.medusajs.com/references/medusa-workflows/dismissItemReturnRequestValidationStep/index.html.md)
 - [dismissItemReturnRequestWorkflow](https://docs.medusajs.com/references/medusa-workflows/dismissItemReturnRequestWorkflow/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)
 - [getOrdersListWorkflow](https://docs.medusajs.com/references/medusa-workflows/getOrdersListWorkflow/index.html.md)
+- [getOrderDetailWorkflow](https://docs.medusajs.com/references/medusa-workflows/getOrderDetailWorkflow/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)
+- [exchangeAddNewItemValidationStep](https://docs.medusajs.com/references/medusa-workflows/exchangeAddNewItemValidationStep/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)
+- [orderClaimAddNewItemValidationStep](https://docs.medusajs.com/references/medusa-workflows/orderClaimAddNewItemValidationStep/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)
-- [orderClaimRequestItemReturnWorkflow](https://docs.medusajs.com/references/medusa-workflows/orderClaimRequestItemReturnWorkflow/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)
-- [orderExchangeRequestItemReturnWorkflow](https://docs.medusajs.com/references/medusa-workflows/orderExchangeRequestItemReturnWorkflow/index.html.md)
-- [orderFulfillmentDeliverablilityValidationStep](https://docs.medusajs.com/references/medusa-workflows/orderFulfillmentDeliverablilityValidationStep/index.html.md)
 - [orderClaimItemValidationStep](https://docs.medusajs.com/references/medusa-workflows/orderClaimItemValidationStep/index.html.md)
-- [orderClaimAddNewItemWorkflow](https://docs.medusajs.com/references/medusa-workflows/orderClaimAddNewItemWorkflow/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)
+- [orderEditUpdateItemQuantityValidationStep](https://docs.medusajs.com/references/medusa-workflows/orderEditUpdateItemQuantityValidationStep/index.html.md)
 - [orderExchangeAddNewItemWorkflow](https://docs.medusajs.com/references/medusa-workflows/orderExchangeAddNewItemWorkflow/index.html.md)
+- [orderEditUpdateItemQuantityWorkflow](https://docs.medusajs.com/references/medusa-workflows/orderEditUpdateItemQuantityWorkflow/index.html.md)
+- [orderFulfillmentDeliverablilityValidationStep](https://docs.medusajs.com/references/medusa-workflows/orderFulfillmentDeliverablilityValidationStep/index.html.md)
+- [receiveAndCompleteReturnOrderWorkflow](https://docs.medusajs.com/references/medusa-workflows/receiveAndCompleteReturnOrderWorkflow/index.html.md)
 - [receiveCompleteReturnValidationStep](https://docs.medusajs.com/references/medusa-workflows/receiveCompleteReturnValidationStep/index.html.md)
-- [receiveItemReturnRequestWorkflow](https://docs.medusajs.com/references/medusa-workflows/receiveItemReturnRequestWorkflow/index.html.md)
+- [receiveItemReturnRequestValidationStep](https://docs.medusajs.com/references/medusa-workflows/receiveItemReturnRequestValidationStep/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)
+- [removeClaimShippingMethodValidationStep](https://docs.medusajs.com/references/medusa-workflows/removeClaimShippingMethodValidationStep/index.html.md)
+- [orderExchangeRequestItemReturnWorkflow](https://docs.medusajs.com/references/medusa-workflows/orderExchangeRequestItemReturnWorkflow/index.html.md)
+- [removeClaimAddItemActionValidationStep](https://docs.medusajs.com/references/medusa-workflows/removeClaimAddItemActionValidationStep/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)
-- [removeClaimShippingMethodValidationStep](https://docs.medusajs.com/references/medusa-workflows/removeClaimShippingMethodValidationStep/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)
-- [removeItemOrderEditActionWorkflow](https://docs.medusajs.com/references/medusa-workflows/removeItemOrderEditActionWorkflow/index.html.md)
 - [removeItemExchangeActionWorkflow](https://docs.medusajs.com/references/medusa-workflows/removeItemExchangeActionWorkflow/index.html.md)
 - [removeItemReceiveReturnActionValidationStep](https://docs.medusajs.com/references/medusa-workflows/removeItemReceiveReturnActionValidationStep/index.html.md)
+- [removeItemOrderEditActionWorkflow](https://docs.medusajs.com/references/medusa-workflows/removeItemOrderEditActionWorkflow/index.html.md)
 - [removeItemReceiveReturnActionWorkflow](https://docs.medusajs.com/references/medusa-workflows/removeItemReceiveReturnActionWorkflow/index.html.md)
+- [removeExchangeShippingMethodWorkflow](https://docs.medusajs.com/references/medusa-workflows/removeExchangeShippingMethodWorkflow/index.html.md)
 - [removeOrderEditItemActionValidationStep](https://docs.medusajs.com/references/medusa-workflows/removeOrderEditItemActionValidationStep/index.html.md)
 - [removeItemReturnActionWorkflow](https://docs.medusajs.com/references/medusa-workflows/removeItemReturnActionWorkflow/index.html.md)
 - [removeOrderEditShippingMethodValidationStep](https://docs.medusajs.com/references/medusa-workflows/removeOrderEditShippingMethodValidationStep/index.html.md)
 - [removeOrderEditShippingMethodWorkflow](https://docs.medusajs.com/references/medusa-workflows/removeOrderEditShippingMethodWorkflow/index.html.md)
-- [removeReturnShippingMethodValidationStep](https://docs.medusajs.com/references/medusa-workflows/removeReturnShippingMethodValidationStep/index.html.md)
 - [removeReturnItemActionValidationStep](https://docs.medusajs.com/references/medusa-workflows/removeReturnItemActionValidationStep/index.html.md)
-- [requestItemReturnValidationStep](https://docs.medusajs.com/references/medusa-workflows/requestItemReturnValidationStep/index.html.md)
 - [removeReturnShippingMethodWorkflow](https://docs.medusajs.com/references/medusa-workflows/removeReturnShippingMethodWorkflow/index.html.md)
+- [removeReturnShippingMethodValidationStep](https://docs.medusajs.com/references/medusa-workflows/removeReturnShippingMethodValidationStep/index.html.md)
+- [requestItemReturnValidationStep](https://docs.medusajs.com/references/medusa-workflows/requestItemReturnValidationStep/index.html.md)
 - [requestOrderEditRequestValidationStep](https://docs.medusajs.com/references/medusa-workflows/requestOrderEditRequestValidationStep/index.html.md)
 - [requestItemReturnWorkflow](https://docs.medusajs.com/references/medusa-workflows/requestItemReturnWorkflow/index.html.md)
 - [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)
-- [throwUnlessPaymentCollectionNotPaid](https://docs.medusajs.com/references/medusa-workflows/throwUnlessPaymentCollectionNotPaid/index.html.md)
-- [throwUnlessStatusIsNotPaid](https://docs.medusajs.com/references/medusa-workflows/throwUnlessStatusIsNotPaid/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)
 - [updateClaimAddItemWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateClaimAddItemWorkflow/index.html.md)
 - [updateClaimItemValidationStep](https://docs.medusajs.com/references/medusa-workflows/updateClaimItemValidationStep/index.html.md)
-- [updateClaimShippingMethodValidationStep](https://docs.medusajs.com/references/medusa-workflows/updateClaimShippingMethodValidationStep/index.html.md)
 - [updateClaimItemWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateClaimItemWorkflow/index.html.md)
+- [throwUnlessPaymentCollectionNotPaid](https://docs.medusajs.com/references/medusa-workflows/throwUnlessPaymentCollectionNotPaid/index.html.md)
+- [updateClaimShippingMethodValidationStep](https://docs.medusajs.com/references/medusa-workflows/updateClaimShippingMethodValidationStep/index.html.md)
 - [updateClaimShippingMethodWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateClaimShippingMethodWorkflow/index.html.md)
 - [updateExchangeAddItemValidationStep](https://docs.medusajs.com/references/medusa-workflows/updateExchangeAddItemValidationStep/index.html.md)
 - [updateExchangeShippingMethodValidationStep](https://docs.medusajs.com/references/medusa-workflows/updateExchangeShippingMethodValidationStep/index.html.md)
+- [requestOrderTransferValidationStep](https://docs.medusajs.com/references/medusa-workflows/requestOrderTransferValidationStep/index.html.md)
 - [updateExchangeAddItemWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateExchangeAddItemWorkflow/index.html.md)
 - [updateExchangeShippingMethodWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateExchangeShippingMethodWorkflow/index.html.md)
 - [updateOrderChangeActionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateOrderChangeActionsWorkflow/index.html.md)
 - [updateOrderChangesWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateOrderChangesWorkflow/index.html.md)
-- [updateOrderEditAddItemValidationStep](https://docs.medusajs.com/references/medusa-workflows/updateOrderEditAddItemValidationStep/index.html.md)
-- [updateOrderEditAddItemWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateOrderEditAddItemWorkflow/index.html.md)
 - [updateOrderEditItemQuantityValidationStep](https://docs.medusajs.com/references/medusa-workflows/updateOrderEditItemQuantityValidationStep/index.html.md)
+- [updateOrderEditAddItemWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateOrderEditAddItemWorkflow/index.html.md)
+- [updateOrderEditAddItemValidationStep](https://docs.medusajs.com/references/medusa-workflows/updateOrderEditAddItemValidationStep/index.html.md)
 - [updateOrderEditItemQuantityWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateOrderEditItemQuantityWorkflow/index.html.md)
 - [updateOrderEditShippingMethodValidationStep](https://docs.medusajs.com/references/medusa-workflows/updateOrderEditShippingMethodValidationStep/index.html.md)
 - [updateOrderEditShippingMethodWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateOrderEditShippingMethodWorkflow/index.html.md)
+- [updateOrderWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateOrderWorkflow/index.html.md)
 - [updateOrderValidationStep](https://docs.medusajs.com/references/medusa-workflows/updateOrderValidationStep/index.html.md)
 - [updateOrderTaxLinesWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateOrderTaxLinesWorkflow/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)
 - [updateRequestItemReturnValidationStep](https://docs.medusajs.com/references/medusa-workflows/updateRequestItemReturnValidationStep/index.html.md)
 - [updateReceiveItemReturnRequestWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateReceiveItemReturnRequestWorkflow/index.html.md)
-- [updateRequestItemReturnWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateRequestItemReturnWorkflow/index.html.md)
 - [updateReturnShippingMethodValidationStep](https://docs.medusajs.com/references/medusa-workflows/updateReturnShippingMethodValidationStep/index.html.md)
-- [updateReturnValidationStep](https://docs.medusajs.com/references/medusa-workflows/updateReturnValidationStep/index.html.md)
-- [updateReturnWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateReturnWorkflow/index.html.md)
+- [updateRequestItemReturnWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateRequestItemReturnWorkflow/index.html.md)
 - [updateReturnShippingMethodWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateReturnShippingMethodWorkflow/index.html.md)
+- [updateReturnWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateReturnWorkflow/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)
+- [updateReturnValidationStep](https://docs.medusajs.com/references/medusa-workflows/updateReturnValidationStep/index.html.md)
+- [refundPaymentsWorkflow](https://docs.medusajs.com/references/medusa-workflows/refundPaymentsWorkflow/index.html.md)
+- [refundPaymentWorkflow](https://docs.medusajs.com/references/medusa-workflows/refundPaymentWorkflow/index.html.md)
+- [validateRefundStep](https://docs.medusajs.com/references/medusa-workflows/validateRefundStep/index.html.md)
+- [validatePaymentsRefundStep](https://docs.medusajs.com/references/medusa-workflows/validatePaymentsRefundStep/index.html.md)
+- [updatePricePreferencesWorkflow](https://docs.medusajs.com/references/medusa-workflows/updatePricePreferencesWorkflow/index.html.md)
+- [deletePricePreferencesWorkflow](https://docs.medusajs.com/references/medusa-workflows/deletePricePreferencesWorkflow/index.html.md)
+- [createPricePreferencesWorkflow](https://docs.medusajs.com/references/medusa-workflows/createPricePreferencesWorkflow/index.html.md)
+- [createProductCategoriesWorkflow](https://docs.medusajs.com/references/medusa-workflows/createProductCategoriesWorkflow/index.html.md)
+- [deleteProductCategoriesWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteProductCategoriesWorkflow/index.html.md)
+- [updateProductCategoriesWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateProductCategoriesWorkflow/index.html.md)
+- [createRegionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createRegionsWorkflow/index.html.md)
+- [updateRegionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateRegionsWorkflow/index.html.md)
+- [deleteRegionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteRegionsWorkflow/index.html.md)
+- [addOrRemoveCampaignPromotionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/addOrRemoveCampaignPromotionsWorkflow/index.html.md)
+- [batchPromotionRulesWorkflow](https://docs.medusajs.com/references/medusa-workflows/batchPromotionRulesWorkflow/index.html.md)
+- [createCampaignsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createCampaignsWorkflow/index.html.md)
+- [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)
+- [deletePromotionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deletePromotionsWorkflow/index.html.md)
+- [updateCampaignsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateCampaignsWorkflow/index.html.md)
+- [updatePromotionsStatusWorkflow](https://docs.medusajs.com/references/medusa-workflows/updatePromotionsStatusWorkflow/index.html.md)
+- [updatePromotionsValidationStep](https://docs.medusajs.com/references/medusa-workflows/updatePromotionsValidationStep/index.html.md)
+- [updatePromotionRulesWorkflow](https://docs.medusajs.com/references/medusa-workflows/updatePromotionRulesWorkflow/index.html.md)
+- [updatePromotionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updatePromotionsWorkflow/index.html.md)
 - [batchLinkProductsToCategoryWorkflow](https://docs.medusajs.com/references/medusa-workflows/batchLinkProductsToCategoryWorkflow/index.html.md)
-- [batchProductVariantsWorkflow](https://docs.medusajs.com/references/medusa-workflows/batchProductVariantsWorkflow/index.html.md)
 - [batchLinkProductsToCollectionWorkflow](https://docs.medusajs.com/references/medusa-workflows/batchLinkProductsToCollectionWorkflow/index.html.md)
+- [batchProductVariantsWorkflow](https://docs.medusajs.com/references/medusa-workflows/batchProductVariantsWorkflow/index.html.md)
 - [batchProductsWorkflow](https://docs.medusajs.com/references/medusa-workflows/batchProductsWorkflow/index.html.md)
 - [createCollectionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createCollectionsWorkflow/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)
-- [createProductsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createProductsWorkflow/index.html.md)
 - [createProductVariantsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createProductVariantsWorkflow/index.html.md)
 - [createProductTypesWorkflow](https://docs.medusajs.com/references/medusa-workflows/createProductTypesWorkflow/index.html.md)
+- [createProductsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createProductsWorkflow/index.html.md)
 - [deleteCollectionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteCollectionsWorkflow/index.html.md)
 - [deleteProductOptionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteProductOptionsWorkflow/index.html.md)
 - [deleteProductTagsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteProductTagsWorkflow/index.html.md)
 - [deleteProductTypesWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteProductTypesWorkflow/index.html.md)
-- [deleteProductVariantsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteProductVariantsWorkflow/index.html.md)
-- [exportProductsWorkflow](https://docs.medusajs.com/references/medusa-workflows/exportProductsWorkflow/index.html.md)
 - [deleteProductsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteProductsWorkflow/index.html.md)
-- [updateCollectionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateCollectionsWorkflow/index.html.md)
+- [deleteProductVariantsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteProductVariantsWorkflow/index.html.md)
 - [importProductsWorkflow](https://docs.medusajs.com/references/medusa-workflows/importProductsWorkflow/index.html.md)
+- [exportProductsWorkflow](https://docs.medusajs.com/references/medusa-workflows/exportProductsWorkflow/index.html.md)
 - [updateProductOptionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateProductOptionsWorkflow/index.html.md)
+- [updateCollectionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateCollectionsWorkflow/index.html.md)
 - [updateProductTagsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateProductTagsWorkflow/index.html.md)
 - [updateProductTypesWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateProductTypesWorkflow/index.html.md)
 - [updateProductVariantsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateProductVariantsWorkflow/index.html.md)
 - [updateProductsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateProductsWorkflow/index.html.md)
 - [upsertVariantPricesWorkflow](https://docs.medusajs.com/references/medusa-workflows/upsertVariantPricesWorkflow/index.html.md)
 - [validateProductInputStep](https://docs.medusajs.com/references/medusa-workflows/validateProductInputStep/index.html.md)
-- [createRegionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createRegionsWorkflow/index.html.md)
-- [deleteRegionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteRegionsWorkflow/index.html.md)
-- [updateRegionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateRegionsWorkflow/index.html.md)
-- [addOrRemoveCampaignPromotionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/addOrRemoveCampaignPromotionsWorkflow/index.html.md)
-- [batchPromotionRulesWorkflow](https://docs.medusajs.com/references/medusa-workflows/batchPromotionRulesWorkflow/index.html.md)
-- [createCampaignsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createCampaignsWorkflow/index.html.md)
-- [createPromotionRulesWorkflow](https://docs.medusajs.com/references/medusa-workflows/createPromotionRulesWorkflow/index.html.md)
-- [deleteCampaignsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteCampaignsWorkflow/index.html.md)
-- [createPromotionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createPromotionsWorkflow/index.html.md)
-- [deletePromotionRulesWorkflow](https://docs.medusajs.com/references/medusa-workflows/deletePromotionRulesWorkflow/index.html.md)
-- [deletePromotionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deletePromotionsWorkflow/index.html.md)
-- [updatePromotionRulesWorkflow](https://docs.medusajs.com/references/medusa-workflows/updatePromotionRulesWorkflow/index.html.md)
-- [updateCampaignsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateCampaignsWorkflow/index.html.md)
-- [updatePromotionsStatusWorkflow](https://docs.medusajs.com/references/medusa-workflows/updatePromotionsStatusWorkflow/index.html.md)
-- [updatePromotionsValidationStep](https://docs.medusajs.com/references/medusa-workflows/updatePromotionsValidationStep/index.html.md)
-- [updatePromotionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updatePromotionsWorkflow/index.html.md)
-- [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)
-- [createReservationsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createReservationsWorkflow/index.html.md)
-- [deleteReservationsByLineItemsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteReservationsByLineItemsWorkflow/index.html.md)
-- [updateReservationsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateReservationsWorkflow/index.html.md)
-- [deleteReservationsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteReservationsWorkflow/index.html.md)
 - [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)
+- [createReservationsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createReservationsWorkflow/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)
 - [deleteShippingProfileWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteShippingProfileWorkflow/index.html.md)
 - [validateStepShippingProfileDelete](https://docs.medusajs.com/references/medusa-workflows/validateStepShippingProfileDelete/index.html.md)
 - [createSalesChannelsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createSalesChannelsWorkflow/index.html.md)
@@ -29999,28 +30146,28 @@ For each product variant, you:
 - [linkProductsToSalesChannelWorkflow](https://docs.medusajs.com/references/medusa-workflows/linkProductsToSalesChannelWorkflow/index.html.md)
 - [updateSalesChannelsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateSalesChannelsWorkflow/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)
 - [deleteStockLocationsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteStockLocationsWorkflow/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)
+- [deleteStoresWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteStoresWorkflow/index.html.md)
+- [updateStoresWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateStoresWorkflow/index.html.md)
+- [createStoresWorkflow](https://docs.medusajs.com/references/medusa-workflows/createStoresWorkflow/index.html.md)
+- [createTaxRatesWorkflow](https://docs.medusajs.com/references/medusa-workflows/createTaxRatesWorkflow/index.html.md)
+- [createTaxRateRulesWorkflow](https://docs.medusajs.com/references/medusa-workflows/createTaxRateRulesWorkflow/index.html.md)
+- [createTaxRegionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createTaxRegionsWorkflow/index.html.md)
+- [deleteTaxRateRulesWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteTaxRateRulesWorkflow/index.html.md)
+- [deleteTaxRatesWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteTaxRatesWorkflow/index.html.md)
+- [deleteTaxRegionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteTaxRegionsWorkflow/index.html.md)
+- [maybeListTaxRateRuleIdsStep](https://docs.medusajs.com/references/medusa-workflows/maybeListTaxRateRuleIdsStep/index.html.md)
+- [setTaxRateRulesWorkflow](https://docs.medusajs.com/references/medusa-workflows/setTaxRateRulesWorkflow/index.html.md)
+- [updateTaxRegionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateTaxRegionsWorkflow/index.html.md)
+- [updateTaxRatesWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateTaxRatesWorkflow/index.html.md)
+- [createUserAccountWorkflow](https://docs.medusajs.com/references/medusa-workflows/createUserAccountWorkflow/index.html.md)
 - [createUsersWorkflow](https://docs.medusajs.com/references/medusa-workflows/createUsersWorkflow/index.html.md)
 - [deleteUsersWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteUsersWorkflow/index.html.md)
-- [createUserAccountWorkflow](https://docs.medusajs.com/references/medusa-workflows/createUserAccountWorkflow/index.html.md)
 - [removeUserAccountWorkflow](https://docs.medusajs.com/references/medusa-workflows/removeUserAccountWorkflow/index.html.md)
 - [updateUsersWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateUsersWorkflow/index.html.md)
-- [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)
-- [createTaxRateRulesWorkflow](https://docs.medusajs.com/references/medusa-workflows/createTaxRateRulesWorkflow/index.html.md)
-- [createTaxRatesWorkflow](https://docs.medusajs.com/references/medusa-workflows/createTaxRatesWorkflow/index.html.md)
-- [deleteTaxRatesWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteTaxRatesWorkflow/index.html.md)
-- [deleteTaxRateRulesWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteTaxRateRulesWorkflow/index.html.md)
-- [createTaxRegionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createTaxRegionsWorkflow/index.html.md)
-- [deleteTaxRegionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteTaxRegionsWorkflow/index.html.md)
-- [updateTaxRatesWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateTaxRatesWorkflow/index.html.md)
-- [setTaxRateRulesWorkflow](https://docs.medusajs.com/references/medusa-workflows/setTaxRateRulesWorkflow/index.html.md)
-- [maybeListTaxRateRuleIdsStep](https://docs.medusajs.com/references/medusa-workflows/maybeListTaxRateRuleIdsStep/index.html.md)
-- [updateTaxRegionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateTaxRegionsWorkflow/index.html.md)
 
 
 ## Steps
@@ -30029,118 +30176,118 @@ For each product variant, you:
 - [addShippingMethodToCartStep](https://docs.medusajs.com/references/medusa-workflows/steps/addShippingMethodToCartStep/index.html.md)
 - [confirmInventoryStep](https://docs.medusajs.com/references/medusa-workflows/steps/confirmInventoryStep/index.html.md)
 - [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)
+- [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)
 - [createShippingMethodAdjustmentsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createShippingMethodAdjustmentsStep/index.html.md)
-- [createLineItemAdjustmentsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createLineItemAdjustmentsStep/index.html.md)
 - [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)
+- [getVariantPriceSetsStep](https://docs.medusajs.com/references/medusa-workflows/steps/getVariantPriceSetsStep/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)
-- [createPaymentCollectionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createPaymentCollectionsStep/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)
+- [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)
 - [prepareAdjustmentsFromPromotionActionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/prepareAdjustmentsFromPromotionActionsStep/index.html.md)
 - [removeShippingMethodFromCartStep](https://docs.medusajs.com/references/medusa-workflows/steps/removeShippingMethodFromCartStep/index.html.md)
 - [reserveInventoryStep](https://docs.medusajs.com/references/medusa-workflows/steps/reserveInventoryStep/index.html.md)
 - [retrieveCartStep](https://docs.medusajs.com/references/medusa-workflows/steps/retrieveCartStep/index.html.md)
-- [removeShippingMethodAdjustmentsStep](https://docs.medusajs.com/references/medusa-workflows/steps/removeShippingMethodAdjustmentsStep/index.html.md)
 - [setTaxLinesForItemsStep](https://docs.medusajs.com/references/medusa-workflows/steps/setTaxLinesForItemsStep/index.html.md)
-- [removeLineItemAdjustmentsStep](https://docs.medusajs.com/references/medusa-workflows/steps/removeLineItemAdjustmentsStep/index.html.md)
 - [updateCartPromotionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateCartPromotionsStep/index.html.md)
 - [updateCartsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateCartsStep/index.html.md)
-- [validateAndReturnShippingMethodsDataStep](https://docs.medusajs.com/references/medusa-workflows/steps/validateAndReturnShippingMethodsDataStep/index.html.md)
-- [validateCartPaymentsStep](https://docs.medusajs.com/references/medusa-workflows/steps/validateCartPaymentsStep/index.html.md)
 - [updateLineItemsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateLineItemsStep/index.html.md)
 - [updateShippingMethodsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateShippingMethodsStep/index.html.md)
+- [validateAndReturnShippingMethodsDataStep](https://docs.medusajs.com/references/medusa-workflows/steps/validateAndReturnShippingMethodsDataStep/index.html.md)
 - [validateCartShippingOptionsPriceStep](https://docs.medusajs.com/references/medusa-workflows/steps/validateCartShippingOptionsPriceStep/index.html.md)
+- [validateCartPaymentsStep](https://docs.medusajs.com/references/medusa-workflows/steps/validateCartPaymentsStep/index.html.md)
 - [validateCartShippingOptionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/validateCartShippingOptionsStep/index.html.md)
-- [validateShippingStep](https://docs.medusajs.com/references/medusa-workflows/steps/validateShippingStep/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)
 - [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)
 - [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)
 - [linkSalesChannelsToApiKeyStep](https://docs.medusajs.com/references/medusa-workflows/steps/linkSalesChannelsToApiKeyStep/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)
+- [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)
+- [createCustomerAddressesStep](https://docs.medusajs.com/references/medusa-workflows/steps/createCustomerAddressesStep/index.html.md)
+- [deleteCustomerAddressesStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteCustomerAddressesStep/index.html.md)
+- [deleteCustomersStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteCustomersStep/index.html.md)
+- [createCustomersStep](https://docs.medusajs.com/references/medusa-workflows/steps/createCustomersStep/index.html.md)
+- [maybeUnsetDefaultBillingAddressesStep](https://docs.medusajs.com/references/medusa-workflows/steps/maybeUnsetDefaultBillingAddressesStep/index.html.md)
+- [maybeUnsetDefaultShippingAddressesStep](https://docs.medusajs.com/references/medusa-workflows/steps/maybeUnsetDefaultShippingAddressesStep/index.html.md)
+- [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)
+- [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)
+- [linkCustomersToCustomerGroupStep](https://docs.medusajs.com/references/medusa-workflows/steps/linkCustomersToCustomerGroupStep/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)
 - [updateCustomerGroupsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateCustomerGroupsStep/index.html.md)
-- [linkCustomersToCustomerGroupStep](https://docs.medusajs.com/references/medusa-workflows/steps/linkCustomersToCustomerGroupStep/index.html.md)
-- [createDefaultStoreStep](https://docs.medusajs.com/references/medusa-workflows/steps/createDefaultStoreStep/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)
-- [createCustomerAddressesStep](https://docs.medusajs.com/references/medusa-workflows/steps/createCustomerAddressesStep/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)
-- [deleteCustomersStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteCustomersStep/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)
-- [updateCustomersStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateCustomersStep/index.html.md)
 - [uploadFilesStep](https://docs.medusajs.com/references/medusa-workflows/steps/uploadFilesStep/index.html.md)
 - [deleteFilesStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteFilesStep/index.html.md)
-- [adjustInventoryLevelsStep](https://docs.medusajs.com/references/medusa-workflows/steps/adjustInventoryLevelsStep/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)
-- [deleteInventoryLevelsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteInventoryLevelsStep/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)
-- [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)
-- [updateInventoryItemsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateInventoryItemsStep/index.html.md)
-- [validateInventoryLocationsStep](https://docs.medusajs.com/references/medusa-workflows/steps/validateInventoryLocationsStep/index.html.md)
 - [calculateShippingOptionsPricesStep](https://docs.medusajs.com/references/medusa-workflows/steps/calculateShippingOptionsPricesStep/index.html.md)
-- [cancelFulfillmentStep](https://docs.medusajs.com/references/medusa-workflows/steps/cancelFulfillmentStep/index.html.md)
 - [buildPriceSet](https://docs.medusajs.com/references/medusa-workflows/steps/buildPriceSet/index.html.md)
-- [createFulfillmentStep](https://docs.medusajs.com/references/medusa-workflows/steps/createFulfillmentStep/index.html.md)
+- [cancelFulfillmentStep](https://docs.medusajs.com/references/medusa-workflows/steps/cancelFulfillmentStep/index.html.md)
 - [createFulfillmentSets](https://docs.medusajs.com/references/medusa-workflows/steps/createFulfillmentSets/index.html.md)
-- [createShippingOptionRulesStep](https://docs.medusajs.com/references/medusa-workflows/steps/createShippingOptionRulesStep/index.html.md)
-- [createShippingOptionsPriceSetsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createShippingOptionsPriceSetsStep/index.html.md)
+- [createFulfillmentStep](https://docs.medusajs.com/references/medusa-workflows/steps/createFulfillmentStep/index.html.md)
 - [createReturnFulfillmentStep](https://docs.medusajs.com/references/medusa-workflows/steps/createReturnFulfillmentStep/index.html.md)
-- [createShippingProfilesStep](https://docs.medusajs.com/references/medusa-workflows/steps/createShippingProfilesStep/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)
+- [createShippingOptionsPriceSetsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createShippingOptionsPriceSetsStep/index.html.md)
+- [createShippingOptionRulesStep](https://docs.medusajs.com/references/medusa-workflows/steps/createShippingOptionRulesStep/index.html.md)
 - [deleteFulfillmentSetsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteFulfillmentSetsStep/index.html.md)
 - [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)
-- [setShippingOptionsPricesStep](https://docs.medusajs.com/references/medusa-workflows/steps/setShippingOptionsPricesStep/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)
+- [deleteShippingOptionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteShippingOptionsStep/index.html.md)
 - [updateServiceZonesStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateServiceZonesStep/index.html.md)
+- [updateShippingOptionRulesStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateShippingOptionRulesStep/index.html.md)
+- [updateFulfillmentStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateFulfillmentStep/index.html.md)
+- [setShippingOptionsPricesStep](https://docs.medusajs.com/references/medusa-workflows/steps/setShippingOptionsPricesStep/index.html.md)
 - [updateShippingProfilesStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateShippingProfilesStep/index.html.md)
 - [upsertShippingOptionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/upsertShippingOptionsStep/index.html.md)
 - [validateShipmentStep](https://docs.medusajs.com/references/medusa-workflows/steps/validateShipmentStep/index.html.md)
-- [deleteShippingOptionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteShippingOptionsStep/index.html.md)
 - [validateShippingOptionPricesStep](https://docs.medusajs.com/references/medusa-workflows/steps/validateShippingOptionPricesStep/index.html.md)
+- [adjustInventoryLevelsStep](https://docs.medusajs.com/references/medusa-workflows/steps/adjustInventoryLevelsStep/index.html.md)
+- [attachInventoryItemToVariants](https://docs.medusajs.com/references/medusa-workflows/steps/attachInventoryItemToVariants/index.html.md)
+- [createInventoryLevelsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createInventoryLevelsStep/index.html.md)
+- [createInventoryItemsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createInventoryItemsStep/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)
+- [updateInventoryLevelsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateInventoryLevelsStep/index.html.md)
+- [validateInventoryDeleteStep](https://docs.medusajs.com/references/medusa-workflows/steps/validateInventoryDeleteStep/index.html.md)
+- [validateInventoryItemsForCreate](https://docs.medusajs.com/references/medusa-workflows/steps/validateInventoryItemsForCreate/index.html.md)
+- [validateInventoryLocationsStep](https://docs.medusajs.com/references/medusa-workflows/steps/validateInventoryLocationsStep/index.html.md)
 - [createInviteStep](https://docs.medusajs.com/references/medusa-workflows/steps/createInviteStep/index.html.md)
-- [deleteInvitesStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteInvitesStep/index.html.md)
 - [refreshInviteTokensStep](https://docs.medusajs.com/references/medusa-workflows/steps/refreshInviteTokensStep/index.html.md)
+- [deleteInvitesStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteInvitesStep/index.html.md)
 - [validateTokenStep](https://docs.medusajs.com/references/medusa-workflows/steps/validateTokenStep/index.html.md)
+- [updateLineItemsStepWithSelector](https://docs.medusajs.com/references/medusa-workflows/steps/updateLineItemsStepWithSelector/index.html.md)
 - [deleteLineItemsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteLineItemsStep/index.html.md)
 - [listLineItemsStep](https://docs.medusajs.com/references/medusa-workflows/steps/listLineItemsStep/index.html.md)
-- [updateLineItemsStepWithSelector](https://docs.medusajs.com/references/medusa-workflows/steps/updateLineItemsStepWithSelector/index.html.md)
-- [addOrderTransactionStep](https://docs.medusajs.com/references/medusa-workflows/steps/addOrderTransactionStep/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)
+- [archiveOrdersStep](https://docs.medusajs.com/references/medusa-workflows/steps/archiveOrdersStep/index.html.md)
 - [cancelOrderClaimStep](https://docs.medusajs.com/references/medusa-workflows/steps/cancelOrderClaimStep/index.html.md)
+- [addOrderTransactionStep](https://docs.medusajs.com/references/medusa-workflows/steps/addOrderTransactionStep/index.html.md)
+- [cancelOrderExchangeStep](https://docs.medusajs.com/references/medusa-workflows/steps/cancelOrderExchangeStep/index.html.md)
 - [cancelOrderFulfillmentStep](https://docs.medusajs.com/references/medusa-workflows/steps/cancelOrderFulfillmentStep/index.html.md)
-- [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)
-- [createCompleteReturnStep](https://docs.medusajs.com/references/medusa-workflows/steps/createCompleteReturnStep/index.html.md)
+- [completeOrdersStep](https://docs.medusajs.com/references/medusa-workflows/steps/completeOrdersStep/index.html.md)
 - [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)
+- [cancelOrdersStep](https://docs.medusajs.com/references/medusa-workflows/steps/cancelOrdersStep/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)
-- [completeOrdersStep](https://docs.medusajs.com/references/medusa-workflows/steps/completeOrdersStep/index.html.md)
 - [createOrderExchangeItemsFromActionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createOrderExchangeItemsFromActionsStep/index.html.md)
 - [createOrderExchangesStep](https://docs.medusajs.com/references/medusa-workflows/steps/createOrderExchangesStep/index.html.md)
+- [createReturnsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createReturnsStep/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)
 - [declineOrderChangeStep](https://docs.medusajs.com/references/medusa-workflows/steps/declineOrderChangeStep/index.html.md)
 - [deleteClaimsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteClaimsStep/index.html.md)
 - [deleteExchangesStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteExchangesStep/index.html.md)
@@ -30150,41 +30297,16 @@ For each product variant, you:
 - [deleteOrderShippingMethods](https://docs.medusajs.com/references/medusa-workflows/steps/deleteOrderShippingMethods/index.html.md)
 - [deleteOrderLineItems](https://docs.medusajs.com/references/medusa-workflows/steps/deleteOrderLineItems/index.html.md)
 - [previewOrderChangeStep](https://docs.medusajs.com/references/medusa-workflows/steps/previewOrderChangeStep/index.html.md)
-- [registerOrderFulfillmentStep](https://docs.medusajs.com/references/medusa-workflows/steps/registerOrderFulfillmentStep/index.html.md)
-- [registerOrderShipmentStep](https://docs.medusajs.com/references/medusa-workflows/steps/registerOrderShipmentStep/index.html.md)
 - [registerOrderChangesStep](https://docs.medusajs.com/references/medusa-workflows/steps/registerOrderChangesStep/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)
+- [updateOrderShippingMethodsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateOrderShippingMethodsStep/index.html.md)
 - [updateOrderChangeActionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateOrderChangeActionsStep/index.html.md)
 - [updateOrderChangesStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateOrderChangesStep/index.html.md)
-- [updateOrderShippingMethodsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateOrderShippingMethodsStep/index.html.md)
 - [updateOrdersStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateOrdersStep/index.html.md)
 - [updateReturnItemsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateReturnItemsStep/index.html.md)
 - [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)
-- [updateRefundReasonsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateRefundReasonsStep/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)
-- [validateDeletedPaymentSessionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/validateDeletedPaymentSessionsStep/index.html.md)
-- [createPriceListPricesStep](https://docs.medusajs.com/references/medusa-workflows/steps/createPriceListPricesStep/index.html.md)
-- [deletePriceListsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deletePriceListsStep/index.html.md)
-- [getExistingPriceListsPriceIdsStep](https://docs.medusajs.com/references/medusa-workflows/steps/getExistingPriceListsPriceIdsStep/index.html.md)
-- [createPriceListsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createPriceListsStep/index.html.md)
-- [updatePriceListPricesStep](https://docs.medusajs.com/references/medusa-workflows/steps/updatePriceListPricesStep/index.html.md)
-- [updatePriceListsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updatePriceListsStep/index.html.md)
-- [validatePriceListsStep](https://docs.medusajs.com/references/medusa-workflows/steps/validatePriceListsStep/index.html.md)
-- [removePriceListPricesStep](https://docs.medusajs.com/references/medusa-workflows/steps/removePriceListPricesStep/index.html.md)
-- [validateVariantPriceLinksStep](https://docs.medusajs.com/references/medusa-workflows/steps/validateVariantPriceLinksStep/index.html.md)
-- [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)
-- [dismissRemoteLinkStep](https://docs.medusajs.com/references/medusa-workflows/steps/dismissRemoteLinkStep/index.html.md)
-- [useQueryGraphStep](https://docs.medusajs.com/references/medusa-workflows/steps/useQueryGraphStep/index.html.md)
-- [useRemoteQueryStep](https://docs.medusajs.com/references/medusa-workflows/steps/useRemoteQueryStep/index.html.md)
-- [validatePresenceOfStep](https://docs.medusajs.com/references/medusa-workflows/steps/validatePresenceOfStep/index.html.md)
 - [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)
 - [authorizePaymentSessionStep](https://docs.medusajs.com/references/medusa-workflows/steps/authorizePaymentSessionStep/index.html.md)
@@ -30192,20 +30314,40 @@ For each product variant, you:
 - [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)
+- [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)
+- [updateRemoteLinksStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateRemoteLinksStep/index.html.md)
+- [removeRemoteLinkStep](https://docs.medusajs.com/references/medusa-workflows/steps/removeRemoteLinkStep/index.html.md)
+- [emitEventStep](https://docs.medusajs.com/references/medusa-workflows/steps/emitEventStep/index.html.md)
+- [useQueryGraphStep](https://docs.medusajs.com/references/medusa-workflows/steps/useQueryGraphStep/index.html.md)
+- [useRemoteQueryStep](https://docs.medusajs.com/references/medusa-workflows/steps/useRemoteQueryStep/index.html.md)
+- [validatePresenceOfStep](https://docs.medusajs.com/references/medusa-workflows/steps/validatePresenceOfStep/index.html.md)
+- [createPaymentAccountHolderStep](https://docs.medusajs.com/references/medusa-workflows/steps/createPaymentAccountHolderStep/index.html.md)
+- [createPaymentSessionStep](https://docs.medusajs.com/references/medusa-workflows/steps/createPaymentSessionStep/index.html.md)
+- [deletePaymentSessionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deletePaymentSessionsStep/index.html.md)
+- [deleteRefundReasonsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteRefundReasonsStep/index.html.md)
+- [createRefundReasonStep](https://docs.medusajs.com/references/medusa-workflows/steps/createRefundReasonStep/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)
+- [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)
+- [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)
+- [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)
+- [updatePriceListsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updatePriceListsStep/index.html.md)
+- [validateVariantPriceLinksStep](https://docs.medusajs.com/references/medusa-workflows/steps/validateVariantPriceLinksStep/index.html.md)
 - [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)
+- [createPriceSetsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createPriceSetsStep/index.html.md)
 - [updatePricePreferencesAsArrayStep](https://docs.medusajs.com/references/medusa-workflows/steps/updatePricePreferencesAsArrayStep/index.html.md)
 - [updatePricePreferencesStep](https://docs.medusajs.com/references/medusa-workflows/steps/updatePricePreferencesStep/index.html.md)
 - [updatePriceSetsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updatePriceSetsStep/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)
-- [createReservationsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createReservationsStep/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)
-- [updateReservationsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateReservationsStep/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)
 - [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)
 - [batchLinkProductsToCollectionStep](https://docs.medusajs.com/references/medusa-workflows/steps/batchLinkProductsToCollectionStep/index.html.md)
@@ -30214,74 +30356,79 @@ For each product variant, you:
 - [createProductTypesStep](https://docs.medusajs.com/references/medusa-workflows/steps/createProductTypesStep/index.html.md)
 - [createProductVariantsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createProductVariantsStep/index.html.md)
 - [createProductsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createProductsStep/index.html.md)
-- [createVariantPricingLinkStep](https://docs.medusajs.com/references/medusa-workflows/steps/createVariantPricingLinkStep/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)
-- [deleteProductTypesStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteProductTypesStep/index.html.md)
 - [deleteProductVariantsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteProductVariantsStep/index.html.md)
+- [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)
-- [deleteProductsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteProductsStep/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)
 - [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)
+- [parseProductCsvStep](https://docs.medusajs.com/references/medusa-workflows/steps/parseProductCsvStep/index.html.md)
 - [updateCollectionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateCollectionsStep/index.html.md)
 - [updateProductOptionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateProductOptionsStep/index.html.md)
-- [parseProductCsvStep](https://docs.medusajs.com/references/medusa-workflows/steps/parseProductCsvStep/index.html.md)
 - [updateProductTagsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateProductTagsStep/index.html.md)
 - [updateProductTypesStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateProductTypesStep/index.html.md)
 - [updateProductVariantsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateProductVariantsStep/index.html.md)
-- [addCampaignPromotionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/addCampaignPromotionsStep/index.html.md)
-- [waitConfirmationProductImportStep](https://docs.medusajs.com/references/medusa-workflows/steps/waitConfirmationProductImportStep/index.html.md)
 - [updateProductsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateProductsStep/index.html.md)
-- [createPromotionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createPromotionsStep/index.html.md)
-- [addRulesToPromotionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/addRulesToPromotionsStep/index.html.md)
-- [deleteCampaignsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteCampaignsStep/index.html.md)
+- [waitConfirmationProductImportStep](https://docs.medusajs.com/references/medusa-workflows/steps/waitConfirmationProductImportStep/index.html.md)
+- [addCampaignPromotionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/addCampaignPromotionsStep/index.html.md)
 - [createCampaignsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createCampaignsStep/index.html.md)
+- [addRulesToPromotionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/addRulesToPromotionsStep/index.html.md)
+- [createPromotionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createPromotionsStep/index.html.md)
+- [deleteCampaignsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteCampaignsStep/index.html.md)
+- [removeRulesFromPromotionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/removeRulesFromPromotionsStep/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)
 - [updateCampaignsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateCampaignsStep/index.html.md)
-- [removeRulesFromPromotionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/removeRulesFromPromotionsStep/index.html.md)
-- [updatePromotionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updatePromotionsStep/index.html.md)
 - [updatePromotionRulesStep](https://docs.medusajs.com/references/medusa-workflows/steps/updatePromotionRulesStep/index.html.md)
-- [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)
+- [updatePromotionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updatePromotionsStep/index.html.md)
+- [createReservationsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createReservationsStep/index.html.md)
+- [deleteReservationsByLineItemsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteReservationsByLineItemsStep/index.html.md)
+- [deleteReservationsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteReservationsStep/index.html.md)
+- [updateReservationsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateReservationsStep/index.html.md)
 - [createReturnReasonsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createReturnReasonsStep/index.html.md)
 - [deleteReturnReasonStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteReturnReasonStep/index.html.md)
 - [updateReturnReasonsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateReturnReasonsStep/index.html.md)
+- [createRegionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createRegionsStep/index.html.md)
+- [listShippingOptionsForContextStep](https://docs.medusajs.com/references/medusa-workflows/steps/listShippingOptionsForContextStep/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)
+- [deleteStockLocationsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteStockLocationsStep/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)
+- [createStoresStep](https://docs.medusajs.com/references/medusa-workflows/steps/createStoresStep/index.html.md)
+- [deleteStoresStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteStoresStep/index.html.md)
+- [updateStoresStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateStoresStep/index.html.md)
 - [associateLocationsWithSalesChannelsStep](https://docs.medusajs.com/references/medusa-workflows/steps/associateLocationsWithSalesChannelsStep/index.html.md)
 - [associateProductsWithSalesChannelsStep](https://docs.medusajs.com/references/medusa-workflows/steps/associateProductsWithSalesChannelsStep/index.html.md)
-- [canDeleteSalesChannelsOrThrowStep](https://docs.medusajs.com/references/medusa-workflows/steps/canDeleteSalesChannelsOrThrowStep/index.html.md)
 - [createDefaultSalesChannelStep](https://docs.medusajs.com/references/medusa-workflows/steps/createDefaultSalesChannelStep/index.html.md)
 - [createSalesChannelsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createSalesChannelsStep/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)
-- [detachProductsFromSalesChannelsStep](https://docs.medusajs.com/references/medusa-workflows/steps/detachProductsFromSalesChannelsStep/index.html.md)
 - [detachLocationsFromSalesChannelsStep](https://docs.medusajs.com/references/medusa-workflows/steps/detachLocationsFromSalesChannelsStep/index.html.md)
+- [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)
-- [createStockLocations](https://docs.medusajs.com/references/medusa-workflows/steps/createStockLocations/index.html.md)
-- [deleteStockLocationsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteStockLocationsStep/index.html.md)
-- [listShippingOptionsForContextStep](https://docs.medusajs.com/references/medusa-workflows/steps/listShippingOptionsForContextStep/index.html.md)
-- [updateStockLocationsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateStockLocationsStep/index.html.md)
-- [deleteShippingProfilesStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteShippingProfilesStep/index.html.md)
-- [createTaxRateRulesStep](https://docs.medusajs.com/references/medusa-workflows/steps/createTaxRateRulesStep/index.html.md)
 - [createTaxRatesStep](https://docs.medusajs.com/references/medusa-workflows/steps/createTaxRatesStep/index.html.md)
-- [deleteTaxRateRulesStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteTaxRateRulesStep/index.html.md)
-- [deleteTaxRatesStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteTaxRatesStep/index.html.md)
+- [createTaxRateRulesStep](https://docs.medusajs.com/references/medusa-workflows/steps/createTaxRateRulesStep/index.html.md)
 - [createTaxRegionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createTaxRegionsStep/index.html.md)
+- [deleteTaxRatesStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteTaxRatesStep/index.html.md)
 - [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)
 - [updateTaxRatesStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateTaxRatesStep/index.html.md)
-- [deleteStoresStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteStoresStep/index.html.md)
-- [createStoresStep](https://docs.medusajs.com/references/medusa-workflows/steps/createStoresStep/index.html.md)
 - [updateTaxRegionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateTaxRegionsStep/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)
 - [updateUsersStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateUsersStep/index.html.md)
+- [deleteUsersStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteUsersStep/index.html.md)
+- [deleteShippingProfilesStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteShippingProfilesStep/index.html.md)
 
 
 # Medusa CLI Reference
@@ -30307,505 +30454,6 @@ npx medusa --help
 ***
 
 
-# db Commands - Medusa CLI Reference
-
-Commands starting with `db:` perform actions on the database.
-
-## db:setup
-
-Creates a database for the Medusa application with the specified name, if it doesn't exit. Then, it runs migrations and syncs links.
-
-It also updates your `.env` file with the database name.
-
-```bash
-npx medusa db:setup --db <name>
-```
-
-Use this command if you're setting up a Medusa project or database manually.
-
-### Options
-
-|Option|Description|Required|Default|
-|---|---|---|---|---|---|---|
-|\`--db \<name>\`|The database name.|Yes|-|
-|\`--skip-links\`|Skip syncing links to the database.|No|Links are synced by default.|
-|\`--execute-safe-links\`|Skip prompts when syncing links and execute only safe actions.|No|Prompts are shown for unsafe actions, by default.|
-|\`--execute-all-links\`|Skip prompts when syncing links and execute all (including unsafe) actions.|No|Prompts are shown for unsafe actions, by default.|
-|\`--no-interactive\`|Disable the command's prompts.|No|-|
-
-***
-
-## db:create
-
-Creates a database for the Medusa application with the specified name, if it doesn't exit.
-
-It also updates your `.env` file with the database name.
-
-```bash
-npx medusa db:create --db <name>
-```
-
-Use this command if you want to only create a database.
-
-### Options
-
-|Option|Description|Required|Default|
-|---|---|---|---|---|---|---|
-|\`--db \<name>\`|The database name.|Yes|-|
-|\`--no-interactive\`|Disable the command's prompts.|No|-|
-
-***
-
-## db:generate
-
-Generate a migration file for the latest changes in one or more modules.
-
-```bash
-npx medusa db:generate <module_names...>
-```
-
-### Arguments
-
-|Argument|Description|Required|
-|---|---|---|---|---|
-|\`module\_names\`|The name of one or more module (separated by spaces) to generate migrations for. For example, |Yes|
-
-***
-
-## db:migrate
-
-Run the latest migrations to reflect changes on the database, sync link definitions with the database, and run migration data scripts.
-
-```bash
-npx medusa db:migrate
-```
-
-Use this command if you've updated the Medusa packages, or you've created customizations and want to reflect them in the database.
-
-### Options
-
-|Option|Description|Required|Default|
-|---|---|---|---|---|---|---|
-|\`--skip-links\`|Skip syncing links to the database.|No|Links are synced by default.|
-|\`--skip-scripts\`|Skip running data migration scripts. This option is added starting from
-|No|Data migration scripts are run by default starting from
-|
-|\`--execute-safe-links\`|Skip prompts when syncing links and execute only safe actions.|No|Prompts are shown for unsafe actions, by default.|
-|\`--execute-all-links\`|Skip prompts when syncing links and execute all (including unsafe) actions.|No|Prompts are shown for unsafe actions, by default.|
-
-***
-
-## db:rollback
-
-Revert the last migrations ran on one or more modules.
-
-```bash
-npx medusa db:rollback <module_names...>
-```
-
-### Arguments
-
-|Argument|Description|Required|
-|---|---|---|---|---|
-|\`module\_names\`|The name of one or more module (separated by spaces) to rollback their migrations for. For example, |Yes|
-
-***
-
-## db:sync-links
-
-Sync the database with the link definitions in your application, including the definitions in Medusa's modules.
-
-```bash
-npx medusa db:sync-links
-```
-
-### Options
-
-|Option|Description|Required|Default|
-|---|---|---|---|---|---|---|
-|\`--execute-safe\`|Skip prompts when syncing links and execute only safe actions.|No|Prompts are shown for unsafe actions, by default.|
-|\`--execute-all\`|Skip prompts when syncing links and execute all (including unsafe) actions.|No|Prompts are shown for unsafe actions, by default.|
-
-
-# develop Command - Medusa CLI Reference
-
-Start Medusa application in development. This command watches files for any changes, then rebuilds the files and restarts the Medusa application.
-
-```bash
-npx medusa develop
-```
-
-## Options
-
-|Option|Description|Default|
-|---|---|---|---|---|
-|\`-H \<host>\`|Set host of the Medusa server.|\`localhost\`|
-|\`-p \<port>\`|Set port of the Medusa server.|\`9000\`|
-
-
-# new Command - Medusa CLI Reference
-
-Create a new Medusa application. Unlike the `create-medusa-app` CLI tool, this command provides more flexibility for experienced Medusa developers in creating and configuring their project.
-
-```bash
-medusa new [<dir_name> [<starter_url>]]
-```
-
-## Arguments
-
-|Argument|Description|Required|Default|
-|---|---|---|---|---|---|---|
-|\`dir\_name\`|The name of the directory to create the Medusa application in.|Yes|-|
-|\`starter\_url\`|The URL of the starter repository to create the project from.|No|\`https://github.com/medusajs/medusa-starter-default\`|
-
-## Options
-
-|Option|Description|
-|---|---|---|
-|\`-y\`|Skip all prompts, such as databaes prompts. A database might not be created if default PostgreSQL credentials don't work.|
-|\`--skip-db\`|Skip database creation.|
-|\`--skip-env\`|Skip populating |
-|\`--db-user \<user>\`|The database user to use for database setup.|
-|\`--db-database \<database>\`|The name of the database used for database setup.|
-|\`--db-pass \<password>\`|The database password to use for database setup.|
-|\`--db-port \<port>\`|The database port to use for database setup.|
-|\`--db-host \<host>\`|The database host to use for database setup.|
-
-
-# start Command - Medusa CLI Reference
-
-Start the Medusa application in production.
-
-```bash
-npx medusa start
-```
-
-## Options
-
-|Option|Description|Default|
-|---|---|---|---|---|
-|\`-H \<host>\`|Set host of the Medusa server.|\`localhost\`|
-|\`-p \<port>\`|Set port of the Medusa server.|\`9000\`|
-|\`--cluster \<number>\`|Start Medusa's Node.js server in |Cluster mode is disabled by default. If the option is passed but no number is passed, Medusa will try to consume all available CPU cores.|
-
-
-# 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.
-
-
-# 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.
-
-These commands are available starting from [Medusa v2.3.0](https://github.com/medusajs/medusa/releases/tag/v2.3.0).
-
-## plugin:publish
-
-Publish a plugin into the local packages registry. The command uses [Yalc](https://github.com/wclr/yalc) under the hood to publish the plugin to a local package registry. You can then install the plugin in a local Medusa project using the [plugin:add](#pluginadd) command.
-
-```bash
-npx medusa plugin:publish
-```
-
-***
-
-## plugin:add
-
-Install the specified plugins from the local package registry into a local Medusa application. Plugins can be added to the local package registry using the [plugin:publish](#pluginpublish) command.
-
-```bash
-npx medusa plugin:add [names...]
-```
-
-### Arguments
-
-|Argument|Description|Required|
-|---|---|---|---|---|
-|\`names\`|The names of one or more plugins to install from the local package registry. A plugin's name is as specified in its |Yes|
-
-***
-
-## plugin:develop
-
-Start a development server for a plugin. The command will watch for changes in the plugin's source code and automatically re-publish the changes into the local package registry.
-
-```bash
-npx medusa plugin:develop
-```
-
-***
-
-## plugin:db:generate
-
-Generate migrations for all modules in a plugin.
-
-```bash
-npx medusa plugin:db:generate
-```
-
-***
-
-## plugin:build
-
-Build a plugin before publishing it to NPM. The command will compile an output in the `.medusa/server` directory.
-
-```bash
-npx medusa plugin:build
-```
-
-
-# exec Command - Medusa CLI Reference
-
-Run a custom CLI script. Learn more about it in [this guide](https://docs.medusajs.com/docs/learn/fundamentals/custom-cli-scripts/index.html.md).
-
-```bash
-npx medusa exec [file] [args...]
-```
-
-## Arguments
-
-|Argument|Description|Required|
-|---|---|---|---|---|
-|\`file\`|The path to the TypeScript or JavaScript file holding the function to execute.|Yes|
-|\`args\`|A list of arguments to pass to the function. These arguments are passed in the |No|
-
-
-# telemetry Command - Medusa CLI Reference
-
-Enable or disable the collection of anonymous data usage. If no option is provided, the command enables the collection of anonymous data usage.
-
-```bash
-npx medusa telemetry
-```
-
-#### Options
-
-|Option|Description|
-|---|---|---|
-|\`--enable\`|Enable telemetry (default).|
-|\`--disable\`|Disable telemetry.|
-
-
-# user Command - Medusa CLI Reference
-
-Create a new admin user.
-
-```bash
-npx medusa user --email <email> [--password <password>]
-```
-
-## Options
-
-|Option|Description|Required|Default|
-|---|---|---|---|---|---|---|
-|\`-e \<email>\`|The user's email.|Yes|-|
-|\`-p \<password>\`|The user's password.|No|-|
-|\`-i \<id>\`|The user's ID.|No|An automatically generated ID.|
-|\`--invite\`|Whether to create an invite instead of a user. When using this option, you don't need to specify a password.
-If ran successfully, you'll receive the invite token in the output.|No|\`false\`|
-
-
-# Medusa CLI Reference
-
-The Medusa CLI tool provides commands that facilitate your development.
-
-### Prerequisites
-
-- [Node.js v20+](https://nodejs.org/en/download)
-- [Git CLI tool](https://git-scm.com/downloads)
-- [PostgreSQL](https://www.postgresql.org/download/)
-
-## Usage
-
-In your Medusa application's directory, you can use the Medusa CLI tool using NPX.
-
-For example:
-
-```bash
-npx medusa --help
-```
-
-***
-
-
-# db Commands - Medusa CLI Reference
-
-Commands starting with `db:` perform actions on the database.
-
-## db:setup
-
-Creates a database for the Medusa application with the specified name, if it doesn't exit. Then, it runs migrations and syncs links.
-
-It also updates your `.env` file with the database name.
-
-```bash
-npx medusa db:setup --db <name>
-```
-
-Use this command if you're setting up a Medusa project or database manually.
-
-### Options
-
-|Option|Description|Required|Default|
-|---|---|---|---|---|---|---|
-|\`--db \<name>\`|The database name.|Yes|-|
-|\`--skip-links\`|Skip syncing links to the database.|No|Links are synced by default.|
-|\`--execute-safe-links\`|Skip prompts when syncing links and execute only safe actions.|No|Prompts are shown for unsafe actions, by default.|
-|\`--execute-all-links\`|Skip prompts when syncing links and execute all (including unsafe) actions.|No|Prompts are shown for unsafe actions, by default.|
-|\`--no-interactive\`|Disable the command's prompts.|No|-|
-
-***
-
-## db:create
-
-Creates a database for the Medusa application with the specified name, if it doesn't exit.
-
-It also updates your `.env` file with the database name.
-
-```bash
-npx medusa db:create --db <name>
-```
-
-Use this command if you want to only create a database.
-
-### Options
-
-|Option|Description|Required|Default|
-|---|---|---|---|---|---|---|
-|\`--db \<name>\`|The database name.|Yes|-|
-|\`--no-interactive\`|Disable the command's prompts.|No|-|
-
-***
-
-## db:generate
-
-Generate a migration file for the latest changes in one or more modules.
-
-```bash
-npx medusa db:generate <module_names...>
-```
-
-### Arguments
-
-|Argument|Description|Required|
-|---|---|---|---|---|
-|\`module\_names\`|The name of one or more module (separated by spaces) to generate migrations for. For example, |Yes|
-
-***
-
-## db:migrate
-
-Run the latest migrations to reflect changes on the database, sync link definitions with the database, and run migration data scripts.
-
-```bash
-npx medusa db:migrate
-```
-
-Use this command if you've updated the Medusa packages, or you've created customizations and want to reflect them in the database.
-
-### Options
-
-|Option|Description|Required|Default|
-|---|---|---|---|---|---|---|
-|\`--skip-links\`|Skip syncing links to the database.|No|Links are synced by default.|
-|\`--skip-scripts\`|Skip running data migration scripts. This option is added starting from
-|No|Data migration scripts are run by default starting from
-|
-|\`--execute-safe-links\`|Skip prompts when syncing links and execute only safe actions.|No|Prompts are shown for unsafe actions, by default.|
-|\`--execute-all-links\`|Skip prompts when syncing links and execute all (including unsafe) actions.|No|Prompts are shown for unsafe actions, by default.|
-
-***
-
-## db:rollback
-
-Revert the last migrations ran on one or more modules.
-
-```bash
-npx medusa db:rollback <module_names...>
-```
-
-### Arguments
-
-|Argument|Description|Required|
-|---|---|---|---|---|
-|\`module\_names\`|The name of one or more module (separated by spaces) to rollback their migrations for. For example, |Yes|
-
-***
-
-## db:sync-links
-
-Sync the database with the link definitions in your application, including the definitions in Medusa's modules.
-
-```bash
-npx medusa db:sync-links
-```
-
-### Options
-
-|Option|Description|Required|Default|
-|---|---|---|---|---|---|---|
-|\`--execute-safe\`|Skip prompts when syncing links and execute only safe actions.|No|Prompts are shown for unsafe actions, by default.|
-|\`--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).
@@ -30929,6 +30577,126 @@ medusa new [<dir_name> [<starter_url>]]
 |\`--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.
+
+## db:setup
+
+Creates a database for the Medusa application with the specified name, if it doesn't exit. Then, it runs migrations and syncs links.
+
+It also updates your `.env` file with the database name.
+
+```bash
+npx medusa db:setup --db <name>
+```
+
+Use this command if you're setting up a Medusa project or database manually.
+
+### Options
+
+|Option|Description|Required|Default|
+|---|---|---|---|---|---|---|
+|\`--db \<name>\`|The database name.|Yes|-|
+|\`--skip-links\`|Skip syncing links to the database.|No|Links are synced by default.|
+|\`--execute-safe-links\`|Skip prompts when syncing links and execute only safe actions.|No|Prompts are shown for unsafe actions, by default.|
+|\`--execute-all-links\`|Skip prompts when syncing links and execute all (including unsafe) actions.|No|Prompts are shown for unsafe actions, by default.|
+|\`--no-interactive\`|Disable the command's prompts.|No|-|
+
+***
+
+## db:create
+
+Creates a database for the Medusa application with the specified name, if it doesn't exit.
+
+It also updates your `.env` file with the database name.
+
+```bash
+npx medusa db:create --db <name>
+```
+
+Use this command if you want to only create a database.
+
+### Options
+
+|Option|Description|Required|Default|
+|---|---|---|---|---|---|---|
+|\`--db \<name>\`|The database name.|Yes|-|
+|\`--no-interactive\`|Disable the command's prompts.|No|-|
+
+***
+
+## db:generate
+
+Generate a migration file for the latest changes in one or more modules.
+
+```bash
+npx medusa db:generate <module_names...>
+```
+
+### Arguments
+
+|Argument|Description|Required|
+|---|---|---|---|---|
+|\`module\_names\`|The name of one or more module (separated by spaces) to generate migrations for. For example, |Yes|
+
+***
+
+## db:migrate
+
+Run the latest migrations to reflect changes on the database, sync link definitions with the database, and run migration data scripts.
+
+```bash
+npx medusa db:migrate
+```
+
+Use this command if you've updated the Medusa packages, or you've created customizations and want to reflect them in the database.
+
+### Options
+
+|Option|Description|Required|Default|
+|---|---|---|---|---|---|---|
+|\`--skip-links\`|Skip syncing links to the database.|No|Links are synced by default.|
+|\`--skip-scripts\`|Skip running data migration scripts. This option is added starting from
+|No|Data migration scripts are run by default starting from
+|
+|\`--execute-safe-links\`|Skip prompts when syncing links and execute only safe actions.|No|Prompts are shown for unsafe actions, by default.|
+|\`--execute-all-links\`|Skip prompts when syncing links and execute all (including unsafe) actions.|No|Prompts are shown for unsafe actions, by default.|
+
+***
+
+## db:rollback
+
+Revert the last migrations ran on one or more modules.
+
+```bash
+npx medusa db:rollback <module_names...>
+```
+
+### Arguments
+
+|Argument|Description|Required|
+|---|---|---|---|---|
+|\`module\_names\`|The name of one or more module (separated by spaces) to rollback their migrations for. For example, |Yes|
+
+***
+
+## db:sync-links
+
+Sync the database with the link definitions in your application, including the definitions in Medusa's modules.
+
+```bash
+npx medusa db:sync-links
+```
+
+### Options
+
+|Option|Description|Required|Default|
+|---|---|---|---|---|---|---|
+|\`--execute-safe\`|Skip prompts when syncing links and execute only safe actions.|No|Prompts are shown for unsafe actions, by default.|
+|\`--execute-all\`|Skip prompts when syncing links and execute all (including unsafe) actions.|No|Prompts are shown for unsafe actions, by default.|
+
+
 # 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.
@@ -31009,6 +30777,201 @@ 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.|
+
+
+# start Command - Medusa CLI Reference
+
+Start the Medusa application in production.
+
+```bash
+npx medusa start
+```
+
+## Options
+
+|Option|Description|Default|
+|---|---|---|---|---|
+|\`-H \<host>\`|Set host of the Medusa server.|\`localhost\`|
+|\`-p \<port>\`|Set port of the Medusa server.|\`9000\`|
+|\`--cluster \<number>\`|Start Medusa's Node.js server in |Cluster mode is disabled by default. If the option is passed but no number is passed, Medusa will try to consume all available CPU cores.|
+
+
+# Medusa CLI Reference
+
+The Medusa CLI tool provides commands that facilitate your development.
+
+### Prerequisites
+
+- [Node.js v20+](https://nodejs.org/en/download)
+- [Git CLI tool](https://git-scm.com/downloads)
+- [PostgreSQL](https://www.postgresql.org/download/)
+
+## Usage
+
+In your Medusa application's directory, you can use the Medusa CLI tool using NPX.
+
+For example:
+
+```bash
+npx medusa --help
+```
+
+***
+
+
+# build Command - Medusa CLI Reference
+
+Create a standalone build of the Medusa application.
+
+This creates a build that:
+
+- Doesn't rely on the source TypeScript files.
+- Can be copied to a production server reliably.
+
+The build is outputted to a new `.medusa/server` directory.
+
+```bash
+npx medusa build
+```
+
+Refer to [this section](#run-built-medusa-application) for next steps.
+
+## Options
+
+|Option|Description|
+|---|---|---|
+|\`--admin-only\`|Whether to only build the admin to host it separately. If this option is not passed, the admin is built to the |
+
+***
+
+## Run Built Medusa Application
+
+After running the `build` command, use the following step to run the built Medusa application:
+
+- Change to the `.medusa/server` directory and install the dependencies:
+
+```bash npm2yarn
+cd .medusa/server && npm install
+```
+
+- When running the application locally, make sure to copy the `.env` file from the root project's directory. In production, use system environment variables instead.
+
+```bash npm2yarn
+cp .env .medusa/server/.env.production
+```
+
+- In the system environment variables, set `NODE_ENV` to `production`:
+
+```bash
+NODE_ENV=production
+```
+
+- Use the `start` command to run the application:
+
+```bash npm2yarn
+cd .medusa/server && npm run start
+```
+
+***
+
+## Build Medusa Admin
+
+By default, the Medusa Admin is built to the `.medusa/server/public/admin` directory.
+
+If you want a separate build to host the admin standalone, such as on Vercel, pass the `--admin-only` option as explained in the [Options](#options) section. This outputs the admin to the `.medusa/admin` directory instead.
+
+
+# exec Command - Medusa CLI Reference
+
+Run a custom CLI script. Learn more about it in [this guide](https://docs.medusajs.com/docs/learn/fundamentals/custom-cli-scripts/index.html.md).
+
+```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.
+
+These commands are available starting from [Medusa v2.3.0](https://github.com/medusajs/medusa/releases/tag/v2.3.0).
+
+## plugin:publish
+
+Publish a plugin into the local packages registry. The command uses [Yalc](https://github.com/wclr/yalc) under the hood to publish the plugin to a local package registry. You can then install the plugin in a local Medusa project using the [plugin:add](#pluginadd) command.
+
+```bash
+npx medusa plugin:publish
+```
+
+***
+
+## plugin:add
+
+Install the specified plugins from the local package registry into a local Medusa application. Plugins can be added to the local package registry using the [plugin:publish](#pluginpublish) command.
+
+```bash
+npx medusa plugin:add [names...]
+```
+
+### Arguments
+
+|Argument|Description|Required|
+|---|---|---|---|---|
+|\`names\`|The names of one or more plugins to install from the local package registry. A plugin's name is as specified in its |Yes|
+
+***
+
+## plugin:develop
+
+Start a development server for a plugin. The command will watch for changes in the plugin's source code and automatically re-publish the changes into the local package registry.
+
+```bash
+npx medusa plugin:develop
+```
+
+***
+
+## plugin:db:generate
+
+Generate migrations for all modules in a plugin.
+
+```bash
+npx medusa plugin:db:generate
+```
+
+***
+
+## plugin:build
+
+Build a plugin before publishing it to NPM. The command will compile an output in the `.medusa/server` directory.
+
+```bash
+npx medusa plugin:build
+```
+
+
 # start Command - Medusa CLI Reference
 
 Start the Medusa application in production.
@@ -31042,6 +31005,190 @@ npx medusa telemetry
 |\`--disable\`|Disable telemetry.|
 
 
+# user Command - Medusa CLI Reference
+
+Create a new admin user.
+
+```bash
+npx medusa user --email <email> [--password <password>]
+```
+
+## Options
+
+|Option|Description|Required|Default|
+|---|---|---|---|---|---|---|
+|\`-e \<email>\`|The user's email.|Yes|-|
+|\`-p \<password>\`|The user's password.|No|-|
+|\`-i \<id>\`|The user's ID.|No|An automatically generated ID.|
+|\`--invite\`|Whether to create an invite instead of a user. When using this option, you don't need to specify a password.
+If ran successfully, you'll receive the invite token in the output.|No|\`false\`|
+
+
+# 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.
+
+## db:setup
+
+Creates a database for the Medusa application with the specified name, if it doesn't exit. Then, it runs migrations and syncs links.
+
+It also updates your `.env` file with the database name.
+
+```bash
+npx medusa db:setup --db <name>
+```
+
+Use this command if you're setting up a Medusa project or database manually.
+
+### Options
+
+|Option|Description|Required|Default|
+|---|---|---|---|---|---|---|
+|\`--db \<name>\`|The database name.|Yes|-|
+|\`--skip-links\`|Skip syncing links to the database.|No|Links are synced by default.|
+|\`--execute-safe-links\`|Skip prompts when syncing links and execute only safe actions.|No|Prompts are shown for unsafe actions, by default.|
+|\`--execute-all-links\`|Skip prompts when syncing links and execute all (including unsafe) actions.|No|Prompts are shown for unsafe actions, by default.|
+|\`--no-interactive\`|Disable the command's prompts.|No|-|
+
+***
+
+## db:create
+
+Creates a database for the Medusa application with the specified name, if it doesn't exit.
+
+It also updates your `.env` file with the database name.
+
+```bash
+npx medusa db:create --db <name>
+```
+
+Use this command if you want to only create a database.
+
+### Options
+
+|Option|Description|Required|Default|
+|---|---|---|---|---|---|---|
+|\`--db \<name>\`|The database name.|Yes|-|
+|\`--no-interactive\`|Disable the command's prompts.|No|-|
+
+***
+
+## db:generate
+
+Generate a migration file for the latest changes in one or more modules.
+
+```bash
+npx medusa db:generate <module_names...>
+```
+
+### Arguments
+
+|Argument|Description|Required|
+|---|---|---|---|---|
+|\`module\_names\`|The name of one or more module (separated by spaces) to generate migrations for. For example, |Yes|
+
+***
+
+## db:migrate
+
+Run the latest migrations to reflect changes on the database, sync link definitions with the database, and run migration data scripts.
+
+```bash
+npx medusa db:migrate
+```
+
+Use this command if you've updated the Medusa packages, or you've created customizations and want to reflect them in the database.
+
+### Options
+
+|Option|Description|Required|Default|
+|---|---|---|---|---|---|---|
+|\`--skip-links\`|Skip syncing links to the database.|No|Links are synced by default.|
+|\`--skip-scripts\`|Skip running data migration scripts. This option is added starting from
+|No|Data migration scripts are run by default starting from
+|
+|\`--execute-safe-links\`|Skip prompts when syncing links and execute only safe actions.|No|Prompts are shown for unsafe actions, by default.|
+|\`--execute-all-links\`|Skip prompts when syncing links and execute all (including unsafe) actions.|No|Prompts are shown for unsafe actions, by default.|
+
+***
+
+## db:rollback
+
+Revert the last migrations ran on one or more modules.
+
+```bash
+npx medusa db:rollback <module_names...>
+```
+
+### Arguments
+
+|Argument|Description|Required|
+|---|---|---|---|---|
+|\`module\_names\`|The name of one or more module (separated by spaces) to rollback their migrations for. For example, |Yes|
+
+***
+
+## db:sync-links
+
+Sync the database with the link definitions in your application, including the definitions in Medusa's modules.
+
+```bash
+npx medusa db:sync-links
+```
+
+### Options
+
+|Option|Description|Required|Default|
+|---|---|---|---|---|---|---|
+|\`--execute-safe\`|Skip prompts when syncing links and execute only safe actions.|No|Prompts are shown for unsafe actions, by default.|
+|\`--execute-all\`|Skip prompts when syncing links and execute all (including unsafe) actions.|No|Prompts are shown for unsafe actions, by default.|
+
+
 # Medusa JS SDK
 
 In this documentation, you'll learn how to install and use Medusa's JS SDK.
@@ -40812,6 +40959,1797 @@ If you are new to Medusa, check out the [main documentation](https://docs.medusa
 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.
+
+Medusa Cloud provides a beta Store Credits feature that facilitates building a loyalty point system. [Get in touch](https://medusajs.com/contact) for early access.
+
+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 management capabilities related to carts, orders, promotions, and more.
+
+A loyalty point system allows customers to earn points for purchases, which can be redeemed for discounts or rewards. In this tutorial, you'll learn how to customize the Medusa application to implement a loyalty points system.
+
+You can follow this tutorial whether you're new to Medusa or an advanced Medusa developer.
+
+## Summary
+
+By following this tutorial, you will learn how to:
+
+- Install and set up Medusa.
+- Define models to store loyalty points and the logic to manage them.
+- Build flows that allow customers to earn and redeem points during checkout.
+  - Points are redeemed through dynamic promotions specific to the customer.
+- Customize the cart completion flow to validate applied loyalty points.
+
+![Diagram illustrating redeem loyalty points flow](https://res.cloudinary.com/dza7lstvk/image/upload/v1744126213/Medusa%20Resources/redeem-points-flow_kzgkux.jpg)
+
+- [Loyalty Points Repository](https://github.com/medusajs/examples/tree/main/loyalty-points): Find the full code for this guide in this repository.
+- [OpenApi Specs for Postman](https://res.cloudinary.com/dza7lstvk/raw/upload/v1744212595/OpenApi/Loyalty-Points_jwi5e9.yaml): Import this OpenApi Specs file into tools like Postman.
+
+***
+
+## Step 1: Install a Medusa Application
+
+### Prerequisites
+
+- [Node.js v20+](https://nodejs.org/en/download)
+- [Git CLI tool](https://git-scm.com/downloads)
+- [PostgreSQL](https://www.postgresql.org/download/)
+
+Start by installing the Medusa application on your machine with the following command:
+
+```bash
+npx create-medusa-app@latest
+```
+
+You'll first be asked for the project's name. Then, when asked whether you want to install the [Next.js Starter Storefront](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/nextjs-starter/index.html.md), choose Yes.
+
+Afterward, 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. Afterward, you can log in with the new user and explore the dashboard.
+
+Check out the [troubleshooting guides](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/troubleshooting/create-medusa-app-errors/index.html.md) for help.
+
+***
+
+## Step 2: Create Loyalty Module
+
+In Medusa, you can build custom features in a [module](https://docs.medusajs.com/docs/learn/fundamentals/modules/index.html.md). A module is a reusable package with functionalities related to a single feature or domain. Medusa integrates the module into your application without implications or side effects on your setup.
+
+In the module, you define the data models necessary for a feature and the logic to manage these data models. Later, you can build commerce flows around your module.
+
+In this step, you'll build a Loyalty Module that defines the necessary data models to store and manage loyalty points for customers.
+
+Refer to the [Modules documentation](https://docs.medusajs.com/docs/learn/fundamentals/modules/index.html.md) to learn more.
+
+### Create Module Directory
+
+Modules are created under the `src/modules` directory of your Medusa application. So, create the directory `src/modules/loyalty`.
+
+### Create Data Models
+
+A data model represents a table in the database. You create data models using Medusa's Data Model Language (DML). It simplifies defining a table's columns, relations, and indexes with straightforward methods and configurations.
+
+Refer to the [Data Models documentation](https://docs.medusajs.com/docs/learn/fundamentals/modules#1-create-data-model/index.html.md) to learn more.
+
+For the Loyalty Module, you need to define a `LoyaltyPoint` data model that represents a customer's loyalty points. So, create the file `src/modules/loyalty/models/loyalty-point.ts` with the following content:
+
+```ts title="src/modules/loyalty/models/loyalty-point.ts" highlights={dmlHighlights}
+import { model } from "@medusajs/framework/utils"
+
+const LoyaltyPoint = model.define("loyalty_point", {
+  id: model.id().primaryKey(),
+  points: model.number().default(0),
+  customer_id: model.text().unique("IDX_LOYALTY_CUSTOMER_ID"), 
+})
+
+export default LoyaltyPoint
+```
+
+You define the `LoyaltyPoint` data model using the `model.define` method of the DML. It accepts the data model's table name as a first parameter, and the model's schema object as a second parameter.
+
+The `LoyaltyPoint` data model has the following properties:
+
+- `id`: A unique ID for the loyalty points.
+- `points`: The number of loyalty points a customer has.
+- `customer_id`: The ID of the customer who owns the loyalty points. This property has a unique index to ensure that each customer has only one record in the `loyalty_point` table.
+
+Learn more about defining data model properties in the [Property Types documentation](https://docs.medusajs.com/docs/learn/fundamentals/data-models/properties/index.html.md).
+
+### Create Module's Service
+
+You now have the necessary data model in the Loyalty Module, but you'll need to manage its records. You do this by creating a service in the module.
+
+A service is a TypeScript or JavaScript class that the module exports. In the service's methods, you can connect to the database, allowing you to manage your data models, or connect to a third-party service, which is useful if you're integrating with external services.
+
+Refer to the [Module Service documentation](https://docs.medusajs.com/docs/learn/fundamentals/modules#2-create-service/index.html.md) to learn more.
+
+To create the Loyalty Module's service, create the file `src/modules/loyalty/service.ts` with the following content:
+
+```ts title="src/modules/loyalty/service.ts"
+import { MedusaError, MedusaService } from "@medusajs/framework/utils"
+import LoyaltyPoint from "./models/loyalty-point"
+import { InferTypeOf } from "@medusajs/framework/types"
+
+type LoyaltyPoint = InferTypeOf<typeof LoyaltyPoint>
+
+class LoyaltyModuleService extends MedusaService({
+  LoyaltyPoint,
+}) {
+  // TODO add methods
+}
+
+export default LoyaltyModuleService
+```
+
+The `LoyaltyModuleService` extends `MedusaService` from the Modules SDK which generates a class with data-management methods for your module's data models. This saves you time on implementing Create, Read, Update, and Delete (CRUD) methods.
+
+So, the `LoyaltyModuleService` class now has methods like `createLoyaltyPoints` and `retrieveLoyaltyPoint`.
+
+Find all methods generated by the `MedusaService` in [the Service Factory reference](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/service-factory-reference/index.html.md).
+
+#### Add Methods to the Service
+
+Aside from the basic CRUD methods, you need to add methods that handle custom functionalities related to loyalty points.
+
+First, you need a method that adds loyalty points for a customer. Add the following method to the `LoyaltyModuleService`:
+
+```ts title="src/modules/loyalty/service.ts"
+class LoyaltyModuleService extends MedusaService({
+  LoyaltyPoint,
+}) {
+  async addPoints(customerId: string, points: number): Promise<LoyaltyPoint> {
+    const existingPoints = await this.listLoyaltyPoints({
+      customer_id: customerId,
+    })
+
+    if (existingPoints.length > 0) {
+      return await this.updateLoyaltyPoints({
+        id: existingPoints[0].id,
+        points: existingPoints[0].points + points,
+      })
+    }
+
+    return await this.createLoyaltyPoints({
+      customer_id: customerId,
+      points,
+    })
+  }
+}
+```
+
+You add an `addPoints` method that accepts two parameters: the ID of the customer and the points to add.
+
+In the method, you retrieve the customer's existing loyalty points using the `listLoyaltyPoints` method, which is automatically generated by the `MedusaService`. If the customer has existing points, you update them with the new points using the `updateLoyaltyPoints` method.
+
+Otherwise, if the customer doesn't have existing loyalty points, you create a new record with the `createLoyaltyPoints` method.
+
+The next method you'll add deducts points from the customer's loyalty points, which is useful when the customer redeems points. Add the following method to the `LoyaltyModuleService`:
+
+```ts title="src/modules/loyalty/service.ts"
+class LoyaltyModuleService extends MedusaService({
+  LoyaltyPoint,
+}) {
+  // ...
+  async deductPoints(customerId: string, points: number): Promise<LoyaltyPoint> {
+    const existingPoints = await this.listLoyaltyPoints({
+      customer_id: customerId,
+    })
+
+    if (existingPoints.length === 0 || existingPoints[0].points < points) {
+      throw new MedusaError(
+        MedusaError.Types.NOT_ALLOWED,
+        "Insufficient loyalty points"
+      )
+    }
+
+    return await this.updateLoyaltyPoints({
+      id: existingPoints[0].id,
+      points: existingPoints[0].points - points,
+    })
+  }
+}
+```
+
+The `deductPoints` method accepts the customer ID and the points to deduct.
+
+In the method, you retrieve the customer's existing loyalty points using the `listLoyaltyPoints` method. If the customer doesn't have existing points or if the points to deduct are greater than the existing points, you throw an error.
+
+Otherwise, you update the customer's loyalty points with the new value using the `updateLoyaltyPoints` method, which is automatically generated by `MedusaService`.
+
+Next, you'll add the method that retrieves the points of a customer. Add the following method to the `LoyaltyModuleService`:
+
+```ts title="src/modules/loyalty/service.ts"
+class LoyaltyModuleService extends MedusaService({
+  LoyaltyPoint,
+}) {
+  // ...
+  async getPoints(customerId: string): Promise<number> {
+    const points = await this.listLoyaltyPoints({
+      customer_id: customerId,
+    })
+
+    return points[0]?.points || 0
+  }
+}
+```
+
+The `getPoints` method accepts the customer ID and retrieves the customer's loyalty points using the `listLoyaltyPoints` method. If the customer has no points, it returns `0`.
+
+#### Add Method to Map Points to Discount
+
+Finally, you'll add a method that implements the logic of mapping loyalty points to a discount amount. This is useful when the customer wants to redeem their points during checkout.
+
+The mapping logic may differ for each use case. For example, you may need to use a third-party service to map the loyalty points discount amount, or use some custom calculation.
+
+To simplify the logic in this tutorial, you'll use a simple calculation that maps 1 point to 1 currency unit. For example, `100` points = `$100` discount.
+
+Add the following method to the `LoyaltyModuleService`:
+
+```ts title="src/modules/loyalty/service.ts"
+class LoyaltyModuleService extends MedusaService({
+  LoyaltyPoint,
+}) {
+  // ...
+  async calculatePointsFromAmount(amount: number): Promise<number> {
+    // Convert amount to points using a standard conversion rate
+    // For example, $1 = 1 point
+    // Round down to nearest whole point
+    const points = Math.floor(amount)
+
+    if (points < 0) {
+      throw new MedusaError(
+        MedusaError.Types.INVALID_DATA,
+        "Amount cannot be negative"
+      )
+    }
+
+    return points
+  }
+}
+```
+
+The `calculatePointsFromAmount` method accepts the amount and converts it to the nearest whole number of points. If the amount is negative, it throws an error.
+
+You'll use this method later to calculate the amount discounted when a customer redeems their loyalty points.
+
+### Export Module Definition
+
+The final piece to a module is its definition, which you export in an `index.ts` file at its root directory. This definition tells Medusa the name of the module and its service.
+
+So, create the file `src/modules/loyalty/index.ts` with the following content:
+
+```ts title="src/modules/loyalty/index.ts"
+import { Module } from "@medusajs/framework/utils"
+import LoyaltyModuleService from "./service"
+
+export const LOYALTY_MODULE = "loyalty"
+
+export default Module(LOYALTY_MODULE, {
+  service: LoyaltyModuleService,
+})
+```
+
+You use the `Module` function from the Modules SDK to create the module's definition. It accepts two parameters:
+
+1. The module's name, which is `loyalty`.
+2. An object with a required property `service` indicating the module's service.
+
+You also export the module's name as `LOYALTY_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/loyalty",
+    },
+  ],
+})
+```
+
+Each object in the `modules` array has a `resolve` property, whose value is either a path to the module's directory, or an `npm` package’s name.
+
+### Generate Migrations
+
+Since data models represent tables in the database, you define how they're created in the database with migrations. A migration is a TypeScript or JavaScript file that defines database changes made by a module.
+
+Refer to the [Migrations documentation](https://docs.medusajs.com/docs/learn/fundamentals/modules#5-generate-migrations/index.html.md) to learn more.
+
+Medusa's CLI tool can generate the migrations for you. To generate a migration for the Loyalty Module, run the following command in your Medusa application's directory:
+
+```bash
+npx medusa db:generate loyalty
+```
+
+The `db:generate` command of the Medusa CLI accepts the name of the module to generate the migration for. You'll now have a `migrations` directory under `src/modules/loyalty` that holds the generated migration.
+
+Then, to reflect these migrations on the database, run the following command:
+
+```bash
+npx medusa db:migrate
+```
+
+The table for the `LoyaltyPoint` data model is now created in the database.
+
+***
+
+## Step 3: Change Loyalty Points Flow
+
+Now that you have a module that stores and manages loyalty points in the database, you'll start building flows around it that allow customers to earn and redeem points.
+
+The first flow you'll build will either add points to a customer's loyalty points or deduct them based on a purchased order. If the customer hasn't redeemed points, the points are added to their loyalty points. Otherwise, the points are deducted from their loyalty points.
+
+To build custom commerce features in Medusa, you create a [workflow](https://docs.medusajs.com/docs/learn/fundamentals/workflows/index.html.md). A workflow is a series of queries and actions, called steps, that complete a task. You construct a workflow like you construct a function, but it's a special function that allows you to track its executions' progress, define roll-back logic, and configure other advanced features. Then, you execute the workflow from other customizations, such as in an endpoint.
+
+In this section, you'll build the workflow that adds or deducts loyalty points for an order's customer. Later, you'll execute this workflow when an order is placed.
+
+Learn more about workflows in the [Workflows documentation](https://docs.medusajs.com/docs/learn/fundamentals/workflows/index.html.md).
+
+The workflow will have the following steps:
+
+- [useQueryGraphStep](https://docs.medusajs.com/references/helper-steps/useQueryGraphStep/index.html.md): Retrieve the order's details.
+- [validateCustomerExistsStep](#validateCustomerExistsStep): Validate that the customer is registered.
+- [getCartLoyaltyPromoStep](#getCartLoyaltyPromoStep): Retrieve the cart's loyalty promotion.
+
+Medusa provides the `useQueryGraphStep` and `updatePromotionsStep` in its `@medusajs/medusa/core-flows` package. So, you'll only implement the other steps.
+
+### validateCustomerExistsStep
+
+In the workflow, you first need to validate that the customer is registered. Only registered customers can earn and redeem loyalty points.
+
+To do this, create the file `src/workflows/steps/validate-customer-exists.ts` with the following content:
+
+```ts title="src/workflows/steps/validate-customer-exists.ts"
+import { CustomerDTO } from "@medusajs/framework/types"
+import { createStep } from "@medusajs/framework/workflows-sdk"
+import { MedusaError } from "@medusajs/framework/utils"
+
+export type ValidateCustomerExistsStepInput = {
+  customer: CustomerDTO | null | undefined
+}
+
+export const validateCustomerExistsStep = createStep(
+  "validate-customer-exists",
+  async ({ customer }: ValidateCustomerExistsStepInput) => {
+    if (!customer) {
+      throw new MedusaError(
+        MedusaError.Types.INVALID_DATA, 
+        "Customer not found"
+      )
+    }
+
+    if (!customer.has_account) {
+      throw new MedusaError(
+        MedusaError.Types.INVALID_DATA, 
+        "Customer must have an account to earn or manage points"
+      )
+    }
+  }
+)
+```
+
+You create a step with `createStep` from the Workflows SDK. It accepts two parameters:
+
+1. The step's unique name, which is `validate-customer-exists`.
+2. An async function that receives two parameters:
+   - The step's input, which is in this case an object with the customer's details.
+   - 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 validate that the customer is defined and that it's registered based on its `has_account` property. Otherwise, you throw an error.
+
+### getCartLoyaltyPromoStep
+
+Next, you'll need to retrieve the loyalty promotion applied on the cart, if there's any. This is useful to determine whether the customer has redeemed points.
+
+Before you create a step, you'll create a utility function that the step uses to retrieve the loyalty promotion of a cart. You'll create it as a separate utility function to use it later in other customizations.
+
+Create the file `src/utils/promo.ts` with the following content:
+
+```ts title="src/utils/promo.ts"
+import { PromotionDTO, CustomerDTO, CartDTO } from "@medusajs/framework/types"
+
+export type CartData = CartDTO & {
+  promotions?: PromotionDTO[]
+  customer?: CustomerDTO
+  metadata: {
+    loyalty_promo_id?: string
+  }
+}
+
+export function getCartLoyaltyPromotion(
+  cart: CartData
+): PromotionDTO | undefined {
+  if (!cart?.metadata?.loyalty_promo_id) {
+    return
+  }
+
+  return cart.promotions?.find(
+    (promotion) => promotion.id === cart.metadata.loyalty_promo_id
+  )
+}
+```
+
+You create a `getCartLoyaltyPromotion` function that accepts the cart's details as an input and returns the loyalty promotion if it exists. You retrieve the loyalty promotion if its ID is stored in the cart's `metadata.loyalty_promo_id` property.
+
+You can now create the step that uses this utility to retrieve a carts loyalty points promotion. To create the step, create the file `src/workflows/steps/get-cart-loyalty-promo.ts` with the following content:
+
+```ts title="src/workflows/steps/get-cart-loyalty-promo.ts"
+import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk"
+import { CartData, getCartLoyaltyPromotion } from "../../utils/promo"
+import { MedusaError } from "@medusajs/framework/utils"
+
+type GetCartLoyaltyPromoStepInput = {
+  cart: CartData,
+  throwErrorOn?: "found" | "not-found"
+}
+
+export const getCartLoyaltyPromoStep = createStep(
+  "get-cart-loyalty-promo",
+  async ({ cart, throwErrorOn }: GetCartLoyaltyPromoStepInput) => {
+    const loyaltyPromo = getCartLoyaltyPromotion(cart)
+
+    if (throwErrorOn === "found" && loyaltyPromo) {
+      throw new MedusaError(
+        MedusaError.Types.INVALID_DATA,
+        "Loyalty promotion already applied to cart"
+      )
+    } else if (throwErrorOn === "not-found" && !loyaltyPromo) {
+      throw new MedusaError(
+        MedusaError.Types.INVALID_DATA,
+        "No loyalty promotion found on cart"
+      )
+    }
+
+    return new StepResponse(loyaltyPromo)
+  }
+)
+```
+
+You create a step that accepts an object having the following properties:
+
+- `cart`: The cart's details.
+- `throwErrorOn`: An optional property that indicates whether to throw an error if the loyalty promotion is found or not found.
+
+The `throwErrorOn` property is useful to make the step reusable in different scenarios, allowing you to use it in later workflows.
+
+In the step, you call the `getCartLoyaltyPromotion` utility to retrieve the loyalty promotion. If the `throwErrorOn` property is set to `found` and the loyalty promotion is found, you throw an error.
+
+Otherwise, if the `throwErrorOn` property is set to `not-found` and the loyalty promotion is not found, you throw an error.
+
+To return data from a step, you return an instance of `StepResponse` from the Workflows SDK. It accepts as a parameter the data to return, which is the loyalty promotion in this case.
+
+### deductPurchasePointsStep
+
+If the order's cart has a loyalty promotion, you need to deduct points from the customer's loyalty points. To do this, create the file `src/workflows/steps/deduct-purchase-points.ts` with the following content:
+
+```ts title="src/workflows/steps/deduct-purchase-points.ts" highlights={deductStepHighlights} collapsibleLines="1-7" expandButtonLabel="Show Imports"
+import { 
+  createStep,
+  StepResponse, 
+} from "@medusajs/framework/workflows-sdk"
+import { LOYALTY_MODULE } from "../../modules/loyalty"
+import LoyaltyModuleService from "../../modules/loyalty/service"
+
+type DeductPurchasePointsInput = {
+  customer_id: string
+  amount: number
+}
+
+export const deductPurchasePointsStep = createStep(
+  "deduct-purchase-points",
+  async ({ 
+    customer_id, amount,
+  }: DeductPurchasePointsInput, { container }) => {
+    const loyaltyModuleService: LoyaltyModuleService = container.resolve(
+      LOYALTY_MODULE
+    )
+
+    const pointsToDeduct = await loyaltyModuleService.calculatePointsFromAmount(
+      amount
+    )
+
+    const result = await loyaltyModuleService.deductPoints(
+      customer_id,
+      pointsToDeduct
+    )
+
+    return new StepResponse(result, {
+      customer_id,
+      points: pointsToDeduct,
+    })
+  },
+  async (data, { container }) => {
+    if (!data) {
+      return
+    }
+
+    const loyaltyModuleService: LoyaltyModuleService = container.resolve(
+      LOYALTY_MODULE
+    )
+
+    // Restore points in case of failure
+    await loyaltyModuleService.addPoints(
+      data.customer_id,
+      data.points
+    )
+  }
+)
+```
+
+You create a step that accepts an object having the following properties:
+
+- `customer_id`: The ID of the customer to deduct points from.
+- `amount`: The promotion's amount, which will be used to calculate the points to deduct.
+
+In the step, you resolve the Loyalty Module's service from the Medusa container. Then, you use the `calculatePointsFromAmount` method to calculate the points to deduct from the promotion's amount.
+
+After that, you call the `deductPoints` method to deduct the points from the customer's loyalty points.
+
+Finally, you return a `StepResponse` with the result of the `deductPoints`.
+
+#### Compensation Function
+
+This step has a compensation function, which is passed as a third parameter to the `createStep` function.
+
+The compensation function undoes the actions performed in a step. Then, if an error occurs during the workflow's execution, the compensation functions of executed steps are called to roll back the changes. This mechanism ensures data consistency in your application, especially as you integrate external systems.
+
+The compensation function accepts two parameters:
+
+1. Data passed from the step function to the compensation function. The data is passed as a second parameter of the returned `StepResponse` instance.
+2. An object that has properties including the [Medusa container](https://docs.medusajs.com/docs/learn/fundamentals/medusa-container/index.html.md).
+
+In the compensation function, you resolve the Loyalty Module's service from the Medusa container. Then, you call the `addPoints` method to restore the points deducted from the customer's loyalty points if an error occurs.
+
+### addPurchaseAsPointsStep
+
+The last step you'll create adds points to the customer's loyalty points. You'll use this step if the customer didn't redeem points during checkout.
+
+To create the step, create the file `src/workflows/steps/add-purchase-as-points.ts` with the following content:
+
+```ts title="src/workflows/steps/add-purchase-as-points.ts" highlights={addPointsHighlights} collapsibleLines="1-7" expandButtonLabel="Show Imports"
+import {
+  createStep,
+  StepResponse,
+} from "@medusajs/framework/workflows-sdk"
+import { LOYALTY_MODULE } from "../../modules/loyalty"
+import LoyaltyModuleService from "../../modules/loyalty/service"
+
+type StepInput = {
+  customer_id: string
+  amount: number
+}
+
+export const addPurchaseAsPointsStep = createStep(
+  "add-purchase-as-points",
+  async (input: StepInput, { container }) => {
+    const loyaltyModuleService: LoyaltyModuleService = container.resolve(
+      LOYALTY_MODULE
+    )
+
+    const pointsToAdd = await loyaltyModuleService.calculatePointsFromAmount(
+      input.amount
+    )
+
+    const result = await loyaltyModuleService.addPoints(
+      input.customer_id,
+      pointsToAdd
+    )
+
+    return new StepResponse(result, {
+      customer_id: input.customer_id,
+      points: pointsToAdd,
+    })
+  },
+  async (data, { container }) => {
+    if (!data) {
+      return
+    }
+
+    const loyaltyModuleService: LoyaltyModuleService = container.resolve(
+      LOYALTY_MODULE
+    )
+
+    await loyaltyModuleService.deductPoints(
+      data.customer_id,
+      data.points
+    )
+  }
+)
+```
+
+You create a step that accepts an object having the following properties:
+
+- `customer_id`: The ID of the customer to add points to.
+- `amount`: The order's amount, which will be used to calculate the points to add.
+
+In the step, you resolve the Loyalty Module's service from the Medusa container. Then, you use the `calculatePointsFromAmount` method to calculate the points to add from the order's amount.
+
+After that, you call the `addPoints` method to add the points to the customer's loyalty points.
+
+Finally, you return a `StepResponse` with the result of the `addPoints`.
+
+You also pass to the compensation function the customer's ID and the points added. In the compensation function, you deduct the points if an error occurs.
+
+### Add Utility Functions
+
+Before you create the workflow, you need a utility function that checks whether an order's cart has a loyalty promotion. This is useful to determine whether the customer redeemed points during checkout, allowing you to decide which steps to execute.
+
+To add the utility function, add the following to `src/utils/promo.ts`:
+
+```ts title="src/utils/promo.ts"
+import { OrderDTO } from "@medusajs/framework/types"
+
+export type OrderData = OrderDTO & {
+  promotion?: PromotionDTO[]
+  customer?: CustomerDTO
+  cart?: CartData
+}
+
+export const CUSTOMER_ID_PROMOTION_RULE_ATTRIBUTE = "customer_id"
+
+export function orderHasLoyaltyPromotion(order: OrderData): boolean {
+  const loyaltyPromotion = getCartLoyaltyPromotion(
+    order.cart as unknown as CartData
+  )
+
+  return loyaltyPromotion?.rules?.some((rule) => {
+    return rule?.attribute === CUSTOMER_ID_PROMOTION_RULE_ATTRIBUTE && (
+      rule?.values?.some((value) => value.value === order.customer?.id) || false
+    )
+  }) || false
+}
+```
+
+You first define an `OrderData` type that extends the `OrderDTO` type. This type has the order's details, including the cart, customer, and promotions details.
+
+Then, you define a constant `CUSTOMER_ID_PROMOTION_RULE_ATTRIBUTE` that represents the attribute used in the promotion rule to check whether the customer ID is valid.
+
+Finally, you create the `orderHasLoyaltyPromotion` function that accepts an order's details and checks whether it has a loyalty promotion. It returns `true` if:
+
+- The order's cart has a loyalty promotion. You use the `getCartLoyaltyPromotion` utility to try to retrieve the loyalty promotion.
+- The promotion's rules include the `customer_id` attribute and its value matches the order's customer ID.
+  - When you create the promotion for the cart later, you'll see how to set this rule.
+
+You'll use this utility in the workflow next.
+
+### Create the Workflow
+
+Now that you have all the steps, you can create the workflow that uses them.
+
+To create the workflow, create the file `src/workflows/handle-order-points.ts` with the following content:
+
+```ts title="src/workflows/handle-order-points.ts" highlights={handleOrderPointsHighlights} collapsibleLines="1-9" expandButtonLabel="Show Imports"
+import { createWorkflow, when } from "@medusajs/framework/workflows-sdk"
+import { updatePromotionsStep, useQueryGraphStep } from "@medusajs/medusa/core-flows"
+import { validateCustomerExistsStep, ValidateCustomerExistsStepInput } from "./steps/validate-customer-exists"
+import { deductPurchasePointsStep } from "./steps/deduct-purchase-points"
+import { addPurchaseAsPointsStep } from "./steps/add-purchase-as-points"
+import { OrderData, CartData } from "../utils/promo"
+import { orderHasLoyaltyPromotion } from "../utils/promo"
+import { getCartLoyaltyPromoStep } from "./steps/get-cart-loyalty-promo"
+
+type WorkflowInput = {
+  order_id: string
+}
+
+export const handleOrderPointsWorkflow = createWorkflow(
+  "handle-order-points",
+  ({ order_id }: WorkflowInput) => {
+    // @ts-ignore
+    const { data: orders } = useQueryGraphStep({
+      entity: "order",
+      fields: [
+        "id", 
+        "customer.*", 
+        "total", 
+        "cart.*",
+        "cart.promotions.*",
+        "cart.promotions.rules.*",
+        "cart.promotions.rules.values.*",
+        "cart.promotions.application_method.*",
+      ],
+      filters: {
+        id: order_id,
+      },
+      options: {
+        throwIfKeyNotFound: true,
+      },
+    })
+
+    validateCustomerExistsStep({
+      customer: orders[0].customer,
+    } as ValidateCustomerExistsStepInput)
+
+    const loyaltyPointsPromotion = getCartLoyaltyPromoStep({
+      cart: orders[0].cart as unknown as CartData,
+    })
+
+    when(orders, (orders) => 
+      orderHasLoyaltyPromotion(orders[0] as unknown as OrderData) && 
+      loyaltyPointsPromotion !== undefined
+    )
+    .then(() => {
+      deductPurchasePointsStep({
+        customer_id: orders[0].customer!.id,
+        amount: loyaltyPointsPromotion.application_method!.value as number,
+      })
+
+      updatePromotionsStep([
+        {
+          id: loyaltyPointsPromotion.id,
+          status: "inactive",
+        },
+      ])
+    })
+
+
+    when(
+      orders, 
+      (order) => !orderHasLoyaltyPromotion(order[0] as unknown as OrderData)
+    )
+    .then(() => {
+      addPurchaseAsPointsStep({
+        customer_id: orders[0].customer!.id,
+        amount: orders[0].total,
+      })
+    })
+  }
+)
+```
+
+You create a workflow using `createWorkflow` from the Workflows SDK. It accepts the workflow's unique name as a first parameter.
+
+It accepts as a second parameter a constructor function, which is the workflow's implementation. The function can accept input, which in this case is an object with the order's ID.
+
+In the workflow's constructor function, you:
+
+- Use `useQueryGraphStep` to retrieve the order's details. You pass the order's ID as a filter to retrieve the order.
+  - This step uses [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), which is a tool that retrieves data across modules.
+- Validate that the customer is registered using the `validateCustomerExistsStep`.
+- Retrieve the cart's loyalty promotion using the `getCartLoyaltyPromoStep`.
+- Use `when` to check whether the order's cart has a loyalty promotion.
+  - Since you can't perform data manipulation in a workflow's constructor function, `when` allows you to perform steps if a condition is satisfied.
+  - You pass as a first parameter the object to perform the condition on, which is the order in this case. In the second parameter, you pass a function that returns a boolean value, indicating whether the condition is satisfied.
+  - To specify the steps to perform if a condition is satisfied, you chain a `then` method to the `when` method. You can perform any step within the `then` method.
+  - In this case, if the order's cart has a loyalty promotion, you call the `deductPurchasePointsStep` to deduct points from the customer's loyalty points. You also call the `updatePromotionsStep` to deactivate the cart's loyalty promotion.
+- You use another `when` to check whether the order's cart doesn't have a loyalty promotion.
+  - If the condition is satisfied, you call the `addPurchaseAsPointsStep` to add points to the customer's loyalty points.
+
+You'll use this workflow next when an order is placed.
+
+To learn more about the constraints on a workflow's constructor function, refer to the [Workflow Constraints](https://docs.medusajs.com/docs/learn/fundamentals/workflows/constructor-constraints/index.html.md) documentation. Refer to the [When-Then](https://docs.medusajs.com/docs/learn/fundamentals/workflows/conditions/index.html.md) documentation to learn more about the `when` method and how to use it in a workflow.
+
+***
+
+## Step 4: Handle Order Placed Event
+
+Now that you have the workflow that handles adding or deducting loyalty points for an order, you need to execute it when an order is placed.
+
+Medusa has an event system that allows you to listen to events emitted by the Medusa server using a [subscriber](https://docs.medusajs.com/docs//learn/fundamentals/events-and-subscribers/index.html.md). A subscriber is an asynchronous function that's executed when its associated event is emitted. In a subscriber, you can execute a workflow that performs actions in result of the event.
+
+In this step, you'll create a subscriber that listens to the `order.placed` event and executes the `handleOrderPointsWorkflow` workflow.
+
+Refer to the [Events and Subscribers](https://docs.medusajs.com/docs/learn/fundamentals/events-and-subscribers/index.html.md) documentation to learn more.
+
+Subscribers are created in a TypeScript or JavaScript file under the `src/subscribers` directory. So, to create a subscriber, create the fle `src/subscribers/order-placed.ts` with the following content:
+
+```ts title="src/subscribers/order-placed.ts"
+import type {
+  SubscriberArgs,
+  SubscriberConfig,
+} from "@medusajs/framework"
+import { handleOrderPointsWorkflow } from "../workflows/handle-order-points"
+
+export default async function orderPlacedHandler({
+  event: { data },
+  container,
+}: SubscriberArgs<{ id: string }>) {
+  await handleOrderPointsWorkflow(container).run({
+    input: {
+      order_id: data.id,
+    },
+  })
+}
+
+export const config: SubscriberConfig = {
+  event: "order.placed",
+}
+```
+
+The subscriber file must export:
+
+- 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 accepts an object with the following properties:
+
+- `event`: An object with the event's data payload. For example, the `order.placed` event has the order's ID in its data payload.
+- `container`: The Medusa container, which you can use to resolve services and tools.
+
+In the subscriber function, you execute the `handleOrderPointsWorkflow` by invoking it, passing it the Medusa container, then using its `run` method, passing it the workflow's input.
+
+Whenever an order is placed now, the subscriber will be executed, which in turn will execute the workflow that handles the loyalty points flow.
+
+### Test it Out
+
+To test out the loyalty points flow, you'll use the [Next.js Starter Storefront](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/nextjs-starter/index.html.md) that you installed in the first step. As mentioned in that step, the storefront will be installed in a separate directory from the Medusa application, and its name is `{project-name}-storefront`, where `{project-name}` is the name of your Medusa application's directory.
+
+So, run the following command in the Medusa application's directory to start the Medusa server:
+
+```bash npm2yarn badgeLabel="Medusa Application" badgeColor="green"
+npm run dev
+```
+
+Then, run the following command in the Next.js Starter Storefront's directory to start the Next.js server:
+
+```bash npm2yarn badgeLabel="Storefront" badgeColor="blue"
+npm run dev
+```
+
+The Next.js Starter Storefront will be running on `http://localhost:8000`, and the Medusa server will be running on `http://localhost:9000`.
+
+Open the Next.js Starter Storefront in your browser and create a new account by going to Account at the top right.
+
+Once you're logged in, add an item to the cart and go through the checkout flow.
+
+After you place the order, you'll see the following message in your Medusa application's terminal:
+
+```bash
+info:    Processing order.placed which has 1 subscribers
+```
+
+This message indicates that the `order.placed` event was emitted, and that your subscriber was executed.
+
+Since you didn't redeem any points during checkout, loyalty points will be added to your account. You'll implement an API route that allows you to retrieve the loyalty points in the next step.
+
+***
+
+## Step 5: Retrieve Loyalty Points API Route
+
+Next, you want to allow customers to view their loyalty points. You can show them on their profile page, or during checkout.
+
+To expose a feature to clients, you create an [API route](https://docs.medusajs.com/docs/learn/fundamentals/api-routes/index.html.md). An API Route is an endpoint that exposes commerce features to external applications and clients, such as storefronts.
+
+You'll create an API route at the path `/store/customers/me/loyalty-points` that returns the loyalty points of the authenticated customer.
+
+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 `/store/customers/me/loyalty-points`, create the file `src/api/store/customers/me/loyalty-points/route.ts` with the following content:
+
+```ts title="src/api/store/customers/me/loyalty-points/route.ts"
+
+import { 
+  AuthenticatedMedusaRequest, 
+  MedusaResponse,
+} from "@medusajs/framework/http"
+import { LOYALTY_MODULE } from "../../../../../modules/loyalty"
+import LoyaltyModuleService from "../../../../../modules/loyalty/service"
+
+export async function GET(
+  req: AuthenticatedMedusaRequest,
+  res: MedusaResponse
+) {
+  const loyaltyModuleService: LoyaltyModuleService = req.scope.resolve(
+    LOYALTY_MODULE
+  )
+
+  const points = await loyaltyModuleService.getPoints(
+    req.auth_context.actor_id
+  )
+
+  res.json({
+    points,
+  })
+}
+```
+
+Since you export a `GET` route handler function, you're exposing a `GET` endpoint at `/store/customers/me/loyalty-points`.  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.
+
+In the route handler, you resolve the Loyalty Module's service from the Medusa container (which is available at `req.scope`).
+
+Then, you call the service's `getPoints` method to retrieve the authenticated customer's loyalty points. Note that routes starting with `/store/customers/me` are only accessible by authenticated customers. You can access the authenticated customer ID from the request's context, which is available at `req.auth_context.actor_id`.
+
+Finally, you return the loyalty points in the response.
+
+You'll test out this route as you customize the Next.js Starter Storefront next.
+
+***
+
+## Step 6: Show Loyalty Points During Checkout
+
+Now that you have the API route to retrieve the loyalty points, you can show them during checkout.
+
+In this step, you'll customize the Next.js Starter Storefront to show the loyalty points in the checkout page.
+
+First, you'll add a server action function that retrieves the loyalty points from the route you created earlier. In `src/lib/data/customer.ts`, add the following function:
+
+```ts title="src/lib/data/customer.ts" badgeLabel="Storefront" badgeColor="blue"
+export const getLoyaltyPoints = async () => {
+  const headers = {
+    ...(await getAuthHeaders()),
+  }
+
+  return sdk.client.fetch<{ points: number }>(
+    `/store/customers/me/loyalty-points`,
+    {
+      method: "GET",
+      headers,
+    }
+  )
+    .then(({ points }) => points)
+    .catch(() => null)
+}
+```
+
+You add a `getLoyaltyPoints` function that retrieves the authenticated customer's loyalty points from the API route you created earlier. You pass the authentication headers using the `getAuthHeaders` function, which is a utility function defined in the Next.js Starter Storefront.
+
+If the customer isn't authenticated, the request will fail. So, you catch the error and return `null` in that case.
+
+Next, you'll create a component that shows the loyalty points in the checkout page. Create the file `src/modules/checkout/components/loyalty-points/index.tsx` with the following content:
+
+```tsx title="src/modules/checkout/components/loyalty-points/index.tsx" badgeLabel="Storefront" badgeColor="blue" highlights={loyaltyPointsHighlights}
+"use client"
+
+import { HttpTypes } from "@medusajs/types"
+import { useEffect, useMemo, useState } from "react"
+import { getLoyaltyPoints } from "../../../../lib/data/customer"
+import { Button, Heading } from "@medusajs/ui"
+import Link from "next/link"
+
+type LoyaltyPointsProps = {
+  cart: HttpTypes.StoreCart & {
+    promotions: HttpTypes.StorePromotion[]
+  }
+}
+
+const LoyaltyPoints = ({ cart }: LoyaltyPointsProps) => {
+  const isLoyaltyPointsPromoApplied = useMemo(() => {
+    return cart.promotions.find(
+      (promo) => promo.id === cart.metadata?.loyalty_promo_id
+    ) !== undefined
+  }, [cart])
+  const [loyaltyPoints, setLoyaltyPoints] = useState<
+    number | null
+  >(null)
+
+  useEffect(() => {
+    getLoyaltyPoints()
+    .then((points) => {
+      console.log(points)
+      setLoyaltyPoints(points)
+    })
+  }, [])
+
+  const handleTogglePromotion = async (
+    e: React.MouseEvent<HTMLButtonElement, MouseEvent>
+  ) => {
+    e.preventDefault()
+    // TODO apply or remove loyalty promotion
+  }
+
+  return (
+    <>
+      <div className="h-px w-full border-b border-gray-200 my-4" />
+      <div className="flex flex-col">
+        <Heading className="txt-medium mb-2">
+          Loyalty Points
+        </Heading>
+        {loyaltyPoints === null && (
+          <Link href="/account" className="txt-medium text-ui-fg-interactive hover:text-ui-fg-interactive-hover">
+            Sign up to get and use loyalty points
+          </Link>
+        )}
+        {loyaltyPoints !== null && (
+          <div className="flex items-center justify-between my-6 gap-1">
+          <Button
+            variant="secondary"
+            className="w-1/2"
+            onClick={handleTogglePromotion}
+          >
+            {isLoyaltyPointsPromoApplied ? "Remove" : "Apply"} Loyalty Points
+          </Button>
+          <span className="txt-medium text-ui-fg-subtle">
+            You have {loyaltyPoints} loyalty points
+          </span>
+        </div>
+        )}
+      </div>
+    </>
+  )
+}
+
+export default LoyaltyPoints
+```
+
+You create a `LoyaltyPoints` component that accepts the cart's details as a prop. In the component, you:
+
+- Create a `isLoyaltyPointsPromoApplied` memoized value that checks whether the cart has a loyalty promotion applied. You use the `cart.metadata.loyalty_promo_id` property to check this.
+- Create a `loyaltyPoints` state to store the customer's loyalty points.
+- Call the `getLoyaltyPoints` function in a `useEffect` hook to retrieve the loyalty points from the API route you created earlier. You set the `loyaltyPoints` state with the retrieved points.
+- Define `handleTogglePromotion` that, when clicked, would either apply or remove the promotion. You'll implement these functionalities later.
+- Render the loyalty points in the component. If the customer isn't authenticated, you show a link to the account page to sign up. Otherwise, you show the loyalty points and a button to apply or remove the promotion.
+
+Next, you'll show this component at the end of the checkout's summary component. So, import the component in `src/modules/checkout/templates/checkout-summary/index.tsx`:
+
+```tsx title="src/modules/checkout/templates/checkout-summary/index.tsx" badgeLabel="Storefront" badgeColor="blue"
+import LoyaltyPoints from "../../components/loyalty-points"
+```
+
+Then, in the return statement of the `CheckoutSummary` component, add the following after the `div` wrapping the `DiscountCode`:
+
+```tsx title="src/modules/checkout/templates/checkout-summary/index.tsx" badgeLabel="Storefront" badgeColor="blue"
+<LoyaltyPoints cart={cart} />
+```
+
+This will show the loyalty points component at the end of the checkout summary.
+
+### Test it Out
+
+To test out the customizations to the checkout flow, make sure both the Medusa application and Next.js Starter Storefront are running.
+
+Then, as an authenticated customer, add an item to cart and proceed to checkout. You'll find a new "Loyalty Points" section at the end of the checkout summary.
+
+![Loyalty Points Section at the end of the summary section at the right](https://res.cloudinary.com/dza7lstvk/image/upload/v1744195223/Medusa%20Resources/Screenshot_2025-04-09_at_1.39.34_PM_l5oltc.png)
+
+If you made a purchase before, you can see your loyalty points. You'll also see the "Apply Loyalty Points" button, which doesn't yet do anything. You'll add the functionality next.
+
+***
+
+## Step 7: Apply Loyalty Points to Cart
+
+The next feature you'll implement allows the customer to apply their loyalty points during checkout. To implement the feature, you need:
+
+- A workflow that implements the steps of the apply loyalty points flow.
+- An API route that exposes the workflow's functionality to clients. You'll then send a request to this API route to apply the loyalty points on the customer's cart.
+- A function in the Next.js Starter Storefront that sends the request to the API route you created earlier.
+
+The workflow will have the following steps:
+
+- [useQueryGraphStep](https://docs.medusajs.com/references/helper-steps/useQueryGraphStep/index.html.md): Retrieve the cart's details.
+- [validateCustomerExistsStep](#validateCustomerExistsStep): Validate that the customer is registered.
+- [getCartLoyaltyPromoStep](#getCartLoyaltyPromoStep): Retrieve the cart's loyalty promotion.
+- [getCartLoyaltyPromoAmountStep](#getCartLoyaltyPromoAmountStep): Get the amount to be discounted based on the loyalty points.
+- [createPromotionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createPromotionsStep/index.html.md): Create a new loyalty promotion for the cart.
+- [updateCartPromotionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/workflows/updateCartPromotionsWorkflow/index.html.md): Update the cart's promotions with the new loyalty promotion.
+- [updateCartsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateCartsStep/index.html.md): Update the cart to store the ID of the loyalty promotion in the metadata.
+- [useQueryGraphStep](https://docs.medusajs.com/references/helper-steps/useQueryGraphStep/index.html.md): Retrieve the cart's details again.
+
+Most of the workflow's steps are either provided by Medusa in the `@medusajs/medusa/core-flows` package or steps you've already implemented. You only need to implement the `getCartLoyaltyPromoAmountStep` step.
+
+### getCartLoyaltyPromoAmountStep
+
+The fourth step in the workflow is the `getCartLoyaltyPromoAmountStep`, which retrieves the amount to be discounted based on the loyalty points. This step is useful to determine how much discount to apply to the cart.
+
+To create the step, create the file `src/workflows/steps/get-cart-loyalty-promo-amount.ts` with the following content:
+
+```ts title="src/workflows/steps/get-cart-loyalty-promo-amount.ts" highlights={getCartLoyaltyPromoAmountStepHighlights}
+import { PromotionDTO, CustomerDTO } from "@medusajs/framework/types"
+import { MedusaError } from "@medusajs/framework/utils"
+import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk"
+import LoyaltyModuleService from "../../modules/loyalty/service"
+import { LOYALTY_MODULE } from "../../modules/loyalty"
+
+export type GetCartLoyaltyPromoAmountStepInput = {
+  cart: {
+    id: string
+    customer: CustomerDTO
+    promotions?: PromotionDTO[]
+    total: number
+  }
+}
+
+export const getCartLoyaltyPromoAmountStep = createStep(
+  "get-cart-loyalty-promo-amount",
+  async ({ cart }: GetCartLoyaltyPromoAmountStepInput, { container }) => {
+    // Check if customer has any loyalty points
+    const loyaltyModuleService: LoyaltyModuleService = container.resolve(
+      LOYALTY_MODULE
+    )
+    const loyaltyPoints = await loyaltyModuleService.getPoints(
+      cart.customer.id
+    )
+
+    if (loyaltyPoints <= 0) {
+      throw new MedusaError(
+        MedusaError.Types.INVALID_DATA,
+        "Customer has no loyalty points"
+      )
+    }
+    
+    const pointsAmount = await loyaltyModuleService.calculatePointsFromAmount(
+      loyaltyPoints
+    )
+
+    const amount = Math.min(pointsAmount, cart.total)
+
+    return new StepResponse(amount)
+  }
+)
+```
+
+You create a step that accepts an object having the cart's details.
+
+In the step, you resolve the Loyalty Module's service from the Medusa container. Then, you call the `getPoints` method to retrieve the customer's loyalty points. If the customer has no loyalty points, you throw an error.
+
+Next, you call the `calculatePointsFromAmount` method to calculate the amount to be discounted based on the loyalty points. You use the `Math.min` function to ensure that the amount doesn't exceed the cart's total.
+
+Finally, you return a `StepResponse` with the amount to be discounted.
+
+### Create the Workflow
+
+You can now create the workflow that applies a loyalty promotion to the cart.
+
+To create the workflow, create the file `src/workflows/apply-loyalty-on-cart.ts` with the following content:
+
+```ts title="src/workflows/apply-loyalty-on-cart.ts" highlights={applyLoyaltyOnCartWorkflowHighlights} collapsibleLines="1-24" expandButtonLabel="Show Imports"
+import {
+  createWorkflow,
+  transform,
+  WorkflowResponse,
+} from "@medusajs/framework/workflows-sdk"
+import { 
+  createPromotionsStep, 
+  updateCartPromotionsWorkflow, 
+  updateCartsStep, 
+  useQueryGraphStep,
+} from "@medusajs/medusa/core-flows"
+import { 
+  validateCustomerExistsStep, 
+  ValidateCustomerExistsStepInput,
+} from "./steps/validate-customer-exists"
+import { 
+  getCartLoyaltyPromoAmountStep, 
+  GetCartLoyaltyPromoAmountStepInput,
+} from "./steps/get-cart-loyalty-promo-amount"
+import { CartData, CUSTOMER_ID_PROMOTION_RULE_ATTRIBUTE } from "../utils/promo"
+import { CreatePromotionDTO } from "@medusajs/framework/types"
+import { PromotionActions } from "@medusajs/framework/utils"
+import { getCartLoyaltyPromoStep } from "./steps/get-cart-loyalty-promo"
+
+type WorkflowInput = {
+  cart_id: string
+}
+
+const fields = [
+  "id",
+  "customer.*",
+  "promotions.*",
+  "promotions.application_method.*",
+  "promotions.rules.*",
+  "promotions.rules.values.*",
+  "currency_code",
+  "total",
+  "metadata",
+]
+
+export const applyLoyaltyOnCartWorkflow = createWorkflow(
+  "apply-loyalty-on-cart",
+  (input: WorkflowInput) => {
+    // @ts-ignore
+    const { data: carts } = useQueryGraphStep({
+      entity: "cart",
+      fields,
+      filters: {
+        id: input.cart_id,
+      },
+      options: {
+        throwIfKeyNotFound: true,
+      },
+    })
+
+    validateCustomerExistsStep({
+      customer: carts[0].customer,
+    } as ValidateCustomerExistsStepInput)
+
+    getCartLoyaltyPromoStep({
+      cart: carts[0] as unknown as CartData,
+      throwErrorOn: "found",
+    })
+
+    const amount = getCartLoyaltyPromoAmountStep({
+      cart: carts[0],
+    } as unknown as GetCartLoyaltyPromoAmountStepInput)
+
+    // TODO create and apply the promotion on the cart
+  }
+)
+```
+
+You create a workflow that accepts an object with the cart's ID as input.
+
+So far, you:
+
+- Use `useQueryGraphStep` to retrieve the cart's details. You pass the cart's ID as a filter to retrieve the cart.
+- Validate that the customer is registered using the `validateCustomerExistsStep`.
+- Check whether the cart has a loyalty promotion using the `getCartLoyaltyPromoStep`. You pass the `throwErrorOn` parameter with the value `found` to throw an error if a loyalty promotion is found in the cart.
+- Retrieve the amount to be discounted based on the loyalty points using the `getCartLoyaltyPromoAmountStep`.
+
+Next, you need to create a new loyalty promotion for the cart. First, you'll prepare the data of the promotion to be created.
+
+Replace the `TODO` with the following:
+
+```ts title="src/workflows/apply-loyalty-on-cart.ts" highlights={prepareLoyaltyPromoDataHighlights}
+const promoToCreate = transform({
+  carts,
+  amount,
+}, (data) => {
+  const randomStr = Math.random().toString(36).substring(2, 8)
+  const uniqueId = (
+    "LOYALTY-" + data.carts[0].customer?.first_name + "-" + randomStr
+  ).toUpperCase()
+  return {
+    code: uniqueId,
+    type: "standard",
+    status: "active",
+    application_method: {
+      type: "fixed",
+      value: data.amount,
+      target_type: "order",
+      currency_code: data.carts[0].currency_code,
+      allocation: "across",
+    },
+    rules: [
+      {
+        attribute: CUSTOMER_ID_PROMOTION_RULE_ATTRIBUTE,
+        operator: "eq",
+        values: [data.carts[0].customer!.id],
+      },
+    ],
+    campaign: {
+      name: uniqueId,
+      description: "Loyalty points promotion for " + data.carts[0].customer!.email,
+      campaign_identifier: uniqueId,
+      budget: {
+        type: "usage",
+        limit: 1,
+      },
+    },
+  }
+})
+
+// TODO create promotion and apply it on cart
+```
+
+Since data manipulation isn't allowed in a workflow constructor, you use the [transform](https://docs.medusajs.com/docs/learn/fundamentals/workflows/variable-manipulation/index.html.md) function from the Workflows SDK. It accepts two parameters:
+
+- The data to perform manipulation on. In this case, you pass the cart's details and the amount to be discounted.
+- A function that receives the data from the first parameter, and returns the transformed data.
+
+In the transformation function, you prepare th data of the loyalty promotion to be created. Some key details include:
+
+- You set the discount amount in the application method of the promotion.
+- You add a rule to the promotion that ensures it can be used only in carts having their `customer_id` equal to this customer's ID. This prevents other customers from using this promotion.
+- You create a campaign for the promotion, and you set the campaign budget to a single usage. This prevents the customer from using the promotion again.
+
+Learn more about promotion concepts in the [Promotion Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/promotion/index.html.md)'s documentation.
+
+You can now use the returned data to create a promotion and apply it to the cart. Replace the new `TODO` with the following:
+
+```ts title="src/workflows/apply-loyalty-on-cart.ts" highlights={createLoyaltyPromoStepHighlights}
+const loyaltyPromo = createPromotionsStep([
+  promoToCreate,
+] as CreatePromotionDTO[])
+
+const { metadata, ...updatePromoData } = transform({
+  carts,
+  promoToCreate,
+  loyaltyPromo,
+}, (data) => {
+  const promos = [
+    ...(data.carts[0].promotions?.map((promo) => promo?.code).filter(Boolean) || []) as string[],
+    data.promoToCreate.code,
+  ]
+
+  return {
+    cart_id: data.carts[0].id,
+    promo_codes: promos,
+    action: PromotionActions.ADD,
+    metadata: {
+      loyalty_promo_id: data.loyaltyPromo[0].id,
+    },
+  }
+})
+
+updateCartPromotionsWorkflow.runAsStep({
+  input: updatePromoData,
+})
+
+updateCartsStep([
+  {
+    id: input.cart_id,
+    metadata,
+  },
+])
+
+// retrieve cart with updated promotions
+// @ts-ignore
+const { data: updatedCarts } = useQueryGraphStep({
+  entity: "cart",
+  fields,
+  filters: { id: input.cart_id },
+}).config({ name: "retrieve-cart" })
+
+return new WorkflowResponse(updatedCarts[0])
+```
+
+In the rest of the workflow, you:
+
+- Create the loyalty promotion using the data you prepared earlier using the `createPromotionsStep`.
+- Use the `transform` function to prepare the data to update the cart's promotions. You add the new loyalty promotion code to the cart's promotions codes, and set the `loyalty_promo_id` in the cart's metadata.
+- Update the cart's promotions with the new loyalty promotion using the `updateCartPromotionsWorkflow` workflow.
+- Update the cart's metadata with the loyalty promotion ID using the `updateCartsStep`.
+- Retrieve the cart's details again using `useQueryGraphStep` to get the updated cart with the new loyalty promotion.
+
+To return data from the workflow, you must return an instance of `WorkflowResponse`. You pass it the data to be returned, which is in this case the cart's details.
+
+### Create the API Route
+
+Next, you'll create the API route that executes this workflow.
+
+To create the API route, create the file `src/api/store/carts/[id]/loyalty-points/route.ts` with the following content:
+
+```ts title="src/api/store/carts/[id]/loyalty-points/route.ts"
+import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
+import { applyLoyaltyOnCartWorkflow } from "../../../../../workflows/apply-loyalty-on-cart"
+
+export async function POST(
+  req: MedusaRequest,
+  res: MedusaResponse
+) {
+  const { id: cart_id } = req.params
+
+  const { result: cart } = await applyLoyaltyOnCartWorkflow(req.scope)
+    .run({
+      input: {
+        cart_id,
+      },
+    })
+
+  res.json({ cart })
+}
+```
+
+Since you export a `POST` route handler, you expose a `POST` API route at `/store/carts/[id]/loyalty-points`.
+
+In the route handler, you execute the `applyLoyaltyOnCartWorkflow` workflow, passing it the cart ID as an input. You return the cart's details in the response.
+
+You can now use this API route in the Next.js Starter Storefront.
+
+### Apply Loyalty Points in the Storefront
+
+In the Next.js Starter Storefront, you need to add a server action function that sends a request to the API route you created earlier. Then, you'll use that function when the customer clicks the "Apply Loyalty Points" button.
+
+To add the function, add the following to `src/lib/data/cart.ts` in the Next.js Starter Storefront:
+
+```ts title="src/lib/data/cart.ts" badgeLabel="Storefront" badgeColor="blue"
+export async function applyLoyaltyPointsOnCart() {
+  const cartId = await getCartId()
+  const headers = {
+    ...(await getAuthHeaders()),
+  }
+
+  return await sdk.client.fetch<{
+    cart: HttpTypes.StoreCart & {
+      promotions: HttpTypes.StorePromotion[]
+    }
+  }>(`/store/carts/${cartId}/loyalty-points`, {
+    method: "POST",
+    headers,
+  })
+  .then(async (result) => {
+    const cartCacheTag = await getCacheTag("carts")
+    revalidateTag(cartCacheTag)
+
+    return result
+  })
+}
+```
+
+You create an `applyLoyaltyPointsOnCart` function that sends a request to the API route you created earlier.
+
+In the function, you retrieve the cart ID stored in the cookie using the `getCartId` function, which is available in the Next.js Starter Storefront.
+
+Then, you send the request. Once the request is resolved successfully, you revalidate the cart cache tag to ensure that the cart's details are updated and refetched by other components. This ensures that the applied promotion is shown in the checkout summary without needing to refresh the page.
+
+Finally, you'll use this function in the `handleTogglePromotion` function in the `LoyaltyPoints` component you created earlier.
+
+At the top of `src/modules/checkout/components/loyalty-points/index.tsx`, import the function:
+
+```tsx title="src/modules/checkout/components/loyalty-points/index.tsx" badgeLabel="Storefront" badgeColor="blue"
+import { applyLoyaltyPointsOnCart } from "../../../../lib/data/cart"
+```
+
+Then, replace the `handleTogglePromotion` function with the following:
+
+```tsx title="src/modules/checkout/components/loyalty-points/index.tsx" badgeLabel="Storefront" badgeColor="blue"
+const handleTogglePromotion = async (
+  e: React.MouseEvent<HTMLButtonElement, MouseEvent>
+) => {
+  e.preventDefault()
+  if (!isLoyaltyPointsPromoApplied) {
+    await applyLoyaltyPointsOnCart()
+  } else {
+    // TODO remove loyalty points
+  }
+}
+```
+
+In the `handleTogglePromotion` function, you call the `applyLoyaltyPointsOnCart` function if the cart doesn't have a loyalty promotion. This will send a request to the API route you created earlier, which will execute the workflow that applies the loyalty promotion to the cart.
+
+You'll implement removing the loyalty points promotion in a later step.
+
+### Test it Out
+
+To test out applying the loyalty points on the cart, start the Medusa application and Next.js Starter Storefront.
+
+Then, in the checkout flow as an authenticated customer, click on the "Apply Loyalty Points" button. The checkout summary will be updated with the applied promotion and the discount amount.
+
+If you don't want the promotion to be shown in the "Promotions(s) applied" section, you can filter the promotions in `src/modules/checkout/components/discount-code/index.tsx` to not show a promotion matching `cart.metadata.loyalty_promo_id`.
+
+![Discounted amount is shown as part of the summary and the promotion is shown as part of the applied promotions](https://res.cloudinary.com/dza7lstvk/image/upload/v1744200895/Medusa%20Resources/Screenshot_2025-04-09_at_3.14.19_PM_abmtjh.png)
+
+***
+
+## Step 8: Remove Loyalty Points From Cart
+
+In this step, you'll implement the functionality to remove the loyalty points promotion from the cart. This is useful if the customer changes their mind and wants to remove the promotion.
+
+To implement this functionality, you'll need to:
+
+- Create a workflow that removes the loyalty points promotion from the cart.
+- Create an API route that executes the workflow.
+- Create a function in the Next.js Starter Storefront that sends a request to the API route you created earlier.
+- Use the function in the `handleTogglePromotion` function in the `LoyaltyPoints` component you created earlier.
+
+### Create the Workflow
+
+The workflow will have the following steps:
+
+- [useQueryGraphStep](https://docs.medusajs.com/references/helper-steps/useQueryGraphStep/index.html.md): Retrieve the cart's details.
+- [getCartLoyaltyPromoStep](#getCartLoyaltyPromoStep): Retrieve the cart's loyalty promotion.
+- [updateCartPromotionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/workflows/updateCartPromotionsWorkflow/index.html.md): Update the cart's promotions to remove the loyalty promotion.
+- [updateCartsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateCartsStep/index.html.md): Update the cart to remove the loyalty promotion ID from the metadata.
+- [updatePromotionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updatePromotionsStep/index.html.md): Deactive the loyalty promotion.
+- [useQueryGraphStep](https://docs.medusajs.com/references/helper-steps/useQueryGraphStep/index.html.md): Retrieve the cart's details again.
+
+Since you already have all the steps, you can create the workflow.
+
+To create the workflow, create the file `src/workflows/remove-loyalty-from-cart.ts` with the following content:
+
+```ts title="src/workflows/remove-loyalty-from-cart.ts" collapsibleLines="1-15" expandButtonLabel="Show Imports" highlights={removeLoyaltyFromCartWorkflowHighlights}
+import {
+  createWorkflow,
+  transform,
+  WorkflowResponse,
+} from "@medusajs/framework/workflows-sdk"
+import {
+  useQueryGraphStep,
+  updateCartPromotionsWorkflow,
+  updateCartsStep,
+  updatePromotionsStep,
+} from "@medusajs/medusa/core-flows"
+import { getCartLoyaltyPromoStep } from "./steps/get-cart-loyalty-promo"
+import { PromotionActions } from "@medusajs/framework/utils"
+import { CartData } from "../utils/promo"
+
+type WorkflowInput = {
+  cart_id: string
+}
+
+const fields = [
+  "id",
+  "customer.*",
+  "promotions.*",
+  "promotions.application_method.*",
+  "promotions.rules.*",
+  "promotions.rules.values.*",
+  "currency_code",
+  "total",
+  "metadata",
+]
+
+export const removeLoyaltyFromCartWorkflow = createWorkflow(
+  "remove-loyalty-from-cart",
+  (input: WorkflowInput) => {
+    // @ts-ignore
+    const { data: carts } = useQueryGraphStep({
+      entity: "cart",
+      fields,
+      filters: {
+        id: input.cart_id,
+      },
+    })
+
+    const loyaltyPromo = getCartLoyaltyPromoStep({
+      cart: carts[0] as unknown as CartData,
+      throwErrorOn: "not-found",
+    })
+
+    updateCartPromotionsWorkflow.runAsStep({
+      input: {
+        cart_id: input.cart_id,
+        promo_codes: [loyaltyPromo.code!],
+        action: PromotionActions.REMOVE,
+      },
+    })
+
+    const newMetadata = transform({
+      carts,
+    }, (data) => {
+      const { loyalty_promo_id, ...rest } = data.carts[0].metadata || {}
+
+      return {
+        ...rest,
+        loyalty_promo_id: null,
+      }
+    })
+
+    updateCartsStep([
+      {
+        id: input.cart_id,
+        metadata: newMetadata,
+      },
+    ])
+
+    updatePromotionsStep([
+      {
+        id: loyaltyPromo.id,
+        status: "inactive",
+      },
+    ])
+
+    // retrieve cart with updated promotions
+    // @ts-ignore
+    const { data: updatedCarts } = useQueryGraphStep({
+      entity: "cart",
+      fields,
+      filters: { id: input.cart_id },
+    }).config({ name: "retrieve-cart" })
+
+    return new WorkflowResponse(updatedCarts[0])
+  }
+)
+```
+
+You create a workflow that accepts an object with the cart's ID as input.
+
+In the workflow, you:
+
+- Use `useQueryGraphStep` to retrieve the cart's details. You pass the cart's ID as a filter to retrieve the cart.
+- Check whether the cart has a loyalty promotion using the `getCartLoyaltyPromoStep`. You pass the `throwErrorOn` parameter with the value `not-found` to throw an error if a loyalty promotion isn't found in the cart.
+- Update the cart's promotions using the `updateCartPromotionsWorkflow`, removing the loyalty promotion.
+- Use the `transform` function to prepare the new metadata of the cart. You remove the `loyalty_promo_id` from the metadata.
+- Update the cart's metadata with the new metadata using the `updateCartsStep`.
+- Deactivate the loyalty promotion using the `updatePromotionsStep`.
+- Retrieve the cart's details again using `useQueryGraphStep` to get the updated cart with the new loyalty promotion.
+- Return the cart's details in a `WorkflowResponse` instance.
+
+### Create the API Route
+
+Next, you'll create the API route that executes this workflow.
+
+To create the API route, add the following in `src/api/store/carts/[id]/loyalty-points/route.ts`:
+
+```ts title="src/api/store/carts/[id]/loyalty-points/route.ts"
+// other imports...
+import { removeLoyaltyFromCartWorkflow } from "../../../../../workflows/remove-loyalty-from-cart"
+
+// ...
+export async function DELETE(
+  req: MedusaRequest,
+  res: MedusaResponse
+) {
+  const { id: cart_id } = req.params
+
+  const { result: cart } = await removeLoyaltyFromCartWorkflow(req.scope)
+    .run({
+      input: {
+        cart_id,
+      },
+    })
+
+  res.json({ cart })
+}
+```
+
+You export a `DELETE` route handler, which exposes a `DELETE` API route at `/store/carts/[id]/loyalty-points`.
+
+In the route handler, you execute the `removeLoyaltyFromCartWorkflow` workflow, passing it the cart ID as an input. You return the cart's details in the response.
+
+You can now use this API route in the Next.js Starter Storefront.
+
+### Remove Loyalty Points in the Storefront
+
+In the Next.js Starter Storefront, you need to add a server action function that sends a request to the API route you created earlier. Then, you'll use that function when the customer clicks the "Remove Loyalty Points" button, which shows when the cart has a loyalty promotion applied.
+
+To add the function, add the following to `src/lib/data/cart.ts`:
+
+```ts title="src/lib/data/cart.ts" badgeLabel="Storefront" badgeColor="blue"
+export async function removeLoyaltyPointsOnCart() {
+  const cartId = await getCartId()
+  const headers = {
+    ...(await getAuthHeaders()),
+  }
+  const next = {
+    ...(await getCacheOptions("carts")),
+  }
+
+  return await sdk.client.fetch<{
+    cart: HttpTypes.StoreCart & {
+      promotions: HttpTypes.StorePromotion[]
+    }
+  }>(`/store/carts/${cartId}/loyalty-points`, {
+    method: "DELETE",
+    headers,
+  })
+  .then(async (result) => {
+    const cartCacheTag = await getCacheTag("carts")
+    revalidateTag(cartCacheTag)
+
+    return result
+  })
+}
+```
+
+You create a `removeLoyaltyPointsOnCart` function that sends a request to the API route you created earlier.
+
+In the function, you retrieve the cart ID stored in the cookie using the `getCartId` function, which is available in the Next.js Starter Storefront.
+
+Then, you send the request to the API route. Once the request is resolved successfully, you revalidate the cart cache tag to ensure that the cart's details are updated and refetched by other components. This ensures that the promotion is removed from the checkout summary without needing to refresh the page.
+
+Finally, you'll use this function in the `handleTogglePromotion` function in the `LoyaltyPoints` component you created earlier.
+
+At the top of `src/modules/checkout/components/loyalty-points/index.tsx`, add the following import:
+
+```tsx title="src/modules/checkout/components/loyalty-points/index.tsx" badgeLabel="Storefront" badgeColor="blue"
+import { removeLoyaltyPointsOnCart } from "../../../../lib/data/cart"
+```
+
+Then, replace the `TODO` in `handleTogglePromotion` with the following:
+
+```tsx title="src/modules/checkout/components/loyalty-points/index.tsx" badgeLabel="Storefront" badgeColor="blue"
+await removeLoyaltyPointsOnCart()
+```
+
+In the `handleTogglePromotion` function, you call the `removeLoyaltyPointsOnCart` function if the cart has a loyalty promotion. This will send a request to the API route you created earlier, which will execute the workflow that removes the loyalty promotion from the cart.
+
+### Test it Out
+
+To test out removing the loyalty points from the cart, start the Medusa application and Next.js Starter Storefront.
+
+Then, in the checkout flow as an authenticated customer, after applying the loyalty points, click on the "Remove Loyalty Points" button. The checkout summary will be updated with the removed promotion and the discount amount.
+
+![The "Remove Loyalty Points" button is shown in the "Loyalty Points" section](https://res.cloudinary.com/dza7lstvk/image/upload/v1744204436/Medusa%20Resources/Screenshot_2025-04-09_at_4.13.24_PM_xt5trh.png)
+
+***
+
+## Step 9: Validate Loyalty Points on Cart Completion
+
+After the customer applies the loyalty points to the cart and places the order, you need to validate that the customer actually has the loyalty points. This prevents edge cases where the customer may have applied the loyalty points previously but they don't have them anymore.
+
+So, in this step, you'll hook into Medusa's cart completion flow to perform the validation.
+
+Since Medusa uses workflows in its API routes, it allows you to hook into them and perform custom functionalities using [Workflow Hooks](https://docs.medusajs.com/docs/learn/fundamentals/workflows/workflow-hooks/index.html.md). A workflow hook is a point in a workflow where you can inject custom functionality as a step function, called a hook handler.
+
+Medusa uses the [completeCartWorkflow](https://docs.medusajs.com/references/medusa-workflows/completeCartWorkflow/index.html.md) hook to complete the cart and place an order. This workflow has a `validate` hook that allows you to perform custom validation before the cart is completed.
+
+To consume the `validate` hook, create the file `src/workflows/hooks/complete-cart.ts` with the following content:
+
+```ts title="src/workflows/hooks/complete-cart.ts" highlights={completeCartWorkflowHookHighlights} collapsibleLines="1-6" expandButtonLabel="Show Imports"
+import { completeCartWorkflow } from "@medusajs/medusa/core-flows"
+import LoyaltyModuleService from "../../modules/loyalty/service"
+import { LOYALTY_MODULE } from "../../modules/loyalty"
+import { CartData, getCartLoyaltyPromotion } from "../../utils/promo"
+import { MedusaError } from "@medusajs/framework/utils"
+
+completeCartWorkflow.hooks.validate(
+  async ({ cart }, { container }) => {
+    const query = container.resolve("query")
+    const loyaltyModuleService: LoyaltyModuleService = container.resolve(
+      LOYALTY_MODULE
+    )
+
+    const { data: carts } = await query.graph({
+      entity: "cart",
+      fields: [
+        "id", 
+        "promotions.*", 
+        "customer.*", 
+        "promotions.rules.*", 
+        "promotions.rules.values.*", 
+        "promotions.application_method.*", 
+        "metadata",
+      ],
+      filters: {
+        id: cart.id,
+      },
+    }, {
+      throwIfKeyNotFound: true,
+    })
+
+    const loyaltyPromo = getCartLoyaltyPromotion(
+      carts[0] as unknown as CartData
+    )
+
+    if (!loyaltyPromo) {
+      return
+    }
+    
+    const customerLoyaltyPoints = await loyaltyModuleService.getPoints(
+      carts[0].customer!.id
+    )
+    const requiredPoints = await loyaltyModuleService.calculatePointsFromAmount(
+      loyaltyPromo.application_method!.value as number
+    )
+
+    if (customerLoyaltyPoints < requiredPoints) {
+      throw new MedusaError(
+        MedusaError.Types.INVALID_DATA,
+        `Customer does not have enough loyalty points. Required: ${
+          requiredPoints
+        }, Available: ${customerLoyaltyPoints}`
+      )
+    }
+  }
+)
+```
+
+Workflows have a special `hooks` property that includes all the hooks tht you can consume in that workflow. You consume the hook by invoking it from the workflow's `hooks` property.
+
+Since the hook is essentially a step function, it accepts the following parameters:
+
+- The hook's input passed from the workflow, which differs for each hook. The `validate` hook receives an object having the cart's details.
+- The step context object, which contains the Medusa container. You can use it to resolve services and perform actions.
+
+In the hook, you resolve Query and the Loyalty Module's service. Then, you use Query to retrieve the cart's necessary details, including its promotions, customer, and metadata.
+
+After that, you retrieve the customer's loyalty points and calculate the required points to apply the loyalty promotion.
+
+If the customer doesn't have enough loyalty points, you throw an error. This will prevent the cart from being completed if the customer doesn't have enough loyalty points.
+
+***
+
+## Test Out Cart Completion with Loyalty Points
+
+Since you now have the entire loyalty points flow implemented, you can test it out by going through the checkout flow, applying the loyalty points to the cart.
+
+When you place the order, if the customer has sufficient loyalty points, the validation hook will pass.
+
+Then, the `order.placed` event will be emitted, which will execute the subscriber that calls the `handleOrderPointsWorkflow`.
+
+In the workflow, since the order's cart has a loyalty promotion, the points equivalent to the promotion will be deducted, and the promotion becomes inactive.
+
+You can confirm that the loyalty points were deducted either by sending a request to the [retrieve loyalty points API route](#step-5-retrieve-loyalty-points-api-route), or by going through the checkout process again in the storefront.
+
+***
+
+## Next Steps
+
+You've now implement a loyalty points system in Medusa. There's still more that you can implement based on your use case:
+
+- Add loyalty points on registration or other events. Refer to the [Events Reference](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/events-reference/index.html.md) for a full list of available events you can listen to.
+- Show the customer their loyalty point usage history. This will require adding another data model in the Loyalty Module that records the usage history. You can create records of that data model when an order that has a loyalty promotion is placed, then customize the storefront to show a new page for loyalty points history.
+- Customize the Medusa Admin to show a new page or [UI Route](https://docs.medusajs.com/docs/learn/fundamentals/admin/ui-routes/index.html.md) for loyalty points information and analytics.
+
+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.
@@ -42682,1797 +44620,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 Loyalty Points System in Medusa
-
-In this tutorial, you'll learn how to implement a loyalty points system in Medusa.
-
-Medusa Cloud provides a beta Store Credits feature that facilitates building a loyalty point system. [Get in touch](https://medusajs.com/contact) for early access.
-
-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 management capabilities related to carts, orders, promotions, and more.
-
-A loyalty point system allows customers to earn points for purchases, which can be redeemed for discounts or rewards. In this tutorial, you'll learn how to customize the Medusa application to implement a loyalty points system.
-
-You can follow this tutorial whether you're new to Medusa or an advanced Medusa developer.
-
-## Summary
-
-By following this tutorial, you will learn how to:
-
-- Install and set up Medusa.
-- Define models to store loyalty points and the logic to manage them.
-- Build flows that allow customers to earn and redeem points during checkout.
-  - Points are redeemed through dynamic promotions specific to the customer.
-- Customize the cart completion flow to validate applied loyalty points.
-
-![Diagram illustrating redeem loyalty points flow](https://res.cloudinary.com/dza7lstvk/image/upload/v1744126213/Medusa%20Resources/redeem-points-flow_kzgkux.jpg)
-
-- [Loyalty Points Repository](https://github.com/medusajs/examples/tree/main/loyalty-points): Find the full code for this guide in this repository.
-- [OpenApi Specs for Postman](https://res.cloudinary.com/dza7lstvk/raw/upload/v1744212595/OpenApi/Loyalty-Points_jwi5e9.yaml): Import this OpenApi Specs file into tools like Postman.
-
-***
-
-## Step 1: Install a Medusa Application
-
-### Prerequisites
-
-- [Node.js v20+](https://nodejs.org/en/download)
-- [Git CLI tool](https://git-scm.com/downloads)
-- [PostgreSQL](https://www.postgresql.org/download/)
-
-Start by installing the Medusa application on your machine with the following command:
-
-```bash
-npx create-medusa-app@latest
-```
-
-You'll first be asked for the project's name. Then, when asked whether you want to install the [Next.js Starter Storefront](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/nextjs-starter/index.html.md), choose Yes.
-
-Afterward, 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. Afterward, you can log in with the new user and explore the dashboard.
-
-Check out the [troubleshooting guides](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/troubleshooting/create-medusa-app-errors/index.html.md) for help.
-
-***
-
-## Step 2: Create Loyalty Module
-
-In Medusa, you can build custom features in a [module](https://docs.medusajs.com/docs/learn/fundamentals/modules/index.html.md). A module is a reusable package with functionalities related to a single feature or domain. Medusa integrates the module into your application without implications or side effects on your setup.
-
-In the module, you define the data models necessary for a feature and the logic to manage these data models. Later, you can build commerce flows around your module.
-
-In this step, you'll build a Loyalty Module that defines the necessary data models to store and manage loyalty points for customers.
-
-Refer to the [Modules documentation](https://docs.medusajs.com/docs/learn/fundamentals/modules/index.html.md) to learn more.
-
-### Create Module Directory
-
-Modules are created under the `src/modules` directory of your Medusa application. So, create the directory `src/modules/loyalty`.
-
-### Create Data Models
-
-A data model represents a table in the database. You create data models using Medusa's Data Model Language (DML). It simplifies defining a table's columns, relations, and indexes with straightforward methods and configurations.
-
-Refer to the [Data Models documentation](https://docs.medusajs.com/docs/learn/fundamentals/modules#1-create-data-model/index.html.md) to learn more.
-
-For the Loyalty Module, you need to define a `LoyaltyPoint` data model that represents a customer's loyalty points. So, create the file `src/modules/loyalty/models/loyalty-point.ts` with the following content:
-
-```ts title="src/modules/loyalty/models/loyalty-point.ts" highlights={dmlHighlights}
-import { model } from "@medusajs/framework/utils"
-
-const LoyaltyPoint = model.define("loyalty_point", {
-  id: model.id().primaryKey(),
-  points: model.number().default(0),
-  customer_id: model.text().unique("IDX_LOYALTY_CUSTOMER_ID"), 
-})
-
-export default LoyaltyPoint
-```
-
-You define the `LoyaltyPoint` data model using the `model.define` method of the DML. It accepts the data model's table name as a first parameter, and the model's schema object as a second parameter.
-
-The `LoyaltyPoint` data model has the following properties:
-
-- `id`: A unique ID for the loyalty points.
-- `points`: The number of loyalty points a customer has.
-- `customer_id`: The ID of the customer who owns the loyalty points. This property has a unique index to ensure that each customer has only one record in the `loyalty_point` table.
-
-Learn more about defining data model properties in the [Property Types documentation](https://docs.medusajs.com/docs/learn/fundamentals/data-models/properties/index.html.md).
-
-### Create Module's Service
-
-You now have the necessary data model in the Loyalty Module, but you'll need to manage its records. You do this by creating a service in the module.
-
-A service is a TypeScript or JavaScript class that the module exports. In the service's methods, you can connect to the database, allowing you to manage your data models, or connect to a third-party service, which is useful if you're integrating with external services.
-
-Refer to the [Module Service documentation](https://docs.medusajs.com/docs/learn/fundamentals/modules#2-create-service/index.html.md) to learn more.
-
-To create the Loyalty Module's service, create the file `src/modules/loyalty/service.ts` with the following content:
-
-```ts title="src/modules/loyalty/service.ts"
-import { MedusaError, MedusaService } from "@medusajs/framework/utils"
-import LoyaltyPoint from "./models/loyalty-point"
-import { InferTypeOf } from "@medusajs/framework/types"
-
-type LoyaltyPoint = InferTypeOf<typeof LoyaltyPoint>
-
-class LoyaltyModuleService extends MedusaService({
-  LoyaltyPoint,
-}) {
-  // TODO add methods
-}
-
-export default LoyaltyModuleService
-```
-
-The `LoyaltyModuleService` extends `MedusaService` from the Modules SDK which generates a class with data-management methods for your module's data models. This saves you time on implementing Create, Read, Update, and Delete (CRUD) methods.
-
-So, the `LoyaltyModuleService` class now has methods like `createLoyaltyPoints` and `retrieveLoyaltyPoint`.
-
-Find all methods generated by the `MedusaService` in [the Service Factory reference](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/service-factory-reference/index.html.md).
-
-#### Add Methods to the Service
-
-Aside from the basic CRUD methods, you need to add methods that handle custom functionalities related to loyalty points.
-
-First, you need a method that adds loyalty points for a customer. Add the following method to the `LoyaltyModuleService`:
-
-```ts title="src/modules/loyalty/service.ts"
-class LoyaltyModuleService extends MedusaService({
-  LoyaltyPoint,
-}) {
-  async addPoints(customerId: string, points: number): Promise<LoyaltyPoint> {
-    const existingPoints = await this.listLoyaltyPoints({
-      customer_id: customerId,
-    })
-
-    if (existingPoints.length > 0) {
-      return await this.updateLoyaltyPoints({
-        id: existingPoints[0].id,
-        points: existingPoints[0].points + points,
-      })
-    }
-
-    return await this.createLoyaltyPoints({
-      customer_id: customerId,
-      points,
-    })
-  }
-}
-```
-
-You add an `addPoints` method that accepts two parameters: the ID of the customer and the points to add.
-
-In the method, you retrieve the customer's existing loyalty points using the `listLoyaltyPoints` method, which is automatically generated by the `MedusaService`. If the customer has existing points, you update them with the new points using the `updateLoyaltyPoints` method.
-
-Otherwise, if the customer doesn't have existing loyalty points, you create a new record with the `createLoyaltyPoints` method.
-
-The next method you'll add deducts points from the customer's loyalty points, which is useful when the customer redeems points. Add the following method to the `LoyaltyModuleService`:
-
-```ts title="src/modules/loyalty/service.ts"
-class LoyaltyModuleService extends MedusaService({
-  LoyaltyPoint,
-}) {
-  // ...
-  async deductPoints(customerId: string, points: number): Promise<LoyaltyPoint> {
-    const existingPoints = await this.listLoyaltyPoints({
-      customer_id: customerId,
-    })
-
-    if (existingPoints.length === 0 || existingPoints[0].points < points) {
-      throw new MedusaError(
-        MedusaError.Types.NOT_ALLOWED,
-        "Insufficient loyalty points"
-      )
-    }
-
-    return await this.updateLoyaltyPoints({
-      id: existingPoints[0].id,
-      points: existingPoints[0].points - points,
-    })
-  }
-}
-```
-
-The `deductPoints` method accepts the customer ID and the points to deduct.
-
-In the method, you retrieve the customer's existing loyalty points using the `listLoyaltyPoints` method. If the customer doesn't have existing points or if the points to deduct are greater than the existing points, you throw an error.
-
-Otherwise, you update the customer's loyalty points with the new value using the `updateLoyaltyPoints` method, which is automatically generated by `MedusaService`.
-
-Next, you'll add the method that retrieves the points of a customer. Add the following method to the `LoyaltyModuleService`:
-
-```ts title="src/modules/loyalty/service.ts"
-class LoyaltyModuleService extends MedusaService({
-  LoyaltyPoint,
-}) {
-  // ...
-  async getPoints(customerId: string): Promise<number> {
-    const points = await this.listLoyaltyPoints({
-      customer_id: customerId,
-    })
-
-    return points[0]?.points || 0
-  }
-}
-```
-
-The `getPoints` method accepts the customer ID and retrieves the customer's loyalty points using the `listLoyaltyPoints` method. If the customer has no points, it returns `0`.
-
-#### Add Method to Map Points to Discount
-
-Finally, you'll add a method that implements the logic of mapping loyalty points to a discount amount. This is useful when the customer wants to redeem their points during checkout.
-
-The mapping logic may differ for each use case. For example, you may need to use a third-party service to map the loyalty points discount amount, or use some custom calculation.
-
-To simplify the logic in this tutorial, you'll use a simple calculation that maps 1 point to 1 currency unit. For example, `100` points = `$100` discount.
-
-Add the following method to the `LoyaltyModuleService`:
-
-```ts title="src/modules/loyalty/service.ts"
-class LoyaltyModuleService extends MedusaService({
-  LoyaltyPoint,
-}) {
-  // ...
-  async calculatePointsFromAmount(amount: number): Promise<number> {
-    // Convert amount to points using a standard conversion rate
-    // For example, $1 = 1 point
-    // Round down to nearest whole point
-    const points = Math.floor(amount)
-
-    if (points < 0) {
-      throw new MedusaError(
-        MedusaError.Types.INVALID_DATA,
-        "Amount cannot be negative"
-      )
-    }
-
-    return points
-  }
-}
-```
-
-The `calculatePointsFromAmount` method accepts the amount and converts it to the nearest whole number of points. If the amount is negative, it throws an error.
-
-You'll use this method later to calculate the amount discounted when a customer redeems their loyalty points.
-
-### Export Module Definition
-
-The final piece to a module is its definition, which you export in an `index.ts` file at its root directory. This definition tells Medusa the name of the module and its service.
-
-So, create the file `src/modules/loyalty/index.ts` with the following content:
-
-```ts title="src/modules/loyalty/index.ts"
-import { Module } from "@medusajs/framework/utils"
-import LoyaltyModuleService from "./service"
-
-export const LOYALTY_MODULE = "loyalty"
-
-export default Module(LOYALTY_MODULE, {
-  service: LoyaltyModuleService,
-})
-```
-
-You use the `Module` function from the Modules SDK to create the module's definition. It accepts two parameters:
-
-1. The module's name, which is `loyalty`.
-2. An object with a required property `service` indicating the module's service.
-
-You also export the module's name as `LOYALTY_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/loyalty",
-    },
-  ],
-})
-```
-
-Each object in the `modules` array has a `resolve` property, whose value is either a path to the module's directory, or an `npm` package’s name.
-
-### Generate Migrations
-
-Since data models represent tables in the database, you define how they're created in the database with migrations. A migration is a TypeScript or JavaScript file that defines database changes made by a module.
-
-Refer to the [Migrations documentation](https://docs.medusajs.com/docs/learn/fundamentals/modules#5-generate-migrations/index.html.md) to learn more.
-
-Medusa's CLI tool can generate the migrations for you. To generate a migration for the Loyalty Module, run the following command in your Medusa application's directory:
-
-```bash
-npx medusa db:generate loyalty
-```
-
-The `db:generate` command of the Medusa CLI accepts the name of the module to generate the migration for. You'll now have a `migrations` directory under `src/modules/loyalty` that holds the generated migration.
-
-Then, to reflect these migrations on the database, run the following command:
-
-```bash
-npx medusa db:migrate
-```
-
-The table for the `LoyaltyPoint` data model is now created in the database.
-
-***
-
-## Step 3: Change Loyalty Points Flow
-
-Now that you have a module that stores and manages loyalty points in the database, you'll start building flows around it that allow customers to earn and redeem points.
-
-The first flow you'll build will either add points to a customer's loyalty points or deduct them based on a purchased order. If the customer hasn't redeemed points, the points are added to their loyalty points. Otherwise, the points are deducted from their loyalty points.
-
-To build custom commerce features in Medusa, you create a [workflow](https://docs.medusajs.com/docs/learn/fundamentals/workflows/index.html.md). A workflow is a series of queries and actions, called steps, that complete a task. You construct a workflow like you construct a function, but it's a special function that allows you to track its executions' progress, define roll-back logic, and configure other advanced features. Then, you execute the workflow from other customizations, such as in an endpoint.
-
-In this section, you'll build the workflow that adds or deducts loyalty points for an order's customer. Later, you'll execute this workflow when an order is placed.
-
-Learn more about workflows in the [Workflows documentation](https://docs.medusajs.com/docs/learn/fundamentals/workflows/index.html.md).
-
-The workflow will have the following steps:
-
-- [useQueryGraphStep](https://docs.medusajs.com/references/helper-steps/useQueryGraphStep/index.html.md): Retrieve the order's details.
-- [validateCustomerExistsStep](#validateCustomerExistsStep): Validate that the customer is registered.
-- [getCartLoyaltyPromoStep](#getCartLoyaltyPromoStep): Retrieve the cart's loyalty promotion.
-
-Medusa provides the `useQueryGraphStep` and `updatePromotionsStep` in its `@medusajs/medusa/core-flows` package. So, you'll only implement the other steps.
-
-### validateCustomerExistsStep
-
-In the workflow, you first need to validate that the customer is registered. Only registered customers can earn and redeem loyalty points.
-
-To do this, create the file `src/workflows/steps/validate-customer-exists.ts` with the following content:
-
-```ts title="src/workflows/steps/validate-customer-exists.ts"
-import { CustomerDTO } from "@medusajs/framework/types"
-import { createStep } from "@medusajs/framework/workflows-sdk"
-import { MedusaError } from "@medusajs/framework/utils"
-
-export type ValidateCustomerExistsStepInput = {
-  customer: CustomerDTO | null | undefined
-}
-
-export const validateCustomerExistsStep = createStep(
-  "validate-customer-exists",
-  async ({ customer }: ValidateCustomerExistsStepInput) => {
-    if (!customer) {
-      throw new MedusaError(
-        MedusaError.Types.INVALID_DATA, 
-        "Customer not found"
-      )
-    }
-
-    if (!customer.has_account) {
-      throw new MedusaError(
-        MedusaError.Types.INVALID_DATA, 
-        "Customer must have an account to earn or manage points"
-      )
-    }
-  }
-)
-```
-
-You create a step with `createStep` from the Workflows SDK. It accepts two parameters:
-
-1. The step's unique name, which is `validate-customer-exists`.
-2. An async function that receives two parameters:
-   - The step's input, which is in this case an object with the customer's details.
-   - 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 validate that the customer is defined and that it's registered based on its `has_account` property. Otherwise, you throw an error.
-
-### getCartLoyaltyPromoStep
-
-Next, you'll need to retrieve the loyalty promotion applied on the cart, if there's any. This is useful to determine whether the customer has redeemed points.
-
-Before you create a step, you'll create a utility function that the step uses to retrieve the loyalty promotion of a cart. You'll create it as a separate utility function to use it later in other customizations.
-
-Create the file `src/utils/promo.ts` with the following content:
-
-```ts title="src/utils/promo.ts"
-import { PromotionDTO, CustomerDTO, CartDTO } from "@medusajs/framework/types"
-
-export type CartData = CartDTO & {
-  promotions?: PromotionDTO[]
-  customer?: CustomerDTO
-  metadata: {
-    loyalty_promo_id?: string
-  }
-}
-
-export function getCartLoyaltyPromotion(
-  cart: CartData
-): PromotionDTO | undefined {
-  if (!cart?.metadata?.loyalty_promo_id) {
-    return
-  }
-
-  return cart.promotions?.find(
-    (promotion) => promotion.id === cart.metadata.loyalty_promo_id
-  )
-}
-```
-
-You create a `getCartLoyaltyPromotion` function that accepts the cart's details as an input and returns the loyalty promotion if it exists. You retrieve the loyalty promotion if its ID is stored in the cart's `metadata.loyalty_promo_id` property.
-
-You can now create the step that uses this utility to retrieve a carts loyalty points promotion. To create the step, create the file `src/workflows/steps/get-cart-loyalty-promo.ts` with the following content:
-
-```ts title="src/workflows/steps/get-cart-loyalty-promo.ts"
-import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk"
-import { CartData, getCartLoyaltyPromotion } from "../../utils/promo"
-import { MedusaError } from "@medusajs/framework/utils"
-
-type GetCartLoyaltyPromoStepInput = {
-  cart: CartData,
-  throwErrorOn?: "found" | "not-found"
-}
-
-export const getCartLoyaltyPromoStep = createStep(
-  "get-cart-loyalty-promo",
-  async ({ cart, throwErrorOn }: GetCartLoyaltyPromoStepInput) => {
-    const loyaltyPromo = getCartLoyaltyPromotion(cart)
-
-    if (throwErrorOn === "found" && loyaltyPromo) {
-      throw new MedusaError(
-        MedusaError.Types.INVALID_DATA,
-        "Loyalty promotion already applied to cart"
-      )
-    } else if (throwErrorOn === "not-found" && !loyaltyPromo) {
-      throw new MedusaError(
-        MedusaError.Types.INVALID_DATA,
-        "No loyalty promotion found on cart"
-      )
-    }
-
-    return new StepResponse(loyaltyPromo)
-  }
-)
-```
-
-You create a step that accepts an object having the following properties:
-
-- `cart`: The cart's details.
-- `throwErrorOn`: An optional property that indicates whether to throw an error if the loyalty promotion is found or not found.
-
-The `throwErrorOn` property is useful to make the step reusable in different scenarios, allowing you to use it in later workflows.
-
-In the step, you call the `getCartLoyaltyPromotion` utility to retrieve the loyalty promotion. If the `throwErrorOn` property is set to `found` and the loyalty promotion is found, you throw an error.
-
-Otherwise, if the `throwErrorOn` property is set to `not-found` and the loyalty promotion is not found, you throw an error.
-
-To return data from a step, you return an instance of `StepResponse` from the Workflows SDK. It accepts as a parameter the data to return, which is the loyalty promotion in this case.
-
-### deductPurchasePointsStep
-
-If the order's cart has a loyalty promotion, you need to deduct points from the customer's loyalty points. To do this, create the file `src/workflows/steps/deduct-purchase-points.ts` with the following content:
-
-```ts title="src/workflows/steps/deduct-purchase-points.ts" highlights={deductStepHighlights} collapsibleLines="1-7" expandButtonLabel="Show Imports"
-import { 
-  createStep,
-  StepResponse, 
-} from "@medusajs/framework/workflows-sdk"
-import { LOYALTY_MODULE } from "../../modules/loyalty"
-import LoyaltyModuleService from "../../modules/loyalty/service"
-
-type DeductPurchasePointsInput = {
-  customer_id: string
-  amount: number
-}
-
-export const deductPurchasePointsStep = createStep(
-  "deduct-purchase-points",
-  async ({ 
-    customer_id, amount,
-  }: DeductPurchasePointsInput, { container }) => {
-    const loyaltyModuleService: LoyaltyModuleService = container.resolve(
-      LOYALTY_MODULE
-    )
-
-    const pointsToDeduct = await loyaltyModuleService.calculatePointsFromAmount(
-      amount
-    )
-
-    const result = await loyaltyModuleService.deductPoints(
-      customer_id,
-      pointsToDeduct
-    )
-
-    return new StepResponse(result, {
-      customer_id,
-      points: pointsToDeduct,
-    })
-  },
-  async (data, { container }) => {
-    if (!data) {
-      return
-    }
-
-    const loyaltyModuleService: LoyaltyModuleService = container.resolve(
-      LOYALTY_MODULE
-    )
-
-    // Restore points in case of failure
-    await loyaltyModuleService.addPoints(
-      data.customer_id,
-      data.points
-    )
-  }
-)
-```
-
-You create a step that accepts an object having the following properties:
-
-- `customer_id`: The ID of the customer to deduct points from.
-- `amount`: The promotion's amount, which will be used to calculate the points to deduct.
-
-In the step, you resolve the Loyalty Module's service from the Medusa container. Then, you use the `calculatePointsFromAmount` method to calculate the points to deduct from the promotion's amount.
-
-After that, you call the `deductPoints` method to deduct the points from the customer's loyalty points.
-
-Finally, you return a `StepResponse` with the result of the `deductPoints`.
-
-#### Compensation Function
-
-This step has a compensation function, which is passed as a third parameter to the `createStep` function.
-
-The compensation function undoes the actions performed in a step. Then, if an error occurs during the workflow's execution, the compensation functions of executed steps are called to roll back the changes. This mechanism ensures data consistency in your application, especially as you integrate external systems.
-
-The compensation function accepts two parameters:
-
-1. Data passed from the step function to the compensation function. The data is passed as a second parameter of the returned `StepResponse` instance.
-2. An object that has properties including the [Medusa container](https://docs.medusajs.com/docs/learn/fundamentals/medusa-container/index.html.md).
-
-In the compensation function, you resolve the Loyalty Module's service from the Medusa container. Then, you call the `addPoints` method to restore the points deducted from the customer's loyalty points if an error occurs.
-
-### addPurchaseAsPointsStep
-
-The last step you'll create adds points to the customer's loyalty points. You'll use this step if the customer didn't redeem points during checkout.
-
-To create the step, create the file `src/workflows/steps/add-purchase-as-points.ts` with the following content:
-
-```ts title="src/workflows/steps/add-purchase-as-points.ts" highlights={addPointsHighlights} collapsibleLines="1-7" expandButtonLabel="Show Imports"
-import {
-  createStep,
-  StepResponse,
-} from "@medusajs/framework/workflows-sdk"
-import { LOYALTY_MODULE } from "../../modules/loyalty"
-import LoyaltyModuleService from "../../modules/loyalty/service"
-
-type StepInput = {
-  customer_id: string
-  amount: number
-}
-
-export const addPurchaseAsPointsStep = createStep(
-  "add-purchase-as-points",
-  async (input: StepInput, { container }) => {
-    const loyaltyModuleService: LoyaltyModuleService = container.resolve(
-      LOYALTY_MODULE
-    )
-
-    const pointsToAdd = await loyaltyModuleService.calculatePointsFromAmount(
-      input.amount
-    )
-
-    const result = await loyaltyModuleService.addPoints(
-      input.customer_id,
-      pointsToAdd
-    )
-
-    return new StepResponse(result, {
-      customer_id: input.customer_id,
-      points: pointsToAdd,
-    })
-  },
-  async (data, { container }) => {
-    if (!data) {
-      return
-    }
-
-    const loyaltyModuleService: LoyaltyModuleService = container.resolve(
-      LOYALTY_MODULE
-    )
-
-    await loyaltyModuleService.deductPoints(
-      data.customer_id,
-      data.points
-    )
-  }
-)
-```
-
-You create a step that accepts an object having the following properties:
-
-- `customer_id`: The ID of the customer to add points to.
-- `amount`: The order's amount, which will be used to calculate the points to add.
-
-In the step, you resolve the Loyalty Module's service from the Medusa container. Then, you use the `calculatePointsFromAmount` method to calculate the points to add from the order's amount.
-
-After that, you call the `addPoints` method to add the points to the customer's loyalty points.
-
-Finally, you return a `StepResponse` with the result of the `addPoints`.
-
-You also pass to the compensation function the customer's ID and the points added. In the compensation function, you deduct the points if an error occurs.
-
-### Add Utility Functions
-
-Before you create the workflow, you need a utility function that checks whether an order's cart has a loyalty promotion. This is useful to determine whether the customer redeemed points during checkout, allowing you to decide which steps to execute.
-
-To add the utility function, add the following to `src/utils/promo.ts`:
-
-```ts title="src/utils/promo.ts"
-import { OrderDTO } from "@medusajs/framework/types"
-
-export type OrderData = OrderDTO & {
-  promotion?: PromotionDTO[]
-  customer?: CustomerDTO
-  cart?: CartData
-}
-
-export const CUSTOMER_ID_PROMOTION_RULE_ATTRIBUTE = "customer_id"
-
-export function orderHasLoyaltyPromotion(order: OrderData): boolean {
-  const loyaltyPromotion = getCartLoyaltyPromotion(
-    order.cart as unknown as CartData
-  )
-
-  return loyaltyPromotion?.rules?.some((rule) => {
-    return rule?.attribute === CUSTOMER_ID_PROMOTION_RULE_ATTRIBUTE && (
-      rule?.values?.some((value) => value.value === order.customer?.id) || false
-    )
-  }) || false
-}
-```
-
-You first define an `OrderData` type that extends the `OrderDTO` type. This type has the order's details, including the cart, customer, and promotions details.
-
-Then, you define a constant `CUSTOMER_ID_PROMOTION_RULE_ATTRIBUTE` that represents the attribute used in the promotion rule to check whether the customer ID is valid.
-
-Finally, you create the `orderHasLoyaltyPromotion` function that accepts an order's details and checks whether it has a loyalty promotion. It returns `true` if:
-
-- The order's cart has a loyalty promotion. You use the `getCartLoyaltyPromotion` utility to try to retrieve the loyalty promotion.
-- The promotion's rules include the `customer_id` attribute and its value matches the order's customer ID.
-  - When you create the promotion for the cart later, you'll see how to set this rule.
-
-You'll use this utility in the workflow next.
-
-### Create the Workflow
-
-Now that you have all the steps, you can create the workflow that uses them.
-
-To create the workflow, create the file `src/workflows/handle-order-points.ts` with the following content:
-
-```ts title="src/workflows/handle-order-points.ts" highlights={handleOrderPointsHighlights} collapsibleLines="1-9" expandButtonLabel="Show Imports"
-import { createWorkflow, when } from "@medusajs/framework/workflows-sdk"
-import { updatePromotionsStep, useQueryGraphStep } from "@medusajs/medusa/core-flows"
-import { validateCustomerExistsStep, ValidateCustomerExistsStepInput } from "./steps/validate-customer-exists"
-import { deductPurchasePointsStep } from "./steps/deduct-purchase-points"
-import { addPurchaseAsPointsStep } from "./steps/add-purchase-as-points"
-import { OrderData, CartData } from "../utils/promo"
-import { orderHasLoyaltyPromotion } from "../utils/promo"
-import { getCartLoyaltyPromoStep } from "./steps/get-cart-loyalty-promo"
-
-type WorkflowInput = {
-  order_id: string
-}
-
-export const handleOrderPointsWorkflow = createWorkflow(
-  "handle-order-points",
-  ({ order_id }: WorkflowInput) => {
-    // @ts-ignore
-    const { data: orders } = useQueryGraphStep({
-      entity: "order",
-      fields: [
-        "id", 
-        "customer.*", 
-        "total", 
-        "cart.*",
-        "cart.promotions.*",
-        "cart.promotions.rules.*",
-        "cart.promotions.rules.values.*",
-        "cart.promotions.application_method.*",
-      ],
-      filters: {
-        id: order_id,
-      },
-      options: {
-        throwIfKeyNotFound: true,
-      },
-    })
-
-    validateCustomerExistsStep({
-      customer: orders[0].customer,
-    } as ValidateCustomerExistsStepInput)
-
-    const loyaltyPointsPromotion = getCartLoyaltyPromoStep({
-      cart: orders[0].cart as unknown as CartData,
-    })
-
-    when(orders, (orders) => 
-      orderHasLoyaltyPromotion(orders[0] as unknown as OrderData) && 
-      loyaltyPointsPromotion !== undefined
-    )
-    .then(() => {
-      deductPurchasePointsStep({
-        customer_id: orders[0].customer!.id,
-        amount: loyaltyPointsPromotion.application_method!.value as number,
-      })
-
-      updatePromotionsStep([
-        {
-          id: loyaltyPointsPromotion.id,
-          status: "inactive",
-        },
-      ])
-    })
-
-
-    when(
-      orders, 
-      (order) => !orderHasLoyaltyPromotion(order[0] as unknown as OrderData)
-    )
-    .then(() => {
-      addPurchaseAsPointsStep({
-        customer_id: orders[0].customer!.id,
-        amount: orders[0].total,
-      })
-    })
-  }
-)
-```
-
-You create a workflow using `createWorkflow` from the Workflows SDK. It accepts the workflow's unique name as a first parameter.
-
-It accepts as a second parameter a constructor function, which is the workflow's implementation. The function can accept input, which in this case is an object with the order's ID.
-
-In the workflow's constructor function, you:
-
-- Use `useQueryGraphStep` to retrieve the order's details. You pass the order's ID as a filter to retrieve the order.
-  - This step uses [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), which is a tool that retrieves data across modules.
-- Validate that the customer is registered using the `validateCustomerExistsStep`.
-- Retrieve the cart's loyalty promotion using the `getCartLoyaltyPromoStep`.
-- Use `when` to check whether the order's cart has a loyalty promotion.
-  - Since you can't perform data manipulation in a workflow's constructor function, `when` allows you to perform steps if a condition is satisfied.
-  - You pass as a first parameter the object to perform the condition on, which is the order in this case. In the second parameter, you pass a function that returns a boolean value, indicating whether the condition is satisfied.
-  - To specify the steps to perform if a condition is satisfied, you chain a `then` method to the `when` method. You can perform any step within the `then` method.
-  - In this case, if the order's cart has a loyalty promotion, you call the `deductPurchasePointsStep` to deduct points from the customer's loyalty points. You also call the `updatePromotionsStep` to deactivate the cart's loyalty promotion.
-- You use another `when` to check whether the order's cart doesn't have a loyalty promotion.
-  - If the condition is satisfied, you call the `addPurchaseAsPointsStep` to add points to the customer's loyalty points.
-
-You'll use this workflow next when an order is placed.
-
-To learn more about the constraints on a workflow's constructor function, refer to the [Workflow Constraints](https://docs.medusajs.com/docs/learn/fundamentals/workflows/constructor-constraints/index.html.md) documentation. Refer to the [When-Then](https://docs.medusajs.com/docs/learn/fundamentals/workflows/conditions/index.html.md) documentation to learn more about the `when` method and how to use it in a workflow.
-
-***
-
-## Step 4: Handle Order Placed Event
-
-Now that you have the workflow that handles adding or deducting loyalty points for an order, you need to execute it when an order is placed.
-
-Medusa has an event system that allows you to listen to events emitted by the Medusa server using a [subscriber](https://docs.medusajs.com/docs//learn/fundamentals/events-and-subscribers/index.html.md). A subscriber is an asynchronous function that's executed when its associated event is emitted. In a subscriber, you can execute a workflow that performs actions in result of the event.
-
-In this step, you'll create a subscriber that listens to the `order.placed` event and executes the `handleOrderPointsWorkflow` workflow.
-
-Refer to the [Events and Subscribers](https://docs.medusajs.com/docs/learn/fundamentals/events-and-subscribers/index.html.md) documentation to learn more.
-
-Subscribers are created in a TypeScript or JavaScript file under the `src/subscribers` directory. So, to create a subscriber, create the fle `src/subscribers/order-placed.ts` with the following content:
-
-```ts title="src/subscribers/order-placed.ts"
-import type {
-  SubscriberArgs,
-  SubscriberConfig,
-} from "@medusajs/framework"
-import { handleOrderPointsWorkflow } from "../workflows/handle-order-points"
-
-export default async function orderPlacedHandler({
-  event: { data },
-  container,
-}: SubscriberArgs<{ id: string }>) {
-  await handleOrderPointsWorkflow(container).run({
-    input: {
-      order_id: data.id,
-    },
-  })
-}
-
-export const config: SubscriberConfig = {
-  event: "order.placed",
-}
-```
-
-The subscriber file must export:
-
-- 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 accepts an object with the following properties:
-
-- `event`: An object with the event's data payload. For example, the `order.placed` event has the order's ID in its data payload.
-- `container`: The Medusa container, which you can use to resolve services and tools.
-
-In the subscriber function, you execute the `handleOrderPointsWorkflow` by invoking it, passing it the Medusa container, then using its `run` method, passing it the workflow's input.
-
-Whenever an order is placed now, the subscriber will be executed, which in turn will execute the workflow that handles the loyalty points flow.
-
-### Test it Out
-
-To test out the loyalty points flow, you'll use the [Next.js Starter Storefront](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/nextjs-starter/index.html.md) that you installed in the first step. As mentioned in that step, the storefront will be installed in a separate directory from the Medusa application, and its name is `{project-name}-storefront`, where `{project-name}` is the name of your Medusa application's directory.
-
-So, run the following command in the Medusa application's directory to start the Medusa server:
-
-```bash npm2yarn badgeLabel="Medusa Application" badgeColor="green"
-npm run dev
-```
-
-Then, run the following command in the Next.js Starter Storefront's directory to start the Next.js server:
-
-```bash npm2yarn badgeLabel="Storefront" badgeColor="blue"
-npm run dev
-```
-
-The Next.js Starter Storefront will be running on `http://localhost:8000`, and the Medusa server will be running on `http://localhost:9000`.
-
-Open the Next.js Starter Storefront in your browser and create a new account by going to Account at the top right.
-
-Once you're logged in, add an item to the cart and go through the checkout flow.
-
-After you place the order, you'll see the following message in your Medusa application's terminal:
-
-```bash
-info:    Processing order.placed which has 1 subscribers
-```
-
-This message indicates that the `order.placed` event was emitted, and that your subscriber was executed.
-
-Since you didn't redeem any points during checkout, loyalty points will be added to your account. You'll implement an API route that allows you to retrieve the loyalty points in the next step.
-
-***
-
-## Step 5: Retrieve Loyalty Points API Route
-
-Next, you want to allow customers to view their loyalty points. You can show them on their profile page, or during checkout.
-
-To expose a feature to clients, you create an [API route](https://docs.medusajs.com/docs/learn/fundamentals/api-routes/index.html.md). An API Route is an endpoint that exposes commerce features to external applications and clients, such as storefronts.
-
-You'll create an API route at the path `/store/customers/me/loyalty-points` that returns the loyalty points of the authenticated customer.
-
-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 `/store/customers/me/loyalty-points`, create the file `src/api/store/customers/me/loyalty-points/route.ts` with the following content:
-
-```ts title="src/api/store/customers/me/loyalty-points/route.ts"
-
-import { 
-  AuthenticatedMedusaRequest, 
-  MedusaResponse,
-} from "@medusajs/framework/http"
-import { LOYALTY_MODULE } from "../../../../../modules/loyalty"
-import LoyaltyModuleService from "../../../../../modules/loyalty/service"
-
-export async function GET(
-  req: AuthenticatedMedusaRequest,
-  res: MedusaResponse
-) {
-  const loyaltyModuleService: LoyaltyModuleService = req.scope.resolve(
-    LOYALTY_MODULE
-  )
-
-  const points = await loyaltyModuleService.getPoints(
-    req.auth_context.actor_id
-  )
-
-  res.json({
-    points,
-  })
-}
-```
-
-Since you export a `GET` route handler function, you're exposing a `GET` endpoint at `/store/customers/me/loyalty-points`.  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.
-
-In the route handler, you resolve the Loyalty Module's service from the Medusa container (which is available at `req.scope`).
-
-Then, you call the service's `getPoints` method to retrieve the authenticated customer's loyalty points. Note that routes starting with `/store/customers/me` are only accessible by authenticated customers. You can access the authenticated customer ID from the request's context, which is available at `req.auth_context.actor_id`.
-
-Finally, you return the loyalty points in the response.
-
-You'll test out this route as you customize the Next.js Starter Storefront next.
-
-***
-
-## Step 6: Show Loyalty Points During Checkout
-
-Now that you have the API route to retrieve the loyalty points, you can show them during checkout.
-
-In this step, you'll customize the Next.js Starter Storefront to show the loyalty points in the checkout page.
-
-First, you'll add a server action function that retrieves the loyalty points from the route you created earlier. In `src/lib/data/customer.ts`, add the following function:
-
-```ts title="src/lib/data/customer.ts" badgeLabel="Storefront" badgeColor="blue"
-export const getLoyaltyPoints = async () => {
-  const headers = {
-    ...(await getAuthHeaders()),
-  }
-
-  return sdk.client.fetch<{ points: number }>(
-    `/store/customers/me/loyalty-points`,
-    {
-      method: "GET",
-      headers,
-    }
-  )
-    .then(({ points }) => points)
-    .catch(() => null)
-}
-```
-
-You add a `getLoyaltyPoints` function that retrieves the authenticated customer's loyalty points from the API route you created earlier. You pass the authentication headers using the `getAuthHeaders` function, which is a utility function defined in the Next.js Starter Storefront.
-
-If the customer isn't authenticated, the request will fail. So, you catch the error and return `null` in that case.
-
-Next, you'll create a component that shows the loyalty points in the checkout page. Create the file `src/modules/checkout/components/loyalty-points/index.tsx` with the following content:
-
-```tsx title="src/modules/checkout/components/loyalty-points/index.tsx" badgeLabel="Storefront" badgeColor="blue" highlights={loyaltyPointsHighlights}
-"use client"
-
-import { HttpTypes } from "@medusajs/types"
-import { useEffect, useMemo, useState } from "react"
-import { getLoyaltyPoints } from "../../../../lib/data/customer"
-import { Button, Heading } from "@medusajs/ui"
-import Link from "next/link"
-
-type LoyaltyPointsProps = {
-  cart: HttpTypes.StoreCart & {
-    promotions: HttpTypes.StorePromotion[]
-  }
-}
-
-const LoyaltyPoints = ({ cart }: LoyaltyPointsProps) => {
-  const isLoyaltyPointsPromoApplied = useMemo(() => {
-    return cart.promotions.find(
-      (promo) => promo.id === cart.metadata?.loyalty_promo_id
-    ) !== undefined
-  }, [cart])
-  const [loyaltyPoints, setLoyaltyPoints] = useState<
-    number | null
-  >(null)
-
-  useEffect(() => {
-    getLoyaltyPoints()
-    .then((points) => {
-      console.log(points)
-      setLoyaltyPoints(points)
-    })
-  }, [])
-
-  const handleTogglePromotion = async (
-    e: React.MouseEvent<HTMLButtonElement, MouseEvent>
-  ) => {
-    e.preventDefault()
-    // TODO apply or remove loyalty promotion
-  }
-
-  return (
-    <>
-      <div className="h-px w-full border-b border-gray-200 my-4" />
-      <div className="flex flex-col">
-        <Heading className="txt-medium mb-2">
-          Loyalty Points
-        </Heading>
-        {loyaltyPoints === null && (
-          <Link href="/account" className="txt-medium text-ui-fg-interactive hover:text-ui-fg-interactive-hover">
-            Sign up to get and use loyalty points
-          </Link>
-        )}
-        {loyaltyPoints !== null && (
-          <div className="flex items-center justify-between my-6 gap-1">
-          <Button
-            variant="secondary"
-            className="w-1/2"
-            onClick={handleTogglePromotion}
-          >
-            {isLoyaltyPointsPromoApplied ? "Remove" : "Apply"} Loyalty Points
-          </Button>
-          <span className="txt-medium text-ui-fg-subtle">
-            You have {loyaltyPoints} loyalty points
-          </span>
-        </div>
-        )}
-      </div>
-    </>
-  )
-}
-
-export default LoyaltyPoints
-```
-
-You create a `LoyaltyPoints` component that accepts the cart's details as a prop. In the component, you:
-
-- Create a `isLoyaltyPointsPromoApplied` memoized value that checks whether the cart has a loyalty promotion applied. You use the `cart.metadata.loyalty_promo_id` property to check this.
-- Create a `loyaltyPoints` state to store the customer's loyalty points.
-- Call the `getLoyaltyPoints` function in a `useEffect` hook to retrieve the loyalty points from the API route you created earlier. You set the `loyaltyPoints` state with the retrieved points.
-- Define `handleTogglePromotion` that, when clicked, would either apply or remove the promotion. You'll implement these functionalities later.
-- Render the loyalty points in the component. If the customer isn't authenticated, you show a link to the account page to sign up. Otherwise, you show the loyalty points and a button to apply or remove the promotion.
-
-Next, you'll show this component at the end of the checkout's summary component. So, import the component in `src/modules/checkout/templates/checkout-summary/index.tsx`:
-
-```tsx title="src/modules/checkout/templates/checkout-summary/index.tsx" badgeLabel="Storefront" badgeColor="blue"
-import LoyaltyPoints from "../../components/loyalty-points"
-```
-
-Then, in the return statement of the `CheckoutSummary` component, add the following after the `div` wrapping the `DiscountCode`:
-
-```tsx title="src/modules/checkout/templates/checkout-summary/index.tsx" badgeLabel="Storefront" badgeColor="blue"
-<LoyaltyPoints cart={cart} />
-```
-
-This will show the loyalty points component at the end of the checkout summary.
-
-### Test it Out
-
-To test out the customizations to the checkout flow, make sure both the Medusa application and Next.js Starter Storefront are running.
-
-Then, as an authenticated customer, add an item to cart and proceed to checkout. You'll find a new "Loyalty Points" section at the end of the checkout summary.
-
-![Loyalty Points Section at the end of the summary section at the right](https://res.cloudinary.com/dza7lstvk/image/upload/v1744195223/Medusa%20Resources/Screenshot_2025-04-09_at_1.39.34_PM_l5oltc.png)
-
-If you made a purchase before, you can see your loyalty points. You'll also see the "Apply Loyalty Points" button, which doesn't yet do anything. You'll add the functionality next.
-
-***
-
-## Step 7: Apply Loyalty Points to Cart
-
-The next feature you'll implement allows the customer to apply their loyalty points during checkout. To implement the feature, you need:
-
-- A workflow that implements the steps of the apply loyalty points flow.
-- An API route that exposes the workflow's functionality to clients. You'll then send a request to this API route to apply the loyalty points on the customer's cart.
-- A function in the Next.js Starter Storefront that sends the request to the API route you created earlier.
-
-The workflow will have the following steps:
-
-- [useQueryGraphStep](https://docs.medusajs.com/references/helper-steps/useQueryGraphStep/index.html.md): Retrieve the cart's details.
-- [validateCustomerExistsStep](#validateCustomerExistsStep): Validate that the customer is registered.
-- [getCartLoyaltyPromoStep](#getCartLoyaltyPromoStep): Retrieve the cart's loyalty promotion.
-- [getCartLoyaltyPromoAmountStep](#getCartLoyaltyPromoAmountStep): Get the amount to be discounted based on the loyalty points.
-- [createPromotionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/createPromotionsStep/index.html.md): Create a new loyalty promotion for the cart.
-- [updateCartPromotionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/workflows/updateCartPromotionsWorkflow/index.html.md): Update the cart's promotions with the new loyalty promotion.
-- [updateCartsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateCartsStep/index.html.md): Update the cart to store the ID of the loyalty promotion in the metadata.
-- [useQueryGraphStep](https://docs.medusajs.com/references/helper-steps/useQueryGraphStep/index.html.md): Retrieve the cart's details again.
-
-Most of the workflow's steps are either provided by Medusa in the `@medusajs/medusa/core-flows` package or steps you've already implemented. You only need to implement the `getCartLoyaltyPromoAmountStep` step.
-
-### getCartLoyaltyPromoAmountStep
-
-The fourth step in the workflow is the `getCartLoyaltyPromoAmountStep`, which retrieves the amount to be discounted based on the loyalty points. This step is useful to determine how much discount to apply to the cart.
-
-To create the step, create the file `src/workflows/steps/get-cart-loyalty-promo-amount.ts` with the following content:
-
-```ts title="src/workflows/steps/get-cart-loyalty-promo-amount.ts" highlights={getCartLoyaltyPromoAmountStepHighlights}
-import { PromotionDTO, CustomerDTO } from "@medusajs/framework/types"
-import { MedusaError } from "@medusajs/framework/utils"
-import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk"
-import LoyaltyModuleService from "../../modules/loyalty/service"
-import { LOYALTY_MODULE } from "../../modules/loyalty"
-
-export type GetCartLoyaltyPromoAmountStepInput = {
-  cart: {
-    id: string
-    customer: CustomerDTO
-    promotions?: PromotionDTO[]
-    total: number
-  }
-}
-
-export const getCartLoyaltyPromoAmountStep = createStep(
-  "get-cart-loyalty-promo-amount",
-  async ({ cart }: GetCartLoyaltyPromoAmountStepInput, { container }) => {
-    // Check if customer has any loyalty points
-    const loyaltyModuleService: LoyaltyModuleService = container.resolve(
-      LOYALTY_MODULE
-    )
-    const loyaltyPoints = await loyaltyModuleService.getPoints(
-      cart.customer.id
-    )
-
-    if (loyaltyPoints <= 0) {
-      throw new MedusaError(
-        MedusaError.Types.INVALID_DATA,
-        "Customer has no loyalty points"
-      )
-    }
-    
-    const pointsAmount = await loyaltyModuleService.calculatePointsFromAmount(
-      loyaltyPoints
-    )
-
-    const amount = Math.min(pointsAmount, cart.total)
-
-    return new StepResponse(amount)
-  }
-)
-```
-
-You create a step that accepts an object having the cart's details.
-
-In the step, you resolve the Loyalty Module's service from the Medusa container. Then, you call the `getPoints` method to retrieve the customer's loyalty points. If the customer has no loyalty points, you throw an error.
-
-Next, you call the `calculatePointsFromAmount` method to calculate the amount to be discounted based on the loyalty points. You use the `Math.min` function to ensure that the amount doesn't exceed the cart's total.
-
-Finally, you return a `StepResponse` with the amount to be discounted.
-
-### Create the Workflow
-
-You can now create the workflow that applies a loyalty promotion to the cart.
-
-To create the workflow, create the file `src/workflows/apply-loyalty-on-cart.ts` with the following content:
-
-```ts title="src/workflows/apply-loyalty-on-cart.ts" highlights={applyLoyaltyOnCartWorkflowHighlights} collapsibleLines="1-24" expandButtonLabel="Show Imports"
-import {
-  createWorkflow,
-  transform,
-  WorkflowResponse,
-} from "@medusajs/framework/workflows-sdk"
-import { 
-  createPromotionsStep, 
-  updateCartPromotionsWorkflow, 
-  updateCartsStep, 
-  useQueryGraphStep,
-} from "@medusajs/medusa/core-flows"
-import { 
-  validateCustomerExistsStep, 
-  ValidateCustomerExistsStepInput,
-} from "./steps/validate-customer-exists"
-import { 
-  getCartLoyaltyPromoAmountStep, 
-  GetCartLoyaltyPromoAmountStepInput,
-} from "./steps/get-cart-loyalty-promo-amount"
-import { CartData, CUSTOMER_ID_PROMOTION_RULE_ATTRIBUTE } from "../utils/promo"
-import { CreatePromotionDTO } from "@medusajs/framework/types"
-import { PromotionActions } from "@medusajs/framework/utils"
-import { getCartLoyaltyPromoStep } from "./steps/get-cart-loyalty-promo"
-
-type WorkflowInput = {
-  cart_id: string
-}
-
-const fields = [
-  "id",
-  "customer.*",
-  "promotions.*",
-  "promotions.application_method.*",
-  "promotions.rules.*",
-  "promotions.rules.values.*",
-  "currency_code",
-  "total",
-  "metadata",
-]
-
-export const applyLoyaltyOnCartWorkflow = createWorkflow(
-  "apply-loyalty-on-cart",
-  (input: WorkflowInput) => {
-    // @ts-ignore
-    const { data: carts } = useQueryGraphStep({
-      entity: "cart",
-      fields,
-      filters: {
-        id: input.cart_id,
-      },
-      options: {
-        throwIfKeyNotFound: true,
-      },
-    })
-
-    validateCustomerExistsStep({
-      customer: carts[0].customer,
-    } as ValidateCustomerExistsStepInput)
-
-    getCartLoyaltyPromoStep({
-      cart: carts[0] as unknown as CartData,
-      throwErrorOn: "found",
-    })
-
-    const amount = getCartLoyaltyPromoAmountStep({
-      cart: carts[0],
-    } as unknown as GetCartLoyaltyPromoAmountStepInput)
-
-    // TODO create and apply the promotion on the cart
-  }
-)
-```
-
-You create a workflow that accepts an object with the cart's ID as input.
-
-So far, you:
-
-- Use `useQueryGraphStep` to retrieve the cart's details. You pass the cart's ID as a filter to retrieve the cart.
-- Validate that the customer is registered using the `validateCustomerExistsStep`.
-- Check whether the cart has a loyalty promotion using the `getCartLoyaltyPromoStep`. You pass the `throwErrorOn` parameter with the value `found` to throw an error if a loyalty promotion is found in the cart.
-- Retrieve the amount to be discounted based on the loyalty points using the `getCartLoyaltyPromoAmountStep`.
-
-Next, you need to create a new loyalty promotion for the cart. First, you'll prepare the data of the promotion to be created.
-
-Replace the `TODO` with the following:
-
-```ts title="src/workflows/apply-loyalty-on-cart.ts" highlights={prepareLoyaltyPromoDataHighlights}
-const promoToCreate = transform({
-  carts,
-  amount,
-}, (data) => {
-  const randomStr = Math.random().toString(36).substring(2, 8)
-  const uniqueId = (
-    "LOYALTY-" + data.carts[0].customer?.first_name + "-" + randomStr
-  ).toUpperCase()
-  return {
-    code: uniqueId,
-    type: "standard",
-    status: "active",
-    application_method: {
-      type: "fixed",
-      value: data.amount,
-      target_type: "order",
-      currency_code: data.carts[0].currency_code,
-      allocation: "across",
-    },
-    rules: [
-      {
-        attribute: CUSTOMER_ID_PROMOTION_RULE_ATTRIBUTE,
-        operator: "eq",
-        values: [data.carts[0].customer!.id],
-      },
-    ],
-    campaign: {
-      name: uniqueId,
-      description: "Loyalty points promotion for " + data.carts[0].customer!.email,
-      campaign_identifier: uniqueId,
-      budget: {
-        type: "usage",
-        limit: 1,
-      },
-    },
-  }
-})
-
-// TODO create promotion and apply it on cart
-```
-
-Since data manipulation isn't allowed in a workflow constructor, you use the [transform](https://docs.medusajs.com/docs/learn/fundamentals/workflows/variable-manipulation/index.html.md) function from the Workflows SDK. It accepts two parameters:
-
-- The data to perform manipulation on. In this case, you pass the cart's details and the amount to be discounted.
-- A function that receives the data from the first parameter, and returns the transformed data.
-
-In the transformation function, you prepare th data of the loyalty promotion to be created. Some key details include:
-
-- You set the discount amount in the application method of the promotion.
-- You add a rule to the promotion that ensures it can be used only in carts having their `customer_id` equal to this customer's ID. This prevents other customers from using this promotion.
-- You create a campaign for the promotion, and you set the campaign budget to a single usage. This prevents the customer from using the promotion again.
-
-Learn more about promotion concepts in the [Promotion Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/promotion/index.html.md)'s documentation.
-
-You can now use the returned data to create a promotion and apply it to the cart. Replace the new `TODO` with the following:
-
-```ts title="src/workflows/apply-loyalty-on-cart.ts" highlights={createLoyaltyPromoStepHighlights}
-const loyaltyPromo = createPromotionsStep([
-  promoToCreate,
-] as CreatePromotionDTO[])
-
-const { metadata, ...updatePromoData } = transform({
-  carts,
-  promoToCreate,
-  loyaltyPromo,
-}, (data) => {
-  const promos = [
-    ...(data.carts[0].promotions?.map((promo) => promo?.code).filter(Boolean) || []) as string[],
-    data.promoToCreate.code,
-  ]
-
-  return {
-    cart_id: data.carts[0].id,
-    promo_codes: promos,
-    action: PromotionActions.ADD,
-    metadata: {
-      loyalty_promo_id: data.loyaltyPromo[0].id,
-    },
-  }
-})
-
-updateCartPromotionsWorkflow.runAsStep({
-  input: updatePromoData,
-})
-
-updateCartsStep([
-  {
-    id: input.cart_id,
-    metadata,
-  },
-])
-
-// retrieve cart with updated promotions
-// @ts-ignore
-const { data: updatedCarts } = useQueryGraphStep({
-  entity: "cart",
-  fields,
-  filters: { id: input.cart_id },
-}).config({ name: "retrieve-cart" })
-
-return new WorkflowResponse(updatedCarts[0])
-```
-
-In the rest of the workflow, you:
-
-- Create the loyalty promotion using the data you prepared earlier using the `createPromotionsStep`.
-- Use the `transform` function to prepare the data to update the cart's promotions. You add the new loyalty promotion code to the cart's promotions codes, and set the `loyalty_promo_id` in the cart's metadata.
-- Update the cart's promotions with the new loyalty promotion using the `updateCartPromotionsWorkflow` workflow.
-- Update the cart's metadata with the loyalty promotion ID using the `updateCartsStep`.
-- Retrieve the cart's details again using `useQueryGraphStep` to get the updated cart with the new loyalty promotion.
-
-To return data from the workflow, you must return an instance of `WorkflowResponse`. You pass it the data to be returned, which is in this case the cart's details.
-
-### Create the API Route
-
-Next, you'll create the API route that executes this workflow.
-
-To create the API route, create the file `src/api/store/carts/[id]/loyalty-points/route.ts` with the following content:
-
-```ts title="src/api/store/carts/[id]/loyalty-points/route.ts"
-import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
-import { applyLoyaltyOnCartWorkflow } from "../../../../../workflows/apply-loyalty-on-cart"
-
-export async function POST(
-  req: MedusaRequest,
-  res: MedusaResponse
-) {
-  const { id: cart_id } = req.params
-
-  const { result: cart } = await applyLoyaltyOnCartWorkflow(req.scope)
-    .run({
-      input: {
-        cart_id,
-      },
-    })
-
-  res.json({ cart })
-}
-```
-
-Since you export a `POST` route handler, you expose a `POST` API route at `/store/carts/[id]/loyalty-points`.
-
-In the route handler, you execute the `applyLoyaltyOnCartWorkflow` workflow, passing it the cart ID as an input. You return the cart's details in the response.
-
-You can now use this API route in the Next.js Starter Storefront.
-
-### Apply Loyalty Points in the Storefront
-
-In the Next.js Starter Storefront, you need to add a server action function that sends a request to the API route you created earlier. Then, you'll use that function when the customer clicks the "Apply Loyalty Points" button.
-
-To add the function, add the following to `src/lib/data/cart.ts` in the Next.js Starter Storefront:
-
-```ts title="src/lib/data/cart.ts" badgeLabel="Storefront" badgeColor="blue"
-export async function applyLoyaltyPointsOnCart() {
-  const cartId = await getCartId()
-  const headers = {
-    ...(await getAuthHeaders()),
-  }
-
-  return await sdk.client.fetch<{
-    cart: HttpTypes.StoreCart & {
-      promotions: HttpTypes.StorePromotion[]
-    }
-  }>(`/store/carts/${cartId}/loyalty-points`, {
-    method: "POST",
-    headers,
-  })
-  .then(async (result) => {
-    const cartCacheTag = await getCacheTag("carts")
-    revalidateTag(cartCacheTag)
-
-    return result
-  })
-}
-```
-
-You create an `applyLoyaltyPointsOnCart` function that sends a request to the API route you created earlier.
-
-In the function, you retrieve the cart ID stored in the cookie using the `getCartId` function, which is available in the Next.js Starter Storefront.
-
-Then, you send the request. Once the request is resolved successfully, you revalidate the cart cache tag to ensure that the cart's details are updated and refetched by other components. This ensures that the applied promotion is shown in the checkout summary without needing to refresh the page.
-
-Finally, you'll use this function in the `handleTogglePromotion` function in the `LoyaltyPoints` component you created earlier.
-
-At the top of `src/modules/checkout/components/loyalty-points/index.tsx`, import the function:
-
-```tsx title="src/modules/checkout/components/loyalty-points/index.tsx" badgeLabel="Storefront" badgeColor="blue"
-import { applyLoyaltyPointsOnCart } from "../../../../lib/data/cart"
-```
-
-Then, replace the `handleTogglePromotion` function with the following:
-
-```tsx title="src/modules/checkout/components/loyalty-points/index.tsx" badgeLabel="Storefront" badgeColor="blue"
-const handleTogglePromotion = async (
-  e: React.MouseEvent<HTMLButtonElement, MouseEvent>
-) => {
-  e.preventDefault()
-  if (!isLoyaltyPointsPromoApplied) {
-    await applyLoyaltyPointsOnCart()
-  } else {
-    // TODO remove loyalty points
-  }
-}
-```
-
-In the `handleTogglePromotion` function, you call the `applyLoyaltyPointsOnCart` function if the cart doesn't have a loyalty promotion. This will send a request to the API route you created earlier, which will execute the workflow that applies the loyalty promotion to the cart.
-
-You'll implement removing the loyalty points promotion in a later step.
-
-### Test it Out
-
-To test out applying the loyalty points on the cart, start the Medusa application and Next.js Starter Storefront.
-
-Then, in the checkout flow as an authenticated customer, click on the "Apply Loyalty Points" button. The checkout summary will be updated with the applied promotion and the discount amount.
-
-If you don't want the promotion to be shown in the "Promotions(s) applied" section, you can filter the promotions in `src/modules/checkout/components/discount-code/index.tsx` to not show a promotion matching `cart.metadata.loyalty_promo_id`.
-
-![Discounted amount is shown as part of the summary and the promotion is shown as part of the applied promotions](https://res.cloudinary.com/dza7lstvk/image/upload/v1744200895/Medusa%20Resources/Screenshot_2025-04-09_at_3.14.19_PM_abmtjh.png)
-
-***
-
-## Step 8: Remove Loyalty Points From Cart
-
-In this step, you'll implement the functionality to remove the loyalty points promotion from the cart. This is useful if the customer changes their mind and wants to remove the promotion.
-
-To implement this functionality, you'll need to:
-
-- Create a workflow that removes the loyalty points promotion from the cart.
-- Create an API route that executes the workflow.
-- Create a function in the Next.js Starter Storefront that sends a request to the API route you created earlier.
-- Use the function in the `handleTogglePromotion` function in the `LoyaltyPoints` component you created earlier.
-
-### Create the Workflow
-
-The workflow will have the following steps:
-
-- [useQueryGraphStep](https://docs.medusajs.com/references/helper-steps/useQueryGraphStep/index.html.md): Retrieve the cart's details.
-- [getCartLoyaltyPromoStep](#getCartLoyaltyPromoStep): Retrieve the cart's loyalty promotion.
-- [updateCartPromotionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/workflows/updateCartPromotionsWorkflow/index.html.md): Update the cart's promotions to remove the loyalty promotion.
-- [updateCartsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateCartsStep/index.html.md): Update the cart to remove the loyalty promotion ID from the metadata.
-- [updatePromotionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updatePromotionsStep/index.html.md): Deactive the loyalty promotion.
-- [useQueryGraphStep](https://docs.medusajs.com/references/helper-steps/useQueryGraphStep/index.html.md): Retrieve the cart's details again.
-
-Since you already have all the steps, you can create the workflow.
-
-To create the workflow, create the file `src/workflows/remove-loyalty-from-cart.ts` with the following content:
-
-```ts title="src/workflows/remove-loyalty-from-cart.ts" collapsibleLines="1-15" expandButtonLabel="Show Imports" highlights={removeLoyaltyFromCartWorkflowHighlights}
-import {
-  createWorkflow,
-  transform,
-  WorkflowResponse,
-} from "@medusajs/framework/workflows-sdk"
-import {
-  useQueryGraphStep,
-  updateCartPromotionsWorkflow,
-  updateCartsStep,
-  updatePromotionsStep,
-} from "@medusajs/medusa/core-flows"
-import { getCartLoyaltyPromoStep } from "./steps/get-cart-loyalty-promo"
-import { PromotionActions } from "@medusajs/framework/utils"
-import { CartData } from "../utils/promo"
-
-type WorkflowInput = {
-  cart_id: string
-}
-
-const fields = [
-  "id",
-  "customer.*",
-  "promotions.*",
-  "promotions.application_method.*",
-  "promotions.rules.*",
-  "promotions.rules.values.*",
-  "currency_code",
-  "total",
-  "metadata",
-]
-
-export const removeLoyaltyFromCartWorkflow = createWorkflow(
-  "remove-loyalty-from-cart",
-  (input: WorkflowInput) => {
-    // @ts-ignore
-    const { data: carts } = useQueryGraphStep({
-      entity: "cart",
-      fields,
-      filters: {
-        id: input.cart_id,
-      },
-    })
-
-    const loyaltyPromo = getCartLoyaltyPromoStep({
-      cart: carts[0] as unknown as CartData,
-      throwErrorOn: "not-found",
-    })
-
-    updateCartPromotionsWorkflow.runAsStep({
-      input: {
-        cart_id: input.cart_id,
-        promo_codes: [loyaltyPromo.code!],
-        action: PromotionActions.REMOVE,
-      },
-    })
-
-    const newMetadata = transform({
-      carts,
-    }, (data) => {
-      const { loyalty_promo_id, ...rest } = data.carts[0].metadata || {}
-
-      return {
-        ...rest,
-        loyalty_promo_id: null,
-      }
-    })
-
-    updateCartsStep([
-      {
-        id: input.cart_id,
-        metadata: newMetadata,
-      },
-    ])
-
-    updatePromotionsStep([
-      {
-        id: loyaltyPromo.id,
-        status: "inactive",
-      },
-    ])
-
-    // retrieve cart with updated promotions
-    // @ts-ignore
-    const { data: updatedCarts } = useQueryGraphStep({
-      entity: "cart",
-      fields,
-      filters: { id: input.cart_id },
-    }).config({ name: "retrieve-cart" })
-
-    return new WorkflowResponse(updatedCarts[0])
-  }
-)
-```
-
-You create a workflow that accepts an object with the cart's ID as input.
-
-In the workflow, you:
-
-- Use `useQueryGraphStep` to retrieve the cart's details. You pass the cart's ID as a filter to retrieve the cart.
-- Check whether the cart has a loyalty promotion using the `getCartLoyaltyPromoStep`. You pass the `throwErrorOn` parameter with the value `not-found` to throw an error if a loyalty promotion isn't found in the cart.
-- Update the cart's promotions using the `updateCartPromotionsWorkflow`, removing the loyalty promotion.
-- Use the `transform` function to prepare the new metadata of the cart. You remove the `loyalty_promo_id` from the metadata.
-- Update the cart's metadata with the new metadata using the `updateCartsStep`.
-- Deactivate the loyalty promotion using the `updatePromotionsStep`.
-- Retrieve the cart's details again using `useQueryGraphStep` to get the updated cart with the new loyalty promotion.
-- Return the cart's details in a `WorkflowResponse` instance.
-
-### Create the API Route
-
-Next, you'll create the API route that executes this workflow.
-
-To create the API route, add the following in `src/api/store/carts/[id]/loyalty-points/route.ts`:
-
-```ts title="src/api/store/carts/[id]/loyalty-points/route.ts"
-// other imports...
-import { removeLoyaltyFromCartWorkflow } from "../../../../../workflows/remove-loyalty-from-cart"
-
-// ...
-export async function DELETE(
-  req: MedusaRequest,
-  res: MedusaResponse
-) {
-  const { id: cart_id } = req.params
-
-  const { result: cart } = await removeLoyaltyFromCartWorkflow(req.scope)
-    .run({
-      input: {
-        cart_id,
-      },
-    })
-
-  res.json({ cart })
-}
-```
-
-You export a `DELETE` route handler, which exposes a `DELETE` API route at `/store/carts/[id]/loyalty-points`.
-
-In the route handler, you execute the `removeLoyaltyFromCartWorkflow` workflow, passing it the cart ID as an input. You return the cart's details in the response.
-
-You can now use this API route in the Next.js Starter Storefront.
-
-### Remove Loyalty Points in the Storefront
-
-In the Next.js Starter Storefront, you need to add a server action function that sends a request to the API route you created earlier. Then, you'll use that function when the customer clicks the "Remove Loyalty Points" button, which shows when the cart has a loyalty promotion applied.
-
-To add the function, add the following to `src/lib/data/cart.ts`:
-
-```ts title="src/lib/data/cart.ts" badgeLabel="Storefront" badgeColor="blue"
-export async function removeLoyaltyPointsOnCart() {
-  const cartId = await getCartId()
-  const headers = {
-    ...(await getAuthHeaders()),
-  }
-  const next = {
-    ...(await getCacheOptions("carts")),
-  }
-
-  return await sdk.client.fetch<{
-    cart: HttpTypes.StoreCart & {
-      promotions: HttpTypes.StorePromotion[]
-    }
-  }>(`/store/carts/${cartId}/loyalty-points`, {
-    method: "DELETE",
-    headers,
-  })
-  .then(async (result) => {
-    const cartCacheTag = await getCacheTag("carts")
-    revalidateTag(cartCacheTag)
-
-    return result
-  })
-}
-```
-
-You create a `removeLoyaltyPointsOnCart` function that sends a request to the API route you created earlier.
-
-In the function, you retrieve the cart ID stored in the cookie using the `getCartId` function, which is available in the Next.js Starter Storefront.
-
-Then, you send the request to the API route. Once the request is resolved successfully, you revalidate the cart cache tag to ensure that the cart's details are updated and refetched by other components. This ensures that the promotion is removed from the checkout summary without needing to refresh the page.
-
-Finally, you'll use this function in the `handleTogglePromotion` function in the `LoyaltyPoints` component you created earlier.
-
-At the top of `src/modules/checkout/components/loyalty-points/index.tsx`, add the following import:
-
-```tsx title="src/modules/checkout/components/loyalty-points/index.tsx" badgeLabel="Storefront" badgeColor="blue"
-import { removeLoyaltyPointsOnCart } from "../../../../lib/data/cart"
-```
-
-Then, replace the `TODO` in `handleTogglePromotion` with the following:
-
-```tsx title="src/modules/checkout/components/loyalty-points/index.tsx" badgeLabel="Storefront" badgeColor="blue"
-await removeLoyaltyPointsOnCart()
-```
-
-In the `handleTogglePromotion` function, you call the `removeLoyaltyPointsOnCart` function if the cart has a loyalty promotion. This will send a request to the API route you created earlier, which will execute the workflow that removes the loyalty promotion from the cart.
-
-### Test it Out
-
-To test out removing the loyalty points from the cart, start the Medusa application and Next.js Starter Storefront.
-
-Then, in the checkout flow as an authenticated customer, after applying the loyalty points, click on the "Remove Loyalty Points" button. The checkout summary will be updated with the removed promotion and the discount amount.
-
-![The "Remove Loyalty Points" button is shown in the "Loyalty Points" section](https://res.cloudinary.com/dza7lstvk/image/upload/v1744204436/Medusa%20Resources/Screenshot_2025-04-09_at_4.13.24_PM_xt5trh.png)
-
-***
-
-## Step 9: Validate Loyalty Points on Cart Completion
-
-After the customer applies the loyalty points to the cart and places the order, you need to validate that the customer actually has the loyalty points. This prevents edge cases where the customer may have applied the loyalty points previously but they don't have them anymore.
-
-So, in this step, you'll hook into Medusa's cart completion flow to perform the validation.
-
-Since Medusa uses workflows in its API routes, it allows you to hook into them and perform custom functionalities using [Workflow Hooks](https://docs.medusajs.com/docs/learn/fundamentals/workflows/workflow-hooks/index.html.md). A workflow hook is a point in a workflow where you can inject custom functionality as a step function, called a hook handler.
-
-Medusa uses the [completeCartWorkflow](https://docs.medusajs.com/references/medusa-workflows/completeCartWorkflow/index.html.md) hook to complete the cart and place an order. This workflow has a `validate` hook that allows you to perform custom validation before the cart is completed.
-
-To consume the `validate` hook, create the file `src/workflows/hooks/complete-cart.ts` with the following content:
-
-```ts title="src/workflows/hooks/complete-cart.ts" highlights={completeCartWorkflowHookHighlights} collapsibleLines="1-6" expandButtonLabel="Show Imports"
-import { completeCartWorkflow } from "@medusajs/medusa/core-flows"
-import LoyaltyModuleService from "../../modules/loyalty/service"
-import { LOYALTY_MODULE } from "../../modules/loyalty"
-import { CartData, getCartLoyaltyPromotion } from "../../utils/promo"
-import { MedusaError } from "@medusajs/framework/utils"
-
-completeCartWorkflow.hooks.validate(
-  async ({ cart }, { container }) => {
-    const query = container.resolve("query")
-    const loyaltyModuleService: LoyaltyModuleService = container.resolve(
-      LOYALTY_MODULE
-    )
-
-    const { data: carts } = await query.graph({
-      entity: "cart",
-      fields: [
-        "id", 
-        "promotions.*", 
-        "customer.*", 
-        "promotions.rules.*", 
-        "promotions.rules.values.*", 
-        "promotions.application_method.*", 
-        "metadata",
-      ],
-      filters: {
-        id: cart.id,
-      },
-    }, {
-      throwIfKeyNotFound: true,
-    })
-
-    const loyaltyPromo = getCartLoyaltyPromotion(
-      carts[0] as unknown as CartData
-    )
-
-    if (!loyaltyPromo) {
-      return
-    }
-    
-    const customerLoyaltyPoints = await loyaltyModuleService.getPoints(
-      carts[0].customer!.id
-    )
-    const requiredPoints = await loyaltyModuleService.calculatePointsFromAmount(
-      loyaltyPromo.application_method!.value as number
-    )
-
-    if (customerLoyaltyPoints < requiredPoints) {
-      throw new MedusaError(
-        MedusaError.Types.INVALID_DATA,
-        `Customer does not have enough loyalty points. Required: ${
-          requiredPoints
-        }, Available: ${customerLoyaltyPoints}`
-      )
-    }
-  }
-)
-```
-
-Workflows have a special `hooks` property that includes all the hooks tht you can consume in that workflow. You consume the hook by invoking it from the workflow's `hooks` property.
-
-Since the hook is essentially a step function, it accepts the following parameters:
-
-- The hook's input passed from the workflow, which differs for each hook. The `validate` hook receives an object having the cart's details.
-- The step context object, which contains the Medusa container. You can use it to resolve services and perform actions.
-
-In the hook, you resolve Query and the Loyalty Module's service. Then, you use Query to retrieve the cart's necessary details, including its promotions, customer, and metadata.
-
-After that, you retrieve the customer's loyalty points and calculate the required points to apply the loyalty promotion.
-
-If the customer doesn't have enough loyalty points, you throw an error. This will prevent the cart from being completed if the customer doesn't have enough loyalty points.
-
-***
-
-## Test Out Cart Completion with Loyalty Points
-
-Since you now have the entire loyalty points flow implemented, you can test it out by going through the checkout flow, applying the loyalty points to the cart.
-
-When you place the order, if the customer has sufficient loyalty points, the validation hook will pass.
-
-Then, the `order.placed` event will be emitted, which will execute the subscriber that calls the `handleOrderPointsWorkflow`.
-
-In the workflow, since the order's cart has a loyalty promotion, the points equivalent to the promotion will be deducted, and the promotion becomes inactive.
-
-You can confirm that the loyalty points were deducted either by sending a request to the [retrieve loyalty points API route](#step-5-retrieve-loyalty-points-api-route), or by going through the checkout process again in the storefront.
-
-***
-
-## Next Steps
-
-You've now implement a loyalty points system in Medusa. There's still more that you can implement based on your use case:
-
-- Add loyalty points on registration or other events. Refer to the [Events Reference](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/events-reference/index.html.md) for a full list of available events you can listen to.
-- Show the customer their loyalty point usage history. This will require adding another data model in the Loyalty Module that records the usage history. You can create records of that data model when an order that has a loyalty promotion is placed, then customize the storefront to show a new page for loyalty points history.
-- Customize the Medusa Admin to show a new page or [UI Route](https://docs.medusajs.com/docs/learn/fundamentals/admin/ui-routes/index.html.md) for loyalty points information and analytics.
-
-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.
@@ -44558,3507 +44705,6 @@ Integrate a search engine to index and search products or other types of data in
 - [Algolia](https://docs.medusajs.com/integrations/guides/algolia/index.html.md)
 
 
-# Integrate Algolia (Search) with Medusa
-
-In this tutorial, you'll learn how to integrate Medusa with Algolia.
-
-When you install a Medusa application, you get a fully-fledged commerce platform with a Framework for customization. Medusa's architecture supports integrating third-party services, such as a search engine, allowing you to build your unique requirements around core commerce flows.
-
-[Algolia](https://www.algolia.com/doc/) is a search engine that enables you to build and manage an intuitive search experience for your customers. By integrating Algolia with Medusa, you can index e-commerce data, such as products, and allow clients to search through them.
-
-You can follow this guide whether you're new to Medusa or an advanced Medusa developer.
-
-## Summary
-
-By following this tutorial, you'll learn how to:
-
-- Install and set up Medusa.
-- Integrate Algolia into Medusa.
-- Trigger Algolia reindexing when a product is created, updated, deleted, or when the admin manually triggers a reindex.
-- Customize the Next.js Starter Storefront to allow searching for products through Algolia.
-
-- [Algolia Integration Repository](https://github.com/medusajs/examples/tree/main/algolia-integration): Find the full code for this guide in this repository.
-- [OpenApi Specs for Postman](https://res.cloudinary.com/dza7lstvk/raw/upload/v1742829748/OpenApi/Algolia-Search_t1zlkd.yaml): Import this OpenApi Specs file into tools like Postman.
-
-***
-
-## Step 1: Install a Medusa Application
-
-### Prerequisites
-
-- [Node.js v20+](https://nodejs.org/en/download)
-- [Git CLI tool](https://git-scm.com/downloads)
-- [PostgreSQL](https://www.postgresql.org/download/)
-
-Start by installing the Medusa application on your machine with the following command:
-
-```bash
-npx create-medusa-app@latest
-```
-
-You'll first be asked for the project's name. Then, when asked whether you want to install the [Next.js starter storefront](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/nextjs-starter/index.html.md), choose "Yes."
-
-Afterwards, the installation process will start, which will install the Medusa application in a directory with your project's name and the Next.js Starter Storefront in a separate directory 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 Algolia Module
-
-To integrate third-party services into Medusa, you create a custom module. A module is a reusable package with functionalities related to a single feature or domain. Medusa integrates the module into your application without implications or side effects on your setup.
-
-In this step, you'll create a custom module that provides the necessary functionalities to integrate Algolia with Medusa.
-
-Refer to the [Modules documentation](https://docs.medusajs.com/docs/learn/fundamentals/modules/index.html.md) to learn more.
-
-Before building the module, you need to install Algolia's JavaScript client. Run the following command in your Medusa application's root directory:
-
-```bash npm2yarn
-npm install algoliasearch
-```
-
-### Create Module Directory
-
-A module is created under the `src/modules` directory of your Medusa application. So, create the directory `src/modules/algolia`.
-
-### 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 Algolia Module's service and the methods necessary to manage indexed products in Algolia and search through them.
-
-To create the Algolia Module's service, create the file `src/modules/algolia/service.ts` with the following content:
-
-```ts title="src/modules/algolia/service.ts"
-import { algoliasearch, SearchClient } from "algoliasearch"
-
-type AlgoliaOptions = {
-  apiKey: string;
-  appId: string;
-  productIndexName: string;
-}
-
-export type AlgoliaIndexType = "product"
-
-export default class AlgoliaModuleService {
-  private client: SearchClient
-  private options: AlgoliaOptions
-
-  constructor({}, options: AlgoliaOptions) {
-    this.client = algoliasearch(options.appId, options.apiKey)
-    this.options = options
-  }
-
-  // TODO add methods
-}
-```
-
-You export a class that will be the Algolia Module's main service. In the service, you define two properties:
-
-- `client`: An instance of the Algolia Search Client, which you'll use to perform actions with Algolia's API.
-- `options`: An object of options that the Module receives when it's registered, which you'll learn about later. The options contain:
-  - `apiKey`: The Algolia API key.
-  - `appId`: The Algolia App ID.
-  - `productIndexName`: The name of the index where products are stored.
-
-If you want to index other types of data, such as product categories, you can add new properties for their index names in the `AlgoliaOptions` type.
-
-A module's service receives the module's options as a second parameter in its constructor. In the constructor, you initialize the Algolia client using the module's options.
-
-A module has a container that holds all resources registered in that module, and you can access those resources in the first parameter of the constructor. Learn more about it in the [Module Container documentation](https://docs.medusajs.com/docs/learn/fundamentals/modules/container/index.html.md).
-
-#### Index Data Method
-
-The first method you need to add to the servie is a method that receives an array of data to add or update in Algolia's index.
-
-Add the following methods to the `AlgoliaModuleService` class:
-
-```ts title="src/modules/algolia/service.ts"
-export default class AlgoliaModuleService {
-  // ...
-  async getIndexName(type: AlgoliaIndexType) {
-    switch (type) {
-      case "product":
-        return this.options.productIndexName
-      default:
-        throw new Error(`Invalid index type: ${type}`)
-    }
-  }
-
-  async indexData(data: Record<string, unknown>[], type: AlgoliaIndexType = "product") {
-    const indexName = await this.getIndexName(type)
-    this.client.saveObjects({
-      indexName,
-      objects: data.map((item) => ({
-        ...item,
-        // set the object ID to allow updating later
-        objectID: item.id,
-      })),
-    })
-  }
-}
-```
-
-You define two methods:
-
-1. `getIndexName`: A method that receives an `AlgoliaIndexType` (defined in the previous snippt) and returns the index name for that type. In this case, you only have one type, `product`, so you return the product index name.
-   - If you want to index other types of data, you can add more cases to the switch statement.
-2. `indexData`: A method that receives an array of data and an `AlgoliaIndexType`. The method indexes the data in the Algolia index for the given type.
-   - Notice that you set the `objectID` property of each object to the object's `id`. This ensures that you later update the object instead of creating a new one.
-
-#### Retrieve and Delete Methods
-
-The next methods you'll add to the service are methods to retrieve and delete data from the Algolia index. You'll see their use later as you keep the Algolia index in sync with Medusa.
-
-Add the following methods to the `AlgoliaModuleService` class:
-
-```ts title="src/modules/algolia/service.ts"
-export default class AlgoliaModuleService {
-  // ...
-
-  async retrieveFromIndex(objectIDs: string[], type: AlgoliaIndexType = "product") {
-    const indexName = await this.getIndexName(type)
-    return await this.client.getObjects<Record<string, unknown>>({
-      requests: objectIDs.map((objectID) => ({
-        indexName,
-        objectID,
-      })),
-    })
-  }
-
-  async deleteFromIndex(objectIDs: string[], type: AlgoliaIndexType = "product") {
-    const indexName = await this.getIndexName(type)
-    await this.client.deleteObjects({
-      indexName,
-      objectIDs,
-    })
-  }
-}
-```
-
-You define two methods:
-
-1. `retrieveFromIndex`: A method that receives an array of object IDs and an `AlgoliaIndexType`. The method retrieves the objects with the given IDs from the Algolia index.
-2. `deleteFromIndex`: A method that receives an array of object IDs and an `AlgoliaIndexType`. The method deletes the objects with the given IDs from the Algolia index.
-
-#### Search Method
-
-The last method you'll implement is a method to search through the Algolia index. You'll later use this method to expose the search functionality to clients, such as the Next.js Storefront.
-
-Add the following method to the `AlgoliaModuleService` class:
-
-```ts title="src/modules/algolia/service.ts"
-export default class AlgoliaModuleService {
-  // ...
-
-  async search(query: string, type: AlgoliaIndexType = "product") {
-    const indexName = await this.getIndexName(type)
-    return await this.client.search({
-      requests: [
-        {
-          indexName,
-          query,
-        },
-      ],
-    })
-  }
-}
-```
-
-The `search` method receives a query string and an `AlgoliaIndexType`. The method searches through the Algolia index for the given type, such as products, and returns the results.
-
-### Export Module Definition
-
-The final piece to a module is its definition, which you export in an `index.ts` file at its root directory. This definition tells Medusa the name of the module and its service.
-
-So, create the file `src/modules/algolia/index.ts` with the following content:
-
-```ts title="src/modules/algolia/index.ts"
-import { Module } from "@medusajs/framework/utils"
-import AlgoliaModuleService from "./service"
-
-export const ALGOLIA_MODULE = "algolia"
-
-export default Module(ALGOLIA_MODULE, {
-  service: AlgoliaModuleService,
-})
-```
-
-You use the `Module` function from the Modules SDK to create the module's definition. It accepts two parameters:
-
-1. The module's name, which is `algolia`.
-2. An object with a required property `service` indicating the module's service.
-
-You also export the module's name as `ALGOLIA_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/algolia",
-      options: {
-        appId: process.env.ALGOLIA_APP_ID!,
-        apiKey: process.env.ALGOLIA_API_KEY!,
-        productIndexName: process.env.ALGOLIA_PRODUCT_INDEX_NAME!,
-      },
-    },
-  ],
-})
-```
-
-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 Algolia App ID, API Key, and the product index name.
-
-### Add Environment Variables
-
-Before you can start using the Algolia Module, you need to set the environment variables for the Algolia App ID, API Key, and the product index name.
-
-Add the following environment variables to your `.env` file:
-
-```env
-ALGOLIA_APP_ID=your-algolia-app-id
-ALGOLIA_API_KEY=your-algolia-api-key
-ALGOLIA_PRODUCT_INDEX_NAME=your-product-index-name
-```
-
-Where:
-
-- `your-algolia-app-id` is your Algolia App ID. You can retrieve it from the Algolia dashboard by clicking at the application ID at the top left next to the sidebar. The pop up will show the application ID below the application's name.
-
-![Find the Algolia App ID by clicking on the application name in the Algolia dashboard, then copying the ID below the name in the pop-up](https://res.cloudinary.com/dza7lstvk/image/upload/v1742815360/Medusa%20Resources/Screenshot_2025-03-24_at_1.19.30_PM_kdp3y5.png)
-
-- `your-algolia-api-key` is your Algolia API Key. To retrieve it from the Algolia dashboard:
-  1. Click on Settings in the sidebar.
-  2. Choose API Keys under "Team and Access".
-
-![In the settings page, find the Team and Access section at the right of the page and choose API Keys](https://res.cloudinary.com/dza7lstvk/image/upload/v1742815534/Medusa%20Resources/Screenshot_2025-03-24_at_1.25.09_PM_hwsiba.png)
-
-3. Copy the Admin API Key.
-
-- `your-product-index-name` is the name of the index where you'll store products. You can find it by going to Search -> Index, and copying the index name at the top of the page.
-
-![In the Algolia dashboard, go to Search -> Index and copy the index name at the top of the page](https://res.cloudinary.com/dza7lstvk/image/upload/v1742815790/Medusa%20Resources/Screenshot_2025-03-24_at_1.28.58_PM_yq10sf.png)
-
-Your module is now ready for use. You'll see how to use it in the next steps.
-
-***
-
-## Step 3: Sync Products to Algolia Workflow
-
-To keep the Algolia index in sync with Medusa, you need to trigger indexing when products are created, updated, or deleted in Medusa. You can also allow the admin to manually trigger a reindex.
-
-To implement the indexing functionality, you need to create a [workflow](https://docs.medusajs.com/docs/learn/fundamentals/workflows/index.html.md). A workflow 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 step, you'll create a workflow that indexes products in Algolia. In the next steps, you'll learn how to use the workflow when products are created, updated, or deleted, or when the admin manually triggers a reindex.
-
-The workflow has the following steps:
-
-- [useQueryGraphStep](https://docs.medusajs.com/references/helper-steps/useQueryGraphStep/index.html.md): Retrieve products matching specified filters and pagination parameters.
-- [syncProductsStep](#syncProductsStep): Index products in Algolia.
-
-Medusa provides the `useQueryGraphStep` in its `@medusajs/medusa/core-flows` package. So, you only need to implement the second step.
-
-### syncProductsStep
-
-In the second step of the workflow, you create or update indexes in Algolia for the products retrieved in the first step.
-
-To create the step, create the file `src/workflows/steps/sync-products.ts` with the following content:
-
-```ts title="src/workflows/steps/sync-products.ts"
-import { ProductDTO } from "@medusajs/framework/types"
-import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk"
-import { ALGOLIA_MODULE } from "../../modules/algolia"
-import AlgoliaModuleService from "../../modules/algolia/service"
-
-export type SyncProductsStepInput = {
-  products: ProductDTO[]
-}
-
-export const syncProductsStep = createStep(
-  "sync-products",
-  async ({ products }: SyncProductsStepInput, { container }) => {
-    const algoliaModuleService: AlgoliaModuleService = container.resolve(ALGOLIA_MODULE)
-
-    const existingProducts = (await algoliaModuleService.retrieveFromIndex(
-      products.map((product) => product.id),
-      "product"
-    )).results.filter(Boolean)
-    const newProducts = products.filter(
-      (product) => !existingProducts.some((p) => p.objectID === product.id)
-    )
-    await algoliaModuleService.indexData(
-      products as unknown as Record<string, unknown>[], 
-      "product"
-    )
-
-    return new StepResponse(undefined, {
-      newProducts: newProducts.map((product) => product.id),
-      existingProducts,
-    })
-  }
-  // TODO add compensation
-)
-```
-
-You create a step with `createStep` from the Workflows SDK. It accepts two parameters:
-
-1. The step's unique name, which is `sync-products`.
-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 sync into Algolia.
-   - An object that has properties including the [Medusa container](https://docs.medusajs.com/docs/learn/fundamentals/medusa-container/index.html.md), which is a registry of Framework and commerce tools that you can access in the step.
-
-In the step function, you resolve the Algolia Module's service from the Medusa container using the name you exported in the module definition's file.
-
-Then, you retrieve the products that are already indexed in Algolia and determine which products are new. You'll learn why this is useful in a bit.
-
-Finally, you pass the products you received in the input to Algolia to create or update its indices.
-
-A step function must return a `StepResponse` instance. The `StepResponse` constructor accepts two parameters:
-
-1. The step's output, which is the review created.
-2. Data to pass to the step's compensation function.
-
-#### Compensation Function
-
-The compensation function undoes the actions performed in a step. Then, if an error occurs during the workflow's execution, the compensation functions of executed steps are called to roll back the changes. This mechanism ensures data consistency in your application, especially as you integrate external systems.
-
-To add a compensation function to a step, pass it as a third parameter to `createStep`:
-
-```ts title="src/workflows/steps/sync-products.ts"
-export const syncProductsStep = createStep(
-  // ...
-  async (input, { container }) => {
-    if (!input) {
-      return
-    }
-
-    const algoliaModuleService: AlgoliaModuleService = container.resolve(ALGOLIA_MODULE)
-    
-    if (input.newProducts) {
-      await algoliaModuleService.deleteFromIndex(
-        input.newProducts,
-        "product"
-      )
-    }
-
-    if (input.existingProducts) {
-      await algoliaModuleService.indexData(
-        input.existingProducts,
-        "product"
-      )
-    }
-  }
-)
-```
-
-The compensation function receives two parameters:
-
-1. The data you passed as a second parameter of `StepResponse` in the step function.
-2. A context object similar to the step function that holds the Medusa container.
-
-In the compensation function, you resolve the Algolia Module's service from the container. Then, you delete from Algolia the products that were newly indexed, and revert the existing products to their original data.
-
-### Add Sync Products Workflow
-
-You can now create the worklow that syncs the products to Algolia.
-
-To create the workflow, create the file `src/workflows/sync-products.ts` with the following content:
-
-```ts title="src/workflows/sync-products.ts"
-import { createWorkflow, WorkflowResponse } from "@medusajs/framework/workflows-sdk"
-import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
-import { syncProductsStep, SyncProductsStepInput } from "./steps/sync-products"
-
-type SyncProductsWorkflowInput = {
-  filters?: Record<string, unknown>
-  limit?: number
-  offset?: number
-}
-
-export const syncProductsWorkflow = createWorkflow(
-  "sync-products",
-  ({ filters, limit, offset }: SyncProductsWorkflowInput) => {
-    // @ts-ignore
-    const { data, metadata } = useQueryGraphStep({
-      entity: "product",
-      fields: ["id", "title", "description", "handle", "thumbnail", "categories.*", "tags.*"],
-      pagination: {
-        take: limit,
-        skip: offset,
-      },
-      filters: {
-        // @ts-ignore
-        status: "published",
-        ...filters,
-      },
-    })
-
-    syncProductsStep({
-      products: data,
-    } as SyncProductsStepInput)
-
-    return new WorkflowResponse({
-      products: data,
-      metadata,
-    })
-  }
-)
-```
-
-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 pagination and filter parameters for the products to retrieve.
-
-In the workflow's constructor function, you:
-
-1. Execute `useQueryGraphStep` to retrieve products from Medusa's database. 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 pagination and filter parameters you received in the input.
-2. Execute `syncProductsStep` to index the products in Algolia. You pass it the products you retrieved in the previous step.
-
-A workflow must return an instance of `WorkflowResponse`. The `WorkflowResponse` constructor accepts the workflow's output as a parameter, which is an object holding the retrieved products and their pagination details.
-
-In the next step, you'll learn how to execute this workflow.
-
-***
-
-## Step 4: Trigger Algolia Sync Manually
-
-As mentioned earlier, you'll trigger the Algolia sync automatically when product events occur, but you also want to allow the admin to manually trigger a reindex.
-
-In this step, you'll add the functionality to trigger the `syncProductsWorkflow` manually from the Medusa Admin dashboard. This requires:
-
-1. Creating a subscriber that listens to a custom `algolia.sync` event to trigger syncing products to Algolia.
-2. Creating an API route that the Medusa Admin dashboard can call to emit the `algolia.sync` event, which triggers the subscriber.
-3. Add a new page or UI route to the Medusa Admin dashboard to allow the admin to trigger the reindex.
-
-### Create Products Sync Subscriber
-
-A subscriber 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.
-
-Learn more about subscribers in the [Events and Subscribers documentation](https://docs.medusajs.com/docs/learn/fundamentals/events-and-subscribers/index.html.md).
-
-You create a subscriber in a TypeScript or JavaScript file under the `src/subscribers` directory. So, to create the subscriber that listens to the `algolia.sync` event, create the file `src/subscribers/products-sync.ts` with the following content:
-
-```ts title="src/subscribers/algolia-sync.ts"
-import {
-  SubscriberArgs,
-  type SubscriberConfig,
-} from "@medusajs/framework"
-import { syncProductsWorkflow } from "../workflows/sync-products"
-
-export default async function algoliaSyncHandler({ 
-  container,
-}: SubscriberArgs) {
-  const logger = container.resolve("logger")
-  
-  let hasMore = true
-  let offset = 0
-  const limit = 50
-  let totalIndexed = 0
-
-  logger.info("Starting product indexing...")
-
-  while (hasMore) {
-    const { result: { products, metadata } } = await syncProductsWorkflow(container)
-      .run({
-        input: {
-          limit,
-          offset,
-        },
-      })
-
-    hasMore = offset + limit < (metadata?.count ?? 0)
-    offset += limit
-    totalIndexed += products.length
-  }
-
-  logger.info(`Successfully indexed ${totalIndexed} products`)
-}
-
-export const config: SubscriberConfig = {
-  event: "algolia.sync",
-}
-```
-
-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 `algolia.sync` in this case.
-
-The subscriber function receives an object as a parameter that has a `container` property, which is the Medusa container.
-
-In the subscriber function, you initialize variables to keep track of the pagination and the total number of products indexed.
-
-Then, you start a loop that retrieves products in batches of 50 and indexes them in Algolia using the `syncProductsWorkflow`. Finally, you log the total number of products indexed.
-
-You'll learn how to emit the `algolia.sync` event next.
-
-If you want to sync other data types, you can do it in this subscriber as well.
-
-### Create API Route to Trigger Sync
-
-To allow the Medusa Admin dashboard to trigger the `algolia.sync` event, you need to create an API route that emits the 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/algolia/sync`, create the file `src/api/admin/algolia/sync/route.ts` with the following content:
-
-```ts title="src/api/admin/algolia/sync/route.ts"
-import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
-import { Modules } from "@medusajs/framework/utils"
-
-export async function POST(
-  req: MedusaRequest,
-  res: MedusaResponse
-) {
-  const eventModuleService = req.scope.resolve(Modules.EVENT_BUS)
-  await eventModuleService.emit({
-    name: "algolia.sync",
-    data: {},
-  })
-  res.send({
-    message: "Syncing data to Algolia",
-  })
-}
-```
-
-Since you export a `POST` route handler function, you expose an `API` route at `/admin/algolia/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 use the Medusa container that is available in the request object to resolve the [Event Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/infrastructure-modules/event/index.html.md). This module manages events and their subscribers.
-
-Then, you emit the `algolia.sync` event using the Event Module's `emit` method, passing it the event name.
-
-Finally, you send a response with a message indicating that data is being synced to Algolia.
-
-### Add Algolia Sync Page to Admin Dashboard
-
-The last step is to add a new page to the admin dashboard that allows the admin to trigger the reindex. You add a new page using a [UI Route](https://docs.medusajs.com/docs/learn/fundamentals/admin/ui-routes/index.html.md).
-
-A UI route is a React component that specifies the content to be shown in a new page in the Medusa Admin dashboard. You'll create a UI route to display a button that triggers the reindex when clicked.
-
-Learn more about UI routes in the [UI Routes documentation](https://docs.medusajs.com/docs/learn/fundamentals/admin/ui-routes/index.html.md).
-
-#### Configure JS SDK
-
-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) that you can use to send requests to the Medusa server from any client application, including your Medusa Admin customizations.
-
-The JS SDK is installed by default in your Medusa application. To configure it, create the file `src/admin/lib/sdk.ts` with the following content:
-
-```ts title="src/admin/lib/sdk.ts"
-import Medusa from "@medusajs/js-sdk"
-
-export const sdk = new Medusa({
-  baseUrl: "http://localhost:9000",
-  debug: process.env.NODE_ENV === "development",
-  auth: {
-    type: "session",
-  },
-})
-```
-
-You create an instance of the JS SDK using the `Medusa` class from the JS SDK. You pass it an object having the following properties:
-
-- `baseUrl`: The base URL of the Medusa server.
-- `debug`: A boolean indicating whether to log debug information into the console.
-- `auth`: An object specifying the authentication type. When using the JS SDK for admin customizations, you use the `session` authentication type.
-
-#### Create UI Route
-
-You'll now create the UI route that displays a button to trigger the reindex. You create a UI route 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, to create a new page under the Settings section of the Medusa Admin, create the file `src/admin/routes/settings/algolia/page.tsx` with the following content:
-
-```tsx title="src/admin/routes/settings/algolia/page.tsx"
-import { Container, Heading, Button, toast } from "@medusajs/ui"
-import { useMutation } from "@tanstack/react-query"
-import { sdk } from "../../../lib/sdk"
-import { defineRouteConfig } from "@medusajs/admin-sdk"
-
-const AlgoliaPage = () => {
-  const { mutate, isPending } = useMutation({
-    mutationFn: () => 
-      sdk.client.fetch("/admin/algolia/sync", {
-        method: "POST",
-      }),
-    onSuccess: () => {
-      toast.success("Successfully triggered data sync to Algolia") 
-    },
-    onError: (err) => {
-      console.error(err)
-      toast.error("Failed to sync data to Algolia") 
-    },
-  })
-
-  const handleSync = () => {
-    mutate()
-  }
-
-  return (
-    <Container className="divide-y p-0">
-      <div className="flex items-center justify-between px-6 py-4">
-        <Heading level="h2">Algolia Sync</Heading>
-      </div>
-      <div className="px-6 py-8">
-        <Button 
-          variant="primary"
-          onClick={handleSync}
-          isLoading={isPending}
-        >
-          Sync Data to Algolia
-        </Button>
-      </div>
-    </Container>
-  )
-}
-
-export const config = defineRouteConfig({
-  label: "Algolia",
-})
-
-export default AlgoliaPage
-```
-
-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 it Out
-
-You'll now test out the entire flow, starting from triggering the reindex manually from the Medusa Admin dashboard, to checking the Algolia dashboard for the indexed products.
-
-Run the following command to start the Medusa application:
-
-```bash npm2yarn
-npm run dev
-```
-
-Then, open the Medusa Admin at `http://localhost:9000/app` and log in with the credentials you set up in the first step.
-
-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).
-
-After you log in, go to Settings from the sidebar. You'll find in the Settings' sidebar a new "Algolia" item. If you click on it, you'll find the page you created with the button to sync products to Algolia.
-
-If you click on the button, the products will be synced to Algolia.
-
-![The Algolia Sync page in the Medusa Admin dashboard with a button to sync products to Algolia](https://res.cloudinary.com/dza7lstvk/image/upload/v1742820813/Medusa%20Resources/Screenshot_2025-03-24_at_2.52.31_PM_eiegzb.png)
-
-You can check that the sync ran and was completed by checking the Medusa logs in the terminal where you started the Medusa application. You should find the following messages:
-
-```bash
-info:    Processing algolia.sync which has 1 subscribers
-info:    Starting product indexing...
-info:    Successfully indexed 4 products
-```
-
-These messages indicate that the `algolia.sync` event was emitted, which triggered the subscriber you created to sync the products using the `syncProductsWorkflow`.
-
-Finally, you can check the Algolia dashboard to see the indexed products. Go to Search -> Index, and check the records of the index you set up in the Algolia Module's options (`products`, for example).
-
-![The Algolia dashboard showing the indexed products](https://res.cloudinary.com/dza7lstvk/image/upload/v1742821034/Medusa%20Resources/Screenshot_2025-03-24_at_2.56.38_PM_mtojrv.png)
-
-***
-
-## Step 5: Update Index on Product Changes
-
-You'll now automate the indexing of the products whenever a change occurs. That includes when a product is created, updated, or deleted.
-
-Similar to before, you'll create subscribers to listen to these events.
-
-### Handle Create and Update Products
-
-The action to perform when a product is created or updated is the same. You'll use the `syncProductsWorkflow` to sync the product to Algolia.
-
-So, you only need one subscriber to handle these two events. To create the subscriber, create the file `src/subscribers/product-sync.ts` with the following content:
-
-```ts title="src/subscribers/product-sync.ts"
-import { SubscriberArgs, type SubscriberConfig } from "@medusajs/framework"
-import { syncProductsWorkflow } from "../workflows/sync-products"
-
-export default async function handleProductEvents({
-  event: { data },
-  container,
-}: SubscriberArgs<{ id: string }>) {
-  await syncProductsWorkflow(container)
-    .run({
-      input: {
-        filters: {
-          id: data.id,
-        },
-      },
-    })
-}
-
-export const config: SubscriberConfig = {
-  event: ["product.created", "product.updated"],
-}
-```
-
-The subscriber listens to the `product.created` and `product.updated` events. When either of these events is emitted, the subscriber triggers the `syncProductsWorkflow` to sync the product to Algolia.
-
-When the `product.created` and `product.updated` events are emitted, the product's ID is passed in the event data payload, which you can access in the `event.data` property of the subscriber function's parameter.
-
-So, you pass the product's ID to the `syncProductsWorkflow` as a filter to retrieve only the product that was created or updated.
-
-#### Test it Out
-
-To test it out, start the Medusa application:
-
-```bash npm2yarn
-npm run dev
-```
-
-Then, either create a product or update an existing one using the Medusa Admin dashboard. If you check the Algolia dashboard, you'll find that the product was created or updated.
-
-### Handle Product Deletion
-
-When a product is deleted, you need to remove it from the Algolia index. As this requires a different action than creating or updating a product, you'll create a new workflow that deletes the product from Algolia, then create a subscriber that listens to the `product.deleted` event to trigger the workflow.
-
-#### Create Delete Product Step
-
-The workflow to delete a product from Algolia will have only one step that deletes products by their IDs from Algolia.
-
-So, create the step at `src/workflows/steps/delete-products-from-algolia.ts` with the following content:
-
-```ts title="src/workflows/steps/delete-products-from-algolia.ts"
-import {
-  createStep,
-  StepResponse,
-} from "@medusajs/framework/workflows-sdk"
-import { ALGOLIA_MODULE } from "../../modules/algolia"
-
-export type DeleteProductsFromAlgoliaWorkflow = {
-  ids: string[]
-}
-
-export const deleteProductsFromAlgoliaStep = createStep(
-  "delete-products-from-algolia-step",
-  async (
-    { ids }: DeleteProductsFromAlgoliaWorkflow,
-    { container }
-  ) => {
-    const algoliaModuleService = container.resolve(ALGOLIA_MODULE)
-    
-    const existingRecords = await algoliaModuleService.retrieveFromIndex(
-      ids, 
-      "product"
-    )
-    await algoliaModuleService.deleteFromIndex(
-      ids,
-      "product"
-    )
-
-    return new StepResponse(undefined, existingRecords)
-  },
-  async (existingRecords, { container }) => {
-    if (!existingRecords) {
-      return
-    }
-    const algoliaModuleService = container.resolve(ALGOLIA_MODULE)
-    
-    await algoliaModuleService.indexData(
-      existingRecords as unknown as Record<string, unknown>[],
-      "product"
-    )
-  }
-)
-```
-
-The step receives the IDs of the products to delete as an input.
-
-In the step, you resolve the Algolia Module's service and retrieve the existing records from Algolia. This is useful to revert the deletion if an error occurs.
-
-Then, you delete the products from Algolia and pass the existing records to the compensation function.
-
-In the compensation function, you reindex the existing records if an error occurs.
-
-#### Create Delete Product Workflow
-
-You can now create the workflow that deletes products from Algolia. Create the file `src/workflows/delete-products-from-algolia.ts` with the following content:
-
-```ts title="src/workflows/delete-products-from-algolia.ts"
-import { createWorkflow } from "@medusajs/framework/workflows-sdk"
-import { deleteProductsFromAlgoliaStep } from "./steps/delete-products-from-algolia"
-
-type DeleteProductsFromAlgoliaWorkflowInput = {
-  ids: string[]
-}
-
-export const deleteProductsFromAlgoliaWorkflow = createWorkflow(
-  "delete-products-from-algolia",
-  (input: DeleteProductsFromAlgoliaWorkflowInput) => {
-    deleteProductsFromAlgoliaStep(input)
-  }
-)
-```
-
-The workflow receives an object with the IDs of the products to delete. It then executes the `deleteProductsFromAlgoliaStep` to delete the products from Algolia.
-
-#### Create Delete Product Subscriber
-
-Finally, you'll create the subscriber that listens to the `product.deleted` event to trigger the above workflow.
-
-Create the file `src/subscribers/product-delete.ts` with the following content:
-
-```ts title="src/subscribers/product-delete.ts"
-import { SubscriberArgs, type SubscriberConfig } from "@medusajs/framework"
-import { deleteProductsFromAlgoliaWorkflow } from "../workflows/delete-products-from-algolia"
-
-export default async function handleProductDeleted({
-  event: { data },
-  container,
-}: SubscriberArgs<{ id: string }>) {
-  await deleteProductsFromAlgoliaWorkflow(container)
-    .run({
-      input: {
-        ids: [data.id],
-      },
-    })
-}
-
-export const config: SubscriberConfig = {
-  event: "product.deleted",
-}
-```
-
-The subscriber listens to the `product.deleted` event. When the event is emitted, the subscriber triggers the `deleteProductsFromAlgoliaWorkflow`, passing it the ID of the product to delete.
-
-#### Test it Out
-
-To test product deletion, start the Medusa application:
-
-```bash npm2yarn
-npm run dev
-```
-
-Then, delete a product from the Medusa Admin dashboard. If you check the Algolia dashboard, you'll find that the product was deleted there as well.
-
-***
-
-## Step 6: Add Search API Route
-
-Before customizing the storefront to show the search UI, you'll create an API route in your Medusa application that allows storefronts to search products in Algolia.
-
-While you can implement the search functionality directly in the storefront to interact with Algolia, this approach centralizes your search integration in Medusa, allowing you to change or modify the integration as necessary. You can also rely on the same behavior and results across different storefronts.
-
-To implement the API Route, create the file `src/api/store/products/search/route.ts` with the following content:
-
-```ts title="src/api/store/products/search/route.ts"
-import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
-import { ALGOLIA_MODULE } from "../../../../modules/algolia"
-import AlgoliaModuleService from "../../../../modules/algolia/service"
-import { z } from "zod"
-
-export const SearchSchema = z.object({
-  query: z.string(),
-})
-
-type SearchRequest = z.infer<typeof SearchSchema>
-
-export async function POST(
-  req: MedusaRequest<SearchRequest>,
-  res: MedusaResponse
-) {
-  const algoliaModuleService: AlgoliaModuleService = req.scope.resolve(ALGOLIA_MODULE)
-
-  const { query } = req.validatedBody
-
-  const results = await algoliaModuleService.search(
-    query as string 
-  )
-
-  res.json(results)
-}
-```
-
-You first define a schema with [Zod](https://zod.dev/), a library to define validation schemas. The schema defines the structure of the request body, which in this case is an object with a `query` property of type `string`. Later, you'll use the schema to enforce request body validation.
-
-Then, you expose a `POST` API Route at `/store/search` that searches Algolia using the `search` method you implemented in the Algolia Module's service. You pass to it the query string from the request body.
-
-Finally, you return the search results as it is in the response.
-
-### Add Validation Middleware
-
-To ensure that requests sent to the API route have the required request body parameters, you can use 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. It's executed before the route handler.
-
-Learn more about middleware in the [Middlewares documentation](https://docs.medusajs.com/docs/learn/fundamentals/api-routes/middlewares/index.html.md).
-
-Middlewares are created in the `src/api/middlewares.ts` file. So create the file `src/api/middlewares.ts` with the following content:
-
-```ts title="src/api/middlewares.ts"
-import { 
-  defineMiddlewares,
-  validateAndTransformBody, 
-} from "@medusajs/framework/http"
-import { SearchSchema } from "./store/products/search/route"
-
-export default defineMiddlewares({
-  routes: [
-    {
-      matcher: "/store/products/search",
-      method: ["POST"],
-      middlewares: [
-        validateAndTransformBody(SearchSchema),
-      ],
-    },
-  ],
-})
-```
-
-To export the middlewares, you use the `defineMiddlewares` function. It accepts an object having a `routes` property, whose value is an array of middleware route objects. Each middleware route object has the following properties:
-
-- `matcher`: The path of the route the middleware applies to.
-- `method`: The HTTP methods the middleware applies to, which is in this case `POST`.
-- `middlewares`: An array of middleware functions to apply to the route. You apply the `validateAndTransformBody` middleware which ensures that a request's body has the required parameters. You pass it the schema you defined earlier in the API route's file.
-
-You can use the search API route now. You'll see it in action as you customize the storefront in the next step.
-
-***
-
-## Step 7: Search Products in Next.js Storefront
-
-The last step is to provide the search functionalities to customers on your storefront. In the first step, 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.
-
-In this step, you'll customize the Next.js Starter Storefront to add the search functionality.
-
-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-search`, you can find the storefront by going back to the parent directory and changing to the `medusa-search-storefront` directory:
-
-```bash
-cd ../medusa-search-storefront # change based on your project name
-```
-
-### Install Algolia Packages
-
-Before adding the implementation of the search functionality, you need to install the Algolia packages necessary to add the search functionality in your storefront.
-
-Run the following command in the directory of your Next.js Starter Storefront:
-
-```bash npm2yarn
-npm install algoliasearch react-instantsearch
-```
-
-This installs the Algolia Search JavaScript client and the React InstantSearch library, which you'll use to build the search functionality.
-
-### Add Search Client Configuration
-
-Next, you need to configure the search client. Not only do you need to initialize Algolia, but you also need to change the searching mechanism to use your custom API route in the Medusa application instead of Algolia's API directly.
-
-In `src/lib/config.ts`, add the following imports at the top of the file:
-
-```ts title="src/lib/config.ts" badgeLabel="Storefront" badgeColor="blue"
-import { 
-  liteClient as algoliasearch, 
-  LiteClient as SearchClient,
-} from "algoliasearch/lite"
-```
-
-Then, add the following at the end of the file:
-
-```ts title="src/lib/config.ts" badgeLabel="Storefront" badgeColor="blue"
-export const searchClient: SearchClient = {
-  ...(algoliasearch(
-    process.env.NEXT_PUBLIC_ALGOLIA_APP_ID || "", 
-    process.env.NEXT_PUBLIC_ALGOLIA_API_KEY || ""
-  )),
-  search: async (params) => {
-    const request = Array.isArray(params) ? params[0] : params
-    const query = "params" in request ? request.params?.query : 
-      "query" in request ? request.query : ""
-
-    if (!query) {
-      return {
-        results: [
-          {
-            hits: [],
-            nbHits: 0,
-            nbPages: 0,
-            page: 0,
-            hitsPerPage: 0,
-            processingTimeMS: 0,
-            query: "",
-            params: "",
-          },
-        ],
-      }
-    }
-
-    return await sdk.client.fetch(`/store/products/search`, {
-      method: "POST",
-      body: {
-        query,
-      },
-    })
-  },
-}
-```
-
-In the code above, you create a `searchClient` object that initializes the Algolia client with your Algolia App ID and API Key.
-
-You also define a `search` method that sends a `POST` request to the search API route you created in the Medusa application. You use the JS SDK (which is initialized in this same file) to send the request.
-
-### Set Environment Variables
-
-In the storefront's `.env.local` file, add the following Algolia-related environment variables:
-
-```plain badgeLabel="Storefront" badgeColor="blue"
-NEXT_PUBLIC_ALGOLIA_APP_ID=your_algolia_app_id
-NEXT_PUBLIC_ALGOLIA_API_KEY=your_algolia_api_key
-NEXT_PUBLIC_ALGOLIA_PRODUCT_INDEX_NAME=your-products-index-name
-```
-
-Where:
-
-- `your_algolia_app_id` is your Algolia App ID, as explained in the [Add Environment Variables section](#add-environment-variables) earlier.
-- `your_algolia_api_key` is your Algolia Search API key. You can retrieve it from the [same API keys page on the Algolia dashboard](#add-environment-variables) that you retrieved the Admin API key from.
-- `your-products-index-name` is the name of the index you created in Algolia to store the products, which you can retrieve as explained in the [Add Environment Variables section](#add-environment-variables) earlier. You'll use this variable later.
-
-Do not expose your Admin API key in the storefront. The Admin API key should only be used in the Medusa application to interact with Algolia, as it has full access to your Algolia account.
-
-### Add Search Modal Component
-
-You'll now add a search modal component that customers can use to search for products. The search modal will display the search results in real-time as the customer types in the search query.
-
-Later, you'll add the search modal to the navigation bar, allowing customers to open the search modal from any page.
-
-Create the file `src/modules/search/components/modal/index.tsx` with the following content:
-
-```tsx title="src/modules/search/components/modal/index.tsx" badgeLabel="Storefront" badgeColor="blue"
-"use client"
-
-import React, { useEffect, useState } from "react"
-import { Hits, InstantSearch, SearchBox } from "react-instantsearch"
-import { searchClient } from "../../../../lib/config"
-import Modal from "../../../common/components/modal"
-import { Button } from "@medusajs/ui"
-import Image from "next/image"
-import Link from "next/link"
-import { usePathname } from "next/navigation"
-
-type Hit = {
-  objectID: string;
-  id: string;
-  title: string;
-  description: string;
-  handle: string;
-  thumbnail: string;
-}
-
-export default function SearchModal() {
-  const [isOpen, setIsOpen] = useState(false)
-  const pathname = usePathname()
-
-  useEffect(() => {
-    setIsOpen(false)
-  }, [pathname])
-
-  return (
-    <>
-      <div className="hidden small:flex items-center gap-x-6 h-full">
-        <Button 
-          onClick={() => setIsOpen(true)} 
-          variant="transparent"
-          className="hover:text-ui-fg-base text-small-regular px-0 hover:bg-transparent focus:!bg-transparent"
-        >
-          Search
-        </Button>
-      </div>
-      <Modal isOpen={isOpen} close={() => setIsOpen(false)}>
-        <InstantSearch 
-          searchClient={searchClient} 
-          indexName={process.env.NEXT_PUBLIC_ALGOLIA_PRODUCT_INDEX_NAME}
-        >
-          <SearchBox className="w-full [&_input]:w-[94%] [&_input]:outline-none [&_button]:w-[3%]" />
-          <Hits hitComponent={Hit} />
-        </InstantSearch>
-      </Modal>
-    </>
-  )
-}
-
-const Hit = ({ hit }: { hit: Hit }) => {
-  return (
-    <div className="flex flex-row gap-x-2 mt-4 relative">
-      <Image src={hit.thumbnail} alt={hit.title} width={100} height={100} />
-      <div className="flex flex-col gap-y-1">
-        <h3>{hit.title}</h3>
-        <p className="text-sm text-gray-500">{hit.description}</p>
-      </div>
-      <Link href={`/products/${hit.handle}`} className="absolute right-0 top-0 w-full h-full" aria-label={`View Product: ${hit.title}`} />
-    </div>
-  )
-}
-```
-
-You create a `SearchModal` component that displays a search box and the search results using widgets from Algolia's `react-instantsearch` library.
-
-To display each result item (or hit), you create a `Hit` component that displays the product's title, description, and thumbnail. You also add a link to the product's page.
-
-Finally, you show the search modal when the customer clicks a "Search" button, which you'll add to the navigation bar next.
-
-### Add Search Button to Navigation Bar
-
-The last step is to show the search button in the navigation bar.
-
-In `src/modules/layout/templates/nav/index.tsx`, add the following imports at the top of the file:
-
-```tsx title="src/modules/layout/templates/nav/index.tsx" badgeLabel="Storefront" badgeColor="blue"
-import SearchModal from "@modules/search/components/modal"
-```
-
-Then, in the return statement of the `Nav` component, add the `SearchModal` component before the `div` surrounding the "Account" link:
-
-```tsx title="src/modules/layout/templates/nav/index.tsx" badgeLabel="Storefront" badgeColor="blue"
-<SearchModal />
-```
-
-The search button will now appear in the navigation bar before the Account link.
-
-### Test it Out
-
-To test out the storefront changes and the search API route, start the Medusa application:
-
-```bash npm2yarn
-npm run dev
-```
-
-Then, start the Next.js Starter Storefront from its directory:
-
-```bash npm2yarn
-npm run dev
-```
-
-Next, go to `localhost:8000`. You'll find a Search button at the top right of the navigation bar. If you click on it, you can search through your products. You can also click on a product to view its page.
-
-![The Next.js Starter Storefront showing the search modal with search results](https://res.cloudinary.com/dza7lstvk/image/upload/v1742827777/Medusa%20Resources/Screenshot_2025-03-24_at_4.49.23_PM_kzhldx.png)
-
-***
-
-## Next Steps
-
-You've now integrated Algolia with Medusa and added search functionality to your storefront. You can expand on these features to:
-
-- Add filters to the search results. You can do that using Algolia's [widgets](https://www.algolia.com/doc/guides/building-search-ui/widgets/showcase/react/) and customizing the search API route in Medusa to accept filter parameters.
-- Support indexing other data types, such as product categories. You can create the subscribers and workflows for categories similar to products.
-
-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 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 Magento Data Migration Plugin
-
-In this tutorial, you'll learn how to build a [plugin](https://docs.medusajs.com/docs/learn/fundamentals/plugins/index.html.md) that migrates data, such as products, from Magento to Medusa.
-
-Magento is known for its customization capabilities. However, its monolithic architecture imposes limitations on business requirements, often forcing development teams to implement hacky workarounds. Over time, these customizations become challenging to maintain, especially as the business scales, leading to increased technical debt and slower feature delivery.
-
-Medusa's modular architecture allows you to build a custom digital commerce platform that meets your business requirements without the limitations of a monolithic system. By migrating from Magento to Medusa, you can take advantage of Medusa's modern technology stack to build a scalable and flexible commerce platform that grows with your business.
-
-By following this tutorial, you'll create a Medusa plugin that migrates data from a Magento server to a Medusa application in minimal time. You can re-use this plugin across multiple Medusa applications, allowing you to adopt Medusa across your projects.
-
-## Summary
-
-### Prerequisites
-
-
-
-This tutorial will teach you how to:
-
-- Install and set up a Medusa application project.
-- Install and set up a Medusa plugin.
-- Implement a Magento Module in the plugin to connect to Magento's APIs and retrieve products.
-  - This guide will only focus on migrating product data from Magento to Medusa. You can extend the implementation to migrate other data, such as customers, orders, and more.
-- Trigger data migration from Magento to Medusa in a scheduled job.
-
-You can follow this tutorial whether you're new to Medusa or an advanced Medusa developer.
-
-![Diagram showcasing the flow of migrating data from Magento to Medusa](https://res.cloudinary.com/dza7lstvk/image/upload/v1739360550/Medusa%20Resources/magento-summary_hsewci.jpg)
-
-[Example Repository](https://github.com/medusajs/examples/tree/main/migrate-from-magento): Find the full code of the guide in this repository. The repository also includes additional features, such as triggering migrations from the Medusa Admin dashboard.
-
-***
-
-## Step 1: Install a Medusa Application
-
-You'll first install a Medusa application that exposes core commerce features through REST APIs. You'll later install the Magento plugin in this application to test it out.
-
-### Prerequisites
-
-- [Node.js v20+](https://nodejs.org/en/download)
-- [Git CLI tool](https://git-scm.com/downloads)
-- [PostgreSQL](https://www.postgresql.org/download/)
-
-Start by installing the Medusa application on your machine with the following command:
-
-```bash
-npx create-medusa-app@latest
-```
-
-You'll be asked for the project's name. You can also optionally choose to install the [Next.js starter storefront](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/nextjs-starter/index.html.md).
-
-Afterward, the installation process will start, which will install the Medusa application in a directory with your project's name. If you chose to install the Next.js starter, it'll be installed in a separate directory with the `{project-name}-storefront` name.
-
-The Medusa application is composed of a headless Node.js server and an admin dashboard. The storefront is installed or custom-built separately and connects to the Medusa application through its REST endpoints, called [API routes](https://docs.medusajs.com/docs/learn/fundamentals/api-routes/index.html.md). Refer to the [Medusa Architecture](https://docs.medusajs.com/docs/learn/introduction/architecture/index.html.md) documentation to learn more.
-
-Once the installation finishes successfully, the Medusa Admin dashboard will open with a form to create a new user. Enter the user's credentials and submit the form. Afterward, you can log in with the new user and explore the dashboard.
-
-Check out the [troubleshooting guides](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/troubleshooting/create-medusa-app-errors/index.html.md) for help.
-
-***
-
-## Step 2: Install a Medusa Plugin Project
-
-A plugin is a package of reusable Medusa customizations that you can install in any Medusa application. You can add in the plugin [API Routes](https://docs.medusajs.com/docs/learn/fundamentals/api-routes/index.html.md), [Workflows](https://docs.medusajs.com/docs/learn/fundamentals/workflows/index.html.md), and other customizations, as you'll see in this guide. Afterward, you can test it out locally in a Medusa application, then publish it to npm to install and use it in any Medusa application.
-
-Refer to the [Plugins](https://docs.medusajs.com/docs/learn/fundamentals/plugins/index.html.md) documentation to learn more about plugins.
-
-A Medusa plugin is set up in a different project, giving you the flexibility in building and publishing it, while providing you with the tools to test it out locally in a Medusa application.
-
-To create a new Medusa plugin project, run the following command in a directory different than that of the Medusa application:
-
-```bash npm2yarn
-npx create-medusa-app@latest medusa-plugin-magento --plugin
-```
-
-Where `medusa-plugin-magento` is the name of the plugin's directory and the name set in the plugin's `package.json`. So, if you wish to publish it to NPM later under a different name, you can change it here in the command or later in `package.json`.
-
-Once the installation process is done, a new directory named `medusa-plugin-magento` will be created with the plugin project files.
-
-![Directory structure of a plugin project](https://res.cloudinary.com/dza7lstvk/image/upload/v1737019441/Medusa%20Book/project-dir_q4xtri.jpg)
-
-***
-
-## Step 3: Set up Plugin in Medusa Application
-
-Before you start your development, you'll set up the plugin in the Medusa application you installed in the first step. This will allow you to test the plugin during your development process.
-
-In the plugin's directory, run the following command to publish the plugin to the local package registry:
-
-```bash title="Plugin project"
-npx medusa plugin:publish
-```
-
-This command uses [Yalc](https://github.com/wclr/yalc) under the hood to publish the plugin to a local package registry. The plugin is published locally under the name you specified in `package.json`.
-
-Next, you'll install the plugin in the Medusa application from the local registry.
-
-If you've installed your Medusa project before v2.3.1, you must install [yalc](https://github.com/wclr/yalc) as a development dependency first.
-
-Run the following command in the Medusa application's directory to install the plugin:
-
-```bash title="Medusa application"
-npx medusa plugin:add medusa-plugin-magento
-```
-
-This command installs the plugin in the Medusa application from the local package registry.
-
-Next, register the plugin in the `medusa-config.ts` file of the Medusa application:
-
-```ts title="medusa-config.ts"
-module.exports = defineConfig({
-  // ...
-  plugins: [
-    {
-      resolve: "medusa-plugin-magento",
-      options: {
-        // TODO add options
-      },
-    },
-  ],
-})
-```
-
-You add the plugin to the array of plugins. Later, you'll pass options useful to retrieve data from Magento.
-
-Finally, to ensure your plugin's changes are constantly published to the local registry, simplifying your testing process, keep the following command running in the plugin project during development:
-
-```bash title="Plugin project"
-npx medusa plugin:develop
-```
-
-***
-
-## Step 4: Implement Magento Module
-
-To connect to external applications in Medusa, you create a custom module. A module is a reusable package with functionalities related to a single feature or domain. Medusa integrates the module into your application without implications or side effects on your setup.
-
-In this step, you'll create a Magento Module in the Magento plugin that connects to a Magento server's REST APIs and retrieves data, such as products.
-
-Refer to the [Modules](https://docs.medusajs.com/docs/learn/fundamentals/modules/index.html.md) documentation to learn more about modules.
-
-### Create Module Directory
-
-A module is created under the `src/modules` directory of your plugin. So, create the directory `src/modules/magento`.
-
-![Diagram showcasing the module directory to create](https://res.cloudinary.com/dza7lstvk/image/upload/v1739272368/magento-1_ikev4x.jpg)
-
-### Create Module's Service
-
-You define a module's functionalities in a service. A service is a TypeScript or JavaScript class that the module exports. In the service's methods, you can connect to external systems or the database, which is useful if your module defines tables in the database.
-
-In this section, you'll create the Magento Module's service that connects to Magento's REST APIs and retrieves data.
-
-Start by creating the file `src/modules/magento/service.ts` in the plugin with the following content:
-
-![Diagram showcasing the service file to create](https://res.cloudinary.com/dza7lstvk/image/upload/v1739272483/magento-2_ajetpr.jpg)
-
-```ts title="src/modules/magento/service.ts"
-type Options = {
-  baseUrl: string
-  storeCode?: string
-  username: string
-  password: string
-  migrationOptions?: {
-    imageBaseUrl?: string
-  }
-}
-
-export default class MagentoModuleService {
-  private options: Options
-
-  constructor({}, options: Options) {
-    this.options = {
-      ...options,
-      storeCode: options.storeCode || "default",
-    }
-  }
-}
-```
-
-You create a `MagentoModuleService` that has an `options` property to store the module's options. These options include:
-
-- `baseUrl`: The base URL of the Magento server.
-- `storeCode`: The store code of the Magento store, which is `default` by default.
-- `username`: The username of a Magento admin user to authenticate with the Magento server.
-- `password`: The password of the Magento admin user.
-- `migrationOptions`: Additional options useful for migrating data, such as the base URL to use for product images.
-
-The service's constructor accepts as a first parameter the [Module Container](https://docs.medusajs.com/docs/learn/fundamentals/modules/container/index.html.md), which allows you to access resources available for the module. As a second parameter, it accepts the module's options.
-
-### Add Authentication Logic
-
-To authenticate with the Magento server, you'll add a method to the service that retrieves an access token from Magento using the username and password in the options. This access token is used in subsequent requests to the Magento server.
-
-First, add the following property to the `MagentoModuleService` class:
-
-```ts title="src/modules/magento/service.ts"
-export default class MagentoModuleService {
-  private accessToken: {
-    token: string
-    expiresAt: Date
-  }
-  // ...
-}
-```
-
-You add an `accessToken` property to store the access token and its expiration date. The access token Magento returns expires after four hours, so you store the expiration date to know when to refresh the token.
-
-Next, add the following `authenticate` method to the `MagentoModuleService` class:
-
-```ts title="src/modules/magento/service.ts"
-import { MedusaError } from "@medusajs/framework/utils"
-
-export default class MagentoModuleService {
-  // ...
-  async authenticate() {
-    const response = await fetch(`${this.options.baseUrl}/rest/${this.options.storeCode}/V1/integration/admin/token`, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-      },
-      body: JSON.stringify({ username: this.options.username, password: this.options.password }),
-    })
-
-    const token = await response.text()
-
-    if (!response.ok) {
-      throw new MedusaError(MedusaError.Types.UNAUTHORIZED, `Failed to authenticate with Magento: ${token}`)
-    }
-
-    this.accessToken = {
-      token: token.replaceAll("\"", ""),
-      expiresAt: new Date(Date.now() + 4 * 60 * 60 * 1000), // 4 hours in milliseconds
-    }
-  }
-}
-```
-
-You create an `authenticate` method that sends a POST request to the Magento server's `/rest/{storeCode}/V1/integration/admin/token` endpoint, passing the username and password in the request body.
-
-If the request is successful, you store the access token and its expiration date in the `accessToken` property. If the request fails, you throw a `MedusaError` with the error message returned by Magento.
-
-Lastly, add an `isAccessTokenExpired` method that checks if the access token has expired:
-
-```ts title="src/modules/magento/service.ts"
-export default class MagentoModuleService {
-  // ...
-  async isAccessTokenExpired(): Promise<boolean> {
-    return !this.accessToken || this.accessToken.expiresAt < new Date()
-  }
-}
-```
-
-In the `isAccessTokenExpired` method, you return a boolean indicating whether the access token has expired. You'll use this in later methods to check if you need to refresh the access token.
-
-### Retrieve Products from Magento
-
-Next, you'll add a method that retrieves products from Magento. Due to limitations in Magento's API that makes it difficult to differentiate between simple products that don't belong to a configurable product and those that do, you'll only retrieve configurable products and their children. You'll also retrieve the configurable attributes of the product, such as color and size.
-
-First, you'll add some types to represent a Magento product and its attributes. Create the file `src/modules/magento/types.ts` in the plugin with the following content:
-
-![Diagram showcasing the types file to create](https://res.cloudinary.com/dza7lstvk/image/upload/v1739346287/Medusa%20Resources/magento-3_fpghog.jpg)
-
-```ts title="src/modules/magento/types.ts"
-export type MagentoProduct = {
-  id: number
-  sku: string
-  name: string
-  price: number
-  status: number
-  // not handling other types
-  type_id: "simple" | "configurable"
-  created_at: string
-  updated_at: string
-  extension_attributes: {
-    category_links: {
-      category_id: string
-    }[]
-    configurable_product_links?: number[] 
-    configurable_product_options?: {
-      id: number
-      attribute_id: string
-      label: string
-      position: number
-      values: {
-        value_index: number
-      }[]
-    }[]
-  }
-  media_gallery_entries: {
-    id: number
-    media_type: string
-    label: string
-    position: number
-    disabled: boolean
-    types: string[]
-    file: string
-  }[]
-  custom_attributes: {
-    attribute_code: string
-    value: string
-  }[]
-  // added by module
-  children?: MagentoProduct[]
-}
-
-export type MagentoAttribute = {
-  attribute_code: string
-  attribute_id: number
-  default_frontend_label: string
-  options: {
-    label: string
-    value: string
-  }[]
-}
-
-export type MagentoPagination = {
-  search_criteria: {
-    filter_groups: [],
-    page_size: number
-    current_page: number
-  }
-  total_count: number
-}
-
-export type MagentoPaginatedResponse<TData> = {
-  items: TData[]
-} & MagentoPagination
-```
-
-You define the following types:
-
-- `MagentoProduct`: Represents a product in Magento.
-- `MagentoAttribute`: Represents an attribute in Magento.
-- `MagentoPagination`: Represents the pagination information returned by Magento's API.
-- `MagentoPaginatedResponse`: Represents a paginated response from Magento's API for a specific item type, such as products.
-
-Next, add the `getProducts` method to the `MagentoModuleService` class:
-
-```ts title="src/modules/magento/service.ts"
-export default class MagentoModuleService {
-  // ...
-  async getProducts(options?: {
-    currentPage?: number
-    pageSize?: number
-  }): Promise<{
-    products: MagentoProduct[]
-    attributes: MagentoAttribute[]
-    pagination: MagentoPagination
-  }> {
-    const { currentPage = 1, pageSize = 100 } = options || {}
-    const getAccessToken = await this.isAccessTokenExpired()
-    if (getAccessToken) {
-      await this.authenticate()
-    }
-
-    // TODO prepare query params
-  }
-}
-```
-
-The `getProducts` method receives an optional `options` object with the `currentPage` and `pageSize` properties. So far, you check if the access token has expired and, if so, retrieve a new one using the `authenticate` method.
-
-Next, you'll prepare the query parameters to pass in the request that retrieves products. Replace the `TODO` with the following:
-
-```ts title="src/modules/magento/service.ts"
-const searchQuery = new URLSearchParams()
-// pass pagination parameters
-searchQuery.append(
-  "searchCriteria[currentPage]", 
-  currentPage?.toString() || "1"
-)
-searchQuery.append(
-  "searchCriteria[pageSize]", 
-  pageSize?.toString() || "100"
-)
-
-// retrieve only configurable products
-searchQuery.append(
-  "searchCriteria[filter_groups][1][filters][0][field]", 
-  "type_id"
-)
-searchQuery.append(
-  "searchCriteria[filter_groups][1][filters][0][value]", 
-  "configurable"
-)
-searchQuery.append(
-  "searchCriteria[filter_groups][1][filters][0][condition_type]", 
-  "in"
-)
-
-// TODO send request to retrieve products
-```
-
-You create a `searchQuery` object to store the query parameters to pass in the request. Then, you add the pagination parameters and the filter to retrieve only configurable products.
-
-Next, you'll send the request to retrieve products from Magento. Replace the `TODO` with the following:
-
-```ts title="src/modules/magento/service.ts"
-const { items: products, ...pagination }: MagentoPaginatedResponse<MagentoProduct> = await fetch(
-  `${this.options.baseUrl}/rest/${this.options.storeCode}/V1/products?${searchQuery}`, 
-  {
-    headers: {
-      "Authorization": `Bearer ${this.accessToken.token}`,
-    },
-  }
-).then((res) => res.json())
-.catch((err) => {
-  console.log(err)
-  throw new MedusaError(
-    MedusaError.Types.INVALID_DATA, 
-    `Failed to get products from Magento: ${err.message}`
-  )
-})
-
-// TODO prepare products
-```
-
-You send a `GET` request to the Magento server's `/rest/{storeCode}/V1/products` endpoint, passing the query parameters in the URL. You also pass the access token in the `Authorization` header.
-
-Next, you'll prepare the retrieved products by retrieving their children, configurable attributes, and modifying their image URLs. Replace the `TODO` with the following:
-
-```ts title="src/modules/magento/service.ts"
-const attributeIds: string[] = []
-
-await promiseAll(
-  products.map(async (product) => {
-    // retrieve its children
-    product.children = await fetch(
-      `${this.options.baseUrl}/rest/${this.options.storeCode}/V1/configurable-products/${product.sku}/children`,
-      {
-        headers: {
-          "Authorization": `Bearer ${this.accessToken.token}`,
-        },
-      }
-    ).then((res) => res.json())
-    .catch((err) => {
-      throw new MedusaError(
-        MedusaError.Types.INVALID_DATA, 
-        `Failed to get product children from Magento: ${err.message}`
-      )
-    })
-
-    product.media_gallery_entries = product.media_gallery_entries.map(
-      (entry) => ({
-        ...entry,
-        file: `${this.options.migrationOptions?.imageBaseUrl}${entry.file}`,
-      }
-    ))
-
-    attributeIds.push(...(
-      product.extension_attributes.configurable_product_options?.map(
-        (option) => option.attribute_id) || []
-      )
-    )
-  })
-)
-
-// TODO retrieve attributes
-```
-
-You loop over the retrieved products and retrieve their children using the `/rest/{storeCode}/V1/configurable-products/{sku}/children` endpoint. You also modify the image URLs to use the base URL in the migration options, if provided.
-
-In addition, you store the IDs of the configurable products' attributes in the `attributeIds` array. You'll add a method that retrieves these attributes.
-
-Add the new method `getAttributes` to the `MagentoModuleService` class:
-
-```ts title="src/modules/magento/service.ts"
-export default class MagentoModuleService {
-  // ...
-  async getAttributes({
-    ids,
-  }: {
-    ids: string[]
-  }): Promise<MagentoAttribute[]> {
-    const getAccessToken = await this.isAccessTokenExpired()
-    if (getAccessToken) {
-      await this.authenticate()
-    }
-
-    // filter by attribute IDs
-    const searchQuery = new URLSearchParams()
-    searchQuery.append(
-      "searchCriteria[filter_groups][0][filters][0][field]", 
-      "attribute_id"
-    )
-    searchQuery.append(
-      "searchCriteria[filter_groups][0][filters][0][value]", 
-      ids.join(",")
-    )
-    searchQuery.append(
-      "searchCriteria[filter_groups][0][filters][0][condition_type]", 
-      "in"
-    )
-
-    const { 
-      items: attributes,
-    }: MagentoPaginatedResponse<MagentoAttribute> = await fetch(
-      `${this.options.baseUrl}/rest/${this.options.storeCode}/V1/products/attributes?${searchQuery}`, 
-      {
-        headers: {
-          "Authorization": `Bearer ${this.accessToken.token}`,
-        },
-      }
-    ).then((res) => res.json())
-    .catch((err) => {
-      throw new MedusaError(
-        MedusaError.Types.INVALID_DATA, 
-        `Failed to get attributes from Magento: ${err.message}`
-      )
-    })
-
-    return attributes
-  }
-}
-```
-
-The `getAttributes` method receives an object with the `ids` property, which is an array of attribute IDs. You check if the access token has expired and, if so, retrieve a new one using the `authenticate` method.
-
-Next, you prepare the query parameters to pass in the request to retrieve attributes. You send a `GET` request to the Magento server's `/rest/{storeCode}/V1/products/attributes` endpoint, passing the query parameters in the URL. You also pass the access token in the `Authorization` header.
-
-Finally, you return the retrieved attributes.
-
-Now, go back to the `getProducts` method and replace the `TODO` with the following:
-
-```ts title="src/modules/magento/service.ts"
-const attributes = await this.getAttributes({ ids: attributeIds })
-    
-return { products, attributes, pagination }
-```
-
-You retrieve the configurable products' attributes using the `getAttributes` method and return the products, attributes, and pagination information.
-
-You'll use this method in a later step to retrieve products from Magento.
-
-### Export Module Definition
-
-The final piece to a module is its definition, which you export in an `index.ts` file at its root directory. This definition tells Medusa the name of the module and its service.
-
-So, create the file `src/modules/magento/index.ts` with the following content:
-
-![Diagram showcasing the module definition file to create](https://res.cloudinary.com/dza7lstvk/image/upload/v1739348316/Medusa%20Resources/magento-4_bmepvh.jpg)
-
-```ts title="src/modules/magento/index.ts"
-import { Module } from "@medusajs/framework/utils"
-import MagentoModuleService from "./service"
-
-export const MAGENTO_MODULE = "magento"
-
-export default Module(MAGENTO_MODULE, {
-  service: MagentoModuleService,
-})
-```
-
-You use the `Module` function from the Modules SDK to create the module's definition. It accepts two parameters:
-
-1. The module's name, which is `magento`.
-2. An object with a required property `service` indicating the module's service.
-
-You'll later use the module's service to retrieve products from Magento.
-
-### Pass Options to Plugin
-
-As mentioned earlier when you registered the plugin in the Medusa Application's `medusa-config.ts` file, you can pass options to the plugin. These options are then passed to the modules in the plugin.
-
-So, add the following options to the plugin's registration in the `medusa-config.ts` file of the Medusa application:
-
-```ts title="medusa-config.ts"
-module.exports = defineConfig({
-  // ...
-  plugins: [
-    {
-      resolve: "medusa-plugin-magento",
-      options: {
-        baseUrl: process.env.MAGENTO_BASE_URL,
-        username: process.env.MAGENTO_USERNAME,
-        password: process.env.MAGENTO_PASSWORD,
-        migrationOptions: {
-          imageBaseUrl: process.env.MAGENTO_IMAGE_BASE_URL,
-        },
-      },
-    },
-  ],
-})
-```
-
-You pass the options that you defined in the `MagentoModuleService`. Make sure to also set their environment variables in the `.env` file:
-
-```bash
-MAGENTO_BASE_URL=https://magento.example.com
-MAGENTO_USERNAME=admin
-MAGENTO_PASSWORD=password
-MAGENTO_IMAGE_BASE_URL=https://magento.example.com/pub/media/catalog/product
-```
-
-Where:
-
-- `MAGENTO_BASE_URL`: The base URL of the Magento server. It can also be a local URL, such as `http://localhost:8080`.
-- `MAGENTO_USERNAME`: The username of a Magento admin user to authenticate with the Magento server.
-- `MAGENTO_PASSWORD`: The password of the Magento admin user.
-- `MAGENTO_IMAGE_BASE_URL`: The base URL to use for product images. Magento stores product images in the `pub/media/catalog/product` directory, so you can reference them directly or use a CDN URL. If the URLs of product images in the Medusa server already have a different base URL, you can omit this option.
-
-Medusa supports integrating third-party services, such as [S3](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/infrastructure-modules/file/s3/index.html.md), in a File Module Provider. Refer to the [File Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/infrastructure-modules/file/index.html.md) documentation to find other module providers and how to create a custom provider.
-
-You can now use the Magento Module to migrate data, which you'll do in the next steps.
-
-***
-
-## Step 5: Build Product Migration Workflow
-
-In this section, you'll add the feature to migrate products from Magento to Medusa. To implement this feature, you'll use a workflow.
-
-A workflow is a series of queries and actions, called steps, that complete a task. You construct a workflow like you construct a function, but it's a special function that allows you to track its executions' progress, define roll-back logic, and configure other advanced features. Then, you execute the workflow from other customizations, such as in an API route or a scheduled job.
-
-By implementing the migration feature in a workflow, you ensure that the data remains consistent and that the migration process can be rolled back if an error occurs.
-
-Refer to the [Workflows](https://docs.medusajs.com/docs/learn/fundamentals/workflows/index.html.md) documentation to learn more about workflows.
-
-### Workflow Steps
-
-The workflow you'll create will have the following steps:
-
-- [getMagentoProductsStep](#getMagentoProductsStep): Retrieve products from Magento using the Magento Module.
-- [useQueryGraphStep](https://docs.medusajs.com/references/helper-steps/useQueryGraphStep/index.html.md): Retrieve Medusa store details, which you'll need when creating the products.
-- [useQueryGraphStep](https://docs.medusajs.com/references/helper-steps/useQueryGraphStep/index.html.md): Retrieve a shipping profile, which you'll associate the created products with.
-- [useQueryGraphStep](https://docs.medusajs.com/references/helper-steps/useQueryGraphStep/index.html.md): Retrieve Magento products that are already in Medusa to update them, instead of creating them.
-- [createProductsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createProductsWorkflow/index.html.md): Create products in the Medusa application.
-- [updateProductsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateProductsWorkflow/index.html.md): Update existing products in the Medusa application.
-
-You only need to implement the `getMagentoProductsStep` step, which retrieves the products from Magento. The other steps and workflows are provided by Medusa's `@medusajs/medusa/core-flows` package.
-
-### getMagentoProductsStep
-
-The first step of the workflow retrieves and returns the products from Magento.
-
-In your plugin, create the file `src/workflows/steps/get-magento-products.ts` with the following content:
-
-![Diagram showcasing the get-magento-products file to create](https://res.cloudinary.com/dza7lstvk/image/upload/v1739349590/Medusa%20Resources/magento-5_ueb4wn.jpg)
-
-```ts title="src/workflows/steps/get-magento-products.ts"
-import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk"
-import { MAGENTO_MODULE } from "../../modules/magento"
-import MagentoModuleService from "../../modules/magento/service"
-
-type GetMagentoProductsInput = {
-  currentPage: number
-  pageSize: number
-}
-
-export const getMagentoProductsStep = createStep(
-  "get-magento-products",
-  async ({ currentPage, pageSize }: GetMagentoProductsInput, { container }) => {
-    const magentoModuleService: MagentoModuleService = 
-      container.resolve(MAGENTO_MODULE)
-
-    const response = await magentoModuleService.getProducts({
-      currentPage,
-      pageSize,
-    })
-
-    return new StepResponse(response)
-  }
-)
-```
-
-You create a step using `createStep` from the Workflows SDK. It accepts two parameters:
-
-1. The step's name, which is `get-magento-products`.
-2. An async function that executes the step's logic. The function receives two parameters:
-   - The input data for the step, which in this case is the pagination parameters.
-   - An object holding the workflow's context, including the [Medusa Container](https://docs.medusajs.com/docslearn/fundamentals/medusa-container/index.html.md) that allows you to resolve Framework and commerce tools.
-
-In the step function, you resolve the Magento Module's service from the container, then use its `getProducts` method to retrieve the products from Magento.
-
-Steps that return data must return them in a `StepResponse` instance. The `StepResponse` constructor accepts as a parameter the data to return.
-
-### Create migrateProductsFromMagentoWorkflow
-
-You'll now create the workflow that migrates products from Magento using the step you created and steps from Medusa's `@medusajs/medusa/core-flows` package.
-
-In your plugin, create the file `src/workflows/migrate-products-from-magento.ts` with the following content:
-
-![Diagram showcasing the migrate-products-from-magento file to create](https://res.cloudinary.com/dza7lstvk/image/upload/v1739349820/Medusa%20Resources/magento-6_jjdaxj.jpg)
-
-```ts title="src/workflows/migrate-products-from-magento.ts"
-import { 
-  createWorkflow, transform, WorkflowResponse,
-} from "@medusajs/framework/workflows-sdk"
-import { 
-  CreateProductWorkflowInputDTO, UpsertProductDTO,
-} from "@medusajs/framework/types"
-import { 
-  createProductsWorkflow, 
-  updateProductsWorkflow, 
-  useQueryGraphStep,
-} from "@medusajs/medusa/core-flows"
-import { getMagentoProductsStep } from "./steps/get-magento-products"
-
-type MigrateProductsFromMagentoWorkflowInput = {
-  currentPage: number
-  pageSize: number
-}
-
-export const migrateProductsFromMagentoWorkflowId = 
-  "migrate-products-from-magento"
-
-export const migrateProductsFromMagentoWorkflow = createWorkflow(
-  {
-    name: migrateProductsFromMagentoWorkflowId,
-    retentionTime: 10000,
-    store: true,
-  },
-  (input: MigrateProductsFromMagentoWorkflowInput) => {
-    const { pagination, products, attributes } = getMagentoProductsStep(
-      input
-    )
-    // TODO prepare data to create and update products
-  }
-)
-```
-
-You create a workflow using `createWorkflow` from the Workflows SDK. It accepts two parameters:
-
-1. An object with the workflow's configuration, including the name and whether to store the workflow's executions. You enable storing the workflow execution so that you can view it later in the Medusa Admin dashboard.
-2. A worflow constructor function, which holds the workflow's implementation. The function receives the input data for the workflow, which is the pagination parameters.
-
-In the workflow constructor function, you use the `getMagentoProductsStep` step to retrieve the products from Magento, passing it the pagination parameters from the workflow's input.
-
-Next, you'll retrieve the Medusa store details and shipping profiles. These are necessary to prepare the data of the products to create or update.
-
-Replace the `TODO` in the workflow function with the following:
-
-```ts title="src/workflows/migrate-products-from-magento.ts"
-const { data: stores } = useQueryGraphStep({
-  entity: "store",
-  fields: ["supported_currencies.*", "default_sales_channel_id"],
-  pagination: {
-    take: 1,
-    skip: 0,
-  },
-})
-
-const { data: shippingProfiles } = useQueryGraphStep({
-  entity: "shipping_profile",
-  fields: ["id"],
-  pagination: {
-    take: 1,
-    skip: 0,
-  },
-}).config({ name: "get-shipping-profiles" })
-
-// TODO retrieve existing products
-```
-
-You use the `useQueryGraphStep` step to retrieve the store details and shipping profiles. `useQueryGraphStep` is a Medusa step that wraps [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), allowing you to use it in a workflow. Query is a tool that retrieves data across modules.
-
-Whe retrieving the store details, you specifically retrieve its supported currencies and default sales channel ID. You'll associate the products with the store's default sales channel, and set their variant prices in the supported currencies. You'll also associate the products with a shipping profile.
-
-Next, you'll retrieve products that were previously migrated from Magento to determine which products to create or update. Replace the `TODO` with the following:
-
-```ts title="src/workflows/migrate-products-from-magento.ts"
-const externalIdFilters = transform({
-  products,
-}, (data) => {
-  return data.products.map((product) => product.id.toString())
-})
-
-const { data: existingProducts } = useQueryGraphStep({
-  entity: "product",
-  fields: ["id", "external_id", "variants.id", "variants.metadata"],
-  filters: {
-    external_id: externalIdFilters,
-  },
-}).config({ name: "get-existing-products" })
-
-// TODO prepare products to create or update
-```
-
-Since the Medusa application creates an internal representation of the workflow's constructor function, you can't manipulate data directly, as variables have no value while creating the internal representation.
-
-Refer to the [Workflows](https://docs.medusajs.com/docs/learn/fundamentals/workflows/constructor-constraints/index.html.md) documentation to learn more about the workflow constructor function's constraints.
-
-Instead, you can manipulate data in a workflow's constructor function using `transform` from the Workflows SDK. `transform` is a function that accepts two parameters:
-
-- The data to transform, which in this case is the Magento products.
-- A function that transforms the data. The function receives the data passed in the first parameter and returns the transformed data.
-
-In the transformation function, you return the IDs of the Magento products. Then, you use the `useQueryGraphStep` to retrieve products in the Medusa application that have an `external_id` property matching the IDs of the Magento products. You'll use this property to store the IDs of the products in Magento.
-
-Next, you'll prepare the data to create and update the products. Replace the `TODO` in the workflow function with the following:
-
-```ts title="src/workflows/migrate-products-from-magento.ts" highlights={prepareHighlights}
-const { 
-  productsToCreate,
-  productsToUpdate,
-} = transform({
-  products,
-  attributes,
-  stores,
-  shippingProfiles,
-  existingProducts,
-}, (data) => {
-  const productsToCreate = new Map<string, CreateProductWorkflowInputDTO>()
-  const productsToUpdate = new Map<string, UpsertProductDTO>()
-
-  data.products.forEach((magentoProduct) => {
-    const productData: CreateProductWorkflowInputDTO | UpsertProductDTO = {
-      title: magentoProduct.name,
-      description: magentoProduct.custom_attributes.find(
-        (attr) => attr.attribute_code === "description"
-      )?.value,
-      status: magentoProduct.status === 1 ? "published" : "draft",
-      handle: magentoProduct.custom_attributes.find(
-        (attr) => attr.attribute_code === "url_key"
-      )?.value,
-      external_id: magentoProduct.id.toString(),
-      thumbnail: magentoProduct.media_gallery_entries.find(
-        (entry) => entry.types.includes("thumbnail")
-      )?.file,
-      sales_channels: [{
-        id: data.stores[0].default_sales_channel_id,
-      }],
-      shipping_profile_id: data.shippingProfiles[0].id,
-    }
-    const existingProduct = data.existingProducts.find((p) => p.external_id === productData.external_id)
-
-    if (existingProduct) {
-      productData.id = existingProduct.id
-    }
-
-    productData.options = magentoProduct.extension_attributes.configurable_product_options?.map((option) => {
-      const attribute = data.attributes.find((attr) => attr.attribute_id === parseInt(option.attribute_id))
-      return {
-        title: option.label,
-        values: attribute?.options.filter((opt) => {
-          return option.values.find((v) => v.value_index === parseInt(opt.value))
-        }).map((opt) => opt.label) || [],
-      }
-    }) || []
-
-    productData.variants = magentoProduct.children?.map((child) => {
-      const childOptions: Record<string, string> = {}
-
-      child.custom_attributes.forEach((attr) => {
-        const attrData = data.attributes.find((a) => a.attribute_code === attr.attribute_code)
-        if (!attrData) {
-          return
-        }
-
-        childOptions[attrData.default_frontend_label] = attrData.options.find((opt) => opt.value === attr.value)?.label || ""
-      })
-
-      const variantExternalId = child.id.toString()
-      const existingVariant = existingProduct.variants.find((v) => v.metadata.external_id === variantExternalId)
-
-      return {
-        title: child.name,
-        sku: child.sku,
-        options: childOptions,
-        prices: data.stores[0].supported_currencies.map(({ currency_code }) => {
-          return {
-            amount: child.price,
-            currency_code,
-          }
-        }),
-        metadata: {
-          external_id: variantExternalId,
-        },
-        id: existingVariant?.id,
-      }
-    })
-
-    productData.images = magentoProduct.media_gallery_entries.filter((entry) => !entry.types.includes("thumbnail")).map((entry) => {
-      return {
-        url: entry.file,
-        metadata: {
-          external_id: entry.id.toString(),
-        },
-      }
-    })
-
-    if (productData.id) {
-      productsToUpdate.set(existingProduct.id, productData)
-    } else {
-      productsToCreate.set(productData.external_id!, productData)
-    }
-  })
-
-  return {
-    productsToCreate: Array.from(productsToCreate.values()),
-    productsToUpdate: Array.from(productsToUpdate.values()),
-  }
-})
-
-// TODO create and update products
-```
-
-You use `transform` again to prepare the data to create and update the products in the Medusa application. For each Magento product, you map its equivalent Medusa product's data:
-
-- You set the product's general details, such as the title, description, status, handle, external ID, and thumbnail using the Magento product's data and custom attributes.
-- You associate the product with the default sales channel and shipping profile retrieved previously.
-- You map the Magento product's configurable product options to Medusa product options. In Medusa, a product's option has a label, such as "Color", and values, such as "Red". To map the option values, you use the attributes retrieved from Magento.
-- You map the Magento product's children to Medusa product variants. For the variant options, you pass an object whose keys is the option's label, such as "Color", and values is the option's value, such as "Red". For the prices, you set the variant's price based on the Magento child's price for every supported currency in the Medusa store. Also, you set the Magento child product's ID in the Medusa variant's `metadata.external_id` property.
-- You map the Magento product's media gallery entries to Medusa product images. You filter out the thumbnail image and set the URL and the Magento image's ID in the Medusa image's `metadata.external_id` property.
-
-In addition, you use the existing products retrieved in the previous step to determine whether a product should be created or updated. If there's an existing product whose `external_id` matches the ID of the magento product, you set the existing product's ID in the `id` property of the product to be updated. You also do the same for its variants.
-
-Finally, you return the products to create and update.
-
-The last steps of the workflow is to create and update the products. Replace the `TODO` in the workflow function with the following:
-
-```ts title="src/workflows/migrate-products-from-magento.ts"
-createProductsWorkflow.runAsStep({
-  input: {
-    products: productsToCreate,
-  },
-})
-
-updateProductsWorkflow.runAsStep({
-  input: {
-    products: productsToUpdate,
-  },
-})
-
-return new WorkflowResponse(pagination)
-```
-
-You use the `createProductsWorkflow` and `updateProductsWorkflow` workflows from Medusa's `@medusajs/medusa/core-flows` package to create and update the products in the Medusa application.
-
-Workflows must return an instance of `WorkflowResponse`, passing as a parameter the data to return to the workflow's executor. This workflow returns the pagination parameters, allowing you to paginate the product migration process.
-
-You can now use this workflow to migrate products from Magento to Medusa. You'll learn how to use it in the next steps.
-
-***
-
-## Step 6: Schedule Product Migration
-
-There are many ways to execute tasks asynchronously in Medusa, such as [scheduling a job](https://docs.medusajs.com/docs/learn/fundamentals/scheduled-jobs/index.html.md) or [handling emitted events](https://docs.medusajs.com/docs/learn/fundamentals/events-and-subscribers/index.html.md).
-
-In this guide, you'll learn how to schedule the product migration at a specified interval using a scheduled job. A scheduled job is an asynchronous function that the Medusa application runs at the interval you specify during the Medusa application's runtime.
-
-Refer to the [Scheduled Jobs](https://docs.medusajs.com/docs/learn/fundamentals/scheduled-jobs/index.html.md) documentation to learn more about scheduled jobs.
-
-To create a scheduled job, in your plugin, create the file `src/jobs/migrate-magento.ts` with the following content:
-
-![Diagram showcasing the migrate-magento file to create](https://res.cloudinary.com/dza7lstvk/image/upload/v1739358924/Medusa%20Resources/magento-7_rqoodo.jpg)
-
-```ts title="src/jobs/migrate-magento.ts"
-import { MedusaContainer } from "@medusajs/framework/types"
-import { migrateProductsFromMagentoWorkflow } from "../workflows"
-
-export default async function migrateMagentoJob(
-  container: MedusaContainer
-) {
-  const logger = container.resolve("logger")
-    logger.info("Migrating products from Magento...")
-    
-    let currentPage = 0
-    const pageSize = 100
-    let totalCount = 0
-  
-    do {
-      currentPage++
-  
-      const { 
-        result: pagination,
-      } = await migrateProductsFromMagentoWorkflow(container).run({
-        input: {
-          currentPage,
-          pageSize,
-        },
-      })
-  
-      totalCount = pagination.total_count
-    } while (currentPage * pageSize < totalCount)
-  
-    logger.info("Finished migrating products from Magento")
-}
-
-export const config = {
-  name: "migrate-magento-job",
-  schedule: "0 0 * * *",
-}
-```
-
-A scheduled job file must export:
-
-- An asynchronous function that executes the job's logic. The function receives the [Medusa container](https://docs.medusajs.com/docs/learn/fundamentals/medusa-container/index.html.md) as a parameter.
-- An object with the job's configuration, including the name and the schedule. The schedule is a cron job pattern as a string.
-
-In the job function, you resolve the [logger](https://docs.medusajs.com/docs/learn/debugging-and-testing/logging/index.html.md) from the container to log messages. Then, you paginate the product migration process by running the `migrateProductsFromMagentoWorkflow` workflow at each page until you've migrated all products. You use the pagination result returned by the workflow to determine whether there are more products to migrate.
-
-Based on the job's configurations, the Medusa application will run the job at midnight every day.
-
-### Test it Out
-
-To test out this scheduled job, first, change the configuration to run the job every minute:
-
-```ts title="src/jobs/migrate-magento.ts"
-export const config = {
-  // ...
-  schedule: "* * * * *",
-}
-```
-
-Then, make sure to run the `plugin:develop` command in the plugin if you haven't already:
-
-```bash
-npx medusa plugin:develop
-```
-
-This ensures that the plugin's latest changes are reflected in the Medusa application.
-
-Finally, start the Medusa application that the plugin is installed in:
-
-```bash npm2yarn
-npm run dev
-```
-
-After a minute, you'll see a message in the terminal indicating that the migration started:
-
-```plain title="Terminal"
-info: Migrating products from Magento...
-```
-
-Once the migration is done, you'll see the following message:
-
-```plain title="Terminal"
-info: Finished migrating products from Magento
-```
-
-To confirm that the products were migrated, open the Medusa Admin dashboard at `http://localhost:9000/app` and log in. Then, click on Products in the sidebar. You'll see your magento products in the list of products.
-
-![Click on products at the sidebar on the right, then view the products in the table in the middle.](https://res.cloudinary.com/dza7lstvk/image/upload/v1739359394/Medusa%20Resources/Screenshot_2025-02-12_at_1.22.44_PM_uva98i.png)
-
-***
-
-## Next Steps
-
-You've now implemented the logic to migrate products from Magento to Medusa. You can re-use the plugin across Medusa applications. You can also expand on the plugin to:
-
-- Migrate other entities, such as orders, customers, and categories. Migrating other entities follows the same pattern as migrating products, using workflows and scheduled jobs. You only need to format the data to be migrated as needed.
-- Allow triggering migrations from the Medusa Admin dashboard using [Admin Customizations](https://docs.medusajs.com/docs/learn/fundamentals/admin/index.html.md). This feature is available in the [Example Repository](https://github.com/medusajs/example-repository/tree/main/src/admin).
-
-If you're new to Medusa, check out the [main documentation](https://docs.medusajs.com/docs/learn/index.html.md), where you'll get a more in-depth learning of all the concepts you've used in this guide and more.
-
-To learn more about the commerce features that Medusa provides, check out Medusa's [Commerce Modules](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/index.html.md).
-
-
 # Integrate Medusa with Sanity (CMS)
 
 In this guide, you'll learn how to integrate Medusa with Sanity.
@@ -49873,6 +46519,2268 @@ 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).
 
 
+# How to Build Magento Data Migration Plugin
+
+In this tutorial, you'll learn how to build a [plugin](https://docs.medusajs.com/docs/learn/fundamentals/plugins/index.html.md) that migrates data, such as products, from Magento to Medusa.
+
+Magento is known for its customization capabilities. However, its monolithic architecture imposes limitations on business requirements, often forcing development teams to implement hacky workarounds. Over time, these customizations become challenging to maintain, especially as the business scales, leading to increased technical debt and slower feature delivery.
+
+Medusa's modular architecture allows you to build a custom digital commerce platform that meets your business requirements without the limitations of a monolithic system. By migrating from Magento to Medusa, you can take advantage of Medusa's modern technology stack to build a scalable and flexible commerce platform that grows with your business.
+
+By following this tutorial, you'll create a Medusa plugin that migrates data from a Magento server to a Medusa application in minimal time. You can re-use this plugin across multiple Medusa applications, allowing you to adopt Medusa across your projects.
+
+## Summary
+
+### Prerequisites
+
+
+
+This tutorial will teach you how to:
+
+- Install and set up a Medusa application project.
+- Install and set up a Medusa plugin.
+- Implement a Magento Module in the plugin to connect to Magento's APIs and retrieve products.
+  - This guide will only focus on migrating product data from Magento to Medusa. You can extend the implementation to migrate other data, such as customers, orders, and more.
+- Trigger data migration from Magento to Medusa in a scheduled job.
+
+You can follow this tutorial whether you're new to Medusa or an advanced Medusa developer.
+
+![Diagram showcasing the flow of migrating data from Magento to Medusa](https://res.cloudinary.com/dza7lstvk/image/upload/v1739360550/Medusa%20Resources/magento-summary_hsewci.jpg)
+
+[Example Repository](https://github.com/medusajs/examples/tree/main/migrate-from-magento): Find the full code of the guide in this repository. The repository also includes additional features, such as triggering migrations from the Medusa Admin dashboard.
+
+***
+
+## Step 1: Install a Medusa Application
+
+You'll first install a Medusa application that exposes core commerce features through REST APIs. You'll later install the Magento plugin in this application to test it out.
+
+### Prerequisites
+
+- [Node.js v20+](https://nodejs.org/en/download)
+- [Git CLI tool](https://git-scm.com/downloads)
+- [PostgreSQL](https://www.postgresql.org/download/)
+
+Start by installing the Medusa application on your machine with the following command:
+
+```bash
+npx create-medusa-app@latest
+```
+
+You'll be asked for the project's name. You can also optionally choose to install the [Next.js starter storefront](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/nextjs-starter/index.html.md).
+
+Afterward, the installation process will start, which will install the Medusa application in a directory with your project's name. If you chose to install the Next.js starter, it'll be installed in a separate directory with the `{project-name}-storefront` name.
+
+The Medusa application is composed of a headless Node.js server and an admin dashboard. The storefront is installed or custom-built separately and connects to the Medusa application through its REST endpoints, called [API routes](https://docs.medusajs.com/docs/learn/fundamentals/api-routes/index.html.md). Refer to the [Medusa Architecture](https://docs.medusajs.com/docs/learn/introduction/architecture/index.html.md) documentation to learn more.
+
+Once the installation finishes successfully, the Medusa Admin dashboard will open with a form to create a new user. Enter the user's credentials and submit the form. Afterward, you can log in with the new user and explore the dashboard.
+
+Check out the [troubleshooting guides](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/troubleshooting/create-medusa-app-errors/index.html.md) for help.
+
+***
+
+## Step 2: Install a Medusa Plugin Project
+
+A plugin is a package of reusable Medusa customizations that you can install in any Medusa application. You can add in the plugin [API Routes](https://docs.medusajs.com/docs/learn/fundamentals/api-routes/index.html.md), [Workflows](https://docs.medusajs.com/docs/learn/fundamentals/workflows/index.html.md), and other customizations, as you'll see in this guide. Afterward, you can test it out locally in a Medusa application, then publish it to npm to install and use it in any Medusa application.
+
+Refer to the [Plugins](https://docs.medusajs.com/docs/learn/fundamentals/plugins/index.html.md) documentation to learn more about plugins.
+
+A Medusa plugin is set up in a different project, giving you the flexibility in building and publishing it, while providing you with the tools to test it out locally in a Medusa application.
+
+To create a new Medusa plugin project, run the following command in a directory different than that of the Medusa application:
+
+```bash npm2yarn
+npx create-medusa-app@latest medusa-plugin-magento --plugin
+```
+
+Where `medusa-plugin-magento` is the name of the plugin's directory and the name set in the plugin's `package.json`. So, if you wish to publish it to NPM later under a different name, you can change it here in the command or later in `package.json`.
+
+Once the installation process is done, a new directory named `medusa-plugin-magento` will be created with the plugin project files.
+
+![Directory structure of a plugin project](https://res.cloudinary.com/dza7lstvk/image/upload/v1737019441/Medusa%20Book/project-dir_q4xtri.jpg)
+
+***
+
+## Step 3: Set up Plugin in Medusa Application
+
+Before you start your development, you'll set up the plugin in the Medusa application you installed in the first step. This will allow you to test the plugin during your development process.
+
+In the plugin's directory, run the following command to publish the plugin to the local package registry:
+
+```bash title="Plugin project"
+npx medusa plugin:publish
+```
+
+This command uses [Yalc](https://github.com/wclr/yalc) under the hood to publish the plugin to a local package registry. The plugin is published locally under the name you specified in `package.json`.
+
+Next, you'll install the plugin in the Medusa application from the local registry.
+
+If you've installed your Medusa project before v2.3.1, you must install [yalc](https://github.com/wclr/yalc) as a development dependency first.
+
+Run the following command in the Medusa application's directory to install the plugin:
+
+```bash title="Medusa application"
+npx medusa plugin:add medusa-plugin-magento
+```
+
+This command installs the plugin in the Medusa application from the local package registry.
+
+Next, register the plugin in the `medusa-config.ts` file of the Medusa application:
+
+```ts title="medusa-config.ts"
+module.exports = defineConfig({
+  // ...
+  plugins: [
+    {
+      resolve: "medusa-plugin-magento",
+      options: {
+        // TODO add options
+      },
+    },
+  ],
+})
+```
+
+You add the plugin to the array of plugins. Later, you'll pass options useful to retrieve data from Magento.
+
+Finally, to ensure your plugin's changes are constantly published to the local registry, simplifying your testing process, keep the following command running in the plugin project during development:
+
+```bash title="Plugin project"
+npx medusa plugin:develop
+```
+
+***
+
+## Step 4: Implement Magento Module
+
+To connect to external applications in Medusa, you create a custom module. A module is a reusable package with functionalities related to a single feature or domain. Medusa integrates the module into your application without implications or side effects on your setup.
+
+In this step, you'll create a Magento Module in the Magento plugin that connects to a Magento server's REST APIs and retrieves data, such as products.
+
+Refer to the [Modules](https://docs.medusajs.com/docs/learn/fundamentals/modules/index.html.md) documentation to learn more about modules.
+
+### Create Module Directory
+
+A module is created under the `src/modules` directory of your plugin. So, create the directory `src/modules/magento`.
+
+![Diagram showcasing the module directory to create](https://res.cloudinary.com/dza7lstvk/image/upload/v1739272368/magento-1_ikev4x.jpg)
+
+### Create Module's Service
+
+You define a module's functionalities in a service. A service is a TypeScript or JavaScript class that the module exports. In the service's methods, you can connect to external systems or the database, which is useful if your module defines tables in the database.
+
+In this section, you'll create the Magento Module's service that connects to Magento's REST APIs and retrieves data.
+
+Start by creating the file `src/modules/magento/service.ts` in the plugin with the following content:
+
+![Diagram showcasing the service file to create](https://res.cloudinary.com/dza7lstvk/image/upload/v1739272483/magento-2_ajetpr.jpg)
+
+```ts title="src/modules/magento/service.ts"
+type Options = {
+  baseUrl: string
+  storeCode?: string
+  username: string
+  password: string
+  migrationOptions?: {
+    imageBaseUrl?: string
+  }
+}
+
+export default class MagentoModuleService {
+  private options: Options
+
+  constructor({}, options: Options) {
+    this.options = {
+      ...options,
+      storeCode: options.storeCode || "default",
+    }
+  }
+}
+```
+
+You create a `MagentoModuleService` that has an `options` property to store the module's options. These options include:
+
+- `baseUrl`: The base URL of the Magento server.
+- `storeCode`: The store code of the Magento store, which is `default` by default.
+- `username`: The username of a Magento admin user to authenticate with the Magento server.
+- `password`: The password of the Magento admin user.
+- `migrationOptions`: Additional options useful for migrating data, such as the base URL to use for product images.
+
+The service's constructor accepts as a first parameter the [Module Container](https://docs.medusajs.com/docs/learn/fundamentals/modules/container/index.html.md), which allows you to access resources available for the module. As a second parameter, it accepts the module's options.
+
+### Add Authentication Logic
+
+To authenticate with the Magento server, you'll add a method to the service that retrieves an access token from Magento using the username and password in the options. This access token is used in subsequent requests to the Magento server.
+
+First, add the following property to the `MagentoModuleService` class:
+
+```ts title="src/modules/magento/service.ts"
+export default class MagentoModuleService {
+  private accessToken: {
+    token: string
+    expiresAt: Date
+  }
+  // ...
+}
+```
+
+You add an `accessToken` property to store the access token and its expiration date. The access token Magento returns expires after four hours, so you store the expiration date to know when to refresh the token.
+
+Next, add the following `authenticate` method to the `MagentoModuleService` class:
+
+```ts title="src/modules/magento/service.ts"
+import { MedusaError } from "@medusajs/framework/utils"
+
+export default class MagentoModuleService {
+  // ...
+  async authenticate() {
+    const response = await fetch(`${this.options.baseUrl}/rest/${this.options.storeCode}/V1/integration/admin/token`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({ username: this.options.username, password: this.options.password }),
+    })
+
+    const token = await response.text()
+
+    if (!response.ok) {
+      throw new MedusaError(MedusaError.Types.UNAUTHORIZED, `Failed to authenticate with Magento: ${token}`)
+    }
+
+    this.accessToken = {
+      token: token.replaceAll("\"", ""),
+      expiresAt: new Date(Date.now() + 4 * 60 * 60 * 1000), // 4 hours in milliseconds
+    }
+  }
+}
+```
+
+You create an `authenticate` method that sends a POST request to the Magento server's `/rest/{storeCode}/V1/integration/admin/token` endpoint, passing the username and password in the request body.
+
+If the request is successful, you store the access token and its expiration date in the `accessToken` property. If the request fails, you throw a `MedusaError` with the error message returned by Magento.
+
+Lastly, add an `isAccessTokenExpired` method that checks if the access token has expired:
+
+```ts title="src/modules/magento/service.ts"
+export default class MagentoModuleService {
+  // ...
+  async isAccessTokenExpired(): Promise<boolean> {
+    return !this.accessToken || this.accessToken.expiresAt < new Date()
+  }
+}
+```
+
+In the `isAccessTokenExpired` method, you return a boolean indicating whether the access token has expired. You'll use this in later methods to check if you need to refresh the access token.
+
+### Retrieve Products from Magento
+
+Next, you'll add a method that retrieves products from Magento. Due to limitations in Magento's API that makes it difficult to differentiate between simple products that don't belong to a configurable product and those that do, you'll only retrieve configurable products and their children. You'll also retrieve the configurable attributes of the product, such as color and size.
+
+First, you'll add some types to represent a Magento product and its attributes. Create the file `src/modules/magento/types.ts` in the plugin with the following content:
+
+![Diagram showcasing the types file to create](https://res.cloudinary.com/dza7lstvk/image/upload/v1739346287/Medusa%20Resources/magento-3_fpghog.jpg)
+
+```ts title="src/modules/magento/types.ts"
+export type MagentoProduct = {
+  id: number
+  sku: string
+  name: string
+  price: number
+  status: number
+  // not handling other types
+  type_id: "simple" | "configurable"
+  created_at: string
+  updated_at: string
+  extension_attributes: {
+    category_links: {
+      category_id: string
+    }[]
+    configurable_product_links?: number[] 
+    configurable_product_options?: {
+      id: number
+      attribute_id: string
+      label: string
+      position: number
+      values: {
+        value_index: number
+      }[]
+    }[]
+  }
+  media_gallery_entries: {
+    id: number
+    media_type: string
+    label: string
+    position: number
+    disabled: boolean
+    types: string[]
+    file: string
+  }[]
+  custom_attributes: {
+    attribute_code: string
+    value: string
+  }[]
+  // added by module
+  children?: MagentoProduct[]
+}
+
+export type MagentoAttribute = {
+  attribute_code: string
+  attribute_id: number
+  default_frontend_label: string
+  options: {
+    label: string
+    value: string
+  }[]
+}
+
+export type MagentoPagination = {
+  search_criteria: {
+    filter_groups: [],
+    page_size: number
+    current_page: number
+  }
+  total_count: number
+}
+
+export type MagentoPaginatedResponse<TData> = {
+  items: TData[]
+} & MagentoPagination
+```
+
+You define the following types:
+
+- `MagentoProduct`: Represents a product in Magento.
+- `MagentoAttribute`: Represents an attribute in Magento.
+- `MagentoPagination`: Represents the pagination information returned by Magento's API.
+- `MagentoPaginatedResponse`: Represents a paginated response from Magento's API for a specific item type, such as products.
+
+Next, add the `getProducts` method to the `MagentoModuleService` class:
+
+```ts title="src/modules/magento/service.ts"
+export default class MagentoModuleService {
+  // ...
+  async getProducts(options?: {
+    currentPage?: number
+    pageSize?: number
+  }): Promise<{
+    products: MagentoProduct[]
+    attributes: MagentoAttribute[]
+    pagination: MagentoPagination
+  }> {
+    const { currentPage = 1, pageSize = 100 } = options || {}
+    const getAccessToken = await this.isAccessTokenExpired()
+    if (getAccessToken) {
+      await this.authenticate()
+    }
+
+    // TODO prepare query params
+  }
+}
+```
+
+The `getProducts` method receives an optional `options` object with the `currentPage` and `pageSize` properties. So far, you check if the access token has expired and, if so, retrieve a new one using the `authenticate` method.
+
+Next, you'll prepare the query parameters to pass in the request that retrieves products. Replace the `TODO` with the following:
+
+```ts title="src/modules/magento/service.ts"
+const searchQuery = new URLSearchParams()
+// pass pagination parameters
+searchQuery.append(
+  "searchCriteria[currentPage]", 
+  currentPage?.toString() || "1"
+)
+searchQuery.append(
+  "searchCriteria[pageSize]", 
+  pageSize?.toString() || "100"
+)
+
+// retrieve only configurable products
+searchQuery.append(
+  "searchCriteria[filter_groups][1][filters][0][field]", 
+  "type_id"
+)
+searchQuery.append(
+  "searchCriteria[filter_groups][1][filters][0][value]", 
+  "configurable"
+)
+searchQuery.append(
+  "searchCriteria[filter_groups][1][filters][0][condition_type]", 
+  "in"
+)
+
+// TODO send request to retrieve products
+```
+
+You create a `searchQuery` object to store the query parameters to pass in the request. Then, you add the pagination parameters and the filter to retrieve only configurable products.
+
+Next, you'll send the request to retrieve products from Magento. Replace the `TODO` with the following:
+
+```ts title="src/modules/magento/service.ts"
+const { items: products, ...pagination }: MagentoPaginatedResponse<MagentoProduct> = await fetch(
+  `${this.options.baseUrl}/rest/${this.options.storeCode}/V1/products?${searchQuery}`, 
+  {
+    headers: {
+      "Authorization": `Bearer ${this.accessToken.token}`,
+    },
+  }
+).then((res) => res.json())
+.catch((err) => {
+  console.log(err)
+  throw new MedusaError(
+    MedusaError.Types.INVALID_DATA, 
+    `Failed to get products from Magento: ${err.message}`
+  )
+})
+
+// TODO prepare products
+```
+
+You send a `GET` request to the Magento server's `/rest/{storeCode}/V1/products` endpoint, passing the query parameters in the URL. You also pass the access token in the `Authorization` header.
+
+Next, you'll prepare the retrieved products by retrieving their children, configurable attributes, and modifying their image URLs. Replace the `TODO` with the following:
+
+```ts title="src/modules/magento/service.ts"
+const attributeIds: string[] = []
+
+await promiseAll(
+  products.map(async (product) => {
+    // retrieve its children
+    product.children = await fetch(
+      `${this.options.baseUrl}/rest/${this.options.storeCode}/V1/configurable-products/${product.sku}/children`,
+      {
+        headers: {
+          "Authorization": `Bearer ${this.accessToken.token}`,
+        },
+      }
+    ).then((res) => res.json())
+    .catch((err) => {
+      throw new MedusaError(
+        MedusaError.Types.INVALID_DATA, 
+        `Failed to get product children from Magento: ${err.message}`
+      )
+    })
+
+    product.media_gallery_entries = product.media_gallery_entries.map(
+      (entry) => ({
+        ...entry,
+        file: `${this.options.migrationOptions?.imageBaseUrl}${entry.file}`,
+      }
+    ))
+
+    attributeIds.push(...(
+      product.extension_attributes.configurable_product_options?.map(
+        (option) => option.attribute_id) || []
+      )
+    )
+  })
+)
+
+// TODO retrieve attributes
+```
+
+You loop over the retrieved products and retrieve their children using the `/rest/{storeCode}/V1/configurable-products/{sku}/children` endpoint. You also modify the image URLs to use the base URL in the migration options, if provided.
+
+In addition, you store the IDs of the configurable products' attributes in the `attributeIds` array. You'll add a method that retrieves these attributes.
+
+Add the new method `getAttributes` to the `MagentoModuleService` class:
+
+```ts title="src/modules/magento/service.ts"
+export default class MagentoModuleService {
+  // ...
+  async getAttributes({
+    ids,
+  }: {
+    ids: string[]
+  }): Promise<MagentoAttribute[]> {
+    const getAccessToken = await this.isAccessTokenExpired()
+    if (getAccessToken) {
+      await this.authenticate()
+    }
+
+    // filter by attribute IDs
+    const searchQuery = new URLSearchParams()
+    searchQuery.append(
+      "searchCriteria[filter_groups][0][filters][0][field]", 
+      "attribute_id"
+    )
+    searchQuery.append(
+      "searchCriteria[filter_groups][0][filters][0][value]", 
+      ids.join(",")
+    )
+    searchQuery.append(
+      "searchCriteria[filter_groups][0][filters][0][condition_type]", 
+      "in"
+    )
+
+    const { 
+      items: attributes,
+    }: MagentoPaginatedResponse<MagentoAttribute> = await fetch(
+      `${this.options.baseUrl}/rest/${this.options.storeCode}/V1/products/attributes?${searchQuery}`, 
+      {
+        headers: {
+          "Authorization": `Bearer ${this.accessToken.token}`,
+        },
+      }
+    ).then((res) => res.json())
+    .catch((err) => {
+      throw new MedusaError(
+        MedusaError.Types.INVALID_DATA, 
+        `Failed to get attributes from Magento: ${err.message}`
+      )
+    })
+
+    return attributes
+  }
+}
+```
+
+The `getAttributes` method receives an object with the `ids` property, which is an array of attribute IDs. You check if the access token has expired and, if so, retrieve a new one using the `authenticate` method.
+
+Next, you prepare the query parameters to pass in the request to retrieve attributes. You send a `GET` request to the Magento server's `/rest/{storeCode}/V1/products/attributes` endpoint, passing the query parameters in the URL. You also pass the access token in the `Authorization` header.
+
+Finally, you return the retrieved attributes.
+
+Now, go back to the `getProducts` method and replace the `TODO` with the following:
+
+```ts title="src/modules/magento/service.ts"
+const attributes = await this.getAttributes({ ids: attributeIds })
+    
+return { products, attributes, pagination }
+```
+
+You retrieve the configurable products' attributes using the `getAttributes` method and return the products, attributes, and pagination information.
+
+You'll use this method in a later step to retrieve products from Magento.
+
+### Export Module Definition
+
+The final piece to a module is its definition, which you export in an `index.ts` file at its root directory. This definition tells Medusa the name of the module and its service.
+
+So, create the file `src/modules/magento/index.ts` with the following content:
+
+![Diagram showcasing the module definition file to create](https://res.cloudinary.com/dza7lstvk/image/upload/v1739348316/Medusa%20Resources/magento-4_bmepvh.jpg)
+
+```ts title="src/modules/magento/index.ts"
+import { Module } from "@medusajs/framework/utils"
+import MagentoModuleService from "./service"
+
+export const MAGENTO_MODULE = "magento"
+
+export default Module(MAGENTO_MODULE, {
+  service: MagentoModuleService,
+})
+```
+
+You use the `Module` function from the Modules SDK to create the module's definition. It accepts two parameters:
+
+1. The module's name, which is `magento`.
+2. An object with a required property `service` indicating the module's service.
+
+You'll later use the module's service to retrieve products from Magento.
+
+### Pass Options to Plugin
+
+As mentioned earlier when you registered the plugin in the Medusa Application's `medusa-config.ts` file, you can pass options to the plugin. These options are then passed to the modules in the plugin.
+
+So, add the following options to the plugin's registration in the `medusa-config.ts` file of the Medusa application:
+
+```ts title="medusa-config.ts"
+module.exports = defineConfig({
+  // ...
+  plugins: [
+    {
+      resolve: "medusa-plugin-magento",
+      options: {
+        baseUrl: process.env.MAGENTO_BASE_URL,
+        username: process.env.MAGENTO_USERNAME,
+        password: process.env.MAGENTO_PASSWORD,
+        migrationOptions: {
+          imageBaseUrl: process.env.MAGENTO_IMAGE_BASE_URL,
+        },
+      },
+    },
+  ],
+})
+```
+
+You pass the options that you defined in the `MagentoModuleService`. Make sure to also set their environment variables in the `.env` file:
+
+```bash
+MAGENTO_BASE_URL=https://magento.example.com
+MAGENTO_USERNAME=admin
+MAGENTO_PASSWORD=password
+MAGENTO_IMAGE_BASE_URL=https://magento.example.com/pub/media/catalog/product
+```
+
+Where:
+
+- `MAGENTO_BASE_URL`: The base URL of the Magento server. It can also be a local URL, such as `http://localhost:8080`.
+- `MAGENTO_USERNAME`: The username of a Magento admin user to authenticate with the Magento server.
+- `MAGENTO_PASSWORD`: The password of the Magento admin user.
+- `MAGENTO_IMAGE_BASE_URL`: The base URL to use for product images. Magento stores product images in the `pub/media/catalog/product` directory, so you can reference them directly or use a CDN URL. If the URLs of product images in the Medusa server already have a different base URL, you can omit this option.
+
+Medusa supports integrating third-party services, such as [S3](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/infrastructure-modules/file/s3/index.html.md), in a File Module Provider. Refer to the [File Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/infrastructure-modules/file/index.html.md) documentation to find other module providers and how to create a custom provider.
+
+You can now use the Magento Module to migrate data, which you'll do in the next steps.
+
+***
+
+## Step 5: Build Product Migration Workflow
+
+In this section, you'll add the feature to migrate products from Magento to Medusa. To implement this feature, you'll use a workflow.
+
+A workflow is a series of queries and actions, called steps, that complete a task. You construct a workflow like you construct a function, but it's a special function that allows you to track its executions' progress, define roll-back logic, and configure other advanced features. Then, you execute the workflow from other customizations, such as in an API route or a scheduled job.
+
+By implementing the migration feature in a workflow, you ensure that the data remains consistent and that the migration process can be rolled back if an error occurs.
+
+Refer to the [Workflows](https://docs.medusajs.com/docs/learn/fundamentals/workflows/index.html.md) documentation to learn more about workflows.
+
+### Workflow Steps
+
+The workflow you'll create will have the following steps:
+
+- [getMagentoProductsStep](#getMagentoProductsStep): Retrieve products from Magento using the Magento Module.
+- [useQueryGraphStep](https://docs.medusajs.com/references/helper-steps/useQueryGraphStep/index.html.md): Retrieve Medusa store details, which you'll need when creating the products.
+- [useQueryGraphStep](https://docs.medusajs.com/references/helper-steps/useQueryGraphStep/index.html.md): Retrieve a shipping profile, which you'll associate the created products with.
+- [useQueryGraphStep](https://docs.medusajs.com/references/helper-steps/useQueryGraphStep/index.html.md): Retrieve Magento products that are already in Medusa to update them, instead of creating them.
+- [createProductsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createProductsWorkflow/index.html.md): Create products in the Medusa application.
+- [updateProductsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateProductsWorkflow/index.html.md): Update existing products in the Medusa application.
+
+You only need to implement the `getMagentoProductsStep` step, which retrieves the products from Magento. The other steps and workflows are provided by Medusa's `@medusajs/medusa/core-flows` package.
+
+### getMagentoProductsStep
+
+The first step of the workflow retrieves and returns the products from Magento.
+
+In your plugin, create the file `src/workflows/steps/get-magento-products.ts` with the following content:
+
+![Diagram showcasing the get-magento-products file to create](https://res.cloudinary.com/dza7lstvk/image/upload/v1739349590/Medusa%20Resources/magento-5_ueb4wn.jpg)
+
+```ts title="src/workflows/steps/get-magento-products.ts"
+import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk"
+import { MAGENTO_MODULE } from "../../modules/magento"
+import MagentoModuleService from "../../modules/magento/service"
+
+type GetMagentoProductsInput = {
+  currentPage: number
+  pageSize: number
+}
+
+export const getMagentoProductsStep = createStep(
+  "get-magento-products",
+  async ({ currentPage, pageSize }: GetMagentoProductsInput, { container }) => {
+    const magentoModuleService: MagentoModuleService = 
+      container.resolve(MAGENTO_MODULE)
+
+    const response = await magentoModuleService.getProducts({
+      currentPage,
+      pageSize,
+    })
+
+    return new StepResponse(response)
+  }
+)
+```
+
+You create a step using `createStep` from the Workflows SDK. It accepts two parameters:
+
+1. The step's name, which is `get-magento-products`.
+2. An async function that executes the step's logic. The function receives two parameters:
+   - The input data for the step, which in this case is the pagination parameters.
+   - An object holding the workflow's context, including the [Medusa Container](https://docs.medusajs.com/docslearn/fundamentals/medusa-container/index.html.md) that allows you to resolve Framework and commerce tools.
+
+In the step function, you resolve the Magento Module's service from the container, then use its `getProducts` method to retrieve the products from Magento.
+
+Steps that return data must return them in a `StepResponse` instance. The `StepResponse` constructor accepts as a parameter the data to return.
+
+### Create migrateProductsFromMagentoWorkflow
+
+You'll now create the workflow that migrates products from Magento using the step you created and steps from Medusa's `@medusajs/medusa/core-flows` package.
+
+In your plugin, create the file `src/workflows/migrate-products-from-magento.ts` with the following content:
+
+![Diagram showcasing the migrate-products-from-magento file to create](https://res.cloudinary.com/dza7lstvk/image/upload/v1739349820/Medusa%20Resources/magento-6_jjdaxj.jpg)
+
+```ts title="src/workflows/migrate-products-from-magento.ts"
+import { 
+  createWorkflow, transform, WorkflowResponse,
+} from "@medusajs/framework/workflows-sdk"
+import { 
+  CreateProductWorkflowInputDTO, UpsertProductDTO,
+} from "@medusajs/framework/types"
+import { 
+  createProductsWorkflow, 
+  updateProductsWorkflow, 
+  useQueryGraphStep,
+} from "@medusajs/medusa/core-flows"
+import { getMagentoProductsStep } from "./steps/get-magento-products"
+
+type MigrateProductsFromMagentoWorkflowInput = {
+  currentPage: number
+  pageSize: number
+}
+
+export const migrateProductsFromMagentoWorkflowId = 
+  "migrate-products-from-magento"
+
+export const migrateProductsFromMagentoWorkflow = createWorkflow(
+  {
+    name: migrateProductsFromMagentoWorkflowId,
+    retentionTime: 10000,
+    store: true,
+  },
+  (input: MigrateProductsFromMagentoWorkflowInput) => {
+    const { pagination, products, attributes } = getMagentoProductsStep(
+      input
+    )
+    // TODO prepare data to create and update products
+  }
+)
+```
+
+You create a workflow using `createWorkflow` from the Workflows SDK. It accepts two parameters:
+
+1. An object with the workflow's configuration, including the name and whether to store the workflow's executions. You enable storing the workflow execution so that you can view it later in the Medusa Admin dashboard.
+2. A worflow constructor function, which holds the workflow's implementation. The function receives the input data for the workflow, which is the pagination parameters.
+
+In the workflow constructor function, you use the `getMagentoProductsStep` step to retrieve the products from Magento, passing it the pagination parameters from the workflow's input.
+
+Next, you'll retrieve the Medusa store details and shipping profiles. These are necessary to prepare the data of the products to create or update.
+
+Replace the `TODO` in the workflow function with the following:
+
+```ts title="src/workflows/migrate-products-from-magento.ts"
+const { data: stores } = useQueryGraphStep({
+  entity: "store",
+  fields: ["supported_currencies.*", "default_sales_channel_id"],
+  pagination: {
+    take: 1,
+    skip: 0,
+  },
+})
+
+const { data: shippingProfiles } = useQueryGraphStep({
+  entity: "shipping_profile",
+  fields: ["id"],
+  pagination: {
+    take: 1,
+    skip: 0,
+  },
+}).config({ name: "get-shipping-profiles" })
+
+// TODO retrieve existing products
+```
+
+You use the `useQueryGraphStep` step to retrieve the store details and shipping profiles. `useQueryGraphStep` is a Medusa step that wraps [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md), allowing you to use it in a workflow. Query is a tool that retrieves data across modules.
+
+Whe retrieving the store details, you specifically retrieve its supported currencies and default sales channel ID. You'll associate the products with the store's default sales channel, and set their variant prices in the supported currencies. You'll also associate the products with a shipping profile.
+
+Next, you'll retrieve products that were previously migrated from Magento to determine which products to create or update. Replace the `TODO` with the following:
+
+```ts title="src/workflows/migrate-products-from-magento.ts"
+const externalIdFilters = transform({
+  products,
+}, (data) => {
+  return data.products.map((product) => product.id.toString())
+})
+
+const { data: existingProducts } = useQueryGraphStep({
+  entity: "product",
+  fields: ["id", "external_id", "variants.id", "variants.metadata"],
+  filters: {
+    external_id: externalIdFilters,
+  },
+}).config({ name: "get-existing-products" })
+
+// TODO prepare products to create or update
+```
+
+Since the Medusa application creates an internal representation of the workflow's constructor function, you can't manipulate data directly, as variables have no value while creating the internal representation.
+
+Refer to the [Workflows](https://docs.medusajs.com/docs/learn/fundamentals/workflows/constructor-constraints/index.html.md) documentation to learn more about the workflow constructor function's constraints.
+
+Instead, you can manipulate data in a workflow's constructor function using `transform` from the Workflows SDK. `transform` is a function that accepts two parameters:
+
+- The data to transform, which in this case is the Magento products.
+- A function that transforms the data. The function receives the data passed in the first parameter and returns the transformed data.
+
+In the transformation function, you return the IDs of the Magento products. Then, you use the `useQueryGraphStep` to retrieve products in the Medusa application that have an `external_id` property matching the IDs of the Magento products. You'll use this property to store the IDs of the products in Magento.
+
+Next, you'll prepare the data to create and update the products. Replace the `TODO` in the workflow function with the following:
+
+```ts title="src/workflows/migrate-products-from-magento.ts" highlights={prepareHighlights}
+const { 
+  productsToCreate,
+  productsToUpdate,
+} = transform({
+  products,
+  attributes,
+  stores,
+  shippingProfiles,
+  existingProducts,
+}, (data) => {
+  const productsToCreate = new Map<string, CreateProductWorkflowInputDTO>()
+  const productsToUpdate = new Map<string, UpsertProductDTO>()
+
+  data.products.forEach((magentoProduct) => {
+    const productData: CreateProductWorkflowInputDTO | UpsertProductDTO = {
+      title: magentoProduct.name,
+      description: magentoProduct.custom_attributes.find(
+        (attr) => attr.attribute_code === "description"
+      )?.value,
+      status: magentoProduct.status === 1 ? "published" : "draft",
+      handle: magentoProduct.custom_attributes.find(
+        (attr) => attr.attribute_code === "url_key"
+      )?.value,
+      external_id: magentoProduct.id.toString(),
+      thumbnail: magentoProduct.media_gallery_entries.find(
+        (entry) => entry.types.includes("thumbnail")
+      )?.file,
+      sales_channels: [{
+        id: data.stores[0].default_sales_channel_id,
+      }],
+      shipping_profile_id: data.shippingProfiles[0].id,
+    }
+    const existingProduct = data.existingProducts.find((p) => p.external_id === productData.external_id)
+
+    if (existingProduct) {
+      productData.id = existingProduct.id
+    }
+
+    productData.options = magentoProduct.extension_attributes.configurable_product_options?.map((option) => {
+      const attribute = data.attributes.find((attr) => attr.attribute_id === parseInt(option.attribute_id))
+      return {
+        title: option.label,
+        values: attribute?.options.filter((opt) => {
+          return option.values.find((v) => v.value_index === parseInt(opt.value))
+        }).map((opt) => opt.label) || [],
+      }
+    }) || []
+
+    productData.variants = magentoProduct.children?.map((child) => {
+      const childOptions: Record<string, string> = {}
+
+      child.custom_attributes.forEach((attr) => {
+        const attrData = data.attributes.find((a) => a.attribute_code === attr.attribute_code)
+        if (!attrData) {
+          return
+        }
+
+        childOptions[attrData.default_frontend_label] = attrData.options.find((opt) => opt.value === attr.value)?.label || ""
+      })
+
+      const variantExternalId = child.id.toString()
+      const existingVariant = existingProduct.variants.find((v) => v.metadata.external_id === variantExternalId)
+
+      return {
+        title: child.name,
+        sku: child.sku,
+        options: childOptions,
+        prices: data.stores[0].supported_currencies.map(({ currency_code }) => {
+          return {
+            amount: child.price,
+            currency_code,
+          }
+        }),
+        metadata: {
+          external_id: variantExternalId,
+        },
+        id: existingVariant?.id,
+      }
+    })
+
+    productData.images = magentoProduct.media_gallery_entries.filter((entry) => !entry.types.includes("thumbnail")).map((entry) => {
+      return {
+        url: entry.file,
+        metadata: {
+          external_id: entry.id.toString(),
+        },
+      }
+    })
+
+    if (productData.id) {
+      productsToUpdate.set(existingProduct.id, productData)
+    } else {
+      productsToCreate.set(productData.external_id!, productData)
+    }
+  })
+
+  return {
+    productsToCreate: Array.from(productsToCreate.values()),
+    productsToUpdate: Array.from(productsToUpdate.values()),
+  }
+})
+
+// TODO create and update products
+```
+
+You use `transform` again to prepare the data to create and update the products in the Medusa application. For each Magento product, you map its equivalent Medusa product's data:
+
+- You set the product's general details, such as the title, description, status, handle, external ID, and thumbnail using the Magento product's data and custom attributes.
+- You associate the product with the default sales channel and shipping profile retrieved previously.
+- You map the Magento product's configurable product options to Medusa product options. In Medusa, a product's option has a label, such as "Color", and values, such as "Red". To map the option values, you use the attributes retrieved from Magento.
+- You map the Magento product's children to Medusa product variants. For the variant options, you pass an object whose keys is the option's label, such as "Color", and values is the option's value, such as "Red". For the prices, you set the variant's price based on the Magento child's price for every supported currency in the Medusa store. Also, you set the Magento child product's ID in the Medusa variant's `metadata.external_id` property.
+- You map the Magento product's media gallery entries to Medusa product images. You filter out the thumbnail image and set the URL and the Magento image's ID in the Medusa image's `metadata.external_id` property.
+
+In addition, you use the existing products retrieved in the previous step to determine whether a product should be created or updated. If there's an existing product whose `external_id` matches the ID of the magento product, you set the existing product's ID in the `id` property of the product to be updated. You also do the same for its variants.
+
+Finally, you return the products to create and update.
+
+The last steps of the workflow is to create and update the products. Replace the `TODO` in the workflow function with the following:
+
+```ts title="src/workflows/migrate-products-from-magento.ts"
+createProductsWorkflow.runAsStep({
+  input: {
+    products: productsToCreate,
+  },
+})
+
+updateProductsWorkflow.runAsStep({
+  input: {
+    products: productsToUpdate,
+  },
+})
+
+return new WorkflowResponse(pagination)
+```
+
+You use the `createProductsWorkflow` and `updateProductsWorkflow` workflows from Medusa's `@medusajs/medusa/core-flows` package to create and update the products in the Medusa application.
+
+Workflows must return an instance of `WorkflowResponse`, passing as a parameter the data to return to the workflow's executor. This workflow returns the pagination parameters, allowing you to paginate the product migration process.
+
+You can now use this workflow to migrate products from Magento to Medusa. You'll learn how to use it in the next steps.
+
+***
+
+## Step 6: Schedule Product Migration
+
+There are many ways to execute tasks asynchronously in Medusa, such as [scheduling a job](https://docs.medusajs.com/docs/learn/fundamentals/scheduled-jobs/index.html.md) or [handling emitted events](https://docs.medusajs.com/docs/learn/fundamentals/events-and-subscribers/index.html.md).
+
+In this guide, you'll learn how to schedule the product migration at a specified interval using a scheduled job. A scheduled job is an asynchronous function that the Medusa application runs at the interval you specify during the Medusa application's runtime.
+
+Refer to the [Scheduled Jobs](https://docs.medusajs.com/docs/learn/fundamentals/scheduled-jobs/index.html.md) documentation to learn more about scheduled jobs.
+
+To create a scheduled job, in your plugin, create the file `src/jobs/migrate-magento.ts` with the following content:
+
+![Diagram showcasing the migrate-magento file to create](https://res.cloudinary.com/dza7lstvk/image/upload/v1739358924/Medusa%20Resources/magento-7_rqoodo.jpg)
+
+```ts title="src/jobs/migrate-magento.ts"
+import { MedusaContainer } from "@medusajs/framework/types"
+import { migrateProductsFromMagentoWorkflow } from "../workflows"
+
+export default async function migrateMagentoJob(
+  container: MedusaContainer
+) {
+  const logger = container.resolve("logger")
+    logger.info("Migrating products from Magento...")
+    
+    let currentPage = 0
+    const pageSize = 100
+    let totalCount = 0
+  
+    do {
+      currentPage++
+  
+      const { 
+        result: pagination,
+      } = await migrateProductsFromMagentoWorkflow(container).run({
+        input: {
+          currentPage,
+          pageSize,
+        },
+      })
+  
+      totalCount = pagination.total_count
+    } while (currentPage * pageSize < totalCount)
+  
+    logger.info("Finished migrating products from Magento")
+}
+
+export const config = {
+  name: "migrate-magento-job",
+  schedule: "0 0 * * *",
+}
+```
+
+A scheduled job file must export:
+
+- An asynchronous function that executes the job's logic. The function receives the [Medusa container](https://docs.medusajs.com/docs/learn/fundamentals/medusa-container/index.html.md) as a parameter.
+- An object with the job's configuration, including the name and the schedule. The schedule is a cron job pattern as a string.
+
+In the job function, you resolve the [logger](https://docs.medusajs.com/docs/learn/debugging-and-testing/logging/index.html.md) from the container to log messages. Then, you paginate the product migration process by running the `migrateProductsFromMagentoWorkflow` workflow at each page until you've migrated all products. You use the pagination result returned by the workflow to determine whether there are more products to migrate.
+
+Based on the job's configurations, the Medusa application will run the job at midnight every day.
+
+### Test it Out
+
+To test out this scheduled job, first, change the configuration to run the job every minute:
+
+```ts title="src/jobs/migrate-magento.ts"
+export const config = {
+  // ...
+  schedule: "* * * * *",
+}
+```
+
+Then, make sure to run the `plugin:develop` command in the plugin if you haven't already:
+
+```bash
+npx medusa plugin:develop
+```
+
+This ensures that the plugin's latest changes are reflected in the Medusa application.
+
+Finally, start the Medusa application that the plugin is installed in:
+
+```bash npm2yarn
+npm run dev
+```
+
+After a minute, you'll see a message in the terminal indicating that the migration started:
+
+```plain title="Terminal"
+info: Migrating products from Magento...
+```
+
+Once the migration is done, you'll see the following message:
+
+```plain title="Terminal"
+info: Finished migrating products from Magento
+```
+
+To confirm that the products were migrated, open the Medusa Admin dashboard at `http://localhost:9000/app` and log in. Then, click on Products in the sidebar. You'll see your magento products in the list of products.
+
+![Click on products at the sidebar on the right, then view the products in the table in the middle.](https://res.cloudinary.com/dza7lstvk/image/upload/v1739359394/Medusa%20Resources/Screenshot_2025-02-12_at_1.22.44_PM_uva98i.png)
+
+***
+
+## Next Steps
+
+You've now implemented the logic to migrate products from Magento to Medusa. You can re-use the plugin across Medusa applications. You can also expand on the plugin to:
+
+- Migrate other entities, such as orders, customers, and categories. Migrating other entities follows the same pattern as migrating products, using workflows and scheduled jobs. You only need to format the data to be migrated as needed.
+- Allow triggering migrations from the Medusa Admin dashboard using [Admin Customizations](https://docs.medusajs.com/docs/learn/fundamentals/admin/index.html.md). This feature is available in the [Example Repository](https://github.com/medusajs/example-repository/tree/main/src/admin).
+
+If you're new to Medusa, check out the [main documentation](https://docs.medusajs.com/docs/learn/index.html.md), where you'll get a more in-depth learning of all the concepts you've used in this guide and more.
+
+To learn more about the commerce features that Medusa provides, check out Medusa's [Commerce Modules](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/index.html.md).
+
+
+# Integrate Algolia (Search) with Medusa
+
+In this tutorial, you'll learn how to integrate Medusa with Algolia.
+
+When you install a Medusa application, you get a fully-fledged commerce platform with a Framework for customization. Medusa's architecture supports integrating third-party services, such as a search engine, allowing you to build your unique requirements around core commerce flows.
+
+[Algolia](https://www.algolia.com/doc/) is a search engine that enables you to build and manage an intuitive search experience for your customers. By integrating Algolia with Medusa, you can index e-commerce data, such as products, and allow clients to search through them.
+
+You can follow this guide whether you're new to Medusa or an advanced Medusa developer.
+
+## Summary
+
+By following this tutorial, you'll learn how to:
+
+- Install and set up Medusa.
+- Integrate Algolia into Medusa.
+- Trigger Algolia reindexing when a product is created, updated, deleted, or when the admin manually triggers a reindex.
+- Customize the Next.js Starter Storefront to allow searching for products through Algolia.
+
+- [Algolia Integration Repository](https://github.com/medusajs/examples/tree/main/algolia-integration): Find the full code for this guide in this repository.
+- [OpenApi Specs for Postman](https://res.cloudinary.com/dza7lstvk/raw/upload/v1742829748/OpenApi/Algolia-Search_t1zlkd.yaml): Import this OpenApi Specs file into tools like Postman.
+
+***
+
+## Step 1: Install a Medusa Application
+
+### Prerequisites
+
+- [Node.js v20+](https://nodejs.org/en/download)
+- [Git CLI tool](https://git-scm.com/downloads)
+- [PostgreSQL](https://www.postgresql.org/download/)
+
+Start by installing the Medusa application on your machine with the following command:
+
+```bash
+npx create-medusa-app@latest
+```
+
+You'll first be asked for the project's name. Then, when asked whether you want to install the [Next.js starter storefront](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/nextjs-starter/index.html.md), choose "Yes."
+
+Afterwards, the installation process will start, which will install the Medusa application in a directory with your project's name and the Next.js Starter Storefront in a separate directory 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 Algolia Module
+
+To integrate third-party services into Medusa, you create a custom module. A module is a reusable package with functionalities related to a single feature or domain. Medusa integrates the module into your application without implications or side effects on your setup.
+
+In this step, you'll create a custom module that provides the necessary functionalities to integrate Algolia with Medusa.
+
+Refer to the [Modules documentation](https://docs.medusajs.com/docs/learn/fundamentals/modules/index.html.md) to learn more.
+
+Before building the module, you need to install Algolia's JavaScript client. Run the following command in your Medusa application's root directory:
+
+```bash npm2yarn
+npm install algoliasearch
+```
+
+### Create Module Directory
+
+A module is created under the `src/modules` directory of your Medusa application. So, create the directory `src/modules/algolia`.
+
+### 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 Algolia Module's service and the methods necessary to manage indexed products in Algolia and search through them.
+
+To create the Algolia Module's service, create the file `src/modules/algolia/service.ts` with the following content:
+
+```ts title="src/modules/algolia/service.ts"
+import { algoliasearch, SearchClient } from "algoliasearch"
+
+type AlgoliaOptions = {
+  apiKey: string;
+  appId: string;
+  productIndexName: string;
+}
+
+export type AlgoliaIndexType = "product"
+
+export default class AlgoliaModuleService {
+  private client: SearchClient
+  private options: AlgoliaOptions
+
+  constructor({}, options: AlgoliaOptions) {
+    this.client = algoliasearch(options.appId, options.apiKey)
+    this.options = options
+  }
+
+  // TODO add methods
+}
+```
+
+You export a class that will be the Algolia Module's main service. In the service, you define two properties:
+
+- `client`: An instance of the Algolia Search Client, which you'll use to perform actions with Algolia's API.
+- `options`: An object of options that the Module receives when it's registered, which you'll learn about later. The options contain:
+  - `apiKey`: The Algolia API key.
+  - `appId`: The Algolia App ID.
+  - `productIndexName`: The name of the index where products are stored.
+
+If you want to index other types of data, such as product categories, you can add new properties for their index names in the `AlgoliaOptions` type.
+
+A module's service receives the module's options as a second parameter in its constructor. In the constructor, you initialize the Algolia client using the module's options.
+
+A module has a container that holds all resources registered in that module, and you can access those resources in the first parameter of the constructor. Learn more about it in the [Module Container documentation](https://docs.medusajs.com/docs/learn/fundamentals/modules/container/index.html.md).
+
+#### Index Data Method
+
+The first method you need to add to the servie is a method that receives an array of data to add or update in Algolia's index.
+
+Add the following methods to the `AlgoliaModuleService` class:
+
+```ts title="src/modules/algolia/service.ts"
+export default class AlgoliaModuleService {
+  // ...
+  async getIndexName(type: AlgoliaIndexType) {
+    switch (type) {
+      case "product":
+        return this.options.productIndexName
+      default:
+        throw new Error(`Invalid index type: ${type}`)
+    }
+  }
+
+  async indexData(data: Record<string, unknown>[], type: AlgoliaIndexType = "product") {
+    const indexName = await this.getIndexName(type)
+    this.client.saveObjects({
+      indexName,
+      objects: data.map((item) => ({
+        ...item,
+        // set the object ID to allow updating later
+        objectID: item.id,
+      })),
+    })
+  }
+}
+```
+
+You define two methods:
+
+1. `getIndexName`: A method that receives an `AlgoliaIndexType` (defined in the previous snippt) and returns the index name for that type. In this case, you only have one type, `product`, so you return the product index name.
+   - If you want to index other types of data, you can add more cases to the switch statement.
+2. `indexData`: A method that receives an array of data and an `AlgoliaIndexType`. The method indexes the data in the Algolia index for the given type.
+   - Notice that you set the `objectID` property of each object to the object's `id`. This ensures that you later update the object instead of creating a new one.
+
+#### Retrieve and Delete Methods
+
+The next methods you'll add to the service are methods to retrieve and delete data from the Algolia index. You'll see their use later as you keep the Algolia index in sync with Medusa.
+
+Add the following methods to the `AlgoliaModuleService` class:
+
+```ts title="src/modules/algolia/service.ts"
+export default class AlgoliaModuleService {
+  // ...
+
+  async retrieveFromIndex(objectIDs: string[], type: AlgoliaIndexType = "product") {
+    const indexName = await this.getIndexName(type)
+    return await this.client.getObjects<Record<string, unknown>>({
+      requests: objectIDs.map((objectID) => ({
+        indexName,
+        objectID,
+      })),
+    })
+  }
+
+  async deleteFromIndex(objectIDs: string[], type: AlgoliaIndexType = "product") {
+    const indexName = await this.getIndexName(type)
+    await this.client.deleteObjects({
+      indexName,
+      objectIDs,
+    })
+  }
+}
+```
+
+You define two methods:
+
+1. `retrieveFromIndex`: A method that receives an array of object IDs and an `AlgoliaIndexType`. The method retrieves the objects with the given IDs from the Algolia index.
+2. `deleteFromIndex`: A method that receives an array of object IDs and an `AlgoliaIndexType`. The method deletes the objects with the given IDs from the Algolia index.
+
+#### Search Method
+
+The last method you'll implement is a method to search through the Algolia index. You'll later use this method to expose the search functionality to clients, such as the Next.js Storefront.
+
+Add the following method to the `AlgoliaModuleService` class:
+
+```ts title="src/modules/algolia/service.ts"
+export default class AlgoliaModuleService {
+  // ...
+
+  async search(query: string, type: AlgoliaIndexType = "product") {
+    const indexName = await this.getIndexName(type)
+    return await this.client.search({
+      requests: [
+        {
+          indexName,
+          query,
+        },
+      ],
+    })
+  }
+}
+```
+
+The `search` method receives a query string and an `AlgoliaIndexType`. The method searches through the Algolia index for the given type, such as products, and returns the results.
+
+### Export Module Definition
+
+The final piece to a module is its definition, which you export in an `index.ts` file at its root directory. This definition tells Medusa the name of the module and its service.
+
+So, create the file `src/modules/algolia/index.ts` with the following content:
+
+```ts title="src/modules/algolia/index.ts"
+import { Module } from "@medusajs/framework/utils"
+import AlgoliaModuleService from "./service"
+
+export const ALGOLIA_MODULE = "algolia"
+
+export default Module(ALGOLIA_MODULE, {
+  service: AlgoliaModuleService,
+})
+```
+
+You use the `Module` function from the Modules SDK to create the module's definition. It accepts two parameters:
+
+1. The module's name, which is `algolia`.
+2. An object with a required property `service` indicating the module's service.
+
+You also export the module's name as `ALGOLIA_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/algolia",
+      options: {
+        appId: process.env.ALGOLIA_APP_ID!,
+        apiKey: process.env.ALGOLIA_API_KEY!,
+        productIndexName: process.env.ALGOLIA_PRODUCT_INDEX_NAME!,
+      },
+    },
+  ],
+})
+```
+
+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 Algolia App ID, API Key, and the product index name.
+
+### Add Environment Variables
+
+Before you can start using the Algolia Module, you need to set the environment variables for the Algolia App ID, API Key, and the product index name.
+
+Add the following environment variables to your `.env` file:
+
+```env
+ALGOLIA_APP_ID=your-algolia-app-id
+ALGOLIA_API_KEY=your-algolia-api-key
+ALGOLIA_PRODUCT_INDEX_NAME=your-product-index-name
+```
+
+Where:
+
+- `your-algolia-app-id` is your Algolia App ID. You can retrieve it from the Algolia dashboard by clicking at the application ID at the top left next to the sidebar. The pop up will show the application ID below the application's name.
+
+![Find the Algolia App ID by clicking on the application name in the Algolia dashboard, then copying the ID below the name in the pop-up](https://res.cloudinary.com/dza7lstvk/image/upload/v1742815360/Medusa%20Resources/Screenshot_2025-03-24_at_1.19.30_PM_kdp3y5.png)
+
+- `your-algolia-api-key` is your Algolia API Key. To retrieve it from the Algolia dashboard:
+  1. Click on Settings in the sidebar.
+  2. Choose API Keys under "Team and Access".
+
+![In the settings page, find the Team and Access section at the right of the page and choose API Keys](https://res.cloudinary.com/dza7lstvk/image/upload/v1742815534/Medusa%20Resources/Screenshot_2025-03-24_at_1.25.09_PM_hwsiba.png)
+
+3. Copy the Admin API Key.
+
+- `your-product-index-name` is the name of the index where you'll store products. You can find it by going to Search -> Index, and copying the index name at the top of the page.
+
+![In the Algolia dashboard, go to Search -> Index and copy the index name at the top of the page](https://res.cloudinary.com/dza7lstvk/image/upload/v1742815790/Medusa%20Resources/Screenshot_2025-03-24_at_1.28.58_PM_yq10sf.png)
+
+Your module is now ready for use. You'll see how to use it in the next steps.
+
+***
+
+## Step 3: Sync Products to Algolia Workflow
+
+To keep the Algolia index in sync with Medusa, you need to trigger indexing when products are created, updated, or deleted in Medusa. You can also allow the admin to manually trigger a reindex.
+
+To implement the indexing functionality, you need to create a [workflow](https://docs.medusajs.com/docs/learn/fundamentals/workflows/index.html.md). A workflow 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 step, you'll create a workflow that indexes products in Algolia. In the next steps, you'll learn how to use the workflow when products are created, updated, or deleted, or when the admin manually triggers a reindex.
+
+The workflow has the following steps:
+
+- [useQueryGraphStep](https://docs.medusajs.com/references/helper-steps/useQueryGraphStep/index.html.md): Retrieve products matching specified filters and pagination parameters.
+- [syncProductsStep](#syncProductsStep): Index products in Algolia.
+
+Medusa provides the `useQueryGraphStep` in its `@medusajs/medusa/core-flows` package. So, you only need to implement the second step.
+
+### syncProductsStep
+
+In the second step of the workflow, you create or update indexes in Algolia for the products retrieved in the first step.
+
+To create the step, create the file `src/workflows/steps/sync-products.ts` with the following content:
+
+```ts title="src/workflows/steps/sync-products.ts"
+import { ProductDTO } from "@medusajs/framework/types"
+import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk"
+import { ALGOLIA_MODULE } from "../../modules/algolia"
+import AlgoliaModuleService from "../../modules/algolia/service"
+
+export type SyncProductsStepInput = {
+  products: ProductDTO[]
+}
+
+export const syncProductsStep = createStep(
+  "sync-products",
+  async ({ products }: SyncProductsStepInput, { container }) => {
+    const algoliaModuleService: AlgoliaModuleService = container.resolve(ALGOLIA_MODULE)
+
+    const existingProducts = (await algoliaModuleService.retrieveFromIndex(
+      products.map((product) => product.id),
+      "product"
+    )).results.filter(Boolean)
+    const newProducts = products.filter(
+      (product) => !existingProducts.some((p) => p.objectID === product.id)
+    )
+    await algoliaModuleService.indexData(
+      products as unknown as Record<string, unknown>[], 
+      "product"
+    )
+
+    return new StepResponse(undefined, {
+      newProducts: newProducts.map((product) => product.id),
+      existingProducts,
+    })
+  }
+  // TODO add compensation
+)
+```
+
+You create a step with `createStep` from the Workflows SDK. It accepts two parameters:
+
+1. The step's unique name, which is `sync-products`.
+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 sync into Algolia.
+   - An object that has properties including the [Medusa container](https://docs.medusajs.com/docs/learn/fundamentals/medusa-container/index.html.md), which is a registry of Framework and commerce tools that you can access in the step.
+
+In the step function, you resolve the Algolia Module's service from the Medusa container using the name you exported in the module definition's file.
+
+Then, you retrieve the products that are already indexed in Algolia and determine which products are new. You'll learn why this is useful in a bit.
+
+Finally, you pass the products you received in the input to Algolia to create or update its indices.
+
+A step function must return a `StepResponse` instance. The `StepResponse` constructor accepts two parameters:
+
+1. The step's output, which is the review created.
+2. Data to pass to the step's compensation function.
+
+#### Compensation Function
+
+The compensation function undoes the actions performed in a step. Then, if an error occurs during the workflow's execution, the compensation functions of executed steps are called to roll back the changes. This mechanism ensures data consistency in your application, especially as you integrate external systems.
+
+To add a compensation function to a step, pass it as a third parameter to `createStep`:
+
+```ts title="src/workflows/steps/sync-products.ts"
+export const syncProductsStep = createStep(
+  // ...
+  async (input, { container }) => {
+    if (!input) {
+      return
+    }
+
+    const algoliaModuleService: AlgoliaModuleService = container.resolve(ALGOLIA_MODULE)
+    
+    if (input.newProducts) {
+      await algoliaModuleService.deleteFromIndex(
+        input.newProducts,
+        "product"
+      )
+    }
+
+    if (input.existingProducts) {
+      await algoliaModuleService.indexData(
+        input.existingProducts,
+        "product"
+      )
+    }
+  }
+)
+```
+
+The compensation function receives two parameters:
+
+1. The data you passed as a second parameter of `StepResponse` in the step function.
+2. A context object similar to the step function that holds the Medusa container.
+
+In the compensation function, you resolve the Algolia Module's service from the container. Then, you delete from Algolia the products that were newly indexed, and revert the existing products to their original data.
+
+### Add Sync Products Workflow
+
+You can now create the worklow that syncs the products to Algolia.
+
+To create the workflow, create the file `src/workflows/sync-products.ts` with the following content:
+
+```ts title="src/workflows/sync-products.ts"
+import { createWorkflow, WorkflowResponse } from "@medusajs/framework/workflows-sdk"
+import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
+import { syncProductsStep, SyncProductsStepInput } from "./steps/sync-products"
+
+type SyncProductsWorkflowInput = {
+  filters?: Record<string, unknown>
+  limit?: number
+  offset?: number
+}
+
+export const syncProductsWorkflow = createWorkflow(
+  "sync-products",
+  ({ filters, limit, offset }: SyncProductsWorkflowInput) => {
+    // @ts-ignore
+    const { data, metadata } = useQueryGraphStep({
+      entity: "product",
+      fields: ["id", "title", "description", "handle", "thumbnail", "categories.*", "tags.*"],
+      pagination: {
+        take: limit,
+        skip: offset,
+      },
+      filters: {
+        // @ts-ignore
+        status: "published",
+        ...filters,
+      },
+    })
+
+    syncProductsStep({
+      products: data,
+    } as SyncProductsStepInput)
+
+    return new WorkflowResponse({
+      products: data,
+      metadata,
+    })
+  }
+)
+```
+
+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 pagination and filter parameters for the products to retrieve.
+
+In the workflow's constructor function, you:
+
+1. Execute `useQueryGraphStep` to retrieve products from Medusa's database. 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 pagination and filter parameters you received in the input.
+2. Execute `syncProductsStep` to index the products in Algolia. You pass it the products you retrieved in the previous step.
+
+A workflow must return an instance of `WorkflowResponse`. The `WorkflowResponse` constructor accepts the workflow's output as a parameter, which is an object holding the retrieved products and their pagination details.
+
+In the next step, you'll learn how to execute this workflow.
+
+***
+
+## Step 4: Trigger Algolia Sync Manually
+
+As mentioned earlier, you'll trigger the Algolia sync automatically when product events occur, but you also want to allow the admin to manually trigger a reindex.
+
+In this step, you'll add the functionality to trigger the `syncProductsWorkflow` manually from the Medusa Admin dashboard. This requires:
+
+1. Creating a subscriber that listens to a custom `algolia.sync` event to trigger syncing products to Algolia.
+2. Creating an API route that the Medusa Admin dashboard can call to emit the `algolia.sync` event, which triggers the subscriber.
+3. Add a new page or UI route to the Medusa Admin dashboard to allow the admin to trigger the reindex.
+
+### Create Products Sync Subscriber
+
+A subscriber 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.
+
+Learn more about subscribers in the [Events and Subscribers documentation](https://docs.medusajs.com/docs/learn/fundamentals/events-and-subscribers/index.html.md).
+
+You create a subscriber in a TypeScript or JavaScript file under the `src/subscribers` directory. So, to create the subscriber that listens to the `algolia.sync` event, create the file `src/subscribers/products-sync.ts` with the following content:
+
+```ts title="src/subscribers/algolia-sync.ts"
+import {
+  SubscriberArgs,
+  type SubscriberConfig,
+} from "@medusajs/framework"
+import { syncProductsWorkflow } from "../workflows/sync-products"
+
+export default async function algoliaSyncHandler({ 
+  container,
+}: SubscriberArgs) {
+  const logger = container.resolve("logger")
+  
+  let hasMore = true
+  let offset = 0
+  const limit = 50
+  let totalIndexed = 0
+
+  logger.info("Starting product indexing...")
+
+  while (hasMore) {
+    const { result: { products, metadata } } = await syncProductsWorkflow(container)
+      .run({
+        input: {
+          limit,
+          offset,
+        },
+      })
+
+    hasMore = offset + limit < (metadata?.count ?? 0)
+    offset += limit
+    totalIndexed += products.length
+  }
+
+  logger.info(`Successfully indexed ${totalIndexed} products`)
+}
+
+export const config: SubscriberConfig = {
+  event: "algolia.sync",
+}
+```
+
+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 `algolia.sync` in this case.
+
+The subscriber function receives an object as a parameter that has a `container` property, which is the Medusa container.
+
+In the subscriber function, you initialize variables to keep track of the pagination and the total number of products indexed.
+
+Then, you start a loop that retrieves products in batches of 50 and indexes them in Algolia using the `syncProductsWorkflow`. Finally, you log the total number of products indexed.
+
+You'll learn how to emit the `algolia.sync` event next.
+
+If you want to sync other data types, you can do it in this subscriber as well.
+
+### Create API Route to Trigger Sync
+
+To allow the Medusa Admin dashboard to trigger the `algolia.sync` event, you need to create an API route that emits the 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/algolia/sync`, create the file `src/api/admin/algolia/sync/route.ts` with the following content:
+
+```ts title="src/api/admin/algolia/sync/route.ts"
+import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
+import { Modules } from "@medusajs/framework/utils"
+
+export async function POST(
+  req: MedusaRequest,
+  res: MedusaResponse
+) {
+  const eventModuleService = req.scope.resolve(Modules.EVENT_BUS)
+  await eventModuleService.emit({
+    name: "algolia.sync",
+    data: {},
+  })
+  res.send({
+    message: "Syncing data to Algolia",
+  })
+}
+```
+
+Since you export a `POST` route handler function, you expose an `API` route at `/admin/algolia/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 use the Medusa container that is available in the request object to resolve the [Event Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/infrastructure-modules/event/index.html.md). This module manages events and their subscribers.
+
+Then, you emit the `algolia.sync` event using the Event Module's `emit` method, passing it the event name.
+
+Finally, you send a response with a message indicating that data is being synced to Algolia.
+
+### Add Algolia Sync Page to Admin Dashboard
+
+The last step is to add a new page to the admin dashboard that allows the admin to trigger the reindex. You add a new page using a [UI Route](https://docs.medusajs.com/docs/learn/fundamentals/admin/ui-routes/index.html.md).
+
+A UI route is a React component that specifies the content to be shown in a new page in the Medusa Admin dashboard. You'll create a UI route to display a button that triggers the reindex when clicked.
+
+Learn more about UI routes in the [UI Routes documentation](https://docs.medusajs.com/docs/learn/fundamentals/admin/ui-routes/index.html.md).
+
+#### Configure JS SDK
+
+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) that you can use to send requests to the Medusa server from any client application, including your Medusa Admin customizations.
+
+The JS SDK is installed by default in your Medusa application. To configure it, create the file `src/admin/lib/sdk.ts` with the following content:
+
+```ts title="src/admin/lib/sdk.ts"
+import Medusa from "@medusajs/js-sdk"
+
+export const sdk = new Medusa({
+  baseUrl: "http://localhost:9000",
+  debug: process.env.NODE_ENV === "development",
+  auth: {
+    type: "session",
+  },
+})
+```
+
+You create an instance of the JS SDK using the `Medusa` class from the JS SDK. You pass it an object having the following properties:
+
+- `baseUrl`: The base URL of the Medusa server.
+- `debug`: A boolean indicating whether to log debug information into the console.
+- `auth`: An object specifying the authentication type. When using the JS SDK for admin customizations, you use the `session` authentication type.
+
+#### Create UI Route
+
+You'll now create the UI route that displays a button to trigger the reindex. You create a UI route 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, to create a new page under the Settings section of the Medusa Admin, create the file `src/admin/routes/settings/algolia/page.tsx` with the following content:
+
+```tsx title="src/admin/routes/settings/algolia/page.tsx"
+import { Container, Heading, Button, toast } from "@medusajs/ui"
+import { useMutation } from "@tanstack/react-query"
+import { sdk } from "../../../lib/sdk"
+import { defineRouteConfig } from "@medusajs/admin-sdk"
+
+const AlgoliaPage = () => {
+  const { mutate, isPending } = useMutation({
+    mutationFn: () => 
+      sdk.client.fetch("/admin/algolia/sync", {
+        method: "POST",
+      }),
+    onSuccess: () => {
+      toast.success("Successfully triggered data sync to Algolia") 
+    },
+    onError: (err) => {
+      console.error(err)
+      toast.error("Failed to sync data to Algolia") 
+    },
+  })
+
+  const handleSync = () => {
+    mutate()
+  }
+
+  return (
+    <Container className="divide-y p-0">
+      <div className="flex items-center justify-between px-6 py-4">
+        <Heading level="h2">Algolia Sync</Heading>
+      </div>
+      <div className="px-6 py-8">
+        <Button 
+          variant="primary"
+          onClick={handleSync}
+          isLoading={isPending}
+        >
+          Sync Data to Algolia
+        </Button>
+      </div>
+    </Container>
+  )
+}
+
+export const config = defineRouteConfig({
+  label: "Algolia",
+})
+
+export default AlgoliaPage
+```
+
+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 it Out
+
+You'll now test out the entire flow, starting from triggering the reindex manually from the Medusa Admin dashboard, to checking the Algolia dashboard for the indexed products.
+
+Run the following command to start the Medusa application:
+
+```bash npm2yarn
+npm run dev
+```
+
+Then, open the Medusa Admin at `http://localhost:9000/app` and log in with the credentials you set up in the first step.
+
+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).
+
+After you log in, go to Settings from the sidebar. You'll find in the Settings' sidebar a new "Algolia" item. If you click on it, you'll find the page you created with the button to sync products to Algolia.
+
+If you click on the button, the products will be synced to Algolia.
+
+![The Algolia Sync page in the Medusa Admin dashboard with a button to sync products to Algolia](https://res.cloudinary.com/dza7lstvk/image/upload/v1742820813/Medusa%20Resources/Screenshot_2025-03-24_at_2.52.31_PM_eiegzb.png)
+
+You can check that the sync ran and was completed by checking the Medusa logs in the terminal where you started the Medusa application. You should find the following messages:
+
+```bash
+info:    Processing algolia.sync which has 1 subscribers
+info:    Starting product indexing...
+info:    Successfully indexed 4 products
+```
+
+These messages indicate that the `algolia.sync` event was emitted, which triggered the subscriber you created to sync the products using the `syncProductsWorkflow`.
+
+Finally, you can check the Algolia dashboard to see the indexed products. Go to Search -> Index, and check the records of the index you set up in the Algolia Module's options (`products`, for example).
+
+![The Algolia dashboard showing the indexed products](https://res.cloudinary.com/dza7lstvk/image/upload/v1742821034/Medusa%20Resources/Screenshot_2025-03-24_at_2.56.38_PM_mtojrv.png)
+
+***
+
+## Step 5: Update Index on Product Changes
+
+You'll now automate the indexing of the products whenever a change occurs. That includes when a product is created, updated, or deleted.
+
+Similar to before, you'll create subscribers to listen to these events.
+
+### Handle Create and Update Products
+
+The action to perform when a product is created or updated is the same. You'll use the `syncProductsWorkflow` to sync the product to Algolia.
+
+So, you only need one subscriber to handle these two events. To create the subscriber, create the file `src/subscribers/product-sync.ts` with the following content:
+
+```ts title="src/subscribers/product-sync.ts"
+import { SubscriberArgs, type SubscriberConfig } from "@medusajs/framework"
+import { syncProductsWorkflow } from "../workflows/sync-products"
+
+export default async function handleProductEvents({
+  event: { data },
+  container,
+}: SubscriberArgs<{ id: string }>) {
+  await syncProductsWorkflow(container)
+    .run({
+      input: {
+        filters: {
+          id: data.id,
+        },
+      },
+    })
+}
+
+export const config: SubscriberConfig = {
+  event: ["product.created", "product.updated"],
+}
+```
+
+The subscriber listens to the `product.created` and `product.updated` events. When either of these events is emitted, the subscriber triggers the `syncProductsWorkflow` to sync the product to Algolia.
+
+When the `product.created` and `product.updated` events are emitted, the product's ID is passed in the event data payload, which you can access in the `event.data` property of the subscriber function's parameter.
+
+So, you pass the product's ID to the `syncProductsWorkflow` as a filter to retrieve only the product that was created or updated.
+
+#### Test it Out
+
+To test it out, start the Medusa application:
+
+```bash npm2yarn
+npm run dev
+```
+
+Then, either create a product or update an existing one using the Medusa Admin dashboard. If you check the Algolia dashboard, you'll find that the product was created or updated.
+
+### Handle Product Deletion
+
+When a product is deleted, you need to remove it from the Algolia index. As this requires a different action than creating or updating a product, you'll create a new workflow that deletes the product from Algolia, then create a subscriber that listens to the `product.deleted` event to trigger the workflow.
+
+#### Create Delete Product Step
+
+The workflow to delete a product from Algolia will have only one step that deletes products by their IDs from Algolia.
+
+So, create the step at `src/workflows/steps/delete-products-from-algolia.ts` with the following content:
+
+```ts title="src/workflows/steps/delete-products-from-algolia.ts"
+import {
+  createStep,
+  StepResponse,
+} from "@medusajs/framework/workflows-sdk"
+import { ALGOLIA_MODULE } from "../../modules/algolia"
+
+export type DeleteProductsFromAlgoliaWorkflow = {
+  ids: string[]
+}
+
+export const deleteProductsFromAlgoliaStep = createStep(
+  "delete-products-from-algolia-step",
+  async (
+    { ids }: DeleteProductsFromAlgoliaWorkflow,
+    { container }
+  ) => {
+    const algoliaModuleService = container.resolve(ALGOLIA_MODULE)
+    
+    const existingRecords = await algoliaModuleService.retrieveFromIndex(
+      ids, 
+      "product"
+    )
+    await algoliaModuleService.deleteFromIndex(
+      ids,
+      "product"
+    )
+
+    return new StepResponse(undefined, existingRecords)
+  },
+  async (existingRecords, { container }) => {
+    if (!existingRecords) {
+      return
+    }
+    const algoliaModuleService = container.resolve(ALGOLIA_MODULE)
+    
+    await algoliaModuleService.indexData(
+      existingRecords as unknown as Record<string, unknown>[],
+      "product"
+    )
+  }
+)
+```
+
+The step receives the IDs of the products to delete as an input.
+
+In the step, you resolve the Algolia Module's service and retrieve the existing records from Algolia. This is useful to revert the deletion if an error occurs.
+
+Then, you delete the products from Algolia and pass the existing records to the compensation function.
+
+In the compensation function, you reindex the existing records if an error occurs.
+
+#### Create Delete Product Workflow
+
+You can now create the workflow that deletes products from Algolia. Create the file `src/workflows/delete-products-from-algolia.ts` with the following content:
+
+```ts title="src/workflows/delete-products-from-algolia.ts"
+import { createWorkflow } from "@medusajs/framework/workflows-sdk"
+import { deleteProductsFromAlgoliaStep } from "./steps/delete-products-from-algolia"
+
+type DeleteProductsFromAlgoliaWorkflowInput = {
+  ids: string[]
+}
+
+export const deleteProductsFromAlgoliaWorkflow = createWorkflow(
+  "delete-products-from-algolia",
+  (input: DeleteProductsFromAlgoliaWorkflowInput) => {
+    deleteProductsFromAlgoliaStep(input)
+  }
+)
+```
+
+The workflow receives an object with the IDs of the products to delete. It then executes the `deleteProductsFromAlgoliaStep` to delete the products from Algolia.
+
+#### Create Delete Product Subscriber
+
+Finally, you'll create the subscriber that listens to the `product.deleted` event to trigger the above workflow.
+
+Create the file `src/subscribers/product-delete.ts` with the following content:
+
+```ts title="src/subscribers/product-delete.ts"
+import { SubscriberArgs, type SubscriberConfig } from "@medusajs/framework"
+import { deleteProductsFromAlgoliaWorkflow } from "../workflows/delete-products-from-algolia"
+
+export default async function handleProductDeleted({
+  event: { data },
+  container,
+}: SubscriberArgs<{ id: string }>) {
+  await deleteProductsFromAlgoliaWorkflow(container)
+    .run({
+      input: {
+        ids: [data.id],
+      },
+    })
+}
+
+export const config: SubscriberConfig = {
+  event: "product.deleted",
+}
+```
+
+The subscriber listens to the `product.deleted` event. When the event is emitted, the subscriber triggers the `deleteProductsFromAlgoliaWorkflow`, passing it the ID of the product to delete.
+
+#### Test it Out
+
+To test product deletion, start the Medusa application:
+
+```bash npm2yarn
+npm run dev
+```
+
+Then, delete a product from the Medusa Admin dashboard. If you check the Algolia dashboard, you'll find that the product was deleted there as well.
+
+***
+
+## Step 6: Add Search API Route
+
+Before customizing the storefront to show the search UI, you'll create an API route in your Medusa application that allows storefronts to search products in Algolia.
+
+While you can implement the search functionality directly in the storefront to interact with Algolia, this approach centralizes your search integration in Medusa, allowing you to change or modify the integration as necessary. You can also rely on the same behavior and results across different storefronts.
+
+To implement the API Route, create the file `src/api/store/products/search/route.ts` with the following content:
+
+```ts title="src/api/store/products/search/route.ts"
+import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
+import { ALGOLIA_MODULE } from "../../../../modules/algolia"
+import AlgoliaModuleService from "../../../../modules/algolia/service"
+import { z } from "zod"
+
+export const SearchSchema = z.object({
+  query: z.string(),
+})
+
+type SearchRequest = z.infer<typeof SearchSchema>
+
+export async function POST(
+  req: MedusaRequest<SearchRequest>,
+  res: MedusaResponse
+) {
+  const algoliaModuleService: AlgoliaModuleService = req.scope.resolve(ALGOLIA_MODULE)
+
+  const { query } = req.validatedBody
+
+  const results = await algoliaModuleService.search(
+    query as string 
+  )
+
+  res.json(results)
+}
+```
+
+You first define a schema with [Zod](https://zod.dev/), a library to define validation schemas. The schema defines the structure of the request body, which in this case is an object with a `query` property of type `string`. Later, you'll use the schema to enforce request body validation.
+
+Then, you expose a `POST` API Route at `/store/search` that searches Algolia using the `search` method you implemented in the Algolia Module's service. You pass to it the query string from the request body.
+
+Finally, you return the search results as it is in the response.
+
+### Add Validation Middleware
+
+To ensure that requests sent to the API route have the required request body parameters, you can use 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. It's executed before the route handler.
+
+Learn more about middleware in the [Middlewares documentation](https://docs.medusajs.com/docs/learn/fundamentals/api-routes/middlewares/index.html.md).
+
+Middlewares are created in the `src/api/middlewares.ts` file. So create the file `src/api/middlewares.ts` with the following content:
+
+```ts title="src/api/middlewares.ts"
+import { 
+  defineMiddlewares,
+  validateAndTransformBody, 
+} from "@medusajs/framework/http"
+import { SearchSchema } from "./store/products/search/route"
+
+export default defineMiddlewares({
+  routes: [
+    {
+      matcher: "/store/products/search",
+      method: ["POST"],
+      middlewares: [
+        validateAndTransformBody(SearchSchema),
+      ],
+    },
+  ],
+})
+```
+
+To export the middlewares, you use the `defineMiddlewares` function. It accepts an object having a `routes` property, whose value is an array of middleware route objects. Each middleware route object has the following properties:
+
+- `matcher`: The path of the route the middleware applies to.
+- `method`: The HTTP methods the middleware applies to, which is in this case `POST`.
+- `middlewares`: An array of middleware functions to apply to the route. You apply the `validateAndTransformBody` middleware which ensures that a request's body has the required parameters. You pass it the schema you defined earlier in the API route's file.
+
+You can use the search API route now. You'll see it in action as you customize the storefront in the next step.
+
+***
+
+## Step 7: Search Products in Next.js Storefront
+
+The last step is to provide the search functionalities to customers on your storefront. In the first step, 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.
+
+In this step, you'll customize the Next.js Starter Storefront to add the search functionality.
+
+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-search`, you can find the storefront by going back to the parent directory and changing to the `medusa-search-storefront` directory:
+
+```bash
+cd ../medusa-search-storefront # change based on your project name
+```
+
+### Install Algolia Packages
+
+Before adding the implementation of the search functionality, you need to install the Algolia packages necessary to add the search functionality in your storefront.
+
+Run the following command in the directory of your Next.js Starter Storefront:
+
+```bash npm2yarn
+npm install algoliasearch react-instantsearch
+```
+
+This installs the Algolia Search JavaScript client and the React InstantSearch library, which you'll use to build the search functionality.
+
+### Add Search Client Configuration
+
+Next, you need to configure the search client. Not only do you need to initialize Algolia, but you also need to change the searching mechanism to use your custom API route in the Medusa application instead of Algolia's API directly.
+
+In `src/lib/config.ts`, add the following imports at the top of the file:
+
+```ts title="src/lib/config.ts" badgeLabel="Storefront" badgeColor="blue"
+import { 
+  liteClient as algoliasearch, 
+  LiteClient as SearchClient,
+} from "algoliasearch/lite"
+```
+
+Then, add the following at the end of the file:
+
+```ts title="src/lib/config.ts" badgeLabel="Storefront" badgeColor="blue"
+export const searchClient: SearchClient = {
+  ...(algoliasearch(
+    process.env.NEXT_PUBLIC_ALGOLIA_APP_ID || "", 
+    process.env.NEXT_PUBLIC_ALGOLIA_API_KEY || ""
+  )),
+  search: async (params) => {
+    const request = Array.isArray(params) ? params[0] : params
+    const query = "params" in request ? request.params?.query : 
+      "query" in request ? request.query : ""
+
+    if (!query) {
+      return {
+        results: [
+          {
+            hits: [],
+            nbHits: 0,
+            nbPages: 0,
+            page: 0,
+            hitsPerPage: 0,
+            processingTimeMS: 0,
+            query: "",
+            params: "",
+          },
+        ],
+      }
+    }
+
+    return await sdk.client.fetch(`/store/products/search`, {
+      method: "POST",
+      body: {
+        query,
+      },
+    })
+  },
+}
+```
+
+In the code above, you create a `searchClient` object that initializes the Algolia client with your Algolia App ID and API Key.
+
+You also define a `search` method that sends a `POST` request to the search API route you created in the Medusa application. You use the JS SDK (which is initialized in this same file) to send the request.
+
+### Set Environment Variables
+
+In the storefront's `.env.local` file, add the following Algolia-related environment variables:
+
+```plain badgeLabel="Storefront" badgeColor="blue"
+NEXT_PUBLIC_ALGOLIA_APP_ID=your_algolia_app_id
+NEXT_PUBLIC_ALGOLIA_API_KEY=your_algolia_api_key
+NEXT_PUBLIC_ALGOLIA_PRODUCT_INDEX_NAME=your-products-index-name
+```
+
+Where:
+
+- `your_algolia_app_id` is your Algolia App ID, as explained in the [Add Environment Variables section](#add-environment-variables) earlier.
+- `your_algolia_api_key` is your Algolia Search API key. You can retrieve it from the [same API keys page on the Algolia dashboard](#add-environment-variables) that you retrieved the Admin API key from.
+- `your-products-index-name` is the name of the index you created in Algolia to store the products, which you can retrieve as explained in the [Add Environment Variables section](#add-environment-variables) earlier. You'll use this variable later.
+
+Do not expose your Admin API key in the storefront. The Admin API key should only be used in the Medusa application to interact with Algolia, as it has full access to your Algolia account.
+
+### Add Search Modal Component
+
+You'll now add a search modal component that customers can use to search for products. The search modal will display the search results in real-time as the customer types in the search query.
+
+Later, you'll add the search modal to the navigation bar, allowing customers to open the search modal from any page.
+
+Create the file `src/modules/search/components/modal/index.tsx` with the following content:
+
+```tsx title="src/modules/search/components/modal/index.tsx" badgeLabel="Storefront" badgeColor="blue"
+"use client"
+
+import React, { useEffect, useState } from "react"
+import { Hits, InstantSearch, SearchBox } from "react-instantsearch"
+import { searchClient } from "../../../../lib/config"
+import Modal from "../../../common/components/modal"
+import { Button } from "@medusajs/ui"
+import Image from "next/image"
+import Link from "next/link"
+import { usePathname } from "next/navigation"
+
+type Hit = {
+  objectID: string;
+  id: string;
+  title: string;
+  description: string;
+  handle: string;
+  thumbnail: string;
+}
+
+export default function SearchModal() {
+  const [isOpen, setIsOpen] = useState(false)
+  const pathname = usePathname()
+
+  useEffect(() => {
+    setIsOpen(false)
+  }, [pathname])
+
+  return (
+    <>
+      <div className="hidden small:flex items-center gap-x-6 h-full">
+        <Button 
+          onClick={() => setIsOpen(true)} 
+          variant="transparent"
+          className="hover:text-ui-fg-base text-small-regular px-0 hover:bg-transparent focus:!bg-transparent"
+        >
+          Search
+        </Button>
+      </div>
+      <Modal isOpen={isOpen} close={() => setIsOpen(false)}>
+        <InstantSearch 
+          searchClient={searchClient} 
+          indexName={process.env.NEXT_PUBLIC_ALGOLIA_PRODUCT_INDEX_NAME}
+        >
+          <SearchBox className="w-full [&_input]:w-[94%] [&_input]:outline-none [&_button]:w-[3%]" />
+          <Hits hitComponent={Hit} />
+        </InstantSearch>
+      </Modal>
+    </>
+  )
+}
+
+const Hit = ({ hit }: { hit: Hit }) => {
+  return (
+    <div className="flex flex-row gap-x-2 mt-4 relative">
+      <Image src={hit.thumbnail} alt={hit.title} width={100} height={100} />
+      <div className="flex flex-col gap-y-1">
+        <h3>{hit.title}</h3>
+        <p className="text-sm text-gray-500">{hit.description}</p>
+      </div>
+      <Link href={`/products/${hit.handle}`} className="absolute right-0 top-0 w-full h-full" aria-label={`View Product: ${hit.title}`} />
+    </div>
+  )
+}
+```
+
+You create a `SearchModal` component that displays a search box and the search results using widgets from Algolia's `react-instantsearch` library.
+
+To display each result item (or hit), you create a `Hit` component that displays the product's title, description, and thumbnail. You also add a link to the product's page.
+
+Finally, you show the search modal when the customer clicks a "Search" button, which you'll add to the navigation bar next.
+
+### Add Search Button to Navigation Bar
+
+The last step is to show the search button in the navigation bar.
+
+In `src/modules/layout/templates/nav/index.tsx`, add the following imports at the top of the file:
+
+```tsx title="src/modules/layout/templates/nav/index.tsx" badgeLabel="Storefront" badgeColor="blue"
+import SearchModal from "@modules/search/components/modal"
+```
+
+Then, in the return statement of the `Nav` component, add the `SearchModal` component before the `div` surrounding the "Account" link:
+
+```tsx title="src/modules/layout/templates/nav/index.tsx" badgeLabel="Storefront" badgeColor="blue"
+<SearchModal />
+```
+
+The search button will now appear in the navigation bar before the Account link.
+
+### Test it Out
+
+To test out the storefront changes and the search API route, start the Medusa application:
+
+```bash npm2yarn
+npm run dev
+```
+
+Then, start the Next.js Starter Storefront from its directory:
+
+```bash npm2yarn
+npm run dev
+```
+
+Next, go to `localhost:8000`. You'll find a Search button at the top right of the navigation bar. If you click on it, you can search through your products. You can also click on a product to view its page.
+
+![The Next.js Starter Storefront showing the search modal with search results](https://res.cloudinary.com/dza7lstvk/image/upload/v1742827777/Medusa%20Resources/Screenshot_2025-03-24_at_4.49.23_PM_kzhldx.png)
+
+***
+
+## Next Steps
+
+You've now integrated Algolia with Medusa and added search functionality to your storefront. You can expand on these features to:
+
+- Add filters to the search results. You can do that using Algolia's [widgets](https://www.algolia.com/doc/guides/building-search-ui/widgets/showcase/react/) and customizing the search API route in Medusa to accept filter parameters.
+- Support indexing other data types, such as product categories. You can create the subscribers and workflows for categories similar to products.
+
+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.
@@ -50624,6 +49532,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).
+
+
 # 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.
@@ -52464,346 +52611,346 @@ To learn more about the commerce features that Medusa provides, check out Medusa
 - [batchSalesChannels](https://docs.medusajs.com/references/js_sdk/admin/ApiKey/methods/js_sdk.admin.ApiKey.batchSalesChannels/index.html.md)
 - [create](https://docs.medusajs.com/references/js_sdk/admin/ApiKey/methods/js_sdk.admin.ApiKey.create/index.html.md)
 - [delete](https://docs.medusajs.com/references/js_sdk/admin/ApiKey/methods/js_sdk.admin.ApiKey.delete/index.html.md)
-- [revoke](https://docs.medusajs.com/references/js_sdk/admin/ApiKey/methods/js_sdk.admin.ApiKey.revoke/index.html.md)
-- [retrieve](https://docs.medusajs.com/references/js_sdk/admin/ApiKey/methods/js_sdk.admin.ApiKey.retrieve/index.html.md)
 - [list](https://docs.medusajs.com/references/js_sdk/admin/ApiKey/methods/js_sdk.admin.ApiKey.list/index.html.md)
-- [delete](https://docs.medusajs.com/references/js_sdk/admin/Campaign/methods/js_sdk.admin.Campaign.delete/index.html.md)
-- [create](https://docs.medusajs.com/references/js_sdk/admin/Campaign/methods/js_sdk.admin.Campaign.create/index.html.md)
-- [list](https://docs.medusajs.com/references/js_sdk/admin/Campaign/methods/js_sdk.admin.Campaign.list/index.html.md)
+- [retrieve](https://docs.medusajs.com/references/js_sdk/admin/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)
-- [update](https://docs.medusajs.com/references/js_sdk/admin/Campaign/methods/js_sdk.admin.Campaign.update/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)
-- [fetch](https://docs.medusajs.com/references/js_sdk/admin/Client/methods/js_sdk.admin.Client.fetch/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)
-- [clearToken](https://docs.medusajs.com/references/js_sdk/admin/Client/methods/js_sdk.admin.Client.clearToken/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)
-- [getToken\_](https://docs.medusajs.com/references/js_sdk/admin/Client/methods/js_sdk.admin.Client.getToken_/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)
-- [getApiKeyHeader\_](https://docs.medusajs.com/references/js_sdk/admin/Client/methods/js_sdk.admin.Client.getApiKeyHeader_/index.html.md)
-- [retrieve](https://docs.medusajs.com/references/js_sdk/admin/Currency/methods/js_sdk.admin.Currency.retrieve/index.html.md)
-- [list](https://docs.medusajs.com/references/js_sdk/admin/Currency/methods/js_sdk.admin.Currency.list/index.html.md)
-- [addInboundShipping](https://docs.medusajs.com/references/js_sdk/admin/Claim/methods/js_sdk.admin.Claim.addInboundShipping/index.html.md)
+- [revoke](https://docs.medusajs.com/references/js_sdk/admin/ApiKey/methods/js_sdk.admin.ApiKey.revoke/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)
 - [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)
 - [create](https://docs.medusajs.com/references/js_sdk/admin/Claim/methods/js_sdk.admin.Claim.create/index.html.md)
 - [cancelRequest](https://docs.medusajs.com/references/js_sdk/admin/Claim/methods/js_sdk.admin.Claim.cancelRequest/index.html.md)
 - [deleteOutboundShipping](https://docs.medusajs.com/references/js_sdk/admin/Claim/methods/js_sdk.admin.Claim.deleteOutboundShipping/index.html.md)
 - [deleteInboundShipping](https://docs.medusajs.com/references/js_sdk/admin/Claim/methods/js_sdk.admin.Claim.deleteInboundShipping/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)
-- [request](https://docs.medusajs.com/references/js_sdk/admin/Claim/methods/js_sdk.admin.Claim.request/index.html.md)
-- [removeOutboundItem](https://docs.medusajs.com/references/js_sdk/admin/Claim/methods/js_sdk.admin.Claim.removeOutboundItem/index.html.md)
-- [retrieve](https://docs.medusajs.com/references/js_sdk/admin/Claim/methods/js_sdk.admin.Claim.retrieve/index.html.md)
-- [updateInboundItem](https://docs.medusajs.com/references/js_sdk/admin/Claim/methods/js_sdk.admin.Claim.updateInboundItem/index.html.md)
-- [updateItem](https://docs.medusajs.com/references/js_sdk/admin/Claim/methods/js_sdk.admin.Claim.updateItem/index.html.md)
-- [updateInboundShipping](https://docs.medusajs.com/references/js_sdk/admin/Claim/methods/js_sdk.admin.Claim.updateInboundShipping/index.html.md)
-- [updateOutboundItem](https://docs.medusajs.com/references/js_sdk/admin/Claim/methods/js_sdk.admin.Claim.updateOutboundItem/index.html.md)
-- [updateOutboundShipping](https://docs.medusajs.com/references/js_sdk/admin/Claim/methods/js_sdk.admin.Claim.updateOutboundShipping/index.html.md)
 - [removeItem](https://docs.medusajs.com/references/js_sdk/admin/Claim/methods/js_sdk.admin.Claim.removeItem/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)
-- [cancelEdit](https://docs.medusajs.com/references/js_sdk/admin/DraftOrder/methods/js_sdk.admin.DraftOrder.cancelEdit/index.html.md)
-- [beginEdit](https://docs.medusajs.com/references/js_sdk/admin/DraftOrder/methods/js_sdk.admin.DraftOrder.beginEdit/index.html.md)
-- [addShippingMethod](https://docs.medusajs.com/references/js_sdk/admin/DraftOrder/methods/js_sdk.admin.DraftOrder.addShippingMethod/index.html.md)
-- [confirmEdit](https://docs.medusajs.com/references/js_sdk/admin/DraftOrder/methods/js_sdk.admin.DraftOrder.confirmEdit/index.html.md)
-- [create](https://docs.medusajs.com/references/js_sdk/admin/DraftOrder/methods/js_sdk.admin.DraftOrder.create/index.html.md)
-- [convertToOrder](https://docs.medusajs.com/references/js_sdk/admin/DraftOrder/methods/js_sdk.admin.DraftOrder.convertToOrder/index.html.md)
-- [list](https://docs.medusajs.com/references/js_sdk/admin/DraftOrder/methods/js_sdk.admin.DraftOrder.list/index.html.md)
-- [removeActionItem](https://docs.medusajs.com/references/js_sdk/admin/DraftOrder/methods/js_sdk.admin.DraftOrder.removeActionItem/index.html.md)
-- [removePromotions](https://docs.medusajs.com/references/js_sdk/admin/DraftOrder/methods/js_sdk.admin.DraftOrder.removePromotions/index.html.md)
-- [retrieve](https://docs.medusajs.com/references/js_sdk/admin/DraftOrder/methods/js_sdk.admin.DraftOrder.retrieve/index.html.md)
-- [removeActionShippingMethod](https://docs.medusajs.com/references/js_sdk/admin/DraftOrder/methods/js_sdk.admin.DraftOrder.removeActionShippingMethod/index.html.md)
-- [requestEdit](https://docs.medusajs.com/references/js_sdk/admin/DraftOrder/methods/js_sdk.admin.DraftOrder.requestEdit/index.html.md)
-- [removeShippingMethod](https://docs.medusajs.com/references/js_sdk/admin/DraftOrder/methods/js_sdk.admin.DraftOrder.removeShippingMethod/index.html.md)
-- [updateActionItem](https://docs.medusajs.com/references/js_sdk/admin/DraftOrder/methods/js_sdk.admin.DraftOrder.updateActionItem/index.html.md)
-- [update](https://docs.medusajs.com/references/js_sdk/admin/DraftOrder/methods/js_sdk.admin.DraftOrder.update/index.html.md)
-- [updateActionShippingMethod](https://docs.medusajs.com/references/js_sdk/admin/DraftOrder/methods/js_sdk.admin.DraftOrder.updateActionShippingMethod/index.html.md)
-- [updateItem](https://docs.medusajs.com/references/js_sdk/admin/DraftOrder/methods/js_sdk.admin.DraftOrder.updateItem/index.html.md)
-- [updateShippingMethod](https://docs.medusajs.com/references/js_sdk/admin/DraftOrder/methods/js_sdk.admin.DraftOrder.updateShippingMethod/index.html.md)
+- [request](https://docs.medusajs.com/references/js_sdk/admin/Claim/methods/js_sdk.admin.Claim.request/index.html.md)
+- [updateInboundItem](https://docs.medusajs.com/references/js_sdk/admin/Claim/methods/js_sdk.admin.Claim.updateInboundItem/index.html.md)
+- [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)
+- [updateItem](https://docs.medusajs.com/references/js_sdk/admin/Claim/methods/js_sdk.admin.Claim.updateItem/index.html.md)
+- [removeOutboundItem](https://docs.medusajs.com/references/js_sdk/admin/Claim/methods/js_sdk.admin.Claim.removeOutboundItem/index.html.md)
+- [updateOutboundShipping](https://docs.medusajs.com/references/js_sdk/admin/Claim/methods/js_sdk.admin.Claim.updateOutboundShipping/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)
+- [updateOutboundItem](https://docs.medusajs.com/references/js_sdk/admin/Claim/methods/js_sdk.admin.Claim.updateOutboundItem/index.html.md)
+- [retrieve](https://docs.medusajs.com/references/js_sdk/admin/Campaign/methods/js_sdk.admin.Campaign.retrieve/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)
+- [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/Currency/methods/js_sdk.admin.Currency.retrieve/index.html.md)
+- [list](https://docs.medusajs.com/references/js_sdk/admin/Currency/methods/js_sdk.admin.Currency.list/index.html.md)
+- [getItem](https://docs.medusajs.com/references/js_sdk/admin/CustomStorage/methods/js_sdk.admin.CustomStorage.getItem/index.html.md)
+- [removeItem](https://docs.medusajs.com/references/js_sdk/admin/CustomStorage/methods/js_sdk.admin.CustomStorage.removeItem/index.html.md)
+- [setItem](https://docs.medusajs.com/references/js_sdk/admin/CustomStorage/methods/js_sdk.admin.CustomStorage.setItem/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)
+- [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)
+- [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)
+- [getToken\_](https://docs.medusajs.com/references/js_sdk/admin/Client/methods/js_sdk.admin.Client.getToken_/index.html.md)
+- [setToken\_](https://docs.medusajs.com/references/js_sdk/admin/Client/methods/js_sdk.admin.Client.setToken_/index.html.md)
+- [throwError\_](https://docs.medusajs.com/references/js_sdk/admin/Client/methods/js_sdk.admin.Client.throwError_/index.html.md)
 - [batchCustomers](https://docs.medusajs.com/references/js_sdk/admin/CustomerGroup/methods/js_sdk.admin.CustomerGroup.batchCustomers/index.html.md)
+- [setToken](https://docs.medusajs.com/references/js_sdk/admin/Client/methods/js_sdk.admin.Client.setToken/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)
+- [delete](https://docs.medusajs.com/references/js_sdk/admin/CustomerGroup/methods/js_sdk.admin.CustomerGroup.delete/index.html.md)
 - [update](https://docs.medusajs.com/references/js_sdk/admin/CustomerGroup/methods/js_sdk.admin.CustomerGroup.update/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)
-- [addOutboundItems](https://docs.medusajs.com/references/js_sdk/admin/Exchange/methods/js_sdk.admin.Exchange.addOutboundItems/index.html.md)
-- [cancelRequest](https://docs.medusajs.com/references/js_sdk/admin/Exchange/methods/js_sdk.admin.Exchange.cancelRequest/index.html.md)
-- [addOutboundShipping](https://docs.medusajs.com/references/js_sdk/admin/Exchange/methods/js_sdk.admin.Exchange.addOutboundShipping/index.html.md)
-- [cancel](https://docs.medusajs.com/references/js_sdk/admin/Exchange/methods/js_sdk.admin.Exchange.cancel/index.html.md)
-- [create](https://docs.medusajs.com/references/js_sdk/admin/Exchange/methods/js_sdk.admin.Exchange.create/index.html.md)
-- [deleteOutboundShipping](https://docs.medusajs.com/references/js_sdk/admin/Exchange/methods/js_sdk.admin.Exchange.deleteOutboundShipping/index.html.md)
-- [list](https://docs.medusajs.com/references/js_sdk/admin/Exchange/methods/js_sdk.admin.Exchange.list/index.html.md)
-- [deleteInboundShipping](https://docs.medusajs.com/references/js_sdk/admin/Exchange/methods/js_sdk.admin.Exchange.deleteInboundShipping/index.html.md)
-- [removeInboundItem](https://docs.medusajs.com/references/js_sdk/admin/Exchange/methods/js_sdk.admin.Exchange.removeInboundItem/index.html.md)
-- [retrieve](https://docs.medusajs.com/references/js_sdk/admin/Exchange/methods/js_sdk.admin.Exchange.retrieve/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)
-- [updateInboundItem](https://docs.medusajs.com/references/js_sdk/admin/Exchange/methods/js_sdk.admin.Exchange.updateInboundItem/index.html.md)
-- [updateInboundShipping](https://docs.medusajs.com/references/js_sdk/admin/Exchange/methods/js_sdk.admin.Exchange.updateInboundShipping/index.html.md)
-- [updateOutboundItem](https://docs.medusajs.com/references/js_sdk/admin/Exchange/methods/js_sdk.admin.Exchange.updateOutboundItem/index.html.md)
-- [setItem](https://docs.medusajs.com/references/js_sdk/admin/CustomStorage/methods/js_sdk.admin.CustomStorage.setItem/index.html.md)
-- [removeItem](https://docs.medusajs.com/references/js_sdk/admin/CustomStorage/methods/js_sdk.admin.CustomStorage.removeItem/index.html.md)
-- [getItem](https://docs.medusajs.com/references/js_sdk/admin/CustomStorage/methods/js_sdk.admin.CustomStorage.getItem/index.html.md)
-- [updateOutboundShipping](https://docs.medusajs.com/references/js_sdk/admin/Exchange/methods/js_sdk.admin.Exchange.updateOutboundShipping/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)
+- [batchCustomerGroups](https://docs.medusajs.com/references/js_sdk/admin/Customer/methods/js_sdk.admin.Customer.batchCustomerGroups/index.html.md)
+- [create](https://docs.medusajs.com/references/js_sdk/admin/Customer/methods/js_sdk.admin.Customer.create/index.html.md)
+- [createAddress](https://docs.medusajs.com/references/js_sdk/admin/Customer/methods/js_sdk.admin.Customer.createAddress/index.html.md)
+- [delete](https://docs.medusajs.com/references/js_sdk/admin/Customer/methods/js_sdk.admin.Customer.delete/index.html.md)
+- [deleteAddress](https://docs.medusajs.com/references/js_sdk/admin/Customer/methods/js_sdk.admin.Customer.deleteAddress/index.html.md)
+- [list](https://docs.medusajs.com/references/js_sdk/admin/Customer/methods/js_sdk.admin.Customer.list/index.html.md)
+- [listAddresses](https://docs.medusajs.com/references/js_sdk/admin/Customer/methods/js_sdk.admin.Customer.listAddresses/index.html.md)
+- [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)
+- [retrieve](https://docs.medusajs.com/references/js_sdk/admin/Customer/methods/js_sdk.admin.Customer.retrieve/index.html.md)
+- [retrieveAddress](https://docs.medusajs.com/references/js_sdk/admin/Customer/methods/js_sdk.admin.Customer.retrieveAddress/index.html.md)
 - [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)
-- [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)
-- [batchUpdateLevels](https://docs.medusajs.com/references/js_sdk/admin/InventoryItem/methods/js_sdk.admin.InventoryItem.batchUpdateLevels/index.html.md)
-- [delete](https://docs.medusajs.com/references/js_sdk/admin/InventoryItem/methods/js_sdk.admin.InventoryItem.delete/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)
-- [update](https://docs.medusajs.com/references/js_sdk/admin/InventoryItem/methods/js_sdk.admin.InventoryItem.update/index.html.md)
-- [create](https://docs.medusajs.com/references/js_sdk/admin/InventoryItem/methods/js_sdk.admin.InventoryItem.create/index.html.md)
-- [updateLevel](https://docs.medusajs.com/references/js_sdk/admin/InventoryItem/methods/js_sdk.admin.InventoryItem.updateLevel/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)
-- [retrieve](https://docs.medusajs.com/references/js_sdk/admin/InventoryItem/methods/js_sdk.admin.InventoryItem.retrieve/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)
-- [retrieve](https://docs.medusajs.com/references/js_sdk/admin/Invite/methods/js_sdk.admin.Invite.retrieve/index.html.md)
-- [resend](https://docs.medusajs.com/references/js_sdk/admin/Invite/methods/js_sdk.admin.Invite.resend/index.html.md)
-- [list](https://docs.medusajs.com/references/js_sdk/admin/Notification/methods/js_sdk.admin.Notification.list/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)
+- [addOutboundItems](https://docs.medusajs.com/references/js_sdk/admin/Exchange/methods/js_sdk.admin.Exchange.addOutboundItems/index.html.md)
+- [addOutboundShipping](https://docs.medusajs.com/references/js_sdk/admin/Exchange/methods/js_sdk.admin.Exchange.addOutboundShipping/index.html.md)
+- [cancelRequest](https://docs.medusajs.com/references/js_sdk/admin/Exchange/methods/js_sdk.admin.Exchange.cancelRequest/index.html.md)
+- [cancel](https://docs.medusajs.com/references/js_sdk/admin/Exchange/methods/js_sdk.admin.Exchange.cancel/index.html.md)
+- [create](https://docs.medusajs.com/references/js_sdk/admin/Exchange/methods/js_sdk.admin.Exchange.create/index.html.md)
+- [deleteInboundShipping](https://docs.medusajs.com/references/js_sdk/admin/Exchange/methods/js_sdk.admin.Exchange.deleteInboundShipping/index.html.md)
+- [list](https://docs.medusajs.com/references/js_sdk/admin/Exchange/methods/js_sdk.admin.Exchange.list/index.html.md)
+- [deleteOutboundShipping](https://docs.medusajs.com/references/js_sdk/admin/Exchange/methods/js_sdk.admin.Exchange.deleteOutboundShipping/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)
+- [updateInboundItem](https://docs.medusajs.com/references/js_sdk/admin/Exchange/methods/js_sdk.admin.Exchange.updateInboundItem/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)
+- [updateOutboundItem](https://docs.medusajs.com/references/js_sdk/admin/Exchange/methods/js_sdk.admin.Exchange.updateOutboundItem/index.html.md)
 - [retrieve](https://docs.medusajs.com/references/js_sdk/admin/Notification/methods/js_sdk.admin.Notification.retrieve/index.html.md)
-- [cancel](https://docs.medusajs.com/references/js_sdk/admin/Order/methods/js_sdk.admin.Order.cancel/index.html.md)
-- [createCreditLine](https://docs.medusajs.com/references/js_sdk/admin/Order/methods/js_sdk.admin.Order.createCreditLine/index.html.md)
+- [list](https://docs.medusajs.com/references/js_sdk/admin/Notification/methods/js_sdk.admin.Notification.list/index.html.md)
+- [addItems](https://docs.medusajs.com/references/js_sdk/admin/DraftOrder/methods/js_sdk.admin.DraftOrder.addItems/index.html.md)
+- [updateOutboundShipping](https://docs.medusajs.com/references/js_sdk/admin/Exchange/methods/js_sdk.admin.Exchange.updateOutboundShipping/index.html.md)
+- [addShippingMethod](https://docs.medusajs.com/references/js_sdk/admin/DraftOrder/methods/js_sdk.admin.DraftOrder.addShippingMethod/index.html.md)
+- [beginEdit](https://docs.medusajs.com/references/js_sdk/admin/DraftOrder/methods/js_sdk.admin.DraftOrder.beginEdit/index.html.md)
+- [addPromotions](https://docs.medusajs.com/references/js_sdk/admin/DraftOrder/methods/js_sdk.admin.DraftOrder.addPromotions/index.html.md)
+- [confirmEdit](https://docs.medusajs.com/references/js_sdk/admin/DraftOrder/methods/js_sdk.admin.DraftOrder.confirmEdit/index.html.md)
+- [convertToOrder](https://docs.medusajs.com/references/js_sdk/admin/DraftOrder/methods/js_sdk.admin.DraftOrder.convertToOrder/index.html.md)
+- [list](https://docs.medusajs.com/references/js_sdk/admin/DraftOrder/methods/js_sdk.admin.DraftOrder.list/index.html.md)
+- [cancelEdit](https://docs.medusajs.com/references/js_sdk/admin/DraftOrder/methods/js_sdk.admin.DraftOrder.cancelEdit/index.html.md)
+- [removeActionItem](https://docs.medusajs.com/references/js_sdk/admin/DraftOrder/methods/js_sdk.admin.DraftOrder.removeActionItem/index.html.md)
+- [removePromotions](https://docs.medusajs.com/references/js_sdk/admin/DraftOrder/methods/js_sdk.admin.DraftOrder.removePromotions/index.html.md)
+- [removeActionShippingMethod](https://docs.medusajs.com/references/js_sdk/admin/DraftOrder/methods/js_sdk.admin.DraftOrder.removeActionShippingMethod/index.html.md)
+- [requestEdit](https://docs.medusajs.com/references/js_sdk/admin/DraftOrder/methods/js_sdk.admin.DraftOrder.requestEdit/index.html.md)
+- [create](https://docs.medusajs.com/references/js_sdk/admin/DraftOrder/methods/js_sdk.admin.DraftOrder.create/index.html.md)
+- [update](https://docs.medusajs.com/references/js_sdk/admin/DraftOrder/methods/js_sdk.admin.DraftOrder.update/index.html.md)
+- [retrieve](https://docs.medusajs.com/references/js_sdk/admin/DraftOrder/methods/js_sdk.admin.DraftOrder.retrieve/index.html.md)
+- [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)
+- [updateShippingMethod](https://docs.medusajs.com/references/js_sdk/admin/DraftOrder/methods/js_sdk.admin.DraftOrder.updateShippingMethod/index.html.md)
+- [createServiceZone](https://docs.medusajs.com/references/js_sdk/admin/FulfillmentSet/methods/js_sdk.admin.FulfillmentSet.createServiceZone/index.html.md)
+- [updateActionItem](https://docs.medusajs.com/references/js_sdk/admin/DraftOrder/methods/js_sdk.admin.DraftOrder.updateActionItem/index.html.md)
+- [deleteServiceZone](https://docs.medusajs.com/references/js_sdk/admin/FulfillmentSet/methods/js_sdk.admin.FulfillmentSet.deleteServiceZone/index.html.md)
+- [delete](https://docs.medusajs.com/references/js_sdk/admin/FulfillmentSet/methods/js_sdk.admin.FulfillmentSet.delete/index.html.md)
+- [removeShippingMethod](https://docs.medusajs.com/references/js_sdk/admin/DraftOrder/methods/js_sdk.admin.DraftOrder.removeShippingMethod/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)
 - [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)
-- [createShipment](https://docs.medusajs.com/references/js_sdk/admin/Order/methods/js_sdk.admin.Order.createShipment/index.html.md)
+- [createCreditLine](https://docs.medusajs.com/references/js_sdk/admin/Order/methods/js_sdk.admin.Order.createCreditLine/index.html.md)
+- [cancel](https://docs.medusajs.com/references/js_sdk/admin/Order/methods/js_sdk.admin.Order.cancel/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)
 - [list](https://docs.medusajs.com/references/js_sdk/admin/Order/methods/js_sdk.admin.Order.list/index.html.md)
 - [listLineItems](https://docs.medusajs.com/references/js_sdk/admin/Order/methods/js_sdk.admin.Order.listLineItems/index.html.md)
+- [createShipment](https://docs.medusajs.com/references/js_sdk/admin/Order/methods/js_sdk.admin.Order.createShipment/index.html.md)
 - [markAsDelivered](https://docs.medusajs.com/references/js_sdk/admin/Order/methods/js_sdk.admin.Order.markAsDelivered/index.html.md)
-- [requestTransfer](https://docs.medusajs.com/references/js_sdk/admin/Order/methods/js_sdk.admin.Order.requestTransfer/index.html.md)
+- [listChanges](https://docs.medusajs.com/references/js_sdk/admin/Order/methods/js_sdk.admin.Order.listChanges/index.html.md)
 - [retrievePreview](https://docs.medusajs.com/references/js_sdk/admin/Order/methods/js_sdk.admin.Order.retrievePreview/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)
 - [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/Order/methods/js_sdk.admin.Order.retrieve/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)
+- [accept](https://docs.medusajs.com/references/js_sdk/admin/Invite/methods/js_sdk.admin.Invite.accept/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)
+- [capture](https://docs.medusajs.com/references/js_sdk/admin/Payment/methods/js_sdk.admin.Payment.capture/index.html.md)
+- [list](https://docs.medusajs.com/references/js_sdk/admin/Payment/methods/js_sdk.admin.Payment.list/index.html.md)
+- [listPaymentProviders](https://docs.medusajs.com/references/js_sdk/admin/Payment/methods/js_sdk.admin.Payment.listPaymentProviders/index.html.md)
+- [refund](https://docs.medusajs.com/references/js_sdk/admin/Payment/methods/js_sdk.admin.Payment.refund/index.html.md)
+- [retrieve](https://docs.medusajs.com/references/js_sdk/admin/Invite/methods/js_sdk.admin.Invite.retrieve/index.html.md)
+- [retrieve](https://docs.medusajs.com/references/js_sdk/admin/Payment/methods/js_sdk.admin.Payment.retrieve/index.html.md)
+- [batchInventoryItemsLocationLevels](https://docs.medusajs.com/references/js_sdk/admin/InventoryItem/methods/js_sdk.admin.InventoryItem.batchInventoryItemsLocationLevels/index.html.md)
+- [batchInventoryItemLocationLevels](https://docs.medusajs.com/references/js_sdk/admin/InventoryItem/methods/js_sdk.admin.InventoryItem.batchInventoryItemLocationLevels/index.html.md)
+- [create](https://docs.medusajs.com/references/js_sdk/admin/InventoryItem/methods/js_sdk.admin.InventoryItem.create/index.html.md)
+- [delete](https://docs.medusajs.com/references/js_sdk/admin/InventoryItem/methods/js_sdk.admin.InventoryItem.delete/index.html.md)
+- [list](https://docs.medusajs.com/references/js_sdk/admin/InventoryItem/methods/js_sdk.admin.InventoryItem.list/index.html.md)
+- [batchUpdateLevels](https://docs.medusajs.com/references/js_sdk/admin/InventoryItem/methods/js_sdk.admin.InventoryItem.batchUpdateLevels/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)
+- [create](https://docs.medusajs.com/references/js_sdk/admin/PaymentCollection/methods/js_sdk.admin.PaymentCollection.create/index.html.md)
+- [update](https://docs.medusajs.com/references/js_sdk/admin/InventoryItem/methods/js_sdk.admin.InventoryItem.update/index.html.md)
+- [deleteLevel](https://docs.medusajs.com/references/js_sdk/admin/InventoryItem/methods/js_sdk.admin.InventoryItem.deleteLevel/index.html.md)
+- [delete](https://docs.medusajs.com/references/js_sdk/admin/PaymentCollection/methods/js_sdk.admin.PaymentCollection.delete/index.html.md)
+- [updateLevel](https://docs.medusajs.com/references/js_sdk/admin/InventoryItem/methods/js_sdk.admin.InventoryItem.updateLevel/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)
+- [markAsPaid](https://docs.medusajs.com/references/js_sdk/admin/PaymentCollection/methods/js_sdk.admin.PaymentCollection.markAsPaid/index.html.md)
 - [addItems](https://docs.medusajs.com/references/js_sdk/admin/OrderEdit/methods/js_sdk.admin.OrderEdit.addItems/index.html.md)
 - [initiateRequest](https://docs.medusajs.com/references/js_sdk/admin/OrderEdit/methods/js_sdk.admin.OrderEdit.initiateRequest/index.html.md)
 - [removeAddedItem](https://docs.medusajs.com/references/js_sdk/admin/OrderEdit/methods/js_sdk.admin.OrderEdit.removeAddedItem/index.html.md)
-- [request](https://docs.medusajs.com/references/js_sdk/admin/OrderEdit/methods/js_sdk.admin.OrderEdit.request/index.html.md)
-- [updateAddedItem](https://docs.medusajs.com/references/js_sdk/admin/OrderEdit/methods/js_sdk.admin.OrderEdit.updateAddedItem/index.html.md)
-- [updateOriginalItem](https://docs.medusajs.com/references/js_sdk/admin/OrderEdit/methods/js_sdk.admin.OrderEdit.updateOriginalItem/index.html.md)
-- [create](https://docs.medusajs.com/references/js_sdk/admin/Customer/methods/js_sdk.admin.Customer.create/index.html.md)
-- [batchCustomerGroups](https://docs.medusajs.com/references/js_sdk/admin/Customer/methods/js_sdk.admin.Customer.batchCustomerGroups/index.html.md)
-- [delete](https://docs.medusajs.com/references/js_sdk/admin/Customer/methods/js_sdk.admin.Customer.delete/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)
-- [list](https://docs.medusajs.com/references/js_sdk/admin/Customer/methods/js_sdk.admin.Customer.list/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)
-- [retrieveAddress](https://docs.medusajs.com/references/js_sdk/admin/Customer/methods/js_sdk.admin.Customer.retrieveAddress/index.html.md)
-- [updateAddress](https://docs.medusajs.com/references/js_sdk/admin/Customer/methods/js_sdk.admin.Customer.updateAddress/index.html.md)
-- [update](https://docs.medusajs.com/references/js_sdk/admin/Customer/methods/js_sdk.admin.Customer.update/index.html.md)
-- [list](https://docs.medusajs.com/references/js_sdk/admin/Payment/methods/js_sdk.admin.Payment.list/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)
-- [refund](https://docs.medusajs.com/references/js_sdk/admin/Payment/methods/js_sdk.admin.Payment.refund/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)
-- [create](https://docs.medusajs.com/references/js_sdk/admin/PaymentCollection/methods/js_sdk.admin.PaymentCollection.create/index.html.md)
-- [markAsPaid](https://docs.medusajs.com/references/js_sdk/admin/PaymentCollection/methods/js_sdk.admin.PaymentCollection.markAsPaid/index.html.md)
-- [delete](https://docs.medusajs.com/references/js_sdk/admin/PaymentCollection/methods/js_sdk.admin.PaymentCollection.delete/index.html.md)
-- [createServiceZone](https://docs.medusajs.com/references/js_sdk/admin/FulfillmentSet/methods/js_sdk.admin.FulfillmentSet.createServiceZone/index.html.md)
-- [retrieveServiceZone](https://docs.medusajs.com/references/js_sdk/admin/FulfillmentSet/methods/js_sdk.admin.FulfillmentSet.retrieveServiceZone/index.html.md)
-- [deleteServiceZone](https://docs.medusajs.com/references/js_sdk/admin/FulfillmentSet/methods/js_sdk.admin.FulfillmentSet.deleteServiceZone/index.html.md)
-- [delete](https://docs.medusajs.com/references/js_sdk/admin/FulfillmentSet/methods/js_sdk.admin.FulfillmentSet.delete/index.html.md)
-- [updateServiceZone](https://docs.medusajs.com/references/js_sdk/admin/FulfillmentSet/methods/js_sdk.admin.FulfillmentSet.updateServiceZone/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)
+- [updateAddedItem](https://docs.medusajs.com/references/js_sdk/admin/OrderEdit/methods/js_sdk.admin.OrderEdit.updateAddedItem/index.html.md)
+- [request](https://docs.medusajs.com/references/js_sdk/admin/OrderEdit/methods/js_sdk.admin.OrderEdit.request/index.html.md)
+- [create](https://docs.medusajs.com/references/js_sdk/admin/PriceList/methods/js_sdk.admin.PriceList.create/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)
+- [linkProducts](https://docs.medusajs.com/references/js_sdk/admin/PriceList/methods/js_sdk.admin.PriceList.linkProducts/index.html.md)
+- [updateOriginalItem](https://docs.medusajs.com/references/js_sdk/admin/OrderEdit/methods/js_sdk.admin.OrderEdit.updateOriginalItem/index.html.md)
+- [update](https://docs.medusajs.com/references/js_sdk/admin/PriceList/methods/js_sdk.admin.PriceList.update/index.html.md)
+- [list](https://docs.medusajs.com/references/js_sdk/admin/PriceList/methods/js_sdk.admin.PriceList.list/index.html.md)
 - [batchVariantInventoryItems](https://docs.medusajs.com/references/js_sdk/admin/Product/methods/js_sdk.admin.Product.batchVariantInventoryItems/index.html.md)
-- [batch](https://docs.medusajs.com/references/js_sdk/admin/Product/methods/js_sdk.admin.Product.batch/index.html.md)
 - [batchVariants](https://docs.medusajs.com/references/js_sdk/admin/Product/methods/js_sdk.admin.Product.batchVariants/index.html.md)
 - [confirmImport](https://docs.medusajs.com/references/js_sdk/admin/Product/methods/js_sdk.admin.Product.confirmImport/index.html.md)
 - [createOption](https://docs.medusajs.com/references/js_sdk/admin/Product/methods/js_sdk.admin.Product.createOption/index.html.md)
 - [create](https://docs.medusajs.com/references/js_sdk/admin/Product/methods/js_sdk.admin.Product.create/index.html.md)
-- [createVariant](https://docs.medusajs.com/references/js_sdk/admin/Product/methods/js_sdk.admin.Product.createVariant/index.html.md)
-- [deleteVariant](https://docs.medusajs.com/references/js_sdk/admin/Product/methods/js_sdk.admin.Product.deleteVariant/index.html.md)
-- [deleteOption](https://docs.medusajs.com/references/js_sdk/admin/Product/methods/js_sdk.admin.Product.deleteOption/index.html.md)
-- [delete](https://docs.medusajs.com/references/js_sdk/admin/Product/methods/js_sdk.admin.Product.delete/index.html.md)
-- [list](https://docs.medusajs.com/references/js_sdk/admin/Product/methods/js_sdk.admin.Product.list/index.html.md)
-- [import](https://docs.medusajs.com/references/js_sdk/admin/Product/methods/js_sdk.admin.Product.import/index.html.md)
-- [export](https://docs.medusajs.com/references/js_sdk/admin/Product/methods/js_sdk.admin.Product.export/index.html.md)
-- [listOptions](https://docs.medusajs.com/references/js_sdk/admin/Product/methods/js_sdk.admin.Product.listOptions/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)
-- [retrieve](https://docs.medusajs.com/references/js_sdk/admin/Product/methods/js_sdk.admin.Product.retrieve/index.html.md)
-- [listVariants](https://docs.medusajs.com/references/js_sdk/admin/Product/methods/js_sdk.admin.Product.listVariants/index.html.md)
-- [updateOption](https://docs.medusajs.com/references/js_sdk/admin/Product/methods/js_sdk.admin.Product.updateOption/index.html.md)
-- [update](https://docs.medusajs.com/references/js_sdk/admin/Product/methods/js_sdk.admin.Product.update/index.html.md)
-- [updateVariant](https://docs.medusajs.com/references/js_sdk/admin/Product/methods/js_sdk.admin.Product.updateVariant/index.html.md)
-- [batchPrices](https://docs.medusajs.com/references/js_sdk/admin/PriceList/methods/js_sdk.admin.PriceList.batchPrices/index.html.md)
-- [create](https://docs.medusajs.com/references/js_sdk/admin/PriceList/methods/js_sdk.admin.PriceList.create/index.html.md)
-- [list](https://docs.medusajs.com/references/js_sdk/admin/PriceList/methods/js_sdk.admin.PriceList.list/index.html.md)
-- [delete](https://docs.medusajs.com/references/js_sdk/admin/PriceList/methods/js_sdk.admin.PriceList.delete/index.html.md)
-- [linkProducts](https://docs.medusajs.com/references/js_sdk/admin/PriceList/methods/js_sdk.admin.PriceList.linkProducts/index.html.md)
 - [retrieve](https://docs.medusajs.com/references/js_sdk/admin/PriceList/methods/js_sdk.admin.PriceList.retrieve/index.html.md)
+- [batch](https://docs.medusajs.com/references/js_sdk/admin/Product/methods/js_sdk.admin.Product.batch/index.html.md)
+- [deleteVariant](https://docs.medusajs.com/references/js_sdk/admin/Product/methods/js_sdk.admin.Product.deleteVariant/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)
+- [createVariant](https://docs.medusajs.com/references/js_sdk/admin/Product/methods/js_sdk.admin.Product.createVariant/index.html.md)
+- [export](https://docs.medusajs.com/references/js_sdk/admin/Product/methods/js_sdk.admin.Product.export/index.html.md)
+- [list](https://docs.medusajs.com/references/js_sdk/admin/Product/methods/js_sdk.admin.Product.list/index.html.md)
+- [listVariants](https://docs.medusajs.com/references/js_sdk/admin/Product/methods/js_sdk.admin.Product.listVariants/index.html.md)
+- [listOptions](https://docs.medusajs.com/references/js_sdk/admin/Product/methods/js_sdk.admin.Product.listOptions/index.html.md)
+- [retrieve](https://docs.medusajs.com/references/js_sdk/admin/Product/methods/js_sdk.admin.Product.retrieve/index.html.md)
+- [retrieveVariant](https://docs.medusajs.com/references/js_sdk/admin/Product/methods/js_sdk.admin.Product.retrieveVariant/index.html.md)
+- [update](https://docs.medusajs.com/references/js_sdk/admin/Product/methods/js_sdk.admin.Product.update/index.html.md)
+- [import](https://docs.medusajs.com/references/js_sdk/admin/Product/methods/js_sdk.admin.Product.import/index.html.md)
+- [updateOption](https://docs.medusajs.com/references/js_sdk/admin/Product/methods/js_sdk.admin.Product.updateOption/index.html.md)
+- [retrieveOption](https://docs.medusajs.com/references/js_sdk/admin/Product/methods/js_sdk.admin.Product.retrieveOption/index.html.md)
+- [updateVariant](https://docs.medusajs.com/references/js_sdk/admin/Product/methods/js_sdk.admin.Product.updateVariant/index.html.md)
+- [delete](https://docs.medusajs.com/references/js_sdk/admin/PricePreference/methods/js_sdk.admin.PricePreference.delete/index.html.md)
+- [create](https://docs.medusajs.com/references/js_sdk/admin/PricePreference/methods/js_sdk.admin.PricePreference.create/index.html.md)
+- [list](https://docs.medusajs.com/references/js_sdk/admin/PricePreference/methods/js_sdk.admin.PricePreference.list/index.html.md)
+- [update](https://docs.medusajs.com/references/js_sdk/admin/PricePreference/methods/js_sdk.admin.PricePreference.update/index.html.md)
+- [retrieve](https://docs.medusajs.com/references/js_sdk/admin/PricePreference/methods/js_sdk.admin.PricePreference.retrieve/index.html.md)
 - [create](https://docs.medusajs.com/references/js_sdk/admin/ProductCategory/methods/js_sdk.admin.ProductCategory.create/index.html.md)
 - [delete](https://docs.medusajs.com/references/js_sdk/admin/ProductCategory/methods/js_sdk.admin.ProductCategory.delete/index.html.md)
-- [update](https://docs.medusajs.com/references/js_sdk/admin/PriceList/methods/js_sdk.admin.PriceList.update/index.html.md)
 - [list](https://docs.medusajs.com/references/js_sdk/admin/ProductCategory/methods/js_sdk.admin.ProductCategory.list/index.html.md)
-- [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)
+- [retrieve](https://docs.medusajs.com/references/js_sdk/admin/ProductCategory/methods/js_sdk.admin.ProductCategory.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)
 - [delete](https://docs.medusajs.com/references/js_sdk/admin/ProductCollection/methods/js_sdk.admin.ProductCollection.delete/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)
-- [updateProducts](https://docs.medusajs.com/references/js_sdk/admin/ProductCollection/methods/js_sdk.admin.ProductCollection.updateProducts/index.html.md)
+- [create](https://docs.medusajs.com/references/js_sdk/admin/ProductTag/methods/js_sdk.admin.ProductTag.create/index.html.md)
 - [update](https://docs.medusajs.com/references/js_sdk/admin/ProductCollection/methods/js_sdk.admin.ProductCollection.update/index.html.md)
+- [delete](https://docs.medusajs.com/references/js_sdk/admin/ProductTag/methods/js_sdk.admin.ProductTag.delete/index.html.md)
+- [retrieve](https://docs.medusajs.com/references/js_sdk/admin/ProductTag/methods/js_sdk.admin.ProductTag.retrieve/index.html.md)
+- [list](https://docs.medusajs.com/references/js_sdk/admin/ProductTag/methods/js_sdk.admin.ProductTag.list/index.html.md)
+- [update](https://docs.medusajs.com/references/js_sdk/admin/ProductTag/methods/js_sdk.admin.ProductTag.update/index.html.md)
+- [updateProducts](https://docs.medusajs.com/references/js_sdk/admin/ProductCollection/methods/js_sdk.admin.ProductCollection.updateProducts/index.html.md)
 - [create](https://docs.medusajs.com/references/js_sdk/admin/Promotion/methods/js_sdk.admin.Promotion.create/index.html.md)
-- [addRules](https://docs.medusajs.com/references/js_sdk/admin/Promotion/methods/js_sdk.admin.Promotion.addRules/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)
-- [update](https://docs.medusajs.com/references/js_sdk/admin/Promotion/methods/js_sdk.admin.Promotion.update/index.html.md)
+- [addRules](https://docs.medusajs.com/references/js_sdk/admin/Promotion/methods/js_sdk.admin.Promotion.addRules/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)
+- [list](https://docs.medusajs.com/references/js_sdk/admin/Promotion/methods/js_sdk.admin.Promotion.list/index.html.md)
 - [updateRules](https://docs.medusajs.com/references/js_sdk/admin/Promotion/methods/js_sdk.admin.Promotion.updateRules/index.html.md)
-- [delete](https://docs.medusajs.com/references/js_sdk/admin/ProductType/methods/js_sdk.admin.ProductType.delete/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)
+- [create](https://docs.medusajs.com/references/js_sdk/admin/ProductType/methods/js_sdk.admin.ProductType.create/index.html.md)
+- [delete](https://docs.medusajs.com/references/js_sdk/admin/ProductType/methods/js_sdk.admin.ProductType.delete/index.html.md)
 - [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/ProductVariant/methods/js_sdk.admin.ProductVariant.list/index.html.md)
 - [list](https://docs.medusajs.com/references/js_sdk/admin/RefundReason/methods/js_sdk.admin.RefundReason.list/index.html.md)
+- [list](https://docs.medusajs.com/references/js_sdk/admin/ProductVariant/methods/js_sdk.admin.ProductVariant.list/index.html.md)
 - [create](https://docs.medusajs.com/references/js_sdk/admin/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)
-- [retrieve](https://docs.medusajs.com/references/js_sdk/admin/Region/methods/js_sdk.admin.Region.retrieve/index.html.md)
 - [list](https://docs.medusajs.com/references/js_sdk/admin/Region/methods/js_sdk.admin.Region.list/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)
+- [retrieve](https://docs.medusajs.com/references/js_sdk/admin/Region/methods/js_sdk.admin.Region.retrieve/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)
+- [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)
+- [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)
+- [retrieve](https://docs.medusajs.com/references/js_sdk/admin/SalesChannel/methods/js_sdk.admin.SalesChannel.retrieve/index.html.md)
 - [delete](https://docs.medusajs.com/references/js_sdk/admin/Reservation/methods/js_sdk.admin.Reservation.delete/index.html.md)
 - [create](https://docs.medusajs.com/references/js_sdk/admin/Reservation/methods/js_sdk.admin.Reservation.create/index.html.md)
-- [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)
 - [list](https://docs.medusajs.com/references/js_sdk/admin/Reservation/methods/js_sdk.admin.Reservation.list/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/ReturnReason/methods/js_sdk.admin.ReturnReason.create/index.html.md)
+- [retrieve](https://docs.medusajs.com/references/js_sdk/admin/Reservation/methods/js_sdk.admin.Reservation.retrieve/index.html.md)
+- [delete](https://docs.medusajs.com/references/js_sdk/admin/ReturnReason/methods/js_sdk.admin.ReturnReason.delete/index.html.md)
+- [list](https://docs.medusajs.com/references/js_sdk/admin/ReturnReason/methods/js_sdk.admin.ReturnReason.list/index.html.md)
+- [retrieve](https://docs.medusajs.com/references/js_sdk/admin/ReturnReason/methods/js_sdk.admin.ReturnReason.retrieve/index.html.md)
+- [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/ShippingOption/methods/js_sdk.admin.ShippingOption.create/index.html.md)
+- [list](https://docs.medusajs.com/references/js_sdk/admin/ShippingOption/methods/js_sdk.admin.ShippingOption.list/index.html.md)
+- [delete](https://docs.medusajs.com/references/js_sdk/admin/ShippingOption/methods/js_sdk.admin.ShippingOption.delete/index.html.md)
+- [retrieve](https://docs.medusajs.com/references/js_sdk/admin/ShippingOption/methods/js_sdk.admin.ShippingOption.retrieve/index.html.md)
+- [update](https://docs.medusajs.com/references/js_sdk/admin/ShippingOption/methods/js_sdk.admin.ShippingOption.update/index.html.md)
+- [addReturnItem](https://docs.medusajs.com/references/js_sdk/admin/Return/methods/js_sdk.admin.Return.addReturnItem/index.html.md)
 - [addReturnShipping](https://docs.medusajs.com/references/js_sdk/admin/Return/methods/js_sdk.admin.Return.addReturnShipping/index.html.md)
 - [cancel](https://docs.medusajs.com/references/js_sdk/admin/Return/methods/js_sdk.admin.Return.cancel/index.html.md)
-- [addReturnItem](https://docs.medusajs.com/references/js_sdk/admin/Return/methods/js_sdk.admin.Return.addReturnItem/index.html.md)
+- [updateRules](https://docs.medusajs.com/references/js_sdk/admin/ShippingOption/methods/js_sdk.admin.ShippingOption.updateRules/index.html.md)
 - [cancelRequest](https://docs.medusajs.com/references/js_sdk/admin/Return/methods/js_sdk.admin.Return.cancelRequest/index.html.md)
 - [cancelReceive](https://docs.medusajs.com/references/js_sdk/admin/Return/methods/js_sdk.admin.Return.cancelReceive/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)
-- [initiateRequest](https://docs.medusajs.com/references/js_sdk/admin/Return/methods/js_sdk.admin.Return.initiateRequest/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)
-- [removeDismissItem](https://docs.medusajs.com/references/js_sdk/admin/Return/methods/js_sdk.admin.Return.removeDismissItem/index.html.md)
 - [removeReceiveItem](https://docs.medusajs.com/references/js_sdk/admin/Return/methods/js_sdk.admin.Return.removeReceiveItem/index.html.md)
+- [removeDismissItem](https://docs.medusajs.com/references/js_sdk/admin/Return/methods/js_sdk.admin.Return.removeDismissItem/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)
-- [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)
-- [updateReturnItem](https://docs.medusajs.com/references/js_sdk/admin/Return/methods/js_sdk.admin.Return.updateReturnItem/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)
+- [updateDismissItem](https://docs.medusajs.com/references/js_sdk/admin/Return/methods/js_sdk.admin.Return.updateDismissItem/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/ReturnReason/methods/js_sdk.admin.ReturnReason.create/index.html.md)
-- [list](https://docs.medusajs.com/references/js_sdk/admin/ReturnReason/methods/js_sdk.admin.ReturnReason.list/index.html.md)
-- [delete](https://docs.medusajs.com/references/js_sdk/admin/ReturnReason/methods/js_sdk.admin.ReturnReason.delete/index.html.md)
-- [batchProducts](https://docs.medusajs.com/references/js_sdk/admin/SalesChannel/methods/js_sdk.admin.SalesChannel.batchProducts/index.html.md)
-- [update](https://docs.medusajs.com/references/js_sdk/admin/ReturnReason/methods/js_sdk.admin.ReturnReason.update/index.html.md)
-- [retrieve](https://docs.medusajs.com/references/js_sdk/admin/ReturnReason/methods/js_sdk.admin.ReturnReason.retrieve/index.html.md)
-- [delete](https://docs.medusajs.com/references/js_sdk/admin/SalesChannel/methods/js_sdk.admin.SalesChannel.delete/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)
-- [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)
-- [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)
-- [list](https://docs.medusajs.com/references/js_sdk/admin/Store/methods/js_sdk.admin.Store.list/index.html.md)
+- [create](https://docs.medusajs.com/references/js_sdk/admin/TaxRate/methods/js_sdk.admin.TaxRate.create/index.html.md)
+- [delete](https://docs.medusajs.com/references/js_sdk/admin/TaxRate/methods/js_sdk.admin.TaxRate.delete/index.html.md)
+- [retrieve](https://docs.medusajs.com/references/js_sdk/admin/TaxRate/methods/js_sdk.admin.TaxRate.retrieve/index.html.md)
+- [updateReturnItem](https://docs.medusajs.com/references/js_sdk/admin/Return/methods/js_sdk.admin.Return.updateReturnItem/index.html.md)
+- [list](https://docs.medusajs.com/references/js_sdk/admin/TaxRate/methods/js_sdk.admin.TaxRate.list/index.html.md)
+- [update](https://docs.medusajs.com/references/js_sdk/admin/TaxRate/methods/js_sdk.admin.TaxRate.update/index.html.md)
 - [update](https://docs.medusajs.com/references/js_sdk/admin/Store/methods/js_sdk.admin.Store.update/index.html.md)
 - [retrieve](https://docs.medusajs.com/references/js_sdk/admin/Store/methods/js_sdk.admin.Store.retrieve/index.html.md)
-- [create](https://docs.medusajs.com/references/js_sdk/admin/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)
-- [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)
-- [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/ShippingOption/methods/js_sdk.admin.ShippingOption.retrieve/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/ShippingProfile/methods/js_sdk.admin.ShippingProfile.create/index.html.md)
-- [update](https://docs.medusajs.com/references/js_sdk/admin/ShippingProfile/methods/js_sdk.admin.ShippingProfile.update/index.html.md)
+- [create](https://docs.medusajs.com/references/js_sdk/admin/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)
+- [list](https://docs.medusajs.com/references/js_sdk/admin/Store/methods/js_sdk.admin.Store.list/index.html.md)
+- [list](https://docs.medusajs.com/references/js_sdk/admin/TaxRegion/methods/js_sdk.admin.TaxRegion.list/index.html.md)
 - [delete](https://docs.medusajs.com/references/js_sdk/admin/ShippingProfile/methods/js_sdk.admin.ShippingProfile.delete/index.html.md)
-- [create](https://docs.medusajs.com/references/js_sdk/admin/StockLocation/methods/js_sdk.admin.StockLocation.create/index.html.md)
+- [create](https://docs.medusajs.com/references/js_sdk/admin/ShippingProfile/methods/js_sdk.admin.ShippingProfile.create/index.html.md)
+- [retrieve](https://docs.medusajs.com/references/js_sdk/admin/TaxRegion/methods/js_sdk.admin.TaxRegion.retrieve/index.html.md)
+- [list](https://docs.medusajs.com/references/js_sdk/admin/ShippingProfile/methods/js_sdk.admin.ShippingProfile.list/index.html.md)
+- [retrieve](https://docs.medusajs.com/references/js_sdk/admin/ShippingProfile/methods/js_sdk.admin.ShippingProfile.retrieve/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)
 - [list](https://docs.medusajs.com/references/js_sdk/admin/StockLocation/methods/js_sdk.admin.StockLocation.list/index.html.md)
+- [update](https://docs.medusajs.com/references/js_sdk/admin/ShippingProfile/methods/js_sdk.admin.ShippingProfile.update/index.html.md)
 - [update](https://docs.medusajs.com/references/js_sdk/admin/StockLocation/methods/js_sdk.admin.StockLocation.update/index.html.md)
-- [updateFulfillmentProviders](https://docs.medusajs.com/references/js_sdk/admin/StockLocation/methods/js_sdk.admin.StockLocation.updateFulfillmentProviders/index.html.md)
 - [retrieve](https://docs.medusajs.com/references/js_sdk/admin/StockLocation/methods/js_sdk.admin.StockLocation.retrieve/index.html.md)
+- [create](https://docs.medusajs.com/references/js_sdk/admin/StockLocation/methods/js_sdk.admin.StockLocation.create/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/ShippingProfile/methods/js_sdk.admin.ShippingProfile.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/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)
-- [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/TaxRate/methods/js_sdk.admin.TaxRate.update/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/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)
+- [delete](https://docs.medusajs.com/references/js_sdk/admin/Upload/methods/js_sdk.admin.Upload.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/Upload/methods/js_sdk.admin.Upload.create/index.html.md)
 - [list](https://docs.medusajs.com/references/js_sdk/admin/User/methods/js_sdk.admin.User.list/index.html.md)
 - [delete](https://docs.medusajs.com/references/js_sdk/admin/User/methods/js_sdk.admin.User.delete/index.html.md)
 - [me](https://docs.medusajs.com/references/js_sdk/admin/User/methods/js_sdk.admin.User.me/index.html.md)
 - [retrieve](https://docs.medusajs.com/references/js_sdk/admin/User/methods/js_sdk.admin.User.retrieve/index.html.md)
-- [list](https://docs.medusajs.com/references/js_sdk/admin/TaxRegion/methods/js_sdk.admin.TaxRegion.list/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/Upload/methods/js_sdk.admin.Upload.delete/index.html.md)
-- [create](https://docs.medusajs.com/references/js_sdk/admin/Upload/methods/js_sdk.admin.Upload.create/index.html.md)
-- [retrieve](https://docs.medusajs.com/references/js_sdk/admin/Upload/methods/js_sdk.admin.Upload.retrieve/index.html.md)
 
 
 ## JS SDK Auth
 
-- [callback](https://docs.medusajs.com/references/js-sdk/auth/callback/index.html.md)
-- [login](https://docs.medusajs.com/references/js-sdk/auth/login/index.html.md)
 - [logout](https://docs.medusajs.com/references/js-sdk/auth/logout/index.html.md)
-- [refresh](https://docs.medusajs.com/references/js-sdk/auth/refresh/index.html.md)
 - [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)
 - [updateProvider](https://docs.medusajs.com/references/js-sdk/auth/updateProvider/index.html.md)
+- [callback](https://docs.medusajs.com/references/js-sdk/auth/callback/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)
 
 
 ## JS SDK Store
 
 - [cart](https://docs.medusajs.com/references/js-sdk/store/cart/index.html.md)
-- [customer](https://docs.medusajs.com/references/js-sdk/store/customer/index.html.md)
-- [collection](https://docs.medusajs.com/references/js-sdk/store/collection/index.html.md)
 - [fulfillment](https://docs.medusajs.com/references/js-sdk/store/fulfillment/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)
+- [collection](https://docs.medusajs.com/references/js-sdk/store/collection/index.html.md)
 - [region](https://docs.medusajs.com/references/js-sdk/store/region/index.html.md)
+- [customer](https://docs.medusajs.com/references/js-sdk/store/customer/index.html.md)
 - [category](https://docs.medusajs.com/references/js-sdk/store/category/index.html.md)
 
 
@@ -53457,143 +53604,63 @@ 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.
 
 
-# Two Column Layout - Admin Components
+# Container - Admin Components
 
-The Medusa Admin has pages with two columns of content.
+The Medusa Admin wraps each section of a page in a container.
 
-This doesn't include the sidebar, only the main content.
+![Example of a container in the Medusa Admin](https://res.cloudinary.com/dza7lstvk/image/upload/v1728287102/Medusa%20Resources/container_soenir.png)
 
-![An example of an admin page with two columns](https://res.cloudinary.com/dza7lstvk/image/upload/v1728286690/Medusa%20Resources/two-column_sdnkg0.png)
+To create a 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:
 
-To create a layout that you can use in UI routes to support two columns of content, create the component `src/admin/layouts/two-column.tsx` with the following content:
+```tsx
+import { 
+  Container as UiContainer,
+  clx,
+} from "@medusajs/ui"
 
-```tsx title="src/admin/layouts/two-column.tsx"
-export type TwoColumnLayoutProps = {
-  firstCol: React.ReactNode
-  secondCol: React.ReactNode
-}
+type ContainerProps = React.ComponentProps<typeof UiContainer>
 
-export const TwoColumnLayout = ({ 
-  firstCol,
-  secondCol,
-}: TwoColumnLayoutProps) => {
+export const Container = (props: ContainerProps) => {
   return (
-    <div className="flex flex-col gap-x-4 gap-y-3 xl:flex-row xl:items-start">
-      <div className="flex w-full flex-col gap-y-3">
-          {firstCol}
-        </div>
-        <div className="flex w-full max-w-[100%] flex-col gap-y-3 xl:mt-0 xl:max-w-[440px]">
-          {secondCol}
-        </div>
-    </div>
+    <UiContainer {...props} className={clx(
+      "divide-y p-0",
+      props.className
+    )} />
   )
 }
 ```
 
-The `TwoColumnLayout` accepts two props:
-
-- `firstCol` indicating the content of the first column.
-- `secondCol` indicating the content of the second column.
+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 the `TwoColumnLayout` component in your UI routes that have a single column. For example:
+Use that `Container` component in any widget or UI route.
 
-```tsx title="src/admin/routes/custom/page.tsx" highlights={[["9"]]}
-import { defineRouteConfig } from "@medusajs/admin-sdk"
-import { ChatBubbleLeftRight } from "@medusajs/icons"
-import { Container } from "../../components/container"
-import { Header } from "../../components/header"
-import { TwoColumnLayout } from "../../layouts/two-column"
+For example, create the widget `src/admin/widgets/product-widget.tsx` with the following content:
 
-const CustomPage = () => {
+```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 (
-    <TwoColumnLayout
-      firstCol={
-        <Container>
-          <Header title="First Column" />
-        </Container>
-      }
-      secondCol={
-        <Container>
-          <Header title="Second Column" />
-        </Container>
-      }
-    />
+    <Container>
+      <Header title="Product Widget" />
+    </Container>
   )
 }
 
-export const config = defineRouteConfig({
-  label: "Custom",
-  icon: ChatBubbleLeftRight,
+export const config = defineWidgetConfig({
+  zone: "product.details.before",
 })
 
-export default CustomPage
+export default ProductWidget
 ```
 
-This UI route also uses [Container](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/admin-components/components/container/index.html.md) and [Header]() custom components.
-
-
-# Single Column Layout - Admin Components
-
-The Medusa Admin has pages with a single column of content.
-
-This doesn't include the sidebar, only the main content.
-
-![An example of an admin page with a single column](https://res.cloudinary.com/dza7lstvk/image/upload/v1728286605/Medusa%20Resources/single-column.png)
-
-To create a layout that you can use in UI routes to support one column of content, create the component `src/admin/layouts/single-column.tsx` with the following content:
-
-```tsx title="src/admin/layouts/single-column.tsx"
-export type SingleColumnLayoutProps = {
-  children: React.ReactNode
-}
-
-export const SingleColumnLayout = ({ children }: SingleColumnLayoutProps) => {
-  return (
-    <div className="flex flex-col gap-y-3">
-      {children}
-    </div>
-  )
-}
-```
-
-The `SingleColumnLayout` accepts the content in the `children` props.
-
-***
-
-## Example
-
-Use the `SingleColumnLayout` component in your UI routes that have a single column. For example:
-
-```tsx title="src/admin/routes/custom/page.tsx" highlights={[["9"]]}
-import { defineRouteConfig } from "@medusajs/admin-sdk"
-import { ChatBubbleLeftRight } from "@medusajs/icons"
-import { Container } from "../../components/container"
-import { SingleColumnLayout } from "../../layouts/single-column"
-import { Header } from "../../components/header"
-
-const CustomPage = () => {
-  return (
-    <SingleColumnLayout>
-      <Container>
-        <Header title="Custom Page" />
-      </Container>
-    </SingleColumnLayout>
-  )
-}
-
-export const config = defineRouteConfig({
-  label: "Custom",
-  icon: ChatBubbleLeftRight,
-})
-
-export default CustomPage
-```
-
-This UI route also uses a [Container](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/admin-components/components/container/index.html.md) and a [Header]() custom components.
+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
@@ -54308,53 +54375,222 @@ export default CustomPage
 ```
 
 
-# Container - Admin Components
+# JSON View - Admin Components
 
-The Medusa Admin wraps each section of a page in a container.
+Detail pages in the Medusa Admin show a JSON section to view the current page's details in JSON format.
 
-![Example of a container in the Medusa Admin](https://res.cloudinary.com/dza7lstvk/image/upload/v1728287102/Medusa%20Resources/container_soenir.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 container styling in your widgets or UI routes, create the file `src/admin/components/container.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
-import { 
-  Container as UiContainer,
-  clx,
+```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"
 
-type ContainerProps = React.ComponentProps<typeof UiContainer>
+type JsonViewSectionProps = {
+  data: object
+  title?: string
+}
+
+export const JsonViewSection = ({ data }: JsonViewSectionProps) => {
+  const numberOfKeys = Object.keys(data).length
 
-export const Container = (props: ContainerProps) => {
   return (
-    <UiContainer {...props} className={clx(
-      "divide-y p-0",
-      props.className
-    )} />
+    <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)
+    }
+
+    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 `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.
+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 `JsonViewSection` accepts a `data` prop, which is the data to show as a JSON object in the drawer.
 
 ***
 
 ## Example
 
-Use that `Container` 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" />
-    </Container>
-  )
+  return <JsonViewSection data={{
+    name: "John",
+  }} />
 }
 
 export const config = defineWidgetConfig({
@@ -54364,7 +54600,7 @@ export const config = defineWidgetConfig({
 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.
+This shows the JSON section at the top of the product page, passing it the object `{ name: "John" }`.
 
 
 # Header - Admin Components
@@ -55086,234 +55322,6 @@ 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.
 
 
-# JSON View - Admin Components
-
-Detail pages in the Medusa Admin show a JSON section to view the current page's details in JSON format.
-
-![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 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/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"
-
-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)
-    }
-
-    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 `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 `JsonViewSection` accepts a `data` prop, which is the data to show as a JSON object in the drawer.
-
-***
-
-## Example
-
-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 { JsonViewSection } from "../components/json-view-section"
-
-const ProductWidget = () => {
-  return <JsonViewSection data={{
-    name: "John",
-  }} />
-}
-
-export const config = defineWidgetConfig({
-  zone: "product.details.before",
-})
-
-export default ProductWidget
-```
-
-This shows the JSON section at the top of the product page, passing it the object `{ name: "John" }`.
-
-
 # Section Row - Admin Components
 
 The Medusa Admin often shows information in rows of label-values, such as when showing a product's details.
@@ -55696,6 +55704,145 @@ If `data` isn't `undefined`, you display the `Table` component passing it the fo
 To test it out, log into the Medusa Admin and open `http://localhost:9000/app/custom`. You'll find a table of products with pagination.
 
 
+# Single Column Layout - Admin Components
+
+The Medusa Admin has pages with a single column of content.
+
+This doesn't include the sidebar, only the main content.
+
+![An example of an admin page with a single column](https://res.cloudinary.com/dza7lstvk/image/upload/v1728286605/Medusa%20Resources/single-column.png)
+
+To create a layout that you can use in UI routes to support one column of content, create the component `src/admin/layouts/single-column.tsx` with the following content:
+
+```tsx title="src/admin/layouts/single-column.tsx"
+export type SingleColumnLayoutProps = {
+  children: React.ReactNode
+}
+
+export const SingleColumnLayout = ({ children }: SingleColumnLayoutProps) => {
+  return (
+    <div className="flex flex-col gap-y-3">
+      {children}
+    </div>
+  )
+}
+```
+
+The `SingleColumnLayout` accepts the content in the `children` props.
+
+***
+
+## Example
+
+Use the `SingleColumnLayout` component in your UI routes that have a single column. For example:
+
+```tsx title="src/admin/routes/custom/page.tsx" highlights={[["9"]]}
+import { defineRouteConfig } from "@medusajs/admin-sdk"
+import { ChatBubbleLeftRight } from "@medusajs/icons"
+import { Container } from "../../components/container"
+import { SingleColumnLayout } from "../../layouts/single-column"
+import { Header } from "../../components/header"
+
+const CustomPage = () => {
+  return (
+    <SingleColumnLayout>
+      <Container>
+        <Header title="Custom Page" />
+      </Container>
+    </SingleColumnLayout>
+  )
+}
+
+export const config = defineRouteConfig({
+  label: "Custom",
+  icon: ChatBubbleLeftRight,
+})
+
+export default CustomPage
+```
+
+This UI route also uses a [Container](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/admin-components/components/container/index.html.md) and a [Header]() custom components.
+
+
+# Two Column Layout - Admin Components
+
+The Medusa Admin has pages with two columns of content.
+
+This doesn't include the sidebar, only the main content.
+
+![An example of an admin page with two columns](https://res.cloudinary.com/dza7lstvk/image/upload/v1728286690/Medusa%20Resources/two-column_sdnkg0.png)
+
+To create a layout that you can use in UI routes to support two columns of content, create the component `src/admin/layouts/two-column.tsx` with the following content:
+
+```tsx title="src/admin/layouts/two-column.tsx"
+export type TwoColumnLayoutProps = {
+  firstCol: React.ReactNode
+  secondCol: React.ReactNode
+}
+
+export const TwoColumnLayout = ({ 
+  firstCol,
+  secondCol,
+}: TwoColumnLayoutProps) => {
+  return (
+    <div className="flex flex-col gap-x-4 gap-y-3 xl:flex-row xl:items-start">
+      <div className="flex w-full flex-col gap-y-3">
+          {firstCol}
+        </div>
+        <div className="flex w-full max-w-[100%] flex-col gap-y-3 xl:mt-0 xl:max-w-[440px]">
+          {secondCol}
+        </div>
+    </div>
+  )
+}
+```
+
+The `TwoColumnLayout` accepts two props:
+
+- `firstCol` indicating the content of the first column.
+- `secondCol` indicating the content of the second column.
+
+***
+
+## Example
+
+Use the `TwoColumnLayout` component in your UI routes that have a single column. For example:
+
+```tsx title="src/admin/routes/custom/page.tsx" highlights={[["9"]]}
+import { defineRouteConfig } from "@medusajs/admin-sdk"
+import { ChatBubbleLeftRight } from "@medusajs/icons"
+import { Container } from "../../components/container"
+import { Header } from "../../components/header"
+import { TwoColumnLayout } from "../../layouts/two-column"
+
+const CustomPage = () => {
+  return (
+    <TwoColumnLayout
+      firstCol={
+        <Container>
+          <Header title="First Column" />
+        </Container>
+      }
+      secondCol={
+        <Container>
+          <Header title="Second Column" />
+        </Container>
+      }
+    />
+  )
+}
+
+export const config = defineRouteConfig({
+  label: "Custom",
+  icon: ChatBubbleLeftRight,
+})
+
+export default CustomPage
+```
+
+This UI route also uses [Container](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/admin-components/components/container/index.html.md) and [Header]() custom components.
+
+
 # Service Factory Reference
 
 This section of the documentation provides a reference of the methods generated for services extending the service factory (`MedusaService`), and how to use them.
@@ -55723,6 +55870,171 @@ Some examples of method names:
 The reference uses only the operation name to refer to the method.
 
 
+# create Method - Service Factory Reference
+
+This method creates one or more records of the data model.
+
+## Create One Record
+
+```ts
+const post = await postModuleService.createPosts({
+  name: "My Post",
+  published_at: new Date(),
+  metadata: {
+     external_id: "1234",
+  },
+})
+```
+
+If an object is passed of the method, an object of the created record is also returned.
+
+***
+
+## Create Multiple Records
+
+```ts
+const posts = await postModuleService.createPosts([
+  {
+    name: "My Post",
+    published_at: new Date(),
+  },
+  {
+    name: "My Other Post",
+    published_at: new Date(),
+  },
+])
+```
+
+If an array is passed of the method, an array of the created records is also returned.
+
+
+# delete Method - Service Factory Reference
+
+This method deletes one or more records.
+
+## Delete One Record
+
+```ts
+await postModuleService.deletePosts("123")
+```
+
+To delete one record, pass its ID as a parameter of the method.
+
+***
+
+## Delete Multiple Records
+
+```ts
+await postModuleService.deletePosts([
+  "123",
+  "321",
+])
+```
+
+To delete multiple records, pass an array of IDs as a parameter of the method.
+
+***
+
+## Delete Records Matching Filters
+
+```ts
+await postModuleService.deletePosts({
+  name: "My Post",
+})
+```
+
+To delete records matching a set of filters, pass an object of filters as a parameter.
+
+Learn more about accepted filters in [this documentation](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/service-factory-reference/tips/filtering/index.html.md).
+
+
+# restore Method - Service Factory Reference
+
+This method restores one or more records of the data model that were [soft-deleted](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/service-factory-reference/methods/soft-delete/index.html.md).
+
+## Restore One Record
+
+```ts
+const restoredPosts = await postModuleService.restorePosts("123")
+```
+
+### Parameters
+
+To restore one record, pass its ID as a parameter of the method.
+
+### Returns
+
+The method returns an object, whose keys are of the format `{camel_case_data_model_name}_id`, and their values are arrays of restored records' IDs.
+
+For example, the returned object of the above example is:
+
+```ts
+restoredPosts = {
+  post_id: ["123"],
+}
+```
+
+***
+
+## Restore Multiple Records
+
+```ts
+const restoredPosts = await postModuleService.restorePosts([
+  "123",
+  "321",
+])
+```
+
+### Parameters
+
+To restore multiple records, pass an array of IDs as a parameter of the method.
+
+### Returns
+
+The method returns an object, whose keys are of the format `{camel_case_data_model_name}_id`, and their values are arrays of restored records' IDs.
+
+For example, the returned object of the above example is:
+
+```ts
+restoredPosts = {
+  post_id: [
+    "123",
+    "321",
+  ],
+}
+```
+
+***
+
+## Restore Records Matching Filters
+
+```ts
+const restoredPosts = await postModuleService.restorePosts({
+  name: "My Post",
+})
+```
+
+### Parameters
+
+To restore records matching a set of filters, pass an object of fitlers as a parameter of the method.
+
+Learn more about accepted filters in [this documentation](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/service-factory-reference/tips/filtering/index.html.md).
+
+### Returns
+
+The method returns an object, whose keys are of the format `{camel_case_data_model_name}_id`, and their values are arrays of restored records' IDs.
+
+For example, the returned object of the above example is:
+
+```ts
+restoredPosts = {
+  post_id: [
+    "123",
+  ],
+}
+```
+
+
 # list Method - Service Factory Reference
 
 This method retrieves a list of records.
@@ -55841,44 +56153,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.
 
 
-# create Method - Service Factory Reference
-
-This method creates one or more records of the data model.
-
-## Create One Record
-
-```ts
-const post = await postModuleService.createPosts({
-  name: "My Post",
-  published_at: new Date(),
-  metadata: {
-     external_id: "1234",
-  },
-})
-```
-
-If an object is passed of the method, an object of the created record is also returned.
-
-***
-
-## Create Multiple Records
-
-```ts
-const posts = await postModuleService.createPosts([
-  {
-    name: "My Post",
-    published_at: new Date(),
-  },
-  {
-    name: "My Other Post",
-    published_at: new Date(),
-  },
-])
-```
-
-If an array is passed of the method, an array of the created records is also returned.
-
-
 # listAndCount Method - Service Factory Reference
 
 This method retrieves a list of records with the total count.
@@ -56015,46 +56289,6 @@ The method returns an array with two items:
 2. The second is the total count of records.
 
 
-# delete Method - Service Factory Reference
-
-This method deletes one or more records.
-
-## Delete One Record
-
-```ts
-await postModuleService.deletePosts("123")
-```
-
-To delete one record, pass its ID as a parameter of the method.
-
-***
-
-## Delete Multiple Records
-
-```ts
-await postModuleService.deletePosts([
-  "123",
-  "321",
-])
-```
-
-To delete multiple records, pass an array of IDs as a parameter of the method.
-
-***
-
-## Delete Records Matching Filters
-
-```ts
-await postModuleService.deletePosts({
-  name: "My Post",
-})
-```
-
-To delete records matching a set of filters, pass an object of filters as a parameter.
-
-Learn more about accepted filters in [this documentation](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/service-factory-reference/tips/filtering/index.html.md).
-
-
 # retrieve Method - Service Factory Reference
 
 This method retrieves one record of the data model by its ID.
@@ -56112,180 +56346,6 @@ By default, all of the record's properties are retrieved. To select specific one
 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).
-
-## Restore One Record
-
-```ts
-const restoredPosts = await postModuleService.restorePosts("123")
-```
-
-### Parameters
-
-To restore one record, pass its ID as a parameter of the method.
-
-### Returns
-
-The method returns an object, whose keys are of the format `{camel_case_data_model_name}_id`, and their values are arrays of restored records' IDs.
-
-For example, the returned object of the above example is:
-
-```ts
-restoredPosts = {
-  post_id: ["123"],
-}
-```
-
-***
-
-## Restore Multiple Records
-
-```ts
-const restoredPosts = await postModuleService.restorePosts([
-  "123",
-  "321",
-])
-```
-
-### Parameters
-
-To restore multiple records, pass an array of IDs as a parameter of the method.
-
-### Returns
-
-The method returns an object, whose keys are of the format `{camel_case_data_model_name}_id`, and their values are arrays of restored records' IDs.
-
-For example, the returned object of the above example is:
-
-```ts
-restoredPosts = {
-  post_id: [
-    "123",
-    "321",
-  ],
-}
-```
-
-***
-
-## Restore Records Matching Filters
-
-```ts
-const restoredPosts = await postModuleService.restorePosts({
-  name: "My Post",
-})
-```
-
-### Parameters
-
-To restore records matching a set of filters, pass an object of fitlers as a parameter of the method.
-
-Learn more about accepted filters in [this documentation](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/service-factory-reference/tips/filtering/index.html.md).
-
-### Returns
-
-The method returns an object, whose keys are of the format `{camel_case_data_model_name}_id`, and their values are arrays of restored records' IDs.
-
-For example, the returned object of the above example is:
-
-```ts
-restoredPosts = {
-  post_id: [
-    "123",
-  ],
-}
-```
-
-
-# softDelete Method - Service Factory Reference
-
-This method soft deletes one or more records of the data model.
-
-## Soft Delete One Record
-
-```ts
-const deletedPosts = await postModuleService.softDeletePosts(
-  "123"
-)
-```
-
-### Parameters
-
-To soft delete a record, pass its ID as a parameter of the method.
-
-### Returns
-
-The method returns an object, whose keys are of the format `{camel_case_data_model_name}_id`, and their values are arrays of soft-deleted records' IDs.
-
-For example, the returned object of the above example is:
-
-```ts
-deletedPosts = {
-  post_id: ["123"],
-}
-```
-
-***
-
-## Soft Delete Multiple Records
-
-```ts
-const deletedPosts = await postModuleService.softDeletePosts([
-  "123",
-  "321",
-])
-```
-
-### Parameters
-
-To soft delete multiple records, pass an array of IDs as a parameter of the method.
-
-### Returns
-
-The method returns an object, whose keys are of the format `{camel_case_data_model_name}_id`, and their values are arrays of soft-deleted records' IDs.
-
-For example, the returned object of the above example is:
-
-```ts
-deletedPosts = {
-  post_id: [
-    "123",
-    "321",
-  ],
-}
-```
-
-***
-
-## Soft Delete Records Matching Filters
-
-```ts
-const deletedPosts = await postModuleService.softDeletePosts({
-  name: "My Post",
-})
-```
-
-### Parameters
-
-To soft delete records matching a set of filters, pass an object of filters as a parameter.
-
-Learn more about accepted filters in [this documentation](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/service-factory-reference/tips/filtering/index.html.md).
-
-### Returns
-
-The method returns an object, whose keys are of the format `{camel_case_data_model_name}_id`, and their values are arrays of soft-deleted records' IDs.
-
-For example, the returned object of the above example is:
-
-```ts
-deletedPosts = {
-  post_id: ["123"],
-}
-```
-
-
 # update Method - Service Factory Reference
 
 This method updates one or more records of the data model.
@@ -56409,6 +56469,93 @@ Learn more about accepted filters in [this documentation](https://docs.medusajs.
 The method returns an array of objects of updated records.
 
 
+# softDelete Method - Service Factory Reference
+
+This method soft deletes one or more records of the data model.
+
+## Soft Delete One Record
+
+```ts
+const deletedPosts = await postModuleService.softDeletePosts(
+  "123"
+)
+```
+
+### Parameters
+
+To soft delete a record, pass its ID as a parameter of the method.
+
+### Returns
+
+The method returns an object, whose keys are of the format `{camel_case_data_model_name}_id`, and their values are arrays of soft-deleted records' IDs.
+
+For example, the returned object of the above example is:
+
+```ts
+deletedPosts = {
+  post_id: ["123"],
+}
+```
+
+***
+
+## Soft Delete Multiple Records
+
+```ts
+const deletedPosts = await postModuleService.softDeletePosts([
+  "123",
+  "321",
+])
+```
+
+### Parameters
+
+To soft delete multiple records, pass an array of IDs as a parameter of the method.
+
+### Returns
+
+The method returns an object, whose keys are of the format `{camel_case_data_model_name}_id`, and their values are arrays of soft-deleted records' IDs.
+
+For example, the returned object of the above example is:
+
+```ts
+deletedPosts = {
+  post_id: [
+    "123",
+    "321",
+  ],
+}
+```
+
+***
+
+## Soft Delete Records Matching Filters
+
+```ts
+const deletedPosts = await postModuleService.softDeletePosts({
+  name: "My Post",
+})
+```
+
+### Parameters
+
+To soft delete records matching a set of filters, pass an object of filters as a parameter.
+
+Learn more about accepted filters in [this documentation](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/service-factory-reference/tips/filtering/index.html.md).
+
+### Returns
+
+The method returns an object, whose keys are of the format `{camel_case_data_model_name}_id`, and their values are arrays of soft-deleted records' IDs.
+
+For example, the returned object of the above example is:
+
+```ts
+deletedPosts = {
+  post_id: ["123"],
+}
+```
+
+
 # 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.
@@ -56666,6 +56813,35 @@ In the example above, posts are retrieved if they meet either of the following c
 
 By combining `and` and `or` conditions, you can create complex filters to retrieve records that meet specific criteria.
 
+***
+
+## Supported Filter Operators List
+
+The following operators are supported by the service factory filtering mechanism:
+
+|Operator|Description|
+|---|---|
+|Comparison Operators|
+|\`$eq\`|Matches values that are equal to a specified value.|
+|\`$ne\`|Matches values that are not equal to a specified value.|
+|\`$in\`|Matches any of the values specified in an array.|
+|\`$nin\`|Matches none of the values specified in an array.|
+|\`$like\`|Matches values containing a specified substring.|
+|\`$lt\`|Matches values that are less than a specified value.|
+|\`$lte\`|Matches values that are less than or equal to a specified value.|
+|\`$gt\`|Matches values that are greater than a specified value.|
+|\`$gte\`|Matches values that are greater than or equal to a specified value.|
+|\`$re\`|Matches values that match a specified regular expression.|
+|\`$ilike\`|Matches values containing a specified substring, case-insensitive.|
+|\`$fulltext\`|Performs a full-text search on a text property.|
+|\`$overlap\`|Matches values that have overlapping elements with the specified array.|
+|\`$contains\`|Performs an |
+|\`$contained\`|Performs an |
+|Logical Operators|
+|\`$and\`|Joins two or more conditions with a logical AND.|
+|\`$or\`|Joins two or more conditions with a logical OR.|
+|\`$not\`|Inverts the logic of a condition. For example, |
+
 
 
 
@@ -56768,6 +56944,7 @@ Download this reference as an OpenApi YAML file. You can import this file to too
 - [POST /admin/draft-orders/{id}/edit/request](https://docs.medusajs.com/api/admin#draft-orders_postdraftordersideditrequest)
 - [POST /admin/draft-orders/{id}/edit/shipping-methods](https://docs.medusajs.com/api/admin#draft-orders_postdraftordersideditshippingmethods)
 - [POST /admin/draft-orders/{id}/edit/shipping-methods/method/{method_id}](https://docs.medusajs.com/api/admin#draft-orders_postdraftordersideditshippingmethodsmethodmethod_id)
+- [DELETE /admin/draft-orders/{id}/edit/shipping-methods/method/{method_id}](https://docs.medusajs.com/api/admin#draft-orders_deletedraftordersideditshippingmethodsmethodmethod_id)
 - [POST /admin/draft-orders/{id}/edit/shipping-methods/{action_id}](https://docs.medusajs.com/api/admin#draft-orders_postdraftordersideditshippingmethodsaction_id)
 - [DELETE /admin/draft-orders/{id}/edit/shipping-methods/{action_id}](https://docs.medusajs.com/api/admin#draft-orders_deletedraftordersideditshippingmethodsaction_id)
 - [GET /admin/exchanges](https://docs.medusajs.com/api/admin#exchanges_getexchanges)
@@ -57125,125 +57302,6 @@ How to install and setup Medusa UI.
 
 
 
-# Medusa Admin Extension
-
-How to install and use Medusa UI for building Admin extensions.
-
-## Installation
-
-***
-
-The `@medusajs/ui` package is a already installed as a dependency of the `@medusajs/admin` package. Due to this you can simply import the package and use it in your local Admin extensions.
-
-If you are building a Admin extension as part of a Medusa plugin, you can install the package as a dependency of your plugin.
-
-```bash
-npm install @medusajs/ui
-```
-
-## Configuration
-
-***
-
-The configuration of the UI package is handled by the `@medusajs/admin` package. Therefore, you do not need to any additional configuration to use the UI package in your Admin extensions.
-
-
-# Standalone Project
-
-How to install and use Medusa UI in a standalone project.
-
-## Installation
-
-***
-
-Medusa UI is a React UI library and while it's intended for usage within Medusa projects, it can also be used in any React project.
-
-### Install Medusa UI
-
-Install the React UI library with the following command:
-
-```bash
-npm install @medusajs/ui
-```
-
-### Configuring Tailwind CSS
-
-The components are styled using Tailwind CSS, and in order to use them, you will need to install Tailwind CSS in your project as well.
-For more information on how to install Tailwind CSS, please refer to the [Tailwind CSS documentation](https://tailwindcss.com/docs/installation).
-
-All of the classes used for Medusa UI are shipped as a Tailwind CSS customization.
-You can install it with the following command:
-
-```bash
-npm install @medusajs/ui-preset
-```
-
-After you have installed Tailwind CSS and the Medusa UI preset, you need to add the following to your `tailwind.config.js`file:
-
-```tsx
-module.exports = {
-  presets: [require("@medusajs/ui-preset")],
-  // ...
-}
-```
-
-In order for the styles to be applied correctly to the components, you will also need to ensure that
-`@medusajs/ui` is included in the content field of your `tailwind.config.js` file:
-
-```tsx
-module.exports = {
-  content: [
-    // ...
-    "./node_modules/@medusajs/ui/dist/**/*.{js,jsx,ts,tsx}",
-  ],
-  // ...
-}
-```
-
-If you are working within a monorepo, you may need to add the path to the `@medusajs/ui` package in your `tailwind.config.js` like so:
-
-```tsx
-const path = require("path")
-
-const uiPath = path.resolve(
-  require.resolve("@medusajs/ui"),
-  "../..",
-  "\*_/_.{js,jsx,ts,tsx}"
-)
-
-module.exports = {
-  content: [
-    // ...
-    uiPath,
-  ],
-  // ...
-}
-
-```
-
-## Start building
-
-***
-
-You are now ready to start building your application with Medusa UI. You can import the components like so:
-
-```tsx
-import { Button, Drawer } from "@medusajs/ui"
-```
-
-## Updating UI Packages
-
-***
-
-Medusa's design-system packages, including `@medusajs/ui`, `@medusajs/ui-preset`, and `@medusajs/ui-icons`, are versioned independently. However, they're still part of the latest Medusa release. So, you can browse the [release notes](https://github.com/medusajs/medusa/releases) to see if there are any breaking changes to these packages.
-
-To update these packages, update their version in your `package.json` file and re-install dependencies. For example:
-
-```bash
-npm install @medusajs/ui
-```
-
-
 # Alert
 
 A component for displaying important messages.
@@ -63665,6 +63723,125 @@ 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.
 
 
+# Medusa Admin Extension
+
+How to install and use Medusa UI for building Admin extensions.
+
+## Installation
+
+***
+
+The `@medusajs/ui` package is a already installed as a dependency of the `@medusajs/admin` package. Due to this you can simply import the package and use it in your local Admin extensions.
+
+If you are building a Admin extension as part of a Medusa plugin, you can install the package as a dependency of your plugin.
+
+```bash
+npm install @medusajs/ui
+```
+
+## Configuration
+
+***
+
+The configuration of the UI package is handled by the `@medusajs/admin` package. Therefore, you do not need to any additional configuration to use the UI package in your Admin extensions.
+
+
+# Standalone Project
+
+How to install and use Medusa UI in a standalone project.
+
+## Installation
+
+***
+
+Medusa UI is a React UI library and while it's intended for usage within Medusa projects, it can also be used in any React project.
+
+### Install Medusa UI
+
+Install the React UI library with the following command:
+
+```bash
+npm install @medusajs/ui
+```
+
+### Configuring Tailwind CSS
+
+The components are styled using Tailwind CSS, and in order to use them, you will need to install Tailwind CSS in your project as well.
+For more information on how to install Tailwind CSS, please refer to the [Tailwind CSS documentation](https://tailwindcss.com/docs/installation).
+
+All of the classes used for Medusa UI are shipped as a Tailwind CSS customization.
+You can install it with the following command:
+
+```bash
+npm install @medusajs/ui-preset
+```
+
+After you have installed Tailwind CSS and the Medusa UI preset, you need to add the following to your `tailwind.config.js`file:
+
+```tsx
+module.exports = {
+  presets: [require("@medusajs/ui-preset")],
+  // ...
+}
+```
+
+In order for the styles to be applied correctly to the components, you will also need to ensure that
+`@medusajs/ui` is included in the content field of your `tailwind.config.js` file:
+
+```tsx
+module.exports = {
+  content: [
+    // ...
+    "./node_modules/@medusajs/ui/dist/**/*.{js,jsx,ts,tsx}",
+  ],
+  // ...
+}
+```
+
+If you are working within a monorepo, you may need to add the path to the `@medusajs/ui` package in your `tailwind.config.js` like so:
+
+```tsx
+const path = require("path")
+
+const uiPath = path.resolve(
+  require.resolve("@medusajs/ui"),
+  "../..",
+  "\*_/_.{js,jsx,ts,tsx}"
+)
+
+module.exports = {
+  content: [
+    // ...
+    uiPath,
+  ],
+  // ...
+}
+
+```
+
+## Start building
+
+***
+
+You are now ready to start building your application with Medusa UI. You can import the components like so:
+
+```tsx
+import { Button, Drawer } from "@medusajs/ui"
+```
+
+## Updating UI Packages
+
+***
+
+Medusa's design-system packages, including `@medusajs/ui`, `@medusajs/ui-preset`, and `@medusajs/ui-icons`, are versioned independently. However, they're still part of the latest Medusa release. So, you can browse the [release notes](https://github.com/medusajs/medusa/releases) to see if there are any breaking changes to these packages.
+
+To update these packages, update their version in your `package.json` file and re-install dependencies. For example:
+
+```bash
+npm install @medusajs/ui
+```
+
+
 # clx
 
 Utility function for working with classNames.
diff --git a/www/apps/resources/app/data-model-repository-reference/methods/create/page.mdx b/www/apps/resources/app/data-model-repository-reference/methods/create/page.mdx
new file mode 100644
index 0000000000..9633495a16
--- /dev/null
+++ b/www/apps/resources/app/data-model-repository-reference/methods/create/page.mdx
@@ -0,0 +1,85 @@
+---
+sidebar_label: "create"
+---
+
+import { TypeList } from "docs-ui"
+
+export const metadata = {
+  title: `create Method - Data Model Repository Reference`,
+}
+
+# {metadata.title}
+
+The `create` method of a data model repository creates one or more records of the data model.
+
+<Note>
+
+This reference assumes you've already resolved the data model repository, as explained in the [Data Model Repository Reference](../../page.mdx) documentation.
+
+</Note>
+
+## `create` Parameters
+
+<TypeList
+  types={[
+    {
+      type: "`array`",
+      name: "data",
+      description: "An array of objects to create. The shape of the objects is the same as the shape of the data model.",
+      required: true,
+    }
+  ]}
+  sectionTitle="create Parameters"
+/>
+
+---
+
+## Create Records
+
+```ts
+import { 
+  InjectTransactionManager,
+  MedusaContext,
+  MedusaService,
+} from "@medusajs/framework/utils"
+import { Context, InferTypeOf, DAL } from "@medusajs/framework/types"
+import { EntityManager } from "@mikro-orm/knex"
+import Post from "./models/post"
+
+class BlogModuleService extends MedusaService({
+  Post,
+}){
+  // ...
+  @InjectTransactionManager()
+  protected async doSomething_(
+    id: string,
+    @MedusaContext() sharedContext?: Context<EntityManager>
+  ): Promise<any> {
+    const posts = await this.postRepository_.create([
+      {
+        title: "My Post",
+        content: "This is a post",
+        author_id: "01JSGRGQ8S61SR0Y7VCRV8FH66",
+      }
+    ])
+
+    return posts
+  }
+
+  @InjectManager()
+  async doSomething(
+    id: string,
+    @MedusaContext() sharedContext?: Context<EntityManager>
+  ): Promise<any> {
+    return await this.doSomething_(id, sharedContext)
+  }
+}
+```
+
+### Parameters
+
+The `create` method accepts an array of objects, each representing a record to create. The shape of the objects is the same as the shape of the data model.
+
+### Returns
+
+The method returns an array of the created records.
diff --git a/www/apps/resources/app/data-model-repository-reference/methods/delete/page.mdx b/www/apps/resources/app/data-model-repository-reference/methods/delete/page.mdx
new file mode 100644
index 0000000000..d7cdb87599
--- /dev/null
+++ b/www/apps/resources/app/data-model-repository-reference/methods/delete/page.mdx
@@ -0,0 +1,138 @@
+---
+sidebar_label: "delete"
+---
+
+import { TypeList } from "docs-ui"
+
+export const metadata = {
+  title: `delete Method - Data Model Repository Reference`,
+}
+
+# {metadata.title}
+
+The `delete` method of a data model repository deletes one or more records of the data model.
+
+<Note>
+
+This reference assumes you've already resolved the data model repository, as explained in the [Data Model Repository Reference](../../page.mdx) documentation.
+
+</Note>
+
+## `delete` Parameters
+
+<TypeList
+  types={[
+    {
+      type: "`object`",
+      name: "filters",
+      description: "The filters to select the records to delete. The keys are the property names of the data model, and the values are the values to filter by.",
+      required: true,
+    }
+  ]}
+  sectionTitle="delete Parameters"
+/>
+---
+
+## Delete Record by ID
+
+```ts
+import { 
+  InjectTransactionManager,
+  MedusaContext,
+  MedusaService,
+} from "@medusajs/framework/utils"
+import { Context, InferTypeOf, DAL } from "@medusajs/framework/types"
+import { EntityManager } from "@mikro-orm/knex"
+import Post from "./models/post"
+
+class BlogModuleService extends MedusaService({
+  Post,
+}){
+  // ...
+  @InjectTransactionManager()
+  protected async doSomething_(
+    id: string,
+    @MedusaContext() sharedContext?: Context<EntityManager>
+  ): Promise<any> {
+    const deletedIds = await this.postRepository_.delete({
+      id
+    })
+
+    return deletedIds
+  }
+
+  @InjectManager()
+  async doSomething(
+    id: string,
+    @MedusaContext() sharedContext?: Context<EntityManager>
+  ): Promise<any> {
+    return await this.doSomething_(id, sharedContext)
+  }
+}
+```
+
+### Parameters
+
+The `delete` method accepts an object of filters to select the records to delete.
+
+In the example above, you pass an object with the `id` property to delete a record by its ID.
+
+### Returns
+
+The method returns an array of strings, each representing the ID of a deleted record.
+
+---
+
+## Delete Records by Filters
+
+```ts
+import { 
+  InjectTransactionManager,
+  MedusaContext,
+  MedusaService,
+} from "@medusajs/framework/utils"
+import { Context, InferTypeOf, DAL } from "@medusajs/framework/types"
+import { EntityManager } from "@mikro-orm/knex"
+import Post from "./models/post"
+
+class BlogModuleService extends MedusaService({
+  Post,
+}){
+  // ...
+  @InjectTransactionManager()
+  protected async doSomething_(
+    id: string,
+    @MedusaContext() sharedContext?: Context<EntityManager>
+  ): Promise<any> {
+    const deletedIds = await this.postRepository_.delete({
+      title: "My Post"
+    })
+
+    return deletedIds
+  }
+
+  @InjectManager()
+  async doSomething(
+    id: string,
+    @MedusaContext() sharedContext?: Context<EntityManager>
+  ): Promise<any> {
+    return await this.doSomething_(id, sharedContext)
+  }
+}
+```
+
+### Parameters
+
+Since the `delete` method accepts an object of filters, you can pass any property of the data model as a filter.
+
+In the example above, you pass an object with the `title` property to delete all records with that title.
+
+<Note>
+
+Find examples of different filters in the [Filter Records](../../tips/filtering/page.mdx) documentation.
+
+</Note>
+
+### Returns
+
+The method returns an array of strings, each representing the ID of a deleted record.
diff --git a/www/apps/resources/app/data-model-repository-reference/methods/find/page.mdx b/www/apps/resources/app/data-model-repository-reference/methods/find/page.mdx
new file mode 100644
index 0000000000..894ab5cd73
--- /dev/null
+++ b/www/apps/resources/app/data-model-repository-reference/methods/find/page.mdx
@@ -0,0 +1,460 @@
+---
+sidebar_label: "find"
+---
+
+import { TypeList } from "docs-ui"
+
+export const metadata = {
+  title: `find Method - Data Model Repository Reference`,
+}
+
+# {metadata.title}
+
+The `find` method of a data model repository retrieves a list of records.
+
+<Note>
+
+This reference assumes you've already resolved the data model repository, as explained in the [Data Model Repository Reference](../../page.mdx) documentation.
+
+</Note>
+
+## `find` Parameters
+
+<TypeList
+  types={[
+    {
+      type: "`object`",
+      name: "data",
+      description: "Options to filter and configure the query to retrieve the records.",
+      required: false,
+      children: [
+        {
+          type: "`object`",
+          name: "where",
+          description: "Filters to apply to the query. The keys are the property names of the data model, and the values are the values to filter by.",
+          required: false,
+        },
+        {
+          type: "`object`",
+          name: "options",
+          description: "Options to configure the query.",
+          required: false,
+          children: [
+            {
+              type: "`string[]`",
+              name: "populate",
+              description: "An array of relation names to retrieve.",
+              required: false,
+            },
+            {
+              type: "`string[]`",
+              name: "fields",
+              description: "An array of property names to retrieve.",
+              required: false,
+            },
+            {
+              type: "`number`",
+              name: "limit",
+              description: "The number of records to retrieve.",
+              required: false,
+              defaultValue: "`15`",
+            },
+            {
+              type: "`number`",
+              name: "offset",
+              description: "The number of records to skip before the retrieved records.",
+              required: false,
+              defaultValue: "`0`",
+            },
+            {
+              type: "`object`",
+              name: "orderBy",
+              description: "An object whose keys are the property names of the data model, and values are the sorting order.",
+              required: false,
+            },
+            {
+              type: "`string | string[]`",
+              name: "groupBy",
+              description: "Group the records by one or more properties.",
+              required: false,
+            },
+            {
+              type: "`select-in` \\| `joined`",
+              name: "strategy",
+              description: "The strategy to use to retrieve the records. Learn more in the [MikroORM documentation](https://mikro-orm.io/docs/loading-strategies). If you don't specify a strategy and you specify the `limit` or `offset` options, the default strategy is `select-in`. Otherwise, the default strategy is `joined`.",
+              required: false,
+            }
+          ]
+        }
+      ]
+    }
+  ]}
+  sectionTitle="find Parameters"
+  openedLevel={1}
+/>
+
+---
+
+## Retrieve List of Records
+
+To retrieve a list of records matching a set of filters, use the `find` method of the data model repository:
+
+```ts title="src/modules/blog/service.ts"
+import { 
+  InjectTransactionManager,
+  MedusaContext,
+  MedusaService,
+} from "@medusajs/framework/utils"
+import { Context, InferTypeOf, DAL } from "@medusajs/framework/types"
+import { EntityManager } from "@mikro-orm/knex"
+import Post from "./models/post"
+
+class BlogModuleService extends MedusaService({
+  Post,
+}){
+  // ...
+  @InjectTransactionManager()
+  protected async doSomething_(
+    @MedusaContext() sharedContext?: Context<EntityManager>
+  ): Promise<any> {
+    const posts = await this.postRepository_.find()
+
+    return posts
+  }
+
+  @InjectManager()
+  async doSomething(
+    id: string,
+    @MedusaContext() sharedContext?: Context<EntityManager>
+  ): Promise<any> {
+    return await this.doSomething_(id, sharedContext)
+  }
+}
+```
+
+### Returns
+
+By default, the method returns an array of the first `15` records of the data model.
+
+---
+
+## Filter Records
+
+You can filter the retrieved records by passing filters as a first parameter of the `find` method:
+
+```ts title="src/modules/blog/service.ts"
+import { 
+  InjectTransactionManager,
+  MedusaContext,
+  MedusaService,
+} from "@medusajs/framework/utils"
+import { Context, InferTypeOf, DAL } from "@medusajs/framework/types"
+import { EntityManager } from "@mikro-orm/knex"
+import Post from "./models/post"
+
+class BlogModuleService extends MedusaService({
+  Post,
+}){
+  // ...
+  @InjectTransactionManager()
+  protected async doSomething_(
+    id: string[],
+    @MedusaContext() sharedContext?: Context<EntityManager>
+  ): Promise<any> {
+    const posts = await this.postRepository_.find({
+      where: {
+        id,
+      },
+    })
+
+    return posts
+  }
+
+  @InjectManager()
+  async doSomething(
+    id: string,
+    @MedusaContext() sharedContext?: Context<EntityManager>
+  ): Promise<any> {
+    return await this.doSomething_(id, sharedContext)
+  }
+}
+```
+
+### Parameters
+
+The first object parameter is an object that has a `where` property used to apply filters. `where`'s value is an object whose keys are the property names of the data model, and values are the values to filter by.
+
+In the example above, you filter the retrieved posts by their `id` property.
+
+<Note>
+
+Refer to the [Filtering](../../tips/filtering/page.mdx) reference for more information on how to filter records.
+
+</Note>
+
+### Returns
+
+The method returns an array of the first `15` records matching the filters.
+
+---
+
+## Retrieve Relations
+
+<Note>
+
+This applies to relations between data models of the same module. To retrieve linked records of different modules, use [Query](!docs!/learn/fundamentals/module-links/query).
+
+</Note>
+
+```ts title="src/modules/blog/service.ts"
+import { 
+  InjectTransactionManager,
+  MedusaContext,
+  MedusaService,
+} from "@medusajs/framework/utils"
+import { Context, InferTypeOf, DAL } from "@medusajs/framework/types"
+import { EntityManager } from "@mikro-orm/knex"
+import Post from "./models/post"
+
+class BlogModuleService extends MedusaService({
+  Post,
+}){
+  // ...
+  @InjectTransactionManager()
+  protected async doSomething_(
+    id: string[],
+    @MedusaContext() sharedContext?: Context<EntityManager>
+  ): Promise<any> {
+    const posts = await this.postRepository_.find({
+      where: {
+        id
+      },
+      options: {
+        populate: ["author"]
+      }
+    })
+
+    return posts
+  }
+
+  @InjectManager()
+  async doSomething(
+    id: string,
+    @MedusaContext() sharedContext?: Context<EntityManager>
+  ): Promise<any> {
+    return await this.doSomething_(id, sharedContext)
+  }
+}
+```
+
+### Parameters
+
+The first object parameter of `find` accepts an `option` property, whose value is an object of retrieval options.
+
+It accepts a `populate` property, whose value is an array of relation names to retrieve.
+
+In the example above, you retrieve the `author` relation of the posts.
+
+### Returns
+
+The method returns an array of the first `15` records. Each record will have the specified relations populated:
+
+```json title="Example"
+[
+  {
+    "id": "1",
+    "author": {
+      "id": "1",
+      "name": "John Doe",
+      // ...
+    },
+    // ...
+  }
+]
+```
+  
+
+---
+
+## Select Properties
+
+```ts title="src/modules/blog/service.ts"
+import { 
+  InjectTransactionManager,
+  MedusaContext,
+  MedusaService,
+} from "@medusajs/framework/utils"
+import { Context, InferTypeOf, DAL } from "@medusajs/framework/types"
+import { EntityManager } from "@mikro-orm/knex"
+import Post from "./models/post"
+
+class BlogModuleService extends MedusaService({
+  Post,
+}){
+  // ...
+  @InjectTransactionManager()
+  protected async doSomething_(
+    id: string,
+    @MedusaContext() sharedContext?: Context<EntityManager>
+  ): Promise<any> {
+    const posts = await this.postRepository_.find({
+      where: {
+        id
+      },
+      options: {
+        fields: ["title"]
+      }
+    })
+
+    return posts
+  }
+
+  @InjectManager()
+  async doSomething(
+    id: string,
+    @MedusaContext() sharedContext?: Context<EntityManager>
+  ): Promise<any> {
+    return await this.doSomething_(id, sharedContext)
+  }
+}
+```
+
+### Parameters
+
+By default, retrieved records have all their properties. The first object parameter of `find` accepts in its `options` property a `fields` property, whose value is an array of property names to retrieve.
+
+In the example above, you retrieve only the `title` property of the posts.
+
+### Returns
+
+The method returns an array of the first `15` records. Each record will have only the specified properties:
+
+```json title="Example"
+[
+  {
+    "id": "1",
+    "title": "My first post"
+  }
+]
+```
+
+---
+
+## Paginate Relations
+
+```ts title="src/modules/blog/service.ts"
+import { 
+  InjectTransactionManager,
+  MedusaContext,
+  MedusaService,
+} from "@medusajs/framework/utils"
+import { Context, InferTypeOf, DAL } from "@medusajs/framework/types"
+import { EntityManager } from "@mikro-orm/knex"
+import Post from "./models/post"
+
+class BlogModuleService extends MedusaService({
+  Post,
+}){
+  // ...
+  @InjectTransactionManager()
+  protected async doSomething_(
+    id: string,
+    @MedusaContext() sharedContext?: Context<EntityManager>
+  ): Promise<any> {
+    const posts = await this.postRepository_.find({
+      where: {
+        id
+      },
+      options: {
+        limit: 10,
+        offset: 10,
+      }
+    })
+
+    return posts
+  }
+
+  @InjectManager()
+  async doSomething(
+    id: string,
+    @MedusaContext() sharedContext?: Context<EntityManager>
+  ): Promise<any> {
+    return await this.doSomething_(id, sharedContext)
+  }
+}
+```
+
+### Parameters
+
+By default, the `find` method retrieves the first `15` records.
+
+To change pagination configurations, you can pass to the first object parameter the `options` property, whose value is an object that accepts the following properties for pagination:
+
+- `limit`: a number indicating how many records to retrieve. By default, it's `15`.
+- `offset`: a number indicating how many records to skip before the retrieved records. By default, it's `0`.
+
+In the example above, you retrieve `10` records, skipping the first `10` records.
+
+### Returns
+
+The method returns an array of records. The number of records is less than or equal to `limit`'s value.
+
+---
+
+## Sort Records
+
+```ts title="src/modules/blog/service.ts"
+import { 
+  InjectTransactionManager,
+  MedusaContext,
+  MedusaService,
+} from "@medusajs/framework/utils"
+import { Context, InferTypeOf, DAL } from "@medusajs/framework/types"
+import { EntityManager } from "@mikro-orm/knex"
+import Post from "./models/post"
+
+class BlogModuleService extends MedusaService({
+  Post,
+}){
+  // ...
+  @InjectTransactionManager()
+  protected async doSomething_(
+    id: string,
+    @MedusaContext() sharedContext?: Context<EntityManager>
+  ): Promise<any> {
+    const posts = await this.postRepository_.find({
+      where: {
+        id
+      },
+      options: {
+        orderBy: {
+          title: "ASC"
+        }
+      }
+    })
+
+    return posts
+  }
+
+  @InjectManager()
+  async doSomething(
+    id: string,
+    @MedusaContext() sharedContext?: Context<EntityManager>
+  ): Promise<any> {
+    return await this.doSomething_(id, sharedContext)
+  }
+}
+```
+
+### Parameters
+
+To sort records by one or more properties, the first object parameter of `find` accepts in its `options` property an `orderBy` property. Its value is an object whose keys are the property names of the data model, and values are the sorting order.
+
+The sorting order can be one of the following:
+
+- `ASC` to sort by this property in the ascending order.
+- `DESC` to sort by this property in the descending order.
+
+### Returns
+
+The method returns an array of the first `15` records sorted by the specified properties.
diff --git a/www/apps/resources/app/data-model-repository-reference/methods/findAndCount/page.mdx b/www/apps/resources/app/data-model-repository-reference/methods/findAndCount/page.mdx
new file mode 100644
index 0000000000..ca407e7661
--- /dev/null
+++ b/www/apps/resources/app/data-model-repository-reference/methods/findAndCount/page.mdx
@@ -0,0 +1,495 @@
+---
+sidebar_label: "findAndCount"
+---
+
+import { TypeList } from "docs-ui"
+
+export const metadata = {
+  title: `findAndCount Method - Data Model Repository Reference`,
+}
+
+# {metadata.title}
+
+The `findAndCount` method of a data model repository retrieves a list of records and the total count of records that match the query.
+
+<Note>
+
+This reference assumes you've already resolved the data model repository, as explained in the [Data Model Repository Reference](../../page.mdx) documentation.
+
+</Note>
+
+## `findAndCount` Parameters
+
+<TypeList
+  types={[
+    {
+      type: "`object`",
+      name: "data",
+      description: "Options to filter and configure the query to retrieve the records.",
+      required: false,
+      children: [
+        {
+          type: "`object`",
+          name: "where",
+          description: "Filters to apply to the query. The keys are the property names of the data model, and the values are the values to filter by.",
+          required: false,
+        },
+        {
+          type: "`object`",
+          name: "options",
+          description: "Options to configure the query.",
+          required: false,
+          children: [
+            {
+              type: "`string[]`",
+              name: "populate",
+              description: "An array of relation names to retrieve.",
+              required: false,
+            },
+            {
+              type: "`string[]`",
+              name: "fields",
+              description: "An array of property names to retrieve.",
+              required: false,
+            },
+            {
+              type: "`number`",
+              name: "limit",
+              description: "The number of records to retrieve.",
+              required: false,
+              defaultValue: "`15`",
+            },
+            {
+              type: "`number`",
+              name: "offset",
+              description: "The number of records to skip before the retrieved records.",
+              required: false,
+              defaultValue: "`0`",
+            },
+            {
+              type: "`object`",
+              name: "orderBy",
+              description: "An object whose keys are the property names of the data model, and values are the sorting order.",
+              required: false,
+            },
+            {
+              type: "`string | string[]`",
+              name: "groupBy",
+              description: "Group the records by one or more properties.",
+              required: false,
+            },
+            {
+              type: "`select-in` \\| `joined`",
+              name: "strategy",
+              description: "The strategy to use to retrieve the records. Learn more in the [MikroORM documentation](https://mikro-orm.io/docs/loading-strategies). If you don't specify a strategy and you specify the `limit` or `offset` options, the default strategy is `select-in`. Otherwise, the default strategy is `joined`.",
+              required: false,
+            }
+          ]
+        }
+      ]
+    }
+  ]}
+  sectionTitle="findAndCount Parameters"
+  openedLevel={1}
+/>
+
+---
+
+## Retrieve List of Records
+
+To retrieve a list of records matching a set of filters, use the `findAndCount` method of the data model repository:
+
+```ts title="src/modules/blog/service.ts"
+import { 
+  InjectTransactionManager,
+  MedusaContext,
+  MedusaService,
+} from "@medusajs/framework/utils"
+import { Context, InferTypeOf, DAL } from "@medusajs/framework/types"
+import { EntityManager } from "@mikro-orm/knex"
+import Post from "./models/post"
+
+class BlogModuleService extends MedusaService({
+  Post,
+}){
+  // ...
+  @InjectTransactionManager()
+  protected async doSomething_(
+    id: string,
+    @MedusaContext() sharedContext?: Context<EntityManager>
+  ): Promise<any> {
+    const [posts, count] = await this.postRepository_.findAndCount()
+
+    return {
+      posts,
+      count
+    }
+  }
+
+  @InjectManager()
+  async doSomething(
+    id: string,
+    @MedusaContext() sharedContext?: Context<EntityManager>
+  ): Promise<any> {
+    return await this.doSomething_(id, sharedContext)
+  }
+}
+```
+
+### Returns
+
+The method returns a tuple of two elements:
+
+- An array of the first `15` records of the data model.
+- The total count of records that match the query.
+
+---
+
+## Filter Records
+
+You can filter the retrieved records by passing filters as a first parameter of the `findAndCount` method:
+
+```ts title="src/modules/blog/service.ts"
+import { 
+  InjectTransactionManager,
+  MedusaContext,
+  MedusaService,
+} from "@medusajs/framework/utils"
+import { Context, InferTypeOf, DAL } from "@medusajs/framework/types"
+import { EntityManager } from "@mikro-orm/knex"
+import Post from "./models/post"
+
+class BlogModuleService extends MedusaService({
+  Post,
+}){
+  // ...
+  @InjectTransactionManager()
+  protected async doSomething_(
+    id: string[],
+    @MedusaContext() sharedContext?: Context<EntityManager>
+  ): Promise<any> {
+    const [posts, count] = await this.postRepository_.findAndCount({
+      where: {
+        id,
+      },
+    })
+
+    return {
+      posts,
+      count
+    }
+  }
+
+  @InjectManager()
+  async doSomething(
+    id: string,
+    @MedusaContext() sharedContext?: Context<EntityManager>
+  ): Promise<any> {
+    return await this.doSomething_(id, sharedContext)
+  }
+}
+```
+
+### Parameters
+
+The first object parameter is an object that has a `where` property used to apply filters. `where`'s value is an object whose keys are the property names of the data model, and values are the values to filter by.
+
+In the example above, you filter the retrieved posts by their `id` property.
+
+<Note>
+
+Refer to the [Filtering](../../tips/filtering/page.mdx) reference for more information on how to filter records.
+
+</Note>
+
+### Returns
+
+The method returns a tuple of two elements:
+
+- An array of the first `15` records matching the filters.
+- The total count of records that match the query.
+
+---
+
+## Retrieve Relations
+
+<Note>
+
+This applies to relations between data models of the same module. To retrieve linked records of different modules, use [Query](!docs!/learn/fundamentals/module-links/query).
+
+</Note>
+
+```ts title="src/modules/blog/service.ts"
+import { 
+  InjectTransactionManager,
+  MedusaContext,
+  MedusaService,
+} from "@medusajs/framework/utils"
+import { Context, InferTypeOf, DAL } from "@medusajs/framework/types"
+import { EntityManager } from "@mikro-orm/knex"
+import Post from "./models/post"
+
+class BlogModuleService extends MedusaService({
+  Post,
+}){
+  // ...
+  @InjectTransactionManager()
+  protected async doSomething_(
+    id: string[],
+    @MedusaContext() sharedContext?: Context<EntityManager>
+  ): Promise<any> {
+    const [posts, count] = await this.postRepository_.findAndCount({
+      where: {
+        id
+      },
+      options: {
+        populate: ["author"]
+      }
+    })
+
+    return {
+      posts,
+      count
+    }
+  }
+
+  @InjectManager()
+  async doSomething(
+    id: string,
+    @MedusaContext() sharedContext?: Context<EntityManager>
+  ): Promise<any> {
+    return await this.doSomething_(id, sharedContext)
+  }
+}
+```
+
+### Parameters
+
+The first object parameter of `findAndCount` accepts an `options` property, whose value is an object of retrieval options.
+
+It accepts a `populate` property, whose value is an array of relation names to retrieve.
+
+In the example above, you retrieve the `author` relation of the posts.
+
+### Returns
+
+The method returns a tuple of two elements:
+
+- An array of the first `15` records.
+- The total count of records that match the query.
+
+Each record in the array will have the specified relations populated:
+
+```json title="Example"
+[
+  {
+    "id": "1",
+    "author": {
+      "id": "1",
+      "name": "John Doe",
+      // ...
+    },
+    // ...
+  }
+]
+```
+  
+
+---
+
+## Select Properties
+
+```ts title="src/modules/blog/service.ts"
+import { 
+  InjectTransactionManager,
+  MedusaContext,
+  MedusaService,
+} from "@medusajs/framework/utils"
+import { Context, InferTypeOf, DAL } from "@medusajs/framework/types"
+import { EntityManager } from "@mikro-orm/knex"
+import Post from "./models/post"
+
+class BlogModuleService extends MedusaService({
+  Post,
+}){
+  // ...
+  @InjectTransactionManager()
+  protected async doSomething_(
+    id: string,
+    @MedusaContext() sharedContext?: Context<EntityManager>
+  ): Promise<any> {
+    const [posts, count] = await this.postRepository_.findAndCount({
+      where: {
+        id
+      },
+      options: {
+        fields: ["title"]
+      }
+    })
+
+    return {
+      posts,
+      count
+    }
+  }
+
+  @InjectManager()
+  async doSomething(
+    id: string,
+    @MedusaContext() sharedContext?: Context<EntityManager>
+  ): Promise<any> {
+    return await this.doSomething_(id, sharedContext)
+  }
+}
+```
+
+### Parameters
+
+By default, retrieved records have all their properties. The first object parameter of `findAndCount` accepts in its `options` property a `fields` property, whose value is an array of property names to retrieve.
+
+In the example above, you retrieve only the `title` property of the posts.
+
+### Returns
+
+The method returns a tuple of two elements:
+
+- An array of the first `15` records.
+- The total count of records that match the query.
+
+Each record in the array will have only the specified properties:
+
+```json title="Example"
+[
+  {
+    "id": "1",
+    "title": "My first post"
+  }
+]
+```
+
+---
+
+## Paginate Relations
+
+```ts title="src/modules/blog/service.ts"
+import { 
+  InjectTransactionManager,
+  MedusaContext,
+  MedusaService,
+} from "@medusajs/framework/utils"
+import { Context, InferTypeOf, DAL } from "@medusajs/framework/types"
+import { EntityManager } from "@mikro-orm/knex"
+import Post from "./models/post"
+
+class BlogModuleService extends MedusaService({
+  Post,
+}){
+  // ...
+  @InjectTransactionManager()
+  protected async doSomething_(
+    id: string,
+    @MedusaContext() sharedContext?: Context<EntityManager>
+  ): Promise<any> {
+    const [posts, count] = await this.postRepository_.findAndCount({
+      where: {
+        id
+      },
+      options: {
+        limit: 10,
+        offset: 10,
+      }
+    })
+
+    return posts
+  }
+
+  @InjectManager()
+  async doSomething(
+    id: string,
+    @MedusaContext() sharedContext?: Context<EntityManager>
+  ): Promise<any> {
+    return await this.doSomething_(id, sharedContext)
+  }
+}
+```
+
+### Parameters
+
+By default, the `find` method retrieves the first `15` records.
+
+To change pagination configurations, you can pass to the first object parameter the `options` property, whose value is an object that accepts the following properties for pagination:
+
+- `limit`: a number indicating how many records to retrieve. By default, it's `15`.
+- `offset`: a number indicating how many records to skip before the retrieved records. By default, it's `0`.
+
+In the example above, you retrieve `10` records, skipping the first `10` records.
+
+### Returns
+
+The method returns an array of records. The number of records is less than or equal to `limit`'s value.
+
+---
+
+## Sort Records
+
+```ts title="src/modules/blog/service.ts"
+import { 
+  InjectTransactionManager,
+  MedusaContext,
+  MedusaService,
+} from "@medusajs/framework/utils"
+import { Context, InferTypeOf, DAL } from "@medusajs/framework/types"
+import { EntityManager } from "@mikro-orm/knex"
+import Post from "./models/post"
+
+class BlogModuleService extends MedusaService({
+  Post,
+}){
+  // ...
+  @InjectTransactionManager()
+  protected async doSomething_(
+    id: string,
+    @MedusaContext() sharedContext?: Context<EntityManager>
+  ): Promise<any> {
+    const [posts, count] = await this.postRepository_.findAndCount({
+      where: {
+        id
+      },
+      options: {
+        orderBy: {
+          title: "ASC"
+        }
+      }
+    })
+
+    return {
+      posts,
+      count
+    }
+  }
+
+  @InjectManager()
+  async doSomething(
+    id: string,
+    @MedusaContext() sharedContext?: Context<EntityManager>
+  ): Promise<any> {
+    return await this.doSomething_(id, sharedContext)
+  }
+}
+```
+
+### Parameters
+
+To sort records by one or more properties, the first object parameter of `findAndCount` accepts in its `options` property an `orderBy` property. Its value is an object whose keys are the property names of the data model, and values are the sorting order.
+
+The sorting order can be one of the following:
+
+- `ASC` to sort by this property in the ascending order.
+- `DESC` to sort by this property in the descending order.
+
+### Returns
+
+The method returns a tuple of two elements:
+
+- An array of the first `15` records.
+- The total count of records that match the query.
diff --git a/www/apps/resources/app/data-model-repository-reference/methods/restore/page.mdx b/www/apps/resources/app/data-model-repository-reference/methods/restore/page.mdx
new file mode 100644
index 0000000000..d3a75ca1d2
--- /dev/null
+++ b/www/apps/resources/app/data-model-repository-reference/methods/restore/page.mdx
@@ -0,0 +1,332 @@
+---
+sidebar_label: "restore"
+---
+
+import { TypeList } from "docs-ui"
+
+export const metadata = {
+  title: `restore Method - Data Model Repository Reference`,
+}
+
+# {metadata.title}
+
+The `restore` method of a data model repository restores one or more records of the data model that were previously soft-deleted.
+
+This means that the `deleted_at` property of the records is set to `null`.
+
+<Note>
+
+This reference assumes you've already resolved the data model repository, as explained in the [Data Model Repository Reference](../../page.mdx) documentation.
+
+</Note>
+
+## `restore` Parameters
+
+<TypeList
+  types={[
+    {
+      type: "`string` \\| `string[]` \\| `object`",
+      name: "filters",
+      description: "Can be either the ID of a record to restore, an array of records IDs to restore, or an object of filters to select the records to restore.",
+      required: true,
+    }
+  ]}
+  sectionTitle="restore Parameters"
+/>
+---
+
+## Restore Record by ID
+
+```ts
+import { 
+  InjectTransactionManager,
+  MedusaContext,
+  MedusaService,
+} from "@medusajs/framework/utils"
+import { Context, InferTypeOf, DAL } from "@medusajs/framework/types"
+import { EntityManager } from "@mikro-orm/knex"
+import Post from "./models/post"
+
+class BlogModuleService extends MedusaService({
+  Post,
+}){
+  // ...
+  @InjectTransactionManager()
+  protected async doSomething_(
+    id: string,
+    @MedusaContext() sharedContext?: Context<EntityManager>
+  ): Promise<any> {
+    const [
+      restoredPosts, 
+      restoredEntities
+    ] = await this.postRepository_.restore(id)
+
+    return restoredPosts
+  }
+
+  @InjectManager()
+  async doSomething(
+    id: string,
+    @MedusaContext() sharedContext?: Context<EntityManager>
+  ): Promise<any> {
+    return await this.doSomething_(id, sharedContext)
+  }
+}
+```
+
+### Parameters
+
+The `restore` method can accept the ID of a record to restore as a string.
+
+### Returns
+
+The method returns a tuple with two elements:
+
+- The first element is an array of the restored records.
+- The second element is an object whose keys are the names of restored data models, and values an array of restored record objects.
+    - This is useful if records from other data models were previously soft-deleted due to cascading soft-deletes, and are now restored.
+
+For example:
+
+```json title="Example"
+[
+  [
+    {
+      "id": "01JSHAW6Z7KW4X6E8MFPGNEKHC",
+      "title": "My first post",
+      "content": "This is my first post",
+      "metadata": null,
+      "product_id": null,
+      "product_ids": [
+        "prod_01JP4M5T5K55P2JN1F17EY7B2T"
+      ],
+      "author_id": "01JSHAW6YZNKR65TJ242GCMD2S",
+      "author": "01JSHAW6YZNKR65TJ242GCMD2S",
+      "created_at": "2025-04-23T12:44:59.751Z",
+      "updated_at": "2025-04-23T12:44:59.751Z",
+      "deleted_at": "2025-04-23T12:45:08.750Z"
+    }
+  ],
+  {
+    "Post": [
+      {
+        "id": "01JSHAW6Z7KW4X6E8MFPGNEKHC",
+        "title": "My first post",
+        "content": "This is my first post",
+        "metadata": null,
+        "product_id": null,
+        "product_ids": [
+          "prod_01JP4M5T5K55P2JN1F17EY7B2T"
+        ],
+        "author_id": "01JSHAW6YZNKR65TJ242GCMD2S",
+        "author": "01JSHAW6YZNKR65TJ242GCMD2S",
+        "created_at": "2025-04-23T12:44:59.751Z",
+        "updated_at": "2025-04-23T12:44:59.751Z",
+        "deleted_at": "2025-04-23T12:45:08.750Z"
+      }
+    ]
+  }
+]
+```
+
+---
+
+## Restore Multiple Records By IDs
+
+```ts
+import { 
+  InjectTransactionManager,
+  MedusaContext,
+  MedusaService,
+} from "@medusajs/framework/utils"
+import { Context, InferTypeOf, DAL } from "@medusajs/framework/types"
+import { EntityManager } from "@mikro-orm/knex"
+import Post from "./models/post"
+
+class BlogModuleService extends MedusaService({
+  Post,
+}){
+  // ...
+  @InjectTransactionManager()
+  protected async doSomething_(
+    ids: string[],
+    @MedusaContext() sharedContext?: Context<EntityManager>
+  ): Promise<any> {
+    const [
+      restoredPosts, 
+      restoredEntities
+    ] = await this.postRepository_.restore(ids)
+
+    return restoredPosts
+  }
+
+  @InjectManager()
+  async doSomething(
+    ids: string[],
+    @MedusaContext() sharedContext?: Context<EntityManager>
+  ): Promise<any> {
+    return await this.doSomething_(ids, sharedContext)
+  }
+}
+```
+
+### Parameters
+
+The `restore` method can accept an array of record IDs to restore.
+
+### Returns
+
+The method returns a tuple with two elements:
+
+- The first element is an array of the restored records.
+- The second element is an object whose keys are the names of restored data models, and values an array of restored record objects.
+    - This is useful if records from other data models were previously soft-deleted due to cascading soft-deletes, and are now restored.
+
+For example:
+
+```json title="Example"
+[
+  [
+    {
+      "id": "01JSHAW6Z7KW4X6E8MFPGNEKHC",
+      "title": "My first post",
+      "content": "This is my first post",
+      "metadata": null,
+      "product_id": null,
+      "product_ids": [
+        "prod_01JP4M5T5K55P2JN1F17EY7B2T"
+      ],
+      "author_id": "01JSHAW6YZNKR65TJ242GCMD2S",
+      "author": "01JSHAW6YZNKR65TJ242GCMD2S",
+      "created_at": "2025-04-23T12:44:59.751Z",
+      "updated_at": "2025-04-23T12:44:59.751Z",
+      "deleted_at": "2025-04-23T12:45:08.750Z"
+    }
+  ],
+  {
+    "Post": [
+      {
+        "id": "01JSHAW6Z7KW4X6E8MFPGNEKHC",
+        "title": "My first post",
+        "content": "This is my first post",
+        "metadata": null,
+        "product_id": null,
+        "product_ids": [
+          "prod_01JP4M5T5K55P2JN1F17EY7B2T"
+        ],
+        "author_id": "01JSHAW6YZNKR65TJ242GCMD2S",
+        "author": "01JSHAW6YZNKR65TJ242GCMD2S",
+        "created_at": "2025-04-23T12:44:59.751Z",
+        "updated_at": "2025-04-23T12:44:59.751Z",
+        "deleted_at": "2025-04-23T12:45:08.750Z"
+      }
+    ]
+  }
+]
+```
+
+---
+
+## Restore Records by Filters
+
+```ts
+import { 
+  InjectTransactionManager,
+  MedusaContext,
+  MedusaService,
+} from "@medusajs/framework/utils"
+import { Context, InferTypeOf, DAL } from "@medusajs/framework/types"
+import { EntityManager } from "@mikro-orm/knex"
+import Post from "./models/post"
+
+class BlogModuleService extends MedusaService({
+  Post,
+}){
+  // ...
+  @InjectTransactionManager()
+  protected async doSomething_(
+    id: string,
+    @MedusaContext() sharedContext?: Context<EntityManager>
+  ): Promise<any> {
+    const [
+      restoredPosts, 
+      restoredEntities
+    ] = await this.postRepository_.restore({
+      title: "My Post"
+    })
+
+    return restoredPosts
+  }
+
+  @InjectManager()
+  async doSomething(
+    ids: string[],
+    @MedusaContext() sharedContext?: Context<EntityManager>
+  ): Promise<any> {
+    return await this.doSomething_(ids, sharedContext)
+  }
+}
+```
+
+### Parameters
+
+The `restore` method can accept an object of filters to select the records to restore.
+
+In the example above, you pass an object with the `title` property to restore all records with that title.
+
+<Note>
+
+Find examples of different filters in the [Filter Records](../../tips/filtering/page.mdx) documentation.
+
+</Note>
+
+### Returns
+
+The method returns a tuple with two elements:
+
+- The first element is an array of the restored records.
+- The second element is an object whose keys are the names of restored data models, and values an array of restored record objects.
+    - This is useful if records from other data models were previously soft-deleted due to cascading soft-deletes, and are now restored.
+
+For example:
+
+```json title="Example"
+[
+  [
+    {
+      "id": "01JSHAW6Z7KW4X6E8MFPGNEKHC",
+      "title": "My first post",
+      "content": "This is my first post",
+      "metadata": null,
+      "product_id": null,
+      "product_ids": [
+        "prod_01JP4M5T5K55P2JN1F17EY7B2T"
+      ],
+      "author_id": "01JSHAW6YZNKR65TJ242GCMD2S",
+      "author": "01JSHAW6YZNKR65TJ242GCMD2S",
+      "created_at": "2025-04-23T12:44:59.751Z",
+      "updated_at": "2025-04-23T12:44:59.751Z",
+      "deleted_at": "2025-04-23T12:45:08.750Z"
+    }
+  ],
+  {
+    "Post": [
+      {
+        "id": "01JSHAW6Z7KW4X6E8MFPGNEKHC",
+        "title": "My first post",
+        "content": "This is my first post",
+        "metadata": null,
+        "product_id": null,
+        "product_ids": [
+          "prod_01JP4M5T5K55P2JN1F17EY7B2T"
+        ],
+        "author_id": "01JSHAW6YZNKR65TJ242GCMD2S",
+        "author": "01JSHAW6YZNKR65TJ242GCMD2S",
+        "created_at": "2025-04-23T12:44:59.751Z",
+        "updated_at": "2025-04-23T12:44:59.751Z",
+        "deleted_at": "2025-04-23T12:45:08.750Z"
+      }
+    ]
+  }
+]
+```
\ No newline at end of file
diff --git a/www/apps/resources/app/data-model-repository-reference/methods/softDelete/page.mdx b/www/apps/resources/app/data-model-repository-reference/methods/softDelete/page.mdx
new file mode 100644
index 0000000000..86ee899a53
--- /dev/null
+++ b/www/apps/resources/app/data-model-repository-reference/methods/softDelete/page.mdx
@@ -0,0 +1,334 @@
+---
+sidebar_label: "softDelete"
+---
+
+import { TypeList } from "docs-ui"
+
+export const metadata = {
+  title: `softDelete Method - Data Model Repository Reference`,
+}
+
+# {metadata.title}
+
+The `softDelete` method of a data model repository soft-deletes one or more records of the data model.
+
+This means that the records are still available in the database, but they are marked as deleted by setting their `deleted_at` property to the deletion date.
+
+You can later restore the records using the [restore](../restore/page.mdx) method.
+
+<Note>
+
+This reference assumes you've already resolved the data model repository, as explained in the [Data Model Repository Reference](../../page.mdx) documentation.
+
+</Note>
+
+## `softDelete` Parameters
+
+<TypeList
+  types={[
+    {
+      type: "`string` \\| `string[]` \\| `object`",
+      name: "filters",
+      description: "Can be either the ID of a record to soft-delete, an array of records IDs to soft-delete, or an object of filters to select the records to soft-delete.",
+      required: true,
+    }
+  ]}
+  sectionTitle="softDelete Parameters"
+/>
+---
+
+## Soft-Delete Record by ID
+
+```ts
+import { 
+  InjectTransactionManager,
+  MedusaContext,
+  MedusaService,
+} from "@medusajs/framework/utils"
+import { Context, InferTypeOf, DAL } from "@medusajs/framework/types"
+import { EntityManager } from "@mikro-orm/knex"
+import Post from "./models/post"
+
+class BlogModuleService extends MedusaService({
+  Post,
+}){
+  // ...
+  @InjectTransactionManager()
+  protected async doSomething_(
+    id: string,
+    @MedusaContext() sharedContext?: Context<EntityManager>
+  ): Promise<any> {
+    const [
+      deletedPosts, 
+      deletedEntities
+    ] = await this.postRepository_.softDelete(id)
+
+    return deletedPosts
+  }
+
+  @InjectManager()
+  async doSomething(
+    id: string,
+    @MedusaContext() sharedContext?: Context<EntityManager>
+  ): Promise<any> {
+    return await this.doSomething_(id, sharedContext)
+  }
+}
+```
+
+### Parameters
+
+The `softDelete` method can accept the ID of a record to soft-delete as a string.
+
+### Returns
+
+The method returns a tuple with two elements:
+
+- The first element is an array of the soft-deleted records.
+- The second element is an object whose keys are the names of deleted data models, and values an array of deleted record objects.
+    - This is useful if records from other data models are soft-deleted due to cascading soft-deletes.
+
+For example:
+
+```json title="Example"
+[
+  [
+    {
+      "id": "01JSHAW6Z7KW4X6E8MFPGNEKHC",
+      "title": "My first post",
+      "content": "This is my first post",
+      "metadata": null,
+      "product_id": null,
+      "product_ids": [
+        "prod_01JP4M5T5K55P2JN1F17EY7B2T"
+      ],
+      "author_id": "01JSHAW6YZNKR65TJ242GCMD2S",
+      "author": "01JSHAW6YZNKR65TJ242GCMD2S",
+      "created_at": "2025-04-23T12:44:59.751Z",
+      "updated_at": "2025-04-23T12:44:59.751Z",
+      "deleted_at": "2025-04-23T12:45:08.750Z"
+    }
+  ],
+  {
+    "Post": [
+      {
+        "id": "01JSHAW6Z7KW4X6E8MFPGNEKHC",
+        "title": "My first post",
+        "content": "This is my first post",
+        "metadata": null,
+        "product_id": null,
+        "product_ids": [
+          "prod_01JP4M5T5K55P2JN1F17EY7B2T"
+        ],
+        "author_id": "01JSHAW6YZNKR65TJ242GCMD2S",
+        "author": "01JSHAW6YZNKR65TJ242GCMD2S",
+        "created_at": "2025-04-23T12:44:59.751Z",
+        "updated_at": "2025-04-23T12:44:59.751Z",
+        "deleted_at": "2025-04-23T12:45:08.750Z"
+      }
+    ]
+  }
+]
+```
+
+---
+
+## Soft-Delete Multiple Records By IDs
+
+```ts
+import { 
+  InjectTransactionManager,
+  MedusaContext,
+  MedusaService,
+} from "@medusajs/framework/utils"
+import { Context, InferTypeOf, DAL } from "@medusajs/framework/types"
+import { EntityManager } from "@mikro-orm/knex"
+import Post from "./models/post"
+
+class BlogModuleService extends MedusaService({
+  Post,
+}){
+  // ...
+  @InjectTransactionManager()
+  protected async doSomething_(
+    ids: string[],
+    @MedusaContext() sharedContext?: Context<EntityManager>
+  ): Promise<any> {
+    const [
+      deletedPosts, 
+      deletedEntities
+    ] = await this.postRepository_.softDelete(ids)
+
+    return deletedPosts
+  }
+
+  @InjectManager()
+  async doSomething(
+    ids: string[],
+    @MedusaContext() sharedContext?: Context<EntityManager>
+  ): Promise<any> {
+    return await this.doSomething_(ids, sharedContext)
+  }
+}
+```
+
+### Parameters
+
+The `softDelete` method can accept an array of record IDs to soft-delete.
+
+### Returns
+
+The method returns a tuple with two elements:
+
+- The first element is an array of the soft-deleted records.
+- The second element is an object whose keys are the names of deleted data models, and values an array of deleted record objects.
+    - This is useful if records from other data models are soft-deleted due to cascading soft-deletes.
+
+For example:
+
+```json title="Example"
+[
+  [
+    {
+      "id": "01JSHAW6Z7KW4X6E8MFPGNEKHC",
+      "title": "My first post",
+      "content": "This is my first post",
+      "metadata": null,
+      "product_id": null,
+      "product_ids": [
+        "prod_01JP4M5T5K55P2JN1F17EY7B2T"
+      ],
+      "author_id": "01JSHAW6YZNKR65TJ242GCMD2S",
+      "author": "01JSHAW6YZNKR65TJ242GCMD2S",
+      "created_at": "2025-04-23T12:44:59.751Z",
+      "updated_at": "2025-04-23T12:44:59.751Z",
+      "deleted_at": "2025-04-23T12:45:08.750Z"
+    }
+  ],
+  {
+    "Post": [
+      {
+        "id": "01JSHAW6Z7KW4X6E8MFPGNEKHC",
+        "title": "My first post",
+        "content": "This is my first post",
+        "metadata": null,
+        "product_id": null,
+        "product_ids": [
+          "prod_01JP4M5T5K55P2JN1F17EY7B2T"
+        ],
+        "author_id": "01JSHAW6YZNKR65TJ242GCMD2S",
+        "author": "01JSHAW6YZNKR65TJ242GCMD2S",
+        "created_at": "2025-04-23T12:44:59.751Z",
+        "updated_at": "2025-04-23T12:44:59.751Z",
+        "deleted_at": "2025-04-23T12:45:08.750Z"
+      }
+    ]
+  }
+]
+```
+
+---
+
+## Soft-Delete Records by Filters
+
+```ts
+import { 
+  InjectTransactionManager,
+  MedusaContext,
+  MedusaService,
+} from "@medusajs/framework/utils"
+import { Context, InferTypeOf, DAL } from "@medusajs/framework/types"
+import { EntityManager } from "@mikro-orm/knex"
+import Post from "./models/post"
+
+class BlogModuleService extends MedusaService({
+  Post,
+}){
+  // ...
+  @InjectTransactionManager()
+  protected async doSomething_(
+    id: string,
+    @MedusaContext() sharedContext?: Context<EntityManager>
+  ): Promise<any> {
+    const [
+      deletedPosts, 
+      deletedEntities
+    ] = await this.postRepository_.softDelete({
+      title: "My Post"
+    })
+
+    return deletedPosts
+  }
+
+  @InjectManager()
+  async doSomething(
+    ids: string[],
+    @MedusaContext() sharedContext?: Context<EntityManager>
+  ): Promise<any> {
+    return await this.doSomething_(ids, sharedContext)
+  }
+}
+```
+
+### Parameters
+
+The `softDelete` method can accept an object of filters to select the records to soft-delete.
+
+In the example above, you pass an object with the `title` property to soft-delete all records with that title.
+
+<Note>
+
+Find examples of different filters in the [Filter Records](../../tips/filtering/page.mdx) documentation.
+
+</Note>
+
+### Returns
+
+The method returns a tuple with two elements:
+
+- The first element is an array of the soft-deleted records.
+- The second element is an object whose keys are the names of deleted data models, and values an array of deleted record objects.
+    - This is useful if records from other data models are soft-deleted due to cascading soft-deletes.
+
+For example:
+
+```json title="Example"
+[
+  [
+    {
+      "id": "01JSHAW6Z7KW4X6E8MFPGNEKHC",
+      "title": "My first post",
+      "content": "This is my first post",
+      "metadata": null,
+      "product_id": null,
+      "product_ids": [
+        "prod_01JP4M5T5K55P2JN1F17EY7B2T"
+      ],
+      "author_id": "01JSHAW6YZNKR65TJ242GCMD2S",
+      "author": "01JSHAW6YZNKR65TJ242GCMD2S",
+      "created_at": "2025-04-23T12:44:59.751Z",
+      "updated_at": "2025-04-23T12:44:59.751Z",
+      "deleted_at": "2025-04-23T12:45:08.750Z"
+    }
+  ],
+  {
+    "Post": [
+      {
+        "id": "01JSHAW6Z7KW4X6E8MFPGNEKHC",
+        "title": "My first post",
+        "content": "This is my first post",
+        "metadata": null,
+        "product_id": null,
+        "product_ids": [
+          "prod_01JP4M5T5K55P2JN1F17EY7B2T"
+        ],
+        "author_id": "01JSHAW6YZNKR65TJ242GCMD2S",
+        "author": "01JSHAW6YZNKR65TJ242GCMD2S",
+        "created_at": "2025-04-23T12:44:59.751Z",
+        "updated_at": "2025-04-23T12:44:59.751Z",
+        "deleted_at": "2025-04-23T12:45:08.750Z"
+      }
+    ]
+  }
+]
+```
\ No newline at end of file
diff --git a/www/apps/resources/app/data-model-repository-reference/methods/update/page.mdx b/www/apps/resources/app/data-model-repository-reference/methods/update/page.mdx
new file mode 100644
index 0000000000..6e856cf9e0
--- /dev/null
+++ b/www/apps/resources/app/data-model-repository-reference/methods/update/page.mdx
@@ -0,0 +1,113 @@
+---
+sidebar_label: "update"
+---
+
+import { TypeList } from "docs-ui"
+
+export const metadata = {
+  title: `update Method - Data Model Repository Reference`,
+}
+
+# {metadata.title}
+
+The `update` method of a data model repository updates one or more records of the data model.
+
+<Note>
+
+This reference assumes you've already resolved the data model repository, as explained in the [Data Model Repository Reference](../../page.mdx) documentation.
+
+</Note>
+
+## `update` Parameters
+
+<TypeList
+  types={[
+    {
+      type: "`array`",
+      name: "data",
+      description: "An array of update details.",
+      required: true,
+      children: [
+        {
+          type: "`object`",
+          name: "entity",
+          description: "The entity to update. It must be the entire entity, which can be retrieved using the `find` method.",
+          required: true,
+        },
+        {
+          type: "`object`",
+          name: "update",
+          description: "The properties to update. The keys are the property names of the data model, and the values are the values to update.",
+          required: true,
+        }
+      ]
+    }
+  ]}
+  openedLevel={1}
+  sectionTitle="update Parameters"
+/>
+---
+
+## Update Records
+
+```ts
+import { 
+  InjectTransactionManager,
+  MedusaContext,
+  MedusaService,
+} from "@medusajs/framework/utils"
+import { Context, InferTypeOf, DAL } from "@medusajs/framework/types"
+import { EntityManager } from "@mikro-orm/knex"
+import Post from "./models/post"
+
+class BlogModuleService extends MedusaService({
+  Post,
+}){
+  // ...
+  @InjectTransactionManager()
+  protected async doSomething_(
+    id: string,
+    @MedusaContext() sharedContext?: Context<EntityManager>
+  ): Promise<any> {
+    const existingPost = await this.postRepository_.find({
+      where: {
+        id
+      }
+    })    
+    
+    const posts = await this.postRepository_.update([
+      {
+        entity: existingPost[0],
+        update: {
+          title: "My Post Updated"
+        }
+      }
+    ])
+
+    return posts
+  }
+
+  @InjectManager()
+  async doSomething(
+    id: string,
+    @MedusaContext() sharedContext?: Context<EntityManager>
+  ): Promise<any> {
+    return await this.doSomething_(id, sharedContext)
+  }
+}
+```
+
+### Parameters
+
+The `update` method accepts an array of objects, each representing a record to update.
+
+Each object has two properties:
+
+- `entity`: The entity or record to update. It must be the entire record, which can be retrieved using the [find](../find/page.mdx) or [findAndCount](../findAndCount/page.mdx) methods.
+- `update`: The properties to update. The keys are the property names of the data model, and the values are the values to update.
+
+In the example above, you retrieve the record to update using the `find` method. Then, you pass the entire record and the properties to update to the `update` method.
+
+### Returns
+
+The method returns an array of the updated records.
diff --git a/www/apps/resources/app/data-model-repository-reference/methods/upsert/page.mdx b/www/apps/resources/app/data-model-repository-reference/methods/upsert/page.mdx
new file mode 100644
index 0000000000..168a6f5442
--- /dev/null
+++ b/www/apps/resources/app/data-model-repository-reference/methods/upsert/page.mdx
@@ -0,0 +1,92 @@
+---
+sidebar_label: "upsert"
+---
+
+import { TypeList } from "docs-ui"
+
+export const metadata = {
+  title: `upsert Method - Data Model Repository Reference`,
+}
+
+# {metadata.title}
+
+The `upsert` method of a data model repository creates or updates one or more records of the data model.
+
+<Note>
+
+This reference assumes you've already resolved the data model repository, as explained in the [Data Model Repository Reference](../../page.mdx) documentation.
+
+</Note>
+
+## `upsert` Parameters
+
+<TypeList
+  types={[
+    {
+      type: "`array`",
+      name: "data",
+      description: "An array of records to create or update. If a record object has an `id` property, the method will try to update the record. Otherwise, the method will create a new record.",
+      required: true,
+    }
+  ]}
+  sectionTitle="upsert Parameters"
+/>
+---
+
+## Upsert Records
+
+```ts
+import { 
+  InjectTransactionManager,
+  MedusaContext,
+  MedusaService,
+} from "@medusajs/framework/utils"
+import { Context, InferTypeOf, DAL } from "@medusajs/framework/types"
+import { EntityManager } from "@mikro-orm/knex"
+import Post from "./models/post"
+
+class BlogModuleService extends MedusaService({
+  Post,
+}){
+  // ...
+  @InjectTransactionManager()
+  protected async doSomething_(
+    id: string,
+    @MedusaContext() sharedContext?: Context<EntityManager>
+  ): Promise<any> {
+    const posts = await this.postRepository_.upsert([
+      {
+        id: "01JSHAW6Z7KW4X6E8MFPGNEKHC",
+        title: "My Old Post",
+      },
+      {
+        title: "My New Post",
+      }
+    ])
+
+    return posts
+  }
+
+  @InjectManager()
+  async doSomething(
+    id: string,
+    @MedusaContext() sharedContext?: Context<EntityManager>
+  ): Promise<any> {
+    return await this.doSomething_(id, sharedContext)
+  }
+}
+```
+
+### Parameters
+
+The `upsert` method accepts an array of objects, each representing a record to create or update.
+
+If a record object has an `id` property, the method will try to update a record with that `id`. Otherwise, the method will create a new record.
+
+If the `id` property is specified but no record with that `id` exists, the created record will have the specified `id`.
+
+Each object has the same shape as the data model.
+
+### Returns
+
+The method returns an array of the created or updated records.
diff --git a/www/apps/resources/app/data-model-repository-reference/methods/upsertWithReplace/page.mdx b/www/apps/resources/app/data-model-repository-reference/methods/upsertWithReplace/page.mdx
new file mode 100644
index 0000000000..be54550053
--- /dev/null
+++ b/www/apps/resources/app/data-model-repository-reference/methods/upsertWithReplace/page.mdx
@@ -0,0 +1,149 @@
+---
+sidebar_label: "upsertWithReplace"
+---
+
+import { TypeList } from "docs-ui"
+
+export const metadata = {
+  title: `upsertWithReplace Method - Data Model Repository Reference`,
+}
+
+# {metadata.title}
+
+The `upsertWithReplace` method of a data model repository can do three things:
+
+- Create a new record.
+- Update an existing record.
+- Delete a record related to the record being upserted. If a one-to-many or many-to-many relation is omitted in the new data of a record, the method will delete the related records if they belong to the record being upserted.
+
+This method is useful when you're doing complex upserts with relations, or you want details of the operations performed. Otherwise, use the [upsert](../upsert/page.mdx) method.
+
+<Note>
+
+This reference assumes you've already resolved the data model repository, as explained in the [Data Model Repository Reference](../../page.mdx) documentation.
+
+</Note>
+
+## `upsertWithReplace` Parameters
+
+<TypeList
+  types={[
+    {
+      type: "`array`",
+      name: "data",
+      description: "An array of records to create or update. If a record object has an `id` property, the method will try to update the record. Otherwise, the method will create a new record.",
+      required: true,
+    }
+  ]}
+  sectionTitle="upsertWithReplace Parameters"
+/>
+---
+
+## Upsert Records
+
+```ts
+import { 
+  InjectTransactionManager,
+  MedusaContext,
+  MedusaService,
+} from "@medusajs/framework/utils"
+import { Context, InferTypeOf, DAL } from "@medusajs/framework/types"
+import { EntityManager } from "@mikro-orm/knex"
+import Post from "./models/post"
+
+class BlogModuleService extends MedusaService({
+  Post,
+}){
+  // ...
+  @InjectTransactionManager()
+  protected async doSomething_(
+    id: string,
+    @MedusaContext() sharedContext?: Context<EntityManager>
+  ): Promise<any> {
+    const {
+      entities,
+      performedActions
+    } = await this.postRepository_.upsertWithReplace([
+      {
+        id: "01JSHAW6Z7KW4X6E8MFPGNEKHC",
+        title: "My Old Post",
+        author_id: null
+      },
+      {
+        id: "123",
+        title: "My New Post",
+      }
+    ])
+
+    return {
+      entities,
+      performedActions
+    }
+  }
+
+  @InjectManager()
+  async doSomething(
+    id: string,
+    @MedusaContext() sharedContext?: Context<EntityManager>
+  ): Promise<any> {
+    return await this.doSomething_(id, sharedContext)
+  }
+}
+```
+
+### Parameters
+
+The `upsertWithReplace` method accepts an array of objects, each representing a record to create or update.
+
+If a record object has an `id` property, the method will try to update a record with that `id`. Otherwise, the method will create a new record.
+
+If the `id` property is specified but no record with that `id` exists, the created record will have the specified `id`.
+
+Each object has the same shape as the data model.
+
+### Returns
+
+The method returns an object with two properties:
+
+- `entities`: An array of the created or updated records.
+- `performedActions`: An object with three properties:
+  - `created`: An object whose keys are the names of data models, and values are arrays of the records that were created.
+  - `updated`: An object whose keys are the names of data models, and values are arrays of the records that were updated.
+  - `deleted`: An object whose keys are the names of data models, and values are arrays of the records that were deleted.
+
+For example:
+
+```json title="Example"
+{
+  "entities": [
+    {
+      "id": "01JSHAW6Z7KW4X6E8MFPGNEKHC",
+      "title": "My Old Post",
+      "author_id": null
+    },
+    {
+      "id": "123",
+      "title": "My New Post"
+    }
+  ],
+  "performedActions": {
+    "created": {
+      "Post": [
+        {
+          "id": "123"
+        }
+      ]
+    },
+    "updated": {
+      "Post": [
+        {
+          "id": "01JSHAW6Z7KW4X6E8MFPGNEKHC"
+        }
+      ]
+    },
+    "deleted": {
+
+    }
+  }
+}
+```
diff --git a/www/apps/resources/app/data-model-repository-reference/page.mdx b/www/apps/resources/app/data-model-repository-reference/page.mdx
new file mode 100644
index 0000000000..ebd05e0b26
--- /dev/null
+++ b/www/apps/resources/app/data-model-repository-reference/page.mdx
@@ -0,0 +1,87 @@
+import { ChildDocs } from "docs-ui"
+
+export const metadata = {
+  title: `Data Model Repository Reference`,
+}
+
+# {metadata.title}
+
+This section of the documentation provides a reference of the methods generated for data model repositories that are injected into a module's container.
+
+<Note title="Tip">
+
+Learn more about the data model repository in the [Database Operations](!docs!/learn/fundamentals/modules/db-operations) documentation.
+
+</Note>
+
+## When to Use the Data Model Repository?
+
+If your module has data models, then you should always extend the [service factory](!docs!/learn/fundamentals/modules/service-factory). It generates basic data-mangement operations for your module's data models.
+
+However, there are some cases where you might need to perform more complex database operations and need more control over the parameters you're passing.
+
+In those cases, you can use the data model repository.
+
+---
+
+## Data Model Repository Registration Name
+
+When the Medusa application injects a data model repository into a module's container, it formats the registration name by:
+
+- Taking the data model's name that's passed as the first parameter of `model.define`
+- Lower-casing the first character
+- Suffixing the result with `Repository`.
+
+For example:
+
+- `Post` model: `postRepository`
+- `My_Custom` model: `my_CustomRepository`
+
+---
+
+## Resolve Data Model Repository
+
+To resolve a data model repository from a module's container, pass the data model's name in the first parameter of the module's constructor.
+
+For example:
+
+export const resolveRepoHighlights = [
+  ["17", "postRepository", "Resolve the data model repository for the `Post` model."],
+]
+
+```ts highlights={resolveRepoHighlights}
+import { MedusaService } from "@medusajs/framework/utils"
+import { InferTypeOf, DAL } from "@medusajs/framework/types"
+import Post from "./models/post"
+
+type Post = InferTypeOf<typeof Post>
+
+type InjectedDependencies = {
+  postRepository: DAL.RepositoryService<Post>
+}
+
+class BlogModuleService extends MedusaService({
+  Post,
+}){
+  protected postRepository_: DAL.RepositoryService<Post>
+
+  constructor({ 
+    postRepository 
+  }: InjectedDependencies) {
+    super(...arguments)
+    this.postRepository_ = postRepository
+  }
+}
+
+export default BlogModuleService
+```
+
+In this example, the `BlogModuleService` class resolves the `postRepository` from its container.
+
+---
+
+## Methods Reference
+
+Learn how to use the data model repository's methods to perform database operations on the data model.
+
+<ChildDocs showItems={["Methods"]} hideTitle />
diff --git a/www/apps/resources/app/data-model-repository-reference/tips/filtering/page.mdx b/www/apps/resources/app/data-model-repository-reference/tips/filtering/page.mdx
new file mode 100644
index 0000000000..0c2d59193a
--- /dev/null
+++ b/www/apps/resources/app/data-model-repository-reference/tips/filtering/page.mdx
@@ -0,0 +1,531 @@
+---
+sidebar_label: "Filtering"
+---
+
+import { Table } from "docs-ui"
+
+export const metadata = {
+  title: `Filter Records - Data Model Repository Reference`,
+}
+
+# {metadata.title}
+
+This reference provides examples to different filtering mechanisms and scenarios.
+
+## Methods that Accept Filters
+
+Some of the data model repository's methods allow you to pass filters, including:
+
+<Table>
+  <Table.Header>
+    <Table.Row>
+      <Table.HeaderCell>
+        Method
+      </Table.HeaderCell>
+      <Table.HeaderCell>
+        Filter Parameter
+      </Table.HeaderCell>
+    </Table.Row>
+  </Table.Header>
+  <Table.Body>
+    <Table.Row>
+      <Table.Cell>
+        [find](../../methods/find/page.mdx)
+      </Table.Cell>
+      <Table.Cell>
+        Accepts a `where` property in its first parameter to pass filters.
+      </Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>
+        [findAndCount](../../methods/findAndCount/page.mdx)
+      </Table.Cell>
+      <Table.Cell>
+        Accepts a `where` property in its first parameter to pass filters.
+      </Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>
+        [delete](../../methods/delete/page.mdx)
+      </Table.Cell>
+      <Table.Cell>
+        Accepts an object as a first parameter to pass filters.
+      </Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>
+        [softDelete](../../methods/softDelete/page.mdx)
+      </Table.Cell>
+      <Table.Cell>
+        Accepts an object as a first parameter to pass filters.
+      </Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>
+        [restore](../../methods/restore/page.mdx)
+      </Table.Cell>
+      <Table.Cell>
+        Accepts an object as a first parameter to pass filters.
+      </Table.Cell>
+    </Table.Row>
+  </Table.Body>
+</Table>
+
+While the examples in this reference are based on the `find` method, the same filtering mechanisms apply to the other methods.
+
+---
+
+## Match Exact Value
+
+```ts
+const posts = await this.postRepository_.find({
+  where: {
+    title: "My Post"
+  },
+})
+```
+
+If you pass a property with its value, only records whose properties exactly match the value are selected.
+
+In the example above, only posts having the title `My Post` are retrieved.
+
+---
+
+## Doesn't Match Exact Value
+
+```ts
+const posts = await this.postRepository_.find({
+  where: {
+    title: {
+      $ne: "My Post",
+    }
+  },
+})
+```
+
+To find records with a property that doesn't match a value, pass an object with a `$ne` property. Its value is the value that a record's property shouldn't match.
+
+In the example above, only posts that don't have the title `My Post` are retrieved.
+
+---
+
+## Match Multiple Values
+
+```ts
+const posts = await this.postRepository_.find({
+  where: {
+    views: [
+      50,
+      100,
+    ],
+  },
+})
+```
+
+To find records with a property matching multiple values, pass an array of those values as the property's value in the filter.
+
+In the example above, only posts having either `50` or `100` views are retrieved.
+
+---
+
+## Don't Match Multiple Values
+
+```ts
+const posts = await this.postRepository_.find({
+  where: {
+    title: {
+      $nin: ["My Post", "My Post 2"]
+    }
+  },
+})
+```
+
+To find records with a property that doesn't match one or more values, pass an object with a `$nin` property. Its value is an array of multiple values that a record's property shouldn't match.
+
+In the example above, only posts that don't have the title `My Post` are retrieved.
+
+---
+
+## Match Text Like Value
+
+<Note>
+
+This filter only applies to text-like properties, including `text`, `id`, and `enum` properties.
+
+</Note>
+
+```ts
+const posts = await this.postRepository_.find({
+  where: {
+    title: {
+      $like: "My%"
+    }
+  },
+})
+```
+
+To perform a `like` filter on a record's property, set the property's value to an object with a `$like` property. Its value is the string to use when applying the `like` filter.
+
+The example above matches all posts whose title starts with `My`.
+
+---
+
+## Filter by Null or Not Null
+
+To retrieve records with a property that is `null`, set the property's value to `null`.
+
+For example:
+
+```ts
+const posts = await this.postRepository_.find({
+  where: {
+    published_at: null,
+  },
+})
+```
+In the example above, only posts that have a `null` publish date are retrieved.
+
+On the other hand, to retrieve records with a property that isn't `null`, set the property's value to an object with a `$ne` property.
+
+For example:
+
+```ts
+const posts = await this.postRepository_.find({
+  where: {
+    published_at: {
+      $ne: null,
+    },
+  },
+})
+```
+
+In the example above, only posts that have a publish date are retrieved.
+
+---
+
+## Apply Range Filters
+
+<Note>
+
+This filter only applies to the `number` and `dateTime` properties.
+
+</Note>
+
+```ts
+const posts = await this.postRepository_.find({
+  where: {
+    published_at: {
+      $lt: new Date(),
+    },
+  },
+})
+```
+
+To filter a record's property to be within a range, set the property's value to an object with any of the following properties:
+
+1. `$lt`: The property's value must be less than the supplied value.
+2. `$lte`: The property's value must be less than or equal to the supplied value.
+3. `$gt`: The property's value must be greater than the supplied value.
+4. `$gte`: The property's value must be greater than or equal the supplied value.
+
+In the example above, only posts whose `published_at` property is before the current date and time are retrieved.
+
+### Example: Retrieve Posts Published Today
+
+```ts
+const startToday = new Date()
+startToday.setHours(0, 0, 0, 0)
+
+const endToday = new Date()
+endToday.setHours(23, 59, 59, 59)
+
+const posts = await this.postRepository_.find({
+  where: {
+    published_at: {
+      $gte: startToday,
+      $lte: endToday,
+    },
+  },
+})
+```
+
+The `dateTime` property also stores the time. So, when matching for an exact day, you must set a range filter to be between the beginning and end of the day.
+
+In this example, you retrieve the current date twice: once to set its time to `00:00:00`, and another to set its time `23:59:59`. Then, you retrieve posts whose `published_at` property is between `00:00:00` and `23:59:59` of today.
+
+### Example: Range Filter on Number Property
+
+```ts
+const posts = await this.postRepository_.find({
+  where: {
+    views: {
+      $gte: 50,
+      $lte: 100,
+    },
+  },
+})
+```
+
+In the example above, only posts with `views` between `50` and `100` are retrieved.
+
+---
+
+## Apply Or Condition
+
+```ts
+const posts = await this.postRepository_.find({
+  where: {
+    $or: [
+      {
+        title: "My Post",
+      },
+      {
+      published_at: {
+          $lt: new Date(),
+        },
+      },
+    ],
+  },
+})
+```
+
+To use an `or` condition, pass to the filter object the `$or` property, whose value is an array of filters.
+
+In the example above, posts whose title is `My Post` or their `published_at` date is less than the current date and time are retrieved.
+
+---
+
+## Apply And Condition
+
+```ts
+const posts = await this.postRepository_.find({
+  where: {
+    $and: [
+      {
+        title: "My Post",
+      },
+      {
+        published_at: {
+          $lt: new Date(),
+        },
+      },
+    ],
+  },
+})
+```
+
+To use an `and` condition, pass to the filter object the `$and` property, whose value is an array of filters.
+
+In the example above, only posts whose title is `My Post` and their `published_at` date is less than the current date and time are retrieved.
+
+---
+
+## Complex Filters Example
+
+```ts
+const posts = await this.postRepository_.find({
+  where: {
+    $or: [
+      {
+        $and: [
+          { views: { $gte: 50 } },
+          { 
+            published_at: {
+              $gte: new Date(new Date().getFullYear(), 0, 1),
+            },
+          },
+        ],
+      },
+      {
+        title: {
+          $like: "%Featured%",
+        },
+      },
+    ],
+  },
+})
+```
+
+In the example above, posts are retrieved if they meet either of the following conditions:
+
+1. The post has at least `50` views and was published after the beginning of the current year.
+2. The post's title contains the word `Featured`.
+
+By combining `and` and `or` conditions, you can create complex filters to retrieve records that meet specific criteria.
+
+---
+
+## Supported Filter Operators List
+
+The following operators are supported by the data model repository filtering mechanism:
+
+<Table>
+  <Table.Header>
+    <Table.Row>
+      <Table.HeaderCell>
+        Operator
+      </Table.HeaderCell>
+      <Table.HeaderCell>
+        Description
+      </Table.HeaderCell>
+    </Table.Row>
+  </Table.Header>
+
+  <Table.Body>
+    <Table.Row className="bg-medusa-bg-component">
+      <Table.Cell colSpan={2}>
+        Comparison Operators
+      </Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>
+        `$eq`
+      </Table.Cell>
+      <Table.Cell>
+        Matches values that are equal to a specified value.
+      </Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>
+        `$ne`
+      </Table.Cell>
+      <Table.Cell>
+        Matches values that are not equal to a specified value.
+      </Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>
+        `$in`
+      </Table.Cell>
+      <Table.Cell>
+        Matches any of the values specified in an array.
+      </Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>
+        `$nin`
+      </Table.Cell>
+      <Table.Cell>
+        Matches none of the values specified in an array.
+      </Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>
+        `$like`
+      </Table.Cell>
+      <Table.Cell>
+        Matches values containing a specified substring.
+      </Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>
+        `$lt`
+      </Table.Cell>
+      <Table.Cell>
+        Matches values that are less than a specified value.
+      </Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>
+        `$lte`
+      </Table.Cell>
+      <Table.Cell>
+        Matches values that are less than or equal to a specified value.
+      </Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>
+        `$gt`
+      </Table.Cell>
+      <Table.Cell>
+        Matches values that are greater than a specified value.
+      </Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>
+        `$gte`
+      </Table.Cell>
+      <Table.Cell>
+        Matches values that are greater than or equal to a specified value.
+      </Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>
+        `$re`
+      </Table.Cell>
+      <Table.Cell>
+        Matches values that match a specified regular expression.
+      </Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>
+        `$ilike`
+      </Table.Cell>
+      <Table.Cell>
+        Matches values containing a specified substring, case-insensitive.
+      </Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>
+        `$fulltext`
+      </Table.Cell>
+      <Table.Cell>
+        Performs a full-text search on a text property.
+      </Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>
+        `$overlap`
+      </Table.Cell>
+      <Table.Cell>
+        Matches values that have overlapping elements with the specified array.
+      </Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>
+        `$contains`
+      </Table.Cell>
+      <Table.Cell>
+        Performs an `@> value` comparison. Learn more in the [PostgreSQL documentation](https://www.postgresql.org/docs/9.6/functions-array.html).
+      </Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>
+        `$contained`
+      </Table.Cell>
+      <Table.Cell>
+        Performs an `value @>` comparison. Learn more in the [PostgreSQL documentation](https://www.postgresql.org/docs/9.6/functions-array.html).
+      </Table.Cell>
+    </Table.Row>
+    <Table.Row className="bg-medusa-bg-component">
+      <Table.Cell colSpan={2}>
+        Logical Operators
+      </Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>
+        `$and`
+      </Table.Cell>
+      <Table.Cell>
+        Joins two or more conditions with a logical AND.
+      </Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>
+        `$or`
+      </Table.Cell>
+      <Table.Cell>
+        Joins two or more conditions with a logical OR.
+      </Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>
+        `$not`
+      </Table.Cell>
+      <Table.Cell>
+        Inverts the logic of a condition. For example, `$not: { $eq: value }` matches any value that is not equal to the specified value.
+      </Table.Cell>
+    </Table.Row>
+  </Table.Body>
+</Table>
+
diff --git a/www/apps/resources/app/service-factory-reference/tips/filtering/page.mdx b/www/apps/resources/app/service-factory-reference/tips/filtering/page.mdx
index 846834e6d5..d145a51d81 100644
--- a/www/apps/resources/app/service-factory-reference/tips/filtering/page.mdx
+++ b/www/apps/resources/app/service-factory-reference/tips/filtering/page.mdx
@@ -2,6 +2,8 @@
 sidebar_label: "Filtering"
 ---
 
+import { Table } from "docs-ui"
+
 export const metadata = {
   title: `Filter Records - Service Factory Reference`,
 }
@@ -273,4 +275,181 @@ In the example above, posts are retrieved if they meet either of the following c
 1. The post has at least `50` views and was published after the beginning of the current year.
 2. The post's title contains the word `Featured`.
 
-By combining `and` and `or` conditions, you can create complex filters to retrieve records that meet specific criteria.
\ No newline at end of file
+By combining `and` and `or` conditions, you can create complex filters to retrieve records that meet specific criteria.
+
+---
+
+## Supported Filter Operators List
+
+The following operators are supported by the service factory filtering mechanism:
+
+<Table>
+  <Table.Header>
+    <Table.Row>
+      <Table.HeaderCell>
+        Operator
+      </Table.HeaderCell>
+      <Table.HeaderCell>
+        Description
+      </Table.HeaderCell>
+    </Table.Row>
+  </Table.Header>
+
+  <Table.Body>
+    <Table.Row className="bg-medusa-bg-component">
+      <Table.Cell colSpan={2}>
+        Comparison Operators
+      </Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>
+        `$eq`
+      </Table.Cell>
+      <Table.Cell>
+        Matches values that are equal to a specified value.
+      </Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>
+        `$ne`
+      </Table.Cell>
+      <Table.Cell>
+        Matches values that are not equal to a specified value.
+      </Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>
+        `$in`
+      </Table.Cell>
+      <Table.Cell>
+        Matches any of the values specified in an array.
+      </Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>
+        `$nin`
+      </Table.Cell>
+      <Table.Cell>
+        Matches none of the values specified in an array.
+      </Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>
+        `$like`
+      </Table.Cell>
+      <Table.Cell>
+        Matches values containing a specified substring.
+      </Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>
+        `$lt`
+      </Table.Cell>
+      <Table.Cell>
+        Matches values that are less than a specified value.
+      </Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>
+        `$lte`
+      </Table.Cell>
+      <Table.Cell>
+        Matches values that are less than or equal to a specified value.
+      </Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>
+        `$gt`
+      </Table.Cell>
+      <Table.Cell>
+        Matches values that are greater than a specified value.
+      </Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>
+        `$gte`
+      </Table.Cell>
+      <Table.Cell>
+        Matches values that are greater than or equal to a specified value.
+      </Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>
+        `$re`
+      </Table.Cell>
+      <Table.Cell>
+        Matches values that match a specified regular expression.
+      </Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>
+        `$ilike`
+      </Table.Cell>
+      <Table.Cell>
+        Matches values containing a specified substring, case-insensitive.
+      </Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>
+        `$fulltext`
+      </Table.Cell>
+      <Table.Cell>
+        Performs a full-text search on a text property.
+      </Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>
+        `$overlap`
+      </Table.Cell>
+      <Table.Cell>
+        Matches values that have overlapping elements with the specified array.
+      </Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>
+        `$contains`
+      </Table.Cell>
+      <Table.Cell>
+        Performs an `@> value` comparison. Learn more in the [PostgreSQL documentation](https://www.postgresql.org/docs/9.6/functions-array.html).
+      </Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>
+        `$contained`
+      </Table.Cell>
+      <Table.Cell>
+        Performs an `value @>` comparison. Learn more in the [PostgreSQL documentation](https://www.postgresql.org/docs/9.6/functions-array.html).
+      </Table.Cell>
+    </Table.Row>
+    <Table.Row className="bg-medusa-bg-component">
+      <Table.Cell colSpan={2}>
+        Logical Operators
+      </Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>
+        `$and`
+      </Table.Cell>
+      <Table.Cell>
+        Joins two or more conditions with a logical AND.
+      </Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>
+        `$or`
+      </Table.Cell>
+      <Table.Cell>
+        Joins two or more conditions with a logical OR.
+      </Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>
+        `$not`
+      </Table.Cell>
+      <Table.Cell>
+        Inverts the logic of a condition. For example, `$not: { $eq: value }` matches any value that is not equal to the specified value.
+      </Table.Cell>
+    </Table.Row>
+  </Table.Body>
+</Table>
+
diff --git a/www/apps/resources/generated/edit-dates.mjs b/www/apps/resources/generated/edit-dates.mjs
index 38514fbe4a..20e68bc667 100644
--- a/www/apps/resources/generated/edit-dates.mjs
+++ b/www/apps/resources/generated/edit-dates.mjs
@@ -132,7 +132,7 @@ export const generatedEditDates = {
   "app/service-factory-reference/methods/retrieve/page.mdx": "2024-07-31T17:01:33+03:00",
   "app/service-factory-reference/methods/soft-delete/page.mdx": "2024-07-31T17:01:33+03:00",
   "app/service-factory-reference/methods/update/page.mdx": "2024-07-31T17:01:33+03:00",
-  "app/service-factory-reference/tips/filtering/page.mdx": "2025-03-21T08:32:39.125Z",
+  "app/service-factory-reference/tips/filtering/page.mdx": "2025-04-23T14:38:29.068Z",
   "app/service-factory-reference/page.mdx": "2024-07-26T14:40:56+00:00",
   "app/storefront-development/cart/context/page.mdx": "2025-03-27T14:47:14.258Z",
   "app/storefront-development/cart/create/page.mdx": "2025-03-27T14:46:51.473Z",
diff --git a/www/apps/resources/generated/files-map.mjs b/www/apps/resources/generated/files-map.mjs
index 3342741d6c..949a39c9a4 100644
--- a/www/apps/resources/generated/files-map.mjs
+++ b/www/apps/resources/generated/files-map.mjs
@@ -691,6 +691,50 @@ export const filesMap = [
     "filePath": "/www/apps/resources/app/create-medusa-app/page.mdx",
     "pathname": "/create-medusa-app"
   },
+  {
+    "filePath": "/www/apps/resources/app/data-model-repository-reference/methods/create/page.mdx",
+    "pathname": "/data-model-repository-reference/methods/create"
+  },
+  {
+    "filePath": "/www/apps/resources/app/data-model-repository-reference/methods/delete/page.mdx",
+    "pathname": "/data-model-repository-reference/methods/delete"
+  },
+  {
+    "filePath": "/www/apps/resources/app/data-model-repository-reference/methods/find/page.mdx",
+    "pathname": "/data-model-repository-reference/methods/find"
+  },
+  {
+    "filePath": "/www/apps/resources/app/data-model-repository-reference/methods/findAndCount/page.mdx",
+    "pathname": "/data-model-repository-reference/methods/findAndCount"
+  },
+  {
+    "filePath": "/www/apps/resources/app/data-model-repository-reference/methods/restore/page.mdx",
+    "pathname": "/data-model-repository-reference/methods/restore"
+  },
+  {
+    "filePath": "/www/apps/resources/app/data-model-repository-reference/methods/softDelete/page.mdx",
+    "pathname": "/data-model-repository-reference/methods/softDelete"
+  },
+  {
+    "filePath": "/www/apps/resources/app/data-model-repository-reference/methods/update/page.mdx",
+    "pathname": "/data-model-repository-reference/methods/update"
+  },
+  {
+    "filePath": "/www/apps/resources/app/data-model-repository-reference/methods/upsert/page.mdx",
+    "pathname": "/data-model-repository-reference/methods/upsert"
+  },
+  {
+    "filePath": "/www/apps/resources/app/data-model-repository-reference/methods/upsertWithReplace/page.mdx",
+    "pathname": "/data-model-repository-reference/methods/upsertWithReplace"
+  },
+  {
+    "filePath": "/www/apps/resources/app/data-model-repository-reference/page.mdx",
+    "pathname": "/data-model-repository-reference"
+  },
+  {
+    "filePath": "/www/apps/resources/app/data-model-repository-reference/tips/filtering/page.mdx",
+    "pathname": "/data-model-repository-reference/tips/filtering"
+  },
   {
     "filePath": "/www/apps/resources/app/deployment/medusa-application/railway/page.mdx",
     "pathname": "/deployment/medusa-application/railway"
diff --git a/www/apps/resources/generated/generated-references-sidebar.mjs b/www/apps/resources/generated/generated-references-sidebar.mjs
index 1764811e9e..c0fa3496f7 100644
--- a/www/apps/resources/generated/generated-references-sidebar.mjs
+++ b/www/apps/resources/generated/generated-references-sidebar.mjs
@@ -6367,6 +6367,137 @@ const generatedgeneratedReferencesSidebarSidebar = {
         }
       ]
     },
+    {
+      "loaded": true,
+      "isPathHref": true,
+      "type": "sidebar",
+      "sidebar_id": "data-model-repository-reference",
+      "title": "Data Model Repository",
+      "description": "List of methods in your service extending the data model repository.",
+      "children": [
+        {
+          "loaded": true,
+          "isPathHref": true,
+          "type": "link",
+          "path": "/data-model-repository-reference",
+          "title": "Overview",
+          "children": []
+        },
+        {
+          "type": "separator"
+        },
+        {
+          "loaded": true,
+          "isPathHref": true,
+          "type": "category",
+          "title": "Methods",
+          "initialOpen": true,
+          "autogenerate_path": "/data-model-repository-reference/methods",
+          "children": [
+            {
+              "loaded": true,
+              "isPathHref": true,
+              "type": "link",
+              "path": "/data-model-repository-reference/methods/create",
+              "title": "create",
+              "description": "",
+              "children": []
+            },
+            {
+              "loaded": true,
+              "isPathHref": true,
+              "type": "link",
+              "path": "/data-model-repository-reference/methods/delete",
+              "title": "delete",
+              "description": "",
+              "children": []
+            },
+            {
+              "loaded": true,
+              "isPathHref": true,
+              "type": "link",
+              "path": "/data-model-repository-reference/methods/find",
+              "title": "find",
+              "description": "",
+              "children": []
+            },
+            {
+              "loaded": true,
+              "isPathHref": true,
+              "type": "link",
+              "path": "/data-model-repository-reference/methods/findAndCount",
+              "title": "findAndCount",
+              "description": "",
+              "children": []
+            },
+            {
+              "loaded": true,
+              "isPathHref": true,
+              "type": "link",
+              "path": "/data-model-repository-reference/methods/restore",
+              "title": "restore",
+              "description": "",
+              "children": []
+            },
+            {
+              "loaded": true,
+              "isPathHref": true,
+              "type": "link",
+              "path": "/data-model-repository-reference/methods/softDelete",
+              "title": "softDelete",
+              "description": "",
+              "children": []
+            },
+            {
+              "loaded": true,
+              "isPathHref": true,
+              "type": "link",
+              "path": "/data-model-repository-reference/methods/update",
+              "title": "update",
+              "description": "",
+              "children": []
+            },
+            {
+              "loaded": true,
+              "isPathHref": true,
+              "type": "link",
+              "path": "/data-model-repository-reference/methods/upsert",
+              "title": "upsert",
+              "description": "",
+              "children": []
+            },
+            {
+              "loaded": true,
+              "isPathHref": true,
+              "type": "link",
+              "path": "/data-model-repository-reference/methods/upsertWithReplace",
+              "title": "upsertWithReplace",
+              "description": "",
+              "children": []
+            }
+          ]
+        },
+        {
+          "loaded": true,
+          "isPathHref": true,
+          "type": "category",
+          "title": "Tips",
+          "initialOpen": true,
+          "autogenerate_path": "/data-model-repository-reference/tips",
+          "children": [
+            {
+              "loaded": true,
+              "isPathHref": true,
+              "type": "link",
+              "path": "/data-model-repository-reference/tips/filtering",
+              "title": "Filtering",
+              "description": "",
+              "children": []
+            }
+          ]
+        }
+      ]
+    },
     {
       "loaded": true,
       "isPathHref": true,
diff --git a/www/apps/resources/sidebars/references.mjs b/www/apps/resources/sidebars/references.mjs
index fdc2abbf04..36ef666af2 100644
--- a/www/apps/resources/sidebars/references.mjs
+++ b/www/apps/resources/sidebars/references.mjs
@@ -75,6 +75,35 @@ export const referencesSidebar = [
       },
     ],
   },
+  {
+    type: "sidebar",
+    sidebar_id: "data-model-repository-reference",
+    title: "Data Model Repository",
+    description:
+      "List of methods in your service extending the data model repository.",
+    children: [
+      {
+        type: "link",
+        path: "/data-model-repository-reference",
+        title: "Overview",
+      },
+      {
+        type: "separator",
+      },
+      {
+        type: "category",
+        title: "Methods",
+        initialOpen: true,
+        autogenerate_path: "/data-model-repository-reference/methods",
+      },
+      {
+        type: "category",
+        title: "Tips",
+        initialOpen: true,
+        autogenerate_path: "/data-model-repository-reference/tips",
+      },
+    ],
+  },
   {
     type: "link",
     path: "/events-reference",
diff --git a/www/apps/resources/utils/get-sidebar-for-path.ts b/www/apps/resources/utils/get-sidebar-for-path.ts
index 7af5235d05..150de5d9a7 100644
--- a/www/apps/resources/utils/get-sidebar-for-path.ts
+++ b/www/apps/resources/utils/get-sidebar-for-path.ts
@@ -123,6 +123,7 @@ const sidebarMappings: {
       "/references/workflows",
       "/references-overview",
       "/references/medusa-workflows",
+      "/data-model-repository-reference",
     ],
   },
   {
diff --git a/www/packages/docs-ui/src/constants.tsx b/www/packages/docs-ui/src/constants.tsx
index 3b5a58f267..6b1e2d6e05 100644
--- a/www/packages/docs-ui/src/constants.tsx
+++ b/www/packages/docs-ui/src/constants.tsx
@@ -313,6 +313,11 @@ export const navDropdownItems: NavigationItem[] = [
         title: "Data Model Language",
         link: "/resources/references/data-model",
       },
+      {
+        type: "link",
+        title: "Data Model Repository",
+        link: "/resources/data-model-repository-reference",
+      },
       {
         type: "link",
         title: "Events Reference",