docs: document locks for nested workflows (#14130)

* docs: document locks for nested workflows * smal text change * fix build error
2025-11-26 15:36:58 +02:00
parent 76660fb6cc
commit c1ede88a7e
53 changed files with 712 additions and 208 deletions
@@ -20,8 +20,8 @@ The [Locking Module](!resources!/infrastructure-modules/locking) handles the loc

 Medusa provides two steps that you can use to create locks in your workflows:

- `acquireLockStep`: Attempt to acquire a lock. If the lock is already held by another process, this step will wait until the lock is released. It will fail if a timeout occurs before acquiring the lock.
- `releaseLockStep`: Release a previously acquired lock.
+- [acquireLockStep](!resources!/references/medusa-workflows/steps/acquireLockStep): Attempt to acquire a lock. If the lock is already held by another process, this step will wait until the lock is released. It will fail if a timeout occurs before acquiring the lock.
+- [releaseLockStep](!resources!/references/medusa-workflows/steps/releaseLockStep): Release a previously acquired lock.

 You can use these steps in your workflows to ensure that only one instance of a workflow can modify a resource at a time.

@@ -128,4 +128,61 @@ The step will wait until the lock is acquired based on the configured Locking Mo

 ### Locking Module Service API

-Refer to the [Locking Module reference](!resources!/references/locking-service) for more information on the Locking Module's service methods.
+Refer to the [Locking Module reference](!resources!/references/locking-service) for more information on the Locking Module's service methods.
+
+---
+
+## Locks in Nested Workflows
+
+[Nested workflows](../execute-another-workflow/page.mdx) can't acquire locks. So, if you're using a workflow that acquires locks within another workflow, the parent workflow must handle the locking mechanism.
+
+For example, consider a custom workflow that executes Medusa's [completeCartWorkflow](!resources!/references/medusa-workflows/completeCartWorkflow). The `completeCartWorkflow` acquires locks on the cart to prevent race conditions.
+
+Therefore, the custom workflow must acquire and release the locks around the `completeCartWorkflow` execution. For example:
+
+export const nestedWorkflowLockHighlights = [
+  ["16", "acquireLockStep", "Acquire a lock on the cart before executing the nested workflow."],
+  ["23", "completeCartWorkflow", "Execute the nested workflow that requires the lock."],
+  ["30", "releaseLockStep", "Release the lock after the nested workflow is complete."]
+]
+
+```ts title="src/workflows/custom-complete-cart.ts" highlights={nestedWorkflowLockHighlights}
+import { createWorkflow } from "@medusajs/framework/workflows-sdk"
+import { 
+  acquireLockStep, 
+  releaseLockStep,
+  completeCartWorkflow
+} from "@medusajs/medusa/core-flows"
+
+type WorkflowInput = {
+  cart_id: string;
+}
+
+export const customCompleteCartWorkflow = createWorkflow(
+  "custom-complete-cart",
+  (input: WorkflowInput) => {
+    // acquire the same lock as the nested workflow
+    acquireLockStep({
+      key: input.cart_id,
+      timeout: 30,
+      ttl: 60 * 2,
+    })
+
+    // Execute the nested workflow
+    completeCartWorkflow.runAsStep({
+      input: {
+        id: input.cart_id,
+      }
+    })
+
+    // release the lock after the nested workflow is complete
+    releaseLockStep({
+      key: input.cart_id,
+    })
+  }
+)
+```
+
+In the example above, the `customCompleteCartWorkflow` acquires a lock on the cart before executing the `completeCartWorkflow` and releases it afterward.
+
+Make sure you're acquiring the same lock key as the nested workflow.
@@ -132,7 +132,7 @@ export const generatedEditDates = {
  "app/learn/fundamentals/scheduled-jobs/interval/page.mdx": "2025-09-02T08:36:12.714Z",
  "app/learn/debugging-and-testing/feature-flags/create/page.mdx": "2025-09-02T08:36:12.714Z",
  "app/learn/debugging-and-testing/feature-flags/page.mdx": "2025-09-02T08:36:12.714Z",
-  "app/learn/fundamentals/workflows/locks/page.mdx": "2025-09-15T09:37:00.808Z",
+  "app/learn/fundamentals/workflows/locks/page.mdx": "2025-11-26T11:40:04.279Z",
  "app/learn/codemods/page.mdx": "2025-09-29T15:40:03.620Z",
  "app/learn/codemods/replace-imports/page.mdx": "2025-10-09T11:37:44.754Z",
  "app/learn/fundamentals/admin/translations/page.mdx": "2025-10-30T11:55:32.221Z",
@@ -840,9 +840,9 @@ export const generatedSidebars = [
                "isPathHref": true,
                "type": "link",
                "path": "/learn/fundamentals/workflows/execute-another-workflow",
-                "title": "Execute Nested Workflows",
+                "title": "Nested Workflows",
                "children": [],
-                "chapterTitle": "3.7.13. Execute Nested Workflows",
+                "chapterTitle": "3.7.13. Nested Workflows",
                "number": "3.7.13."
              },
              {
@@ -22299,8 +22299,8 @@ The [Locking Module](https://docs.medusajs.com/resources/infrastructure-modules/

 Medusa provides two steps that you can use to create locks in your workflows:

- `acquireLockStep`: Attempt to acquire a lock. If the lock is already held by another process, this step will wait until the lock is released. It will fail if a timeout occurs before acquiring the lock.
- `releaseLockStep`: Release a previously acquired lock.
+- [acquireLockStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/acquireLockStep/index.html.md): Attempt to acquire a lock. If the lock is already held by another process, this step will wait until the lock is released. It will fail if a timeout occurs before acquiring the lock.
+- [releaseLockStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/releaseLockStep/index.html.md): Release a previously acquired lock.

 You can use these steps in your workflows to ensure that only one instance of a workflow can modify a resource at a time.

@@ -22391,6 +22391,57 @@ The step will wait until the lock is acquired based on the configured Locking Mo

 Refer to the [Locking Module reference](https://docs.medusajs.com/resources/references/locking-service/index.html.md) for more information on the Locking Module's service methods.

+***
+
+## Locks in Nested Workflows
+
+[Nested workflows](https://docs.medusajs.com/learn/fundamentals/workflows/execute-another-workflow/index.html.md) can't acquire locks. So, if you're using a workflow that acquires locks within another workflow, the parent workflow must handle the locking mechanism.
+
+For example, consider a custom workflow that executes Medusa's [completeCartWorkflow](https://docs.medusajs.com/resources/references/medusa-workflows/completeCartWorkflow/index.html.md). The `completeCartWorkflow` acquires locks on the cart to prevent race conditions.
+
+Therefore, the custom workflow must acquire and release the locks around the `completeCartWorkflow` execution. For example:
+
+```ts title="src/workflows/custom-complete-cart.ts" highlights={nestedWorkflowLockHighlights}
+import { createWorkflow } from "@medusajs/framework/workflows-sdk"
+import { 
+  acquireLockStep, 
+  releaseLockStep,
+  completeCartWorkflow
+} from "@medusajs/medusa/core-flows"
+
+type WorkflowInput = {
+  cart_id: string;
+}
+
+export const customCompleteCartWorkflow = createWorkflow(
+  "custom-complete-cart",
+  (input: WorkflowInput) => {
+    // acquire the same lock as the nested workflow
+    acquireLockStep({
+      key: input.cart_id,
+      timeout: 30,
+      ttl: 60 * 2,
+    })
+
+    // Execute the nested workflow
+    completeCartWorkflow.runAsStep({
+      input: {
+        id: input.cart_id,
+      }
+    })
+
+    // release the lock after the nested workflow is complete
+    releaseLockStep({
+      key: input.cart_id,
+    })
+  }
+)
+```
+
+In the example above, the `customCompleteCartWorkflow` acquires a lock on the cart before executing the `completeCartWorkflow` and releases it afterward.
+
+Make sure you're acquiring the same lock key as the nested workflow.
+

 # Long-Running Workflows

@@ -45263,44 +45314,50 @@ For example, Medusa uses the Locking Module in inventory management to ensure th

 You can use the Locking Module as part of the [workflows](https://docs.medusajs.com/docs/learn/fundamentals/workflows/index.html.md) you build for your custom features. A workflow is a special function composed of a series of steps that guarantees data consistency and reliable roll-back mechanism.

-In a step of your workflow, you can resolve the Locking Module's service and use its methods to execute an asynchronous job, acquire a lock, or release locks.
+In a workflow, you can either use:
+
+- Medusa's [acquireLockStep](https://docs.medusajs.com/references/medusa-workflows/steps/acquireLockStep/index.html.md) and [releaseLockStep](https://docs.medusajs.com/references/medusa-workflows/steps/releaseLockStep/index.html.md) to create locks around critical steps in your workflow.
+- The Locking Module's service directly in your steps to have more control over the locking mechanism

 For example:

-```ts
-import { Modules } from "@medusajs/framework/utils"
-import { 
-  createStep,
-  createWorkflow,
-} from "@medusajs/framework/workflows-sdk"
+### Workflow

-const step1 = createStep(
-  "step-1",
-  async ({}, { container }) => {
-    const lockingModuleService = container.resolve(
-      Modules.LOCKING
-    )
-    const productModuleService = container.resolve(
-      Modules.PRODUCT
-    )
+```ts title="src/workflows/charge-customer.ts" highlights={workflowLockHighlights}
+import { createWorkflow } from "@medusajs/framework/workflows-sdk"
+import { acquireLockStep, releaseLockStep } from "@medusajs/medusa/core-flows"
+import { chargeCustomerStep } from "./steps/charge-customer-step"

-    await lockingModuleService.execute("prod_123", async () => {
-      await productModuleService.deleteProduct("prod_123")
+type WorkflowInput = {
+  customer_id: string;
+  order_id: string;
+}
+
+export const chargeCustomerWorkflow = createWorkflow(
+  "charge-customer",
+  (input: WorkflowInput) => {
+    acquireLockStep({
+      key: input.order_id,
+      // Attempt to acquire the lock for two seconds before timing out
+      timeout: 2,
+      // Lock is only held for a maximum of ten seconds
+      ttl: 10,
    })
-  } 
-)

-export const workflow = createWorkflow(
-  "workflow-1",
-  () => {
-    step1()
+    chargeCustomerStep(input)
+
+    releaseLockStep({
+      key: input.order_id,
+    })
  }
 )
 ```

-In the example above, you create a workflow that has a step. In the step, you resolve the services of the Locking and Product modules from the [Medusa container](https://docs.medusajs.com/docs/learn/fundamentals/medusa-container/index.html.md).
+In the example above, you create a workflow that acquires a lock on an order using the `acquireLockStep` before charging a customer. The lock is then released using the `releaseLockStep` after the operation is complete.

-Then, you use the `execute` method of the Locking Module to acquire a lock for the product with the ID `prod_123` and execute an asynchronous function, which deletes the product.
+This ensures that only one instance of the workflow can modify the order at a time, preventing issues like double charging the customer.
+
+### Step

 ***

@@ -441,7 +441,7 @@ export const sidebars = [
              {
                type: "link",
                path: "/learn/fundamentals/workflows/execute-another-workflow",
-                title: "Execute Nested Workflows",
+                title: "Nested Workflows",
              },
              {
                type: "link",
@@ -1,4 +1,4 @@
-import { Table, CardList } from "docs-ui"
+import { Table, CardList, Tabs, TabsList, TabsTrigger, TabsContent, TabsContentWrapper } from "docs-ui"

 export const metadata = {
  title: `Locking Module`,
@@ -22,44 +22,96 @@ For example, Medusa uses the Locking Module in inventory management to ensure th

 You can use the Locking Module as part of the [workflows](!docs!/learn/fundamentals/workflows) you build for your custom features. A workflow is a special function composed of a series of steps that guarantees data consistency and reliable roll-back mechanism.

-In a step of your workflow, you can resolve the Locking Module's service and use its methods to execute an asynchronous job, acquire a lock, or release locks.
+In a workflow, you can either use:
+
+- Medusa's [acquireLockStep](/references/medusa-workflows/steps/acquireLockStep) and [releaseLockStep](/references/medusa-workflows/steps/releaseLockStep) to create locks around critical steps in your workflow.
+- The Locking Module's service directly in your steps to have more control over the locking mechanism

 For example:

-```ts
-import { Modules } from "@medusajs/framework/utils"
-import { 
-  createStep,
-  createWorkflow,
-} from "@medusajs/framework/workflows-sdk"
+<Tabs defaultValue="workflow">
+  <TabsList>
+    <TabsTrigger value="workflow">Workflow</TabsTrigger>
+    <TabsTrigger value="step">Step</TabsTrigger>
+  </TabsList>
+  <TabsContentWrapper>
+    <TabsContent value="workflow">

-const step1 = createStep(
-  "step-1",
-  async ({}, { container }) => {
-    const lockingModuleService = container.resolve(
-      Modules.LOCKING
+    ```ts title="src/workflows/charge-customer.ts"
+    import { createWorkflow } from "@medusajs/framework/workflows-sdk"
+    import { acquireLockStep, releaseLockStep } from "@medusajs/medusa/core-flows"
+    import { chargeCustomerStep } from "./steps/charge-customer-step"
+
+    type WorkflowInput = {
+      customer_id: string;
+      order_id: string;
+    }
+
+    export const chargeCustomerWorkflow = createWorkflow(
+      "charge-customer",
+      (input: WorkflowInput) => {
+        acquireLockStep({
+          key: input.order_id,
+          // Attempt to acquire the lock for two seconds before timing out
+          timeout: 2,
+          // Lock is only held for a maximum of ten seconds
+          ttl: 10,
+        })
+
+        chargeCustomerStep(input)
+
+        releaseLockStep({
+          key: input.order_id,
+        })
+      }
    )
-    const productModuleService = container.resolve(
-      Modules.PRODUCT
+    ```
+
+    In the example above, you create a workflow that acquires a lock on an order using the `acquireLockStep` before charging a customer. The lock is then released using the `releaseLockStep` after the operation is complete.
+
+    This ensures that only one instance of the workflow can modify the order at a time, preventing issues like double charging the customer.
+
+    </TabsContent>
+    <TabsContent value="step">
+
+    ```ts
+    import { Modules } from "@medusajs/framework/utils"
+    import { 
+      createStep,
+      createWorkflow,
+    } from "@medusajs/framework/workflows-sdk"
+
+    const step1 = createStep(
+      "step-1",
+      async ({}, { container }) => {
+        const lockingModuleService = container.resolve(
+          Modules.LOCKING
+        )
+        const productModuleService = container.resolve(
+          Modules.PRODUCT
+        )
+
+        await lockingModuleService.execute("prod_123", async () => {
+          await productModuleService.deleteProduct("prod_123")
+        })
+      } 
    )

-    await lockingModuleService.execute("prod_123", async () => {
-      await productModuleService.deleteProduct("prod_123")
-    })
-  } 
-)
+    export const workflow = createWorkflow(
+      "workflow-1",
+      () => {
+        step1()
+      }
+    )
+    ```

-export const workflow = createWorkflow(
-  "workflow-1",
-  () => {
-    step1()
-  }
-)
-```
+    In the example above, you create a workflow that has a step. In the step, you resolve the services of the Locking and Product modules from the [Medusa container](!docs!/learn/fundamentals/medusa-container).

-In the example above, you create a workflow that has a step. In the step, you resolve the services of the Locking and Product modules from the [Medusa container](!docs!/learn/fundamentals/medusa-container).
+    Then, you use the `execute` method of the Locking Module to acquire a lock for the product with the ID `prod_123` and execute an asynchronous function, which deletes the product.

-Then, you use the `execute` method of the Locking Module to acquire a lock for the product with the ID `prod_123` and execute an asynchronous function, which deletes the product.
+    </TabsContent>
+  </TabsContentWrapper>
+</Tabs>

 ---

@@ -246,7 +246,7 @@ export const generatedEditDates = {
  "references/auth/IAuthModuleService/methods/auth.IAuthModuleService.listAuthIdentities/page.mdx": "2025-10-21T08:10:42.866Z",
  "references/auth/interfaces/auth.FilterableAuthIdentityProps/page.mdx": "2024-12-23T13:57:04.094Z",
  "references/auth/interfaces/auth.IAuthModuleService/page.mdx": "2024-11-25T17:49:28.823Z",
-  "references/core_flows/Cart/Workflows_Cart/functions/core_flows.Cart.Workflows_Cart.completeCartWorkflow/page.mdx": "2025-11-05T12:22:17.415Z",
+  "references/core_flows/Cart/Workflows_Cart/functions/core_flows.Cart.Workflows_Cart.completeCartWorkflow/page.mdx": "2025-11-26T12:02:52.541Z",
  "references/core_flows/Cart/core_flows.Cart.Workflows_Cart/page.mdx": "2025-05-20T07:51:40.757Z",
  "references/core_flows/Common/Steps_Common/functions/core_flows.Common.Steps_Common.createRemoteLinkStep/page.mdx": "2025-04-11T09:04:35.926Z",
  "references/core_flows/Common/Steps_Common/functions/core_flows.Common.Steps_Common.dismissRemoteLinkStep/page.mdx": "2025-04-11T09:04:35.929Z",
@@ -285,17 +285,17 @@ export const generatedEditDates = {
  "references/core_flows/Order/Workflows_Order/functions/core_flows.Order.Workflows_Order.cancelClaimValidateOrderStep/page.mdx": "2025-05-20T07:51:40.794Z",
  "references/core_flows/Order/Workflows_Order/functions/core_flows.Order.Workflows_Order.cancelExchangeValidateOrder/page.mdx": "2025-05-20T07:51:40.794Z",
  "references/core_flows/Order/Workflows_Order/functions/core_flows.Order.Workflows_Order.cancelOrderFulfillmentValidateOrder/page.mdx": "2025-09-12T14:10:31.847Z",
-  "references/core_flows/Order/Workflows_Order/functions/core_flows.Order.Workflows_Order.cancelOrderFulfillmentWorkflow/page.mdx": "2025-11-05T12:22:18.953Z",
+  "references/core_flows/Order/Workflows_Order/functions/core_flows.Order.Workflows_Order.cancelOrderFulfillmentWorkflow/page.mdx": "2025-11-26T12:02:53.343Z",
  "references/core_flows/Order/Workflows_Order/functions/core_flows.Order.Workflows_Order.cancelReceiveReturnValidationStep/page.mdx": "2025-09-12T14:10:32.678Z",
  "references/core_flows/Order/Workflows_Order/functions/core_flows.Order.Workflows_Order.cancelRequestReturnValidationStep/page.mdx": "2025-09-12T14:10:32.687Z",
  "references/core_flows/Order/Workflows_Order/functions/core_flows.Order.Workflows_Order.confirmClaimRequestValidationStep/page.mdx": "2025-09-12T14:10:31.949Z",
-  "references/core_flows/Order/Workflows_Order/functions/core_flows.Order.Workflows_Order.confirmClaimRequestWorkflow/page.mdx": "2025-11-05T12:22:19.065Z",
+  "references/core_flows/Order/Workflows_Order/functions/core_flows.Order.Workflows_Order.confirmClaimRequestWorkflow/page.mdx": "2025-11-26T12:02:53.400Z",
  "references/core_flows/Order/Workflows_Order/functions/core_flows.Order.Workflows_Order.confirmExchangeRequestValidationStep/page.mdx": "2025-09-12T14:10:32.284Z",
-  "references/core_flows/Order/Workflows_Order/functions/core_flows.Order.Workflows_Order.confirmExchangeRequestWorkflow/page.mdx": "2025-11-05T12:22:19.399Z",
+  "references/core_flows/Order/Workflows_Order/functions/core_flows.Order.Workflows_Order.confirmExchangeRequestWorkflow/page.mdx": "2025-11-26T12:02:53.574Z",
  "references/core_flows/Order/Workflows_Order/functions/core_flows.Order.Workflows_Order.confirmOrderEditRequestValidationStep/page.mdx": "2025-09-12T14:10:32.483Z",
-  "references/core_flows/Order/Workflows_Order/functions/core_flows.Order.Workflows_Order.confirmOrderEditRequestWorkflow/page.mdx": "2025-11-05T12:22:19.596Z",
+  "references/core_flows/Order/Workflows_Order/functions/core_flows.Order.Workflows_Order.confirmOrderEditRequestWorkflow/page.mdx": "2025-11-26T12:02:53.678Z",
  "references/core_flows/Order/Workflows_Order/functions/core_flows.Order.Workflows_Order.confirmReceiveReturnValidationStep/page.mdx": "2025-09-12T14:10:32.702Z",
-  "references/core_flows/Order/Workflows_Order/functions/core_flows.Order.Workflows_Order.confirmReturnReceiveWorkflow/page.mdx": "2025-11-05T12:22:19.814Z",
+  "references/core_flows/Order/Workflows_Order/functions/core_flows.Order.Workflows_Order.confirmReturnReceiveWorkflow/page.mdx": "2025-11-26T12:02:53.802Z",
  "references/core_flows/Order/Workflows_Order/functions/core_flows.Order.Workflows_Order.confirmReturnRequestValidationStep/page.mdx": "2025-09-12T14:10:32.719Z",
  "references/core_flows/Order/Workflows_Order/functions/core_flows.Order.Workflows_Order.confirmReturnRequestWorkflow/page.mdx": "2025-11-05T12:22:19.835Z",
  "references/core_flows/Order/Workflows_Order/functions/core_flows.Order.Workflows_Order.createClaimShippingMethodValidationStep/page.mdx": "2025-09-12T14:10:31.968Z",
@@ -305,7 +305,7 @@ export const generatedEditDates = {
  "references/core_flows/Order/Workflows_Order/functions/core_flows.Order.Workflows_Order.createOrderChangeWorkflow/page.mdx": "2025-11-05T12:22:19.257Z",
  "references/core_flows/Order/Workflows_Order/functions/core_flows.Order.Workflows_Order.createOrderEditShippingMethodValidationStep/page.mdx": "2025-09-12T14:10:32.501Z",
  "references/core_flows/Order/Workflows_Order/functions/core_flows.Order.Workflows_Order.createOrderEditShippingMethodWorkflow/page.mdx": "2025-11-05T12:22:19.612Z",
-  "references/core_flows/Order/Workflows_Order/functions/core_flows.Order.Workflows_Order.createOrderFulfillmentWorkflow/page.mdx": "2025-11-05T12:22:19.231Z",
+  "references/core_flows/Order/Workflows_Order/functions/core_flows.Order.Workflows_Order.createOrderFulfillmentWorkflow/page.mdx": "2025-11-26T12:02:53.488Z",
  "references/core_flows/Order/Workflows_Order/functions/core_flows.Order.Workflows_Order.createOrderShipmentWorkflow/page.mdx": "2025-11-05T12:22:19.327Z",
  "references/core_flows/Order/Workflows_Order/functions/core_flows.Order.Workflows_Order.createOrdersWorkflow/page.mdx": "2025-11-05T12:22:19.309Z",
  "references/core_flows/Order/Workflows_Order/functions/core_flows.Order.Workflows_Order.createReturnShippingMethodValidationStep/page.mdx": "2025-09-12T14:10:32.749Z",
@@ -627,14 +627,14 @@ export const generatedEditDates = {
  "references/core_flows/Cart/Steps_Cart/functions/core_flows.Cart.Steps_Cart.setTaxLinesForItemsStep/page.mdx": "2025-10-25T20:13:57.243Z",
  "references/core_flows/Cart/Steps_Cart/functions/core_flows.Cart.Steps_Cart.updateCartsStep/page.mdx": "2025-06-25T10:11:28.124Z",
  "references/core_flows/Cart/Steps_Cart/functions/core_flows.Cart.Steps_Cart.validateCartPaymentsStep/page.mdx": "2025-06-25T10:11:28.183Z",
-  "references/core_flows/Cart/Workflows_Cart/functions/core_flows.Cart.Workflows_Cart.addToCartWorkflow/page.mdx": "2025-11-05T12:22:17.409Z",
+  "references/core_flows/Cart/Workflows_Cart/functions/core_flows.Cart.Workflows_Cart.addToCartWorkflow/page.mdx": "2025-11-26T12:02:52.537Z",
  "references/core_flows/Cart/Workflows_Cart/functions/core_flows.Cart.Workflows_Cart.confirmVariantInventoryWorkflow/page.mdx": "2025-11-05T12:22:17.428Z",
-  "references/core_flows/Cart/Workflows_Cart/functions/core_flows.Cart.Workflows_Cart.createCartWorkflow/page.mdx": "2025-11-05T12:22:17.474Z",
-  "references/core_flows/Cart/Workflows_Cart/functions/core_flows.Cart.Workflows_Cart.createPaymentCollectionForCartWorkflow/page.mdx": "2025-11-05T12:22:17.501Z",
+  "references/core_flows/Cart/Workflows_Cart/functions/core_flows.Cart.Workflows_Cart.createCartWorkflow/page.mdx": "2025-11-26T12:02:52.566Z",
+  "references/core_flows/Cart/Workflows_Cart/functions/core_flows.Cart.Workflows_Cart.createPaymentCollectionForCartWorkflow/page.mdx": "2025-11-26T12:02:52.579Z",
  "references/core_flows/Cart/Workflows_Cart/functions/core_flows.Cart.Workflows_Cart.listShippingOptionsForCartWorkflow/page.mdx": "2025-11-05T12:22:17.524Z",
-  "references/core_flows/Cart/Workflows_Cart/functions/core_flows.Cart.Workflows_Cart.updateCartWorkflow/page.mdx": "2025-11-05T12:22:17.575Z",
-  "references/core_flows/Cart/Workflows_Cart/functions/core_flows.Cart.Workflows_Cart.updateLineItemInCartWorkflow/page.mdx": "2025-11-05T12:22:17.589Z",
-  "references/core_flows/Cart/Workflows_Cart/functions/core_flows.Cart.Workflows_Cart.updateTaxLinesWorkflow/page.mdx": "2025-11-05T12:22:17.606Z",
+  "references/core_flows/Cart/Workflows_Cart/functions/core_flows.Cart.Workflows_Cart.updateCartWorkflow/page.mdx": "2025-11-26T12:02:52.614Z",
+  "references/core_flows/Cart/Workflows_Cart/functions/core_flows.Cart.Workflows_Cart.updateLineItemInCartWorkflow/page.mdx": "2025-11-26T12:02:52.621Z",
+  "references/core_flows/Cart/Workflows_Cart/functions/core_flows.Cart.Workflows_Cart.updateTaxLinesWorkflow/page.mdx": "2025-11-26T12:02:52.628Z",
  "references/core_flows/Cart/core_flows.Cart.Steps_Cart/page.mdx": "2025-02-11T11:36:38.987Z",
  "references/core_flows/Common/Steps_Common/functions/core_flows.Common.Steps_Common.useRemoteQueryStep/page.mdx": "2025-01-13T17:30:23.158Z",
  "references/core_flows/Fulfillment/Steps_Fulfillment/functions/core_flows.Fulfillment.Steps_Fulfillment.createShippingOptionRulesStep/page.mdx": "2025-10-31T09:41:20.667Z",
@@ -1716,8 +1716,8 @@ export const generatedEditDates = {
  "references/core_flows/Cart/Steps_Cart/functions/core_flows.Cart.Steps_Cart.reserveInventoryStep/page.mdx": "2025-04-11T09:04:35.568Z",
  "references/core_flows/Cart/Steps_Cart/functions/core_flows.Cart.Steps_Cart.updateCartPromotionsStep/page.mdx": "2025-11-05T12:22:17.263Z",
  "references/core_flows/Cart/Steps_Cart/functions/core_flows.Cart.Steps_Cart.validateVariantPricesStep/page.mdx": "2025-01-13T18:05:49.333Z",
-  "references/core_flows/Cart/Workflows_Cart/functions/core_flows.Cart.Workflows_Cart.refreshPaymentCollectionForCartWorkflow/page.mdx": "2025-11-05T12:22:17.545Z",
-  "references/core_flows/Cart/Workflows_Cart/functions/core_flows.Cart.Workflows_Cart.updateCartPromotionsWorkflow/page.mdx": "2025-11-05T12:22:17.581Z",
+  "references/core_flows/Cart/Workflows_Cart/functions/core_flows.Cart.Workflows_Cart.refreshPaymentCollectionForCartWorkflow/page.mdx": "2025-11-26T12:02:52.600Z",
+  "references/core_flows/Cart/Workflows_Cart/functions/core_flows.Cart.Workflows_Cart.updateCartPromotionsWorkflow/page.mdx": "2025-11-26T12:02:52.616Z",
  "references/core_flows/Customer/Steps_Customer/functions/core_flows.Customer.Steps_Customer.createCustomerAddressesStep/page.mdx": "2025-05-20T07:51:40.758Z",
  "references/core_flows/Customer/Steps_Customer/functions/core_flows.Customer.Steps_Customer.deleteCustomerAddressesStep/page.mdx": "2025-01-13T17:30:23.181Z",
  "references/core_flows/Customer/Steps_Customer/functions/core_flows.Customer.Steps_Customer.deleteCustomersStep/page.mdx": "2025-01-13T17:30:23.183Z",
@@ -1781,7 +1781,7 @@ export const generatedEditDates = {
  "references/core_flows/Invite/Steps_Invite/functions/core_flows.Invite.Steps_Invite.refreshInviteTokensStep/page.mdx": "2025-04-11T09:04:36.627Z",
  "references/core_flows/Invite/Steps_Invite/functions/core_flows.Invite.Steps_Invite.validateTokenStep/page.mdx": "2025-01-13T17:30:23.565Z",
  "references/core_flows/Line_Item/Steps_Line_Item/functions/core_flows.Line_Item.Steps_Line_Item.deleteLineItemsStep/page.mdx": "2025-01-13T17:30:23.577Z",
-  "references/core_flows/Line_Item/Workflows_Line_Item/functions/core_flows.Line_Item.Workflows_Line_Item.deleteLineItemsWorkflow/page.mdx": "2025-11-05T12:22:18.658Z",
+  "references/core_flows/Line_Item/Workflows_Line_Item/functions/core_flows.Line_Item.Workflows_Line_Item.deleteLineItemsWorkflow/page.mdx": "2025-11-26T12:02:53.180Z",
  "references/core_flows/Order/Steps_Order/functions/core_flows.Order.Steps_Order.cancelOrderChangeStep/page.mdx": "2025-11-05T12:22:18.703Z",
  "references/core_flows/Order/Steps_Order/functions/core_flows.Order.Steps_Order.cancelOrderFulfillmentStep/page.mdx": "2025-05-20T07:51:40.777Z",
  "references/core_flows/Order/Steps_Order/functions/core_flows.Order.Steps_Order.declineOrderChangeStep/page.mdx": "2025-11-05T12:22:18.788Z",
@@ -1905,7 +1905,7 @@ export const generatedEditDates = {
  "references/core_flows/Reservation/Steps_Reservation/functions/core_flows.Reservation.Steps_Reservation.deleteReservationsByLineItemsStep/page.mdx": "2025-01-13T17:30:25.927Z",
  "references/core_flows/Reservation/Steps_Reservation/functions/core_flows.Reservation.Steps_Reservation.deleteReservationsStep/page.mdx": "2025-01-13T17:30:25.928Z",
  "references/core_flows/Reservation/Steps_Reservation/functions/core_flows.Reservation.Steps_Reservation.updateReservationsStep/page.mdx": "2025-04-11T09:04:41.277Z",
-  "references/core_flows/Reservation/Workflows_Reservation/functions/core_flows.Reservation.Workflows_Reservation.createReservationsWorkflow/page.mdx": "2025-11-05T12:22:21.086Z",
+  "references/core_flows/Reservation/Workflows_Reservation/functions/core_flows.Reservation.Workflows_Reservation.createReservationsWorkflow/page.mdx": "2025-11-26T12:02:54.528Z",
  "references/core_flows/Reservation/Workflows_Reservation/functions/core_flows.Reservation.Workflows_Reservation.deleteReservationsByLineItemsWorkflow/page.mdx": "2025-11-05T12:22:21.093Z",
  "references/core_flows/Reservation/Workflows_Reservation/functions/core_flows.Reservation.Workflows_Reservation.deleteReservationsWorkflow/page.mdx": "2025-11-05T12:22:21.090Z",
  "references/core_flows/Reservation/Workflows_Reservation/functions/core_flows.Reservation.Workflows_Reservation.updateReservationsWorkflow/page.mdx": "2025-11-05T12:22:21.099Z",
@@ -2155,7 +2155,7 @@ export const generatedEditDates = {
  "references/types/ModulesSdkTypes/types/types.ModulesSdkTypes.ModuleProvider/page.mdx": "2024-12-09T13:21:35.373Z",
  "references/user/interfaces/user.FindConfig/page.mdx": "2025-05-20T07:51:41.129Z",
  "references/workflows/types/workflows.StepFunction/page.mdx": "2025-05-20T07:51:41.188Z",
-  "references/core_flows/Cart/Workflows_Cart/functions/core_flows.Cart.Workflows_Cart.addShippingMethodToCartWorkflow/page.mdx": "2025-11-05T12:22:17.399Z",
+  "references/core_flows/Cart/Workflows_Cart/functions/core_flows.Cart.Workflows_Cart.addShippingMethodToCartWorkflow/page.mdx": "2025-11-26T12:02:52.532Z",
  "references/fulfillment/IFulfillmentModuleService/methods/fulfillment.IFulfillmentModuleService.validateFulfillmentData/page.mdx": "2025-01-17T16:43:27.199Z",
  "references/fulfillment/interfaces/fulfillment.IFulfillmentModuleService/page.mdx": "2024-12-17T16:57:25.097Z",
  "references/types/CommonTypes/interfaces/types.CommonTypes.RequestQueryFields/page.mdx": "2025-06-25T10:11:37.066Z",
@@ -3360,7 +3360,7 @@ export const generatedEditDates = {
  "references/order/interfaces/order.CreateOrderChangeActionDTO/page.mdx": "2024-12-09T13:22:01.316Z",
  "references/types/DmlTypes/types/types.DmlTypes.EntityIndex/page.mdx": "2025-01-13T18:05:54.118Z",
  "references/types/DmlTypes/types/types.DmlTypes.InferIndexableProperties/page.mdx": "2025-01-13T18:05:54.109Z",
-  "references/core_flows/Cart/Workflows_Cart/functions/core_flows.Cart.Workflows_Cart.transferCartCustomerWorkflow/page.mdx": "2025-11-05T12:22:17.567Z",
+  "references/core_flows/Cart/Workflows_Cart/functions/core_flows.Cart.Workflows_Cart.transferCartCustomerWorkflow/page.mdx": "2025-11-26T12:02:52.610Z",
  "references/core_flows/Common/Steps_Common/functions/core_flows.Common.Steps_Common.validatePresenceOfStep/page.mdx": "2025-01-13T17:30:23.159Z",
  "references/core_flows/Fulfillment/Steps_Fulfillment/functions/core_flows.Fulfillment.Steps_Fulfillment.buildPriceSet/page.mdx": "2024-12-10T14:54:58.496Z",
  "references/core_flows/Order/Steps_Order/functions/core_flows.Order.Steps_Order.registerOrderChangesStep/page.mdx": "2025-01-13T17:30:23.749Z",
@@ -5811,8 +5811,8 @@ export const generatedEditDates = {
  "references/utils/PromotionUtils/enums/utils.PromotionUtils.PromotionStatus/page.mdx": "2025-01-17T16:43:30.762Z",
  "references/core_flows/Cart/Steps_Cart/functions/core_flows.Cart.Steps_Cart.validateAndReturnShippingMethodsDataStep/page.mdx": "2025-03-04T13:33:40.459Z",
  "references/core_flows/Cart/Steps_Cart/functions/core_flows.Cart.Steps_Cart.validateCartStep/page.mdx": "2025-05-20T07:51:40.753Z",
-  "references/core_flows/Cart/Workflows_Cart/functions/core_flows.Cart.Workflows_Cart.refreshCartItemsWorkflow/page.mdx": "2025-11-05T12:22:17.535Z",
-  "references/core_flows/Cart/Workflows_Cart/functions/core_flows.Cart.Workflows_Cart.refreshCartShippingMethodsWorkflow/page.mdx": "2025-11-05T12:22:17.540Z",
+  "references/core_flows/Cart/Workflows_Cart/functions/core_flows.Cart.Workflows_Cart.refreshCartItemsWorkflow/page.mdx": "2025-11-26T12:02:52.593Z",
+  "references/core_flows/Cart/Workflows_Cart/functions/core_flows.Cart.Workflows_Cart.refreshCartShippingMethodsWorkflow/page.mdx": "2025-11-26T12:02:52.596Z",
  "references/core_flows/Order/Workflows_Order/functions/core_flows.Order.Workflows_Order.createOrUpdateOrderPaymentCollectionWorkflow/page.mdx": "2025-11-05T12:22:19.242Z",
  "references/core_flows/Payment_Collection/Workflows_Payment_Collection/functions/core_flows.Payment_Collection.Workflows_Payment_Collection.deleteRefundReasonsWorkflow/page.mdx": "2025-11-05T12:22:20.316Z",
  "references/core_flows/Product/Steps_Product/functions/core_flows.Product.Steps_Product.getVariantAvailabilityStep/page.mdx": "2025-01-17T16:43:24.975Z",
@@ -6011,7 +6011,7 @@ export const generatedEditDates = {
  "app/how-to-tutorials/page.mdx": "2025-03-10T09:33:49.208Z",
  "app/tools/page.mdx": "2025-03-10T12:38:56.520Z",
  "app/references-overview/page.mdx": "2025-03-10T12:55:49.803Z",
-  "app/infrastructure-modules/locking/page.mdx": "2025-04-17T08:29:00.564Z",
+  "app/infrastructure-modules/locking/page.mdx": "2025-11-26T11:45:10.290Z",
  "app/infrastructure-modules/locking/postgres/page.mdx": "2025-03-27T14:53:13.310Z",
  "app/infrastructure-modules/locking/redis/page.mdx": "2025-06-24T08:50:10.115Z",
  "references/locking/interfaces/locking.ILockingModule/page.mdx": "2025-10-21T08:10:48.921Z",
@@ -6127,23 +6127,23 @@ export const generatedEditDates = {
  "references/types/FileTypes/types/types.FileTypes.FileAccessPermission/page.mdx": "2025-04-23T07:49:49.087Z",
  "references/workflows/types/workflows.Void/page.mdx": "2025-04-23T07:49:56.553Z",
  "references/core_flows/Draft_Order/Steps_Draft_Order/functions/core_flows.Draft_Order.Steps_Draft_Order.validateDraftOrderStep/page.mdx": "2025-09-12T14:10:30.701Z",
-  "references/core_flows/Draft_Order/Workflows_Draft_Order/functions/core_flows.Draft_Order.Workflows_Draft_Order.addDraftOrderItemsWorkflow/page.mdx": "2025-11-05T12:22:17.860Z",
-  "references/core_flows/Draft_Order/Workflows_Draft_Order/functions/core_flows.Draft_Order.Workflows_Draft_Order.addDraftOrderPromotionWorkflow/page.mdx": "2025-11-05T12:22:17.881Z",
-  "references/core_flows/Draft_Order/Workflows_Draft_Order/functions/core_flows.Draft_Order.Workflows_Draft_Order.addDraftOrderShippingMethodsWorkflow/page.mdx": "2025-11-05T12:22:17.893Z",
-  "references/core_flows/Draft_Order/Workflows_Draft_Order/functions/core_flows.Draft_Order.Workflows_Draft_Order.beginDraftOrderEditWorkflow/page.mdx": "2025-11-05T12:22:17.909Z",
-  "references/core_flows/Draft_Order/Workflows_Draft_Order/functions/core_flows.Draft_Order.Workflows_Draft_Order.cancelDraftOrderEditWorkflow/page.mdx": "2025-11-05T12:22:17.913Z",
-  "references/core_flows/Draft_Order/Workflows_Draft_Order/functions/core_flows.Draft_Order.Workflows_Draft_Order.confirmDraftOrderEditWorkflow/page.mdx": "2025-11-05T12:22:17.926Z",
-  "references/core_flows/Draft_Order/Workflows_Draft_Order/functions/core_flows.Draft_Order.Workflows_Draft_Order.convertDraftOrderWorkflow/page.mdx": "2025-11-05T12:22:17.954Z",
-  "references/core_flows/Draft_Order/Workflows_Draft_Order/functions/core_flows.Draft_Order.Workflows_Draft_Order.removeDraftOrderActionItemWorkflow/page.mdx": "2025-11-05T12:22:17.970Z",
-  "references/core_flows/Draft_Order/Workflows_Draft_Order/functions/core_flows.Draft_Order.Workflows_Draft_Order.removeDraftOrderActionShippingMethodWorkflow/page.mdx": "2025-11-05T12:22:17.985Z",
-  "references/core_flows/Draft_Order/Workflows_Draft_Order/functions/core_flows.Draft_Order.Workflows_Draft_Order.removeDraftOrderPromotionsWorkflow/page.mdx": "2025-11-05T12:22:18.001Z",
-  "references/core_flows/Draft_Order/Workflows_Draft_Order/functions/core_flows.Draft_Order.Workflows_Draft_Order.removeDraftOrderShippingMethodWorkflow/page.mdx": "2025-11-05T12:22:18.105Z",
-  "references/core_flows/Draft_Order/Workflows_Draft_Order/functions/core_flows.Draft_Order.Workflows_Draft_Order.requestDraftOrderEditWorkflow/page.mdx": "2025-11-05T12:22:18.013Z",
-  "references/core_flows/Draft_Order/Workflows_Draft_Order/functions/core_flows.Draft_Order.Workflows_Draft_Order.updateDraftOrderActionItemWorkflow/page.mdx": "2025-11-05T12:22:18.030Z",
-  "references/core_flows/Draft_Order/Workflows_Draft_Order/functions/core_flows.Draft_Order.Workflows_Draft_Order.updateDraftOrderActionShippingMethodWorkflow/page.mdx": "2025-11-05T12:22:18.043Z",
-  "references/core_flows/Draft_Order/Workflows_Draft_Order/functions/core_flows.Draft_Order.Workflows_Draft_Order.updateDraftOrderItemWorkflow/page.mdx": "2025-11-05T12:22:18.059Z",
-  "references/core_flows/Draft_Order/Workflows_Draft_Order/functions/core_flows.Draft_Order.Workflows_Draft_Order.updateDraftOrderShippingMethodWorkflow/page.mdx": "2025-11-05T12:22:18.094Z",
-  "references/core_flows/Draft_Order/Workflows_Draft_Order/functions/core_flows.Draft_Order.Workflows_Draft_Order.updateDraftOrderWorkflow/page.mdx": "2025-11-05T12:22:18.120Z",
+  "references/core_flows/Draft_Order/Workflows_Draft_Order/functions/core_flows.Draft_Order.Workflows_Draft_Order.addDraftOrderItemsWorkflow/page.mdx": "2025-11-26T12:02:52.767Z",
+  "references/core_flows/Draft_Order/Workflows_Draft_Order/functions/core_flows.Draft_Order.Workflows_Draft_Order.addDraftOrderPromotionWorkflow/page.mdx": "2025-11-26T12:02:52.774Z",
+  "references/core_flows/Draft_Order/Workflows_Draft_Order/functions/core_flows.Draft_Order.Workflows_Draft_Order.addDraftOrderShippingMethodsWorkflow/page.mdx": "2025-11-26T12:02:52.784Z",
+  "references/core_flows/Draft_Order/Workflows_Draft_Order/functions/core_flows.Draft_Order.Workflows_Draft_Order.beginDraftOrderEditWorkflow/page.mdx": "2025-11-26T12:02:52.792Z",
+  "references/core_flows/Draft_Order/Workflows_Draft_Order/functions/core_flows.Draft_Order.Workflows_Draft_Order.cancelDraftOrderEditWorkflow/page.mdx": "2025-11-26T12:02:52.794Z",
+  "references/core_flows/Draft_Order/Workflows_Draft_Order/functions/core_flows.Draft_Order.Workflows_Draft_Order.confirmDraftOrderEditWorkflow/page.mdx": "2025-11-26T12:02:52.802Z",
+  "references/core_flows/Draft_Order/Workflows_Draft_Order/functions/core_flows.Draft_Order.Workflows_Draft_Order.convertDraftOrderWorkflow/page.mdx": "2025-11-26T12:02:52.817Z",
+  "references/core_flows/Draft_Order/Workflows_Draft_Order/functions/core_flows.Draft_Order.Workflows_Draft_Order.removeDraftOrderActionItemWorkflow/page.mdx": "2025-11-26T12:02:52.824Z",
+  "references/core_flows/Draft_Order/Workflows_Draft_Order/functions/core_flows.Draft_Order.Workflows_Draft_Order.removeDraftOrderActionShippingMethodWorkflow/page.mdx": "2025-11-26T12:02:52.832Z",
+  "references/core_flows/Draft_Order/Workflows_Draft_Order/functions/core_flows.Draft_Order.Workflows_Draft_Order.removeDraftOrderPromotionsWorkflow/page.mdx": "2025-11-26T12:02:52.838Z",
+  "references/core_flows/Draft_Order/Workflows_Draft_Order/functions/core_flows.Draft_Order.Workflows_Draft_Order.removeDraftOrderShippingMethodWorkflow/page.mdx": "2025-11-26T12:02:52.893Z",
+  "references/core_flows/Draft_Order/Workflows_Draft_Order/functions/core_flows.Draft_Order.Workflows_Draft_Order.requestDraftOrderEditWorkflow/page.mdx": "2025-11-26T12:02:52.846Z",
+  "references/core_flows/Draft_Order/Workflows_Draft_Order/functions/core_flows.Draft_Order.Workflows_Draft_Order.updateDraftOrderActionItemWorkflow/page.mdx": "2025-11-26T12:02:52.853Z",
+  "references/core_flows/Draft_Order/Workflows_Draft_Order/functions/core_flows.Draft_Order.Workflows_Draft_Order.updateDraftOrderActionShippingMethodWorkflow/page.mdx": "2025-11-26T12:02:52.860Z",
+  "references/core_flows/Draft_Order/Workflows_Draft_Order/functions/core_flows.Draft_Order.Workflows_Draft_Order.updateDraftOrderItemWorkflow/page.mdx": "2025-11-26T12:02:52.868Z",
+  "references/core_flows/Draft_Order/Workflows_Draft_Order/functions/core_flows.Draft_Order.Workflows_Draft_Order.updateDraftOrderShippingMethodWorkflow/page.mdx": "2025-11-26T12:02:52.887Z",
+  "references/core_flows/Draft_Order/Workflows_Draft_Order/functions/core_flows.Draft_Order.Workflows_Draft_Order.updateDraftOrderWorkflow/page.mdx": "2025-11-26T12:02:52.899Z",
  "references/core_flows/Draft_Order/Workflows_Draft_Order/variables/core_flows.Draft_Order.Workflows_Draft_Order.addDraftOrderItemsWorkflowId/page.mdx": "2025-04-23T16:21:18.492Z",
  "references/core_flows/Draft_Order/Workflows_Draft_Order/variables/core_flows.Draft_Order.Workflows_Draft_Order.addDraftOrderPromotionWorkflowId/page.mdx": "2025-04-23T16:21:18.508Z",
  "references/core_flows/Draft_Order/Workflows_Draft_Order/variables/core_flows.Draft_Order.Workflows_Draft_Order.addDraftOrderShippingMethodsWorkflowId/page.mdx": "2025-04-23T16:21:18.524Z",
@@ -28,6 +28,12 @@ This workflow adds a shipping method to a cart. It's executed by the

 You can use this workflow within your own customizations or custom workflows, allowing you to wrap custom logic around adding a shipping method to the cart.

+:::note
+
+If you use this workflow in another, you must acquire a lock before running it and release the lock after. Learn more in the [Locking Operations in Workflows](https://docs.medusajs.com/learn/fundamentals/workflows/locks#locks-in-nested-workflows) guide.
+
+:::
+
 <SourceCodeLink link="https://github.com/medusajs/medusa/blob/147ce2fdc35366e591f552404ec949f6a5b92a11/packages/core/core-flows/src/cart/workflows/add-shipping-method-to-cart.ts#L83" />

 ## Examples
@@ -152,6 +158,7 @@ import { addShippingMethodToCartWorkflow } from "@medusajs/medusa/core-flows"
 const myWorkflow = createWorkflow(
  "my-workflow",
  () => {
+    // Acquire lock from nested workflow here
    const result = addShippingMethodToCartWorkflow
      .runAsStep({
        input: {
@@ -168,6 +175,7 @@ const myWorkflow = createWorkflow(
          ]
        }
      })
+    // Release lock here
  }
 )
 ```
@@ -30,6 +30,12 @@ This workflow adds a product variant to a cart as a line item. It's executed by
 You can use this workflow within your own customizations or custom workflows, allowing you to wrap custom logic around adding an item to the cart.
 For example, you can use this workflow to add a line item to the cart with a custom price.

+:::note
+
+If you use this workflow in another, you must acquire a lock before running it and release the lock after. Learn more in the [Locking Operations in Workflows](https://docs.medusajs.com/learn/fundamentals/workflows/locks#locks-in-nested-workflows) guide.
+
+:::
+
 <SourceCodeLink link="https://github.com/medusajs/medusa/blob/147ce2fdc35366e591f552404ec949f6a5b92a11/packages/core/core-flows/src/cart/workflows/add-to-cart.ts#L114" />

 ## Examples
@@ -154,6 +160,7 @@ import { addToCartWorkflow } from "@medusajs/medusa/core-flows"
 const myWorkflow = createWorkflow(
  "my-workflow",
  () => {
+    // Acquire lock from nested workflow here
    const result = addToCartWorkflow
      .runAsStep({
        input: {
@@ -170,6 +177,7 @@ const myWorkflow = createWorkflow(
          ]
        }
      })
+    // Release lock here
  }
 )
 ```
@@ -28,6 +28,12 @@ You can use this workflow within your own customizations or custom workflows, al
 For example, in the [Subscriptions recipe](https://docs.medusajs.com/resources/recipes/subscriptions/examples/standard#create-workflow),
 this workflow is used within another workflow that creates a subscription order.

+:::note
+
+If you use this workflow in another, you must acquire a lock before running it and release the lock after. Learn more in the [Locking Operations in Workflows](https://docs.medusajs.com/learn/fundamentals/workflows/locks#locks-in-nested-workflows) guide.
+
+:::
+
 <SourceCodeLink link="https://github.com/medusajs/medusa/blob/147ce2fdc35366e591f552404ec949f6a5b92a11/packages/core/core-flows/src/cart/workflows/complete-cart.ts#L93" />

 ## Examples
@@ -122,12 +128,14 @@ import { completeCartWorkflow } from "@medusajs/medusa/core-flows"
 const myWorkflow = createWorkflow(
  "my-workflow",
  () => {
+    // Acquire lock from nested workflow here
    const result = completeCartWorkflow
      .runAsStep({
        input: {
          id: "cart_123"
        }
      })
+    // Release lock here
  }
 )
 ```
@@ -31,6 +31,12 @@ This workflow has a hook that allows you to perform custom actions on the create

 You can also use this workflow within your customizations or your own custom workflows, allowing you to wrap custom logic around cart creation.

+:::note
+
+If you use this workflow in another, you must acquire a lock before running it and release the lock after. Learn more in the [Locking Operations in Workflows](https://docs.medusajs.com/learn/fundamentals/workflows/locks#locks-in-nested-workflows) guide.
+
+:::
+
 <SourceCodeLink link="https://github.com/medusajs/medusa/blob/147ce2fdc35366e591f552404ec949f6a5b92a11/packages/core/core-flows/src/cart/workflows/create-carts.ts#L111" />

 ## Examples
@@ -149,6 +155,7 @@ import { createCartWorkflow } from "@medusajs/medusa/core-flows"
 const myWorkflow = createWorkflow(
  "my-workflow",
  () => {
+    // Acquire lock from nested workflow here
    const result = createCartWorkflow
      .runAsStep({
        input: {
@@ -163,6 +170,7 @@ const myWorkflow = createWorkflow(
          }
        }
      })
+    // Release lock here
  }
 )
 ```
@@ -20,6 +20,12 @@ This workflow creates a payment collection for a cart. It's executed by the

 You can use this workflow within your own customizations or custom workflows, allowing you to wrap custom logic around adding creating a payment collection for a cart.

+:::note
+
+If you use this workflow in another, you must acquire a lock before running it and release the lock after. Learn more in the [Locking Operations in Workflows](https://docs.medusajs.com/learn/fundamentals/workflows/locks#locks-in-nested-workflows) guide.
+
+:::
+
 <SourceCodeLink link="https://github.com/medusajs/medusa/blob/147ce2fdc35366e591f552404ec949f6a5b92a11/packages/core/core-flows/src/cart/workflows/create-payment-collection-for-cart.ts#L84" />

 ## Examples
@@ -123,6 +129,7 @@ import { createPaymentCollectionForCartWorkflow } from "@medusajs/medusa/core-fl
 const myWorkflow = createWorkflow(
  "my-workflow",
  () => {
+    // Acquire lock from nested workflow here
    const result = createPaymentCollectionForCartWorkflow
      .runAsStep({
        input: {
@@ -132,6 +139,7 @@ const myWorkflow = createWorkflow(
          }
        }
      })
+    // Release lock here
  }
 )
 ```
@@ -31,6 +31,12 @@ is added to the cart.
 You can use this workflow within your own customizations or custom workflows, allowing you to refresh the cart after making updates to it in your
 custom flows.

+:::note
+
+If you use this workflow in another, you must acquire a lock before running it and release the lock after. Learn more in the [Locking Operations in Workflows](https://docs.medusajs.com/learn/fundamentals/workflows/locks#locks-in-nested-workflows) guide.
+
+:::
+
 <SourceCodeLink link="https://github.com/medusajs/medusa/blob/147ce2fdc35366e591f552404ec949f6a5b92a11/packages/core/core-flows/src/cart/workflows/refresh-cart-items.ts#L118" />

 ## Examples
@@ -125,12 +131,14 @@ import { refreshCartItemsWorkflow } from "@medusajs/medusa/core-flows"
 const myWorkflow = createWorkflow(
  "my-workflow",
  () => {
+    // Acquire lock from nested workflow here
    const result = refreshCartItemsWorkflow
      .runAsStep({
        input: {
          cart_id: "cart_123",
        }
      })
+    // Release lock here
  }
 )
 ```
@@ -20,6 +20,12 @@ and retrieve their correct pricing after a cart update. This workflow is used by

 You can use this workflow within your own customizations or custom workflows, allowing you to refresh the cart's shipping method after making updates to the cart.

+:::note
+
+If you use this workflow in another, you must acquire a lock before running it and release the lock after. Learn more in the [Locking Operations in Workflows](https://docs.medusajs.com/learn/fundamentals/workflows/locks#locks-in-nested-workflows) guide.
+
+:::
+
 <SourceCodeLink link="https://github.com/medusajs/medusa/blob/147ce2fdc35366e591f552404ec949f6a5b92a11/packages/core/core-flows/src/cart/workflows/refresh-cart-shipping-methods.ts#L54" />

 ## Examples
@@ -114,12 +120,14 @@ import { refreshCartShippingMethodsWorkflow } from "@medusajs/medusa/core-flows"
 const myWorkflow = createWorkflow(
  "my-workflow",
  () => {
+    // Acquire lock from nested workflow here
    const result = refreshCartShippingMethodsWorkflow
      .runAsStep({
        input: {
          cart_id: "cart_123",
        }
      })
+    // Release lock here
  }
 )
 ```
@@ -25,6 +25,12 @@ payment collection after an update.
 You can use this workflow within your own customizations or custom workflows, allowing you to refresh the cart's payment collection after making updates to it in your
 custom flows.

+:::note
+
+If you use this workflow in another, you must acquire a lock before running it and release the lock after. Learn more in the [Locking Operations in Workflows](https://docs.medusajs.com/learn/fundamentals/workflows/locks#locks-in-nested-workflows) guide.
+
+:::
+
 <SourceCodeLink link="https://github.com/medusajs/medusa/blob/147ce2fdc35366e591f552404ec949f6a5b92a11/packages/core/core-flows/src/cart/workflows/refresh-payment-collection.ts#L58" />

 ## Examples
@@ -119,12 +125,14 @@ import { refreshPaymentCollectionForCartWorkflow } from "@medusajs/medusa/core-f
 const myWorkflow = createWorkflow(
  "my-workflow",
  () => {
+    // Acquire lock from nested workflow here
    const result = refreshPaymentCollectionForCartWorkflow
      .runAsStep({
        input: {
          cart_id: "cart_123",
        }
      })
+    // Release lock here
  }
 )
 ```
@@ -29,6 +29,12 @@ by the [Set Cart's Customer Store API Route](https://docs.medusajs.com/api/store

 You can use this workflow within your own customizations or custom workflows, allowing you to set the cart's customer within your custom flows.

+:::note
+
+If you use this workflow in another, you must acquire a lock before running it and release the lock after. Learn more in the [Locking Operations in Workflows](https://docs.medusajs.com/learn/fundamentals/workflows/locks#locks-in-nested-workflows) guide.
+
+:::
+
 <SourceCodeLink link="https://github.com/medusajs/medusa/blob/147ce2fdc35366e591f552404ec949f6a5b92a11/packages/core/core-flows/src/cart/workflows/transfer-cart-customer.ts#L54" />

 ## Examples
@@ -126,6 +132,7 @@ import { transferCartCustomerWorkflow } from "@medusajs/medusa/core-flows"
 const myWorkflow = createWorkflow(
  "my-workflow",
  () => {
+    // Acquire lock from nested workflow here
    const result = transferCartCustomerWorkflow
      .runAsStep({
        input: {
@@ -133,6 +140,7 @@ const myWorkflow = createWorkflow(
          customer_id: "cus_123"
        }
      })
+    // Release lock here
  }
 )
 ```
@@ -24,6 +24,12 @@ that need to be applied to the cart's line items and shipping methods based on t

 You can use this workflow within your own customizations or custom workflows, allowing you to update a cart's promotions within your custom flows.

+:::note
+
+If you use this workflow in another, you must acquire a lock before running it and release the lock after. Learn more in the [Locking Operations in Workflows](https://docs.medusajs.com/learn/fundamentals/workflows/locks#locks-in-nested-workflows) guide.
+
+:::
+
 <SourceCodeLink link="https://github.com/medusajs/medusa/blob/147ce2fdc35366e591f552404ec949f6a5b92a11/packages/core/core-flows/src/cart/workflows/update-cart-promotions.ts#L77" />

 ## Examples
@@ -127,6 +133,7 @@ import { updateCartPromotionsWorkflow } from "@medusajs/medusa/core-flows"
 const myWorkflow = createWorkflow(
  "my-workflow",
  () => {
+    // Acquire lock from nested workflow here
    const result = updateCartPromotionsWorkflow
      .runAsStep({
        input: {
@@ -136,6 +143,7 @@ const myWorkflow = createWorkflow(
          action: PromotionActions.ADD,
        }
      })
+    // Release lock here
  }
 )
 ```
@@ -38,6 +38,12 @@ then update any associated details related to the cart in the workflow's hook.

 You can also use this workflow within your customizations or your own custom workflows, allowing you to wrap custom logic around updating a cart.

+:::note
+
+If you use this workflow in another, you must acquire a lock before running it and release the lock after. Learn more in the [Locking Operations in Workflows](https://docs.medusajs.com/learn/fundamentals/workflows/locks#locks-in-nested-workflows) guide.
+
+:::
+
 <SourceCodeLink link="https://github.com/medusajs/medusa/blob/147ce2fdc35366e591f552404ec949f6a5b92a11/packages/core/core-flows/src/cart/workflows/update-cart.ts#L82" />

 ## Examples
@@ -171,6 +177,7 @@ import { updateCartWorkflow } from "@medusajs/medusa/core-flows"
 const myWorkflow = createWorkflow(
  "my-workflow",
  () => {
+    // Acquire lock from nested workflow here
    const result = updateCartWorkflow
      .runAsStep({
        input: {
@@ -190,6 +197,7 @@ const myWorkflow = createWorkflow(
          }
        }
      })
+    // Release lock here
  }
 )
 ```
@@ -30,6 +30,12 @@ This workflow is executed by the [Update Line Item Store API Route](https://docs

 You can use this workflow within your own customizations or custom workflows, allowing you to update a line item's details in your custom flows.

+:::note
+
+If you use this workflow in another, you must acquire a lock before running it and release the lock after. Learn more in the [Locking Operations in Workflows](https://docs.medusajs.com/learn/fundamentals/workflows/locks#locks-in-nested-workflows) guide.
+
+:::
+
 <SourceCodeLink link="https://github.com/medusajs/medusa/blob/147ce2fdc35366e591f552404ec949f6a5b92a11/packages/core/core-flows/src/cart/workflows/update-line-item-in-cart.ts#L111" />

 ## Examples
@@ -136,6 +142,7 @@ import { updateLineItemInCartWorkflow } from "@medusajs/medusa/core-flows"
 const myWorkflow = createWorkflow(
  "my-workflow",
  () => {
+    // Acquire lock from nested workflow here
    const result = updateLineItemInCartWorkflow
      .runAsStep({
        input: {
@@ -146,6 +153,7 @@ const myWorkflow = createWorkflow(
          }
        }
      })
+    // Release lock here
  }
 )
 ```
@@ -20,6 +20,12 @@ by the [Calculate Taxes Store API Route](https://docs.medusajs.com/api/store#car

 You can use this workflow within your own customizations or custom workflows, allowing you to update a cart's tax lines in your custom flows.

+:::note
+
+If you use this workflow in another, you must acquire a lock before running it and release the lock after. Learn more in the [Locking Operations in Workflows](https://docs.medusajs.com/learn/fundamentals/workflows/locks#locks-in-nested-workflows) guide.
+
+:::
+
 <SourceCodeLink link="https://github.com/medusajs/medusa/blob/147ce2fdc35366e591f552404ec949f6a5b92a11/packages/core/core-flows/src/cart/workflows/update-tax-lines.ts#L124" />

 ## Examples
@@ -114,12 +120,14 @@ import { updateTaxLinesWorkflow } from "@medusajs/medusa/core-flows"
 const myWorkflow = createWorkflow(
  "my-workflow",
  () => {
+    // Acquire lock from nested workflow here
    const result = updateTaxLinesWorkflow
      .runAsStep({
        input: {
          cart_id: "cart_123",
        }
      })
+    // Release lock here
  }
 )
 ```
@@ -23,6 +23,12 @@ This workflow adds items to a draft order. It's used by the
 You can use this workflow within your customizations or your own custom workflows, allowing you to wrap custom logic around adding items to
 a draft order.

+:::note
+
+If you use this workflow in another, you must acquire a lock before running it and release the lock after. Learn more in the [Locking Operations in Workflows](https://docs.medusajs.com/learn/fundamentals/workflows/locks#locks-in-nested-workflows) guide.
+
+:::
+
 <SourceCodeLink link="https://github.com/medusajs/medusa/blob/147ce2fdc35366e591f552404ec949f6a5b92a11/packages/core/core-flows/src/draft-order/workflows/add-draft-order-items.ts#L55" />

 ## Examples
@@ -129,6 +135,7 @@ import { addDraftOrderItemsWorkflow } from "@medusajs/medusa/core-flows"
 const myWorkflow = createWorkflow(
  "my-workflow",
  () => {
+    // Acquire lock from nested workflow here
    const result = addDraftOrderItemsWorkflow
      .runAsStep({
        input: {
@@ -139,6 +146,7 @@ const myWorkflow = createWorkflow(
          }]
        }
      })
+    // Release lock here
  }
 )
 ```
@@ -20,6 +20,12 @@ This workflow adds promotions to a draft order. It's used by the
 You can use this workflow within your customizations or your own custom workflows, allowing you to wrap custom logic around adding promotions to
 a draft order.

+:::note
+
+If you use this workflow in another, you must acquire a lock before running it and release the lock after. Learn more in the [Locking Operations in Workflows](https://docs.medusajs.com/learn/fundamentals/workflows/locks#locks-in-nested-workflows) guide.
+
+:::
+
 <SourceCodeLink link="https://github.com/medusajs/medusa/blob/147ce2fdc35366e591f552404ec949f6a5b92a11/packages/core/core-flows/src/draft-order/workflows/add-draft-order-promotions.ts#L64" />

 ## Examples
@@ -117,6 +123,7 @@ import { addDraftOrderPromotionWorkflow } from "@medusajs/medusa/core-flows"
 const myWorkflow = createWorkflow(
  "my-workflow",
  () => {
+    // Acquire lock from nested workflow here
    const result = addDraftOrderPromotionWorkflow
      .runAsStep({
        input: {
@@ -124,6 +131,7 @@ const myWorkflow = createWorkflow(
          promo_codes: ["PROMO_CODE_1", "PROMO_CODE_2"]
        }
      })
+    // Release lock here
  }
 )
 ```
@@ -21,6 +21,12 @@ This workflow adds shipping methods to a draft order. It's used by the
 You can use this workflow within your customizations or your own custom workflows, allowing you to wrap custom logic around adding shipping methods to
 a draft order.

+:::note
+
+If you use this workflow in another, you must acquire a lock before running it and release the lock after. Learn more in the [Locking Operations in Workflows](https://docs.medusajs.com/learn/fundamentals/workflows/locks#locks-in-nested-workflows) guide.
+
+:::
+
 <SourceCodeLink link="https://github.com/medusajs/medusa/blob/147ce2fdc35366e591f552404ec949f6a5b92a11/packages/core/core-flows/src/draft-order/workflows/add-draft-order-shipping-methods.ts#L100" />

 ## Examples
@@ -121,6 +127,7 @@ import { addDraftOrderShippingMethodsWorkflow } from "@medusajs/medusa/core-flow
 const myWorkflow = createWorkflow(
  "my-workflow",
  () => {
+    // Acquire lock from nested workflow here
    const result = addDraftOrderShippingMethodsWorkflow
      .runAsStep({
        input: {
@@ -129,6 +136,7 @@ const myWorkflow = createWorkflow(
          custom_amount: 10
        }
      })
+    // Release lock here
  }
 )
 ```
@@ -22,6 +22,12 @@ The draft order edit can later be requested using [requestDraftOrderEditWorkflow
 You can use this workflow within your customizations or your own custom workflows, allowing you to wrap custom logic around
 creating a draft order edit request.

+:::note
+
+If you use this workflow in another, you must acquire a lock before running it and release the lock after. Learn more in the [Locking Operations in Workflows](https://docs.medusajs.com/learn/fundamentals/workflows/locks#locks-in-nested-workflows) guide.
+
+:::
+
 <SourceCodeLink link="https://github.com/medusajs/medusa/blob/147ce2fdc35366e591f552404ec949f6a5b92a11/packages/core/core-flows/src/draft-order/workflows/begin-draft-order-edit.ts#L36" />

 ## Examples
@@ -116,12 +122,14 @@ import { beginDraftOrderEditWorkflow } from "@medusajs/medusa/core-flows"
 const myWorkflow = createWorkflow(
  "my-workflow",
  () => {
+    // Acquire lock from nested workflow here
    const result = beginDraftOrderEditWorkflow
      .runAsStep({
        input: {
          order_id: "order_123",
        }
      })
+    // Release lock here
  }
 )
 ```
@@ -20,6 +20,12 @@ This workflow cancels a draft order edit. It's used by the
 You can use this workflow within your customizations or your own custom workflows, allowing you to wrap custom logic around
 cancelling a draft order edit.

+:::note
+
+If you use this workflow in another, you must acquire a lock before running it and release the lock after. Learn more in the [Locking Operations in Workflows](https://docs.medusajs.com/learn/fundamentals/workflows/locks#locks-in-nested-workflows) guide.
+
+:::
+
 <SourceCodeLink link="https://github.com/medusajs/medusa/blob/147ce2fdc35366e591f552404ec949f6a5b92a11/packages/core/core-flows/src/draft-order/workflows/cancel-draft-order-edit.ts#L53" />

 ## Examples
@@ -114,12 +120,14 @@ import { cancelDraftOrderEditWorkflow } from "@medusajs/medusa/core-flows"
 const myWorkflow = createWorkflow(
  "my-workflow",
  () => {
+    // Acquire lock from nested workflow here
    const result = cancelDraftOrderEditWorkflow
      .runAsStep({
        input: {
          order_id: "order_123",
        }
      })
+    // Release lock here
  }
 )
 ```
@@ -23,6 +23,12 @@ This workflow confirms a draft order edit. It's used by the
 You can use this workflow within your customizations or your own custom workflows, allowing you to wrap custom logic around
 confirming a draft order edit.

+:::note
+
+If you use this workflow in another, you must acquire a lock before running it and release the lock after. Learn more in the [Locking Operations in Workflows](https://docs.medusajs.com/learn/fundamentals/workflows/locks#locks-in-nested-workflows) guide.
+
+:::
+
 <SourceCodeLink link="https://github.com/medusajs/medusa/blob/147ce2fdc35366e591f552404ec949f6a5b92a11/packages/core/core-flows/src/draft-order/workflows/confirm-draft-order-edit.ts#L49" />

 ## Examples
@@ -120,6 +126,7 @@ import { confirmDraftOrderEditWorkflow } from "@medusajs/medusa/core-flows"
 const myWorkflow = createWorkflow(
  "my-workflow",
  () => {
+    // Acquire lock from nested workflow here
    const result = confirmDraftOrderEditWorkflow
      .runAsStep({
        input: {
@@ -127,6 +134,7 @@ const myWorkflow = createWorkflow(
          confirmed_by: "user_123",
        }
      })
+    // Release lock here
  }
 )
 ```
@@ -20,6 +20,12 @@ This workflow converts a draft order to a pending order. It's used by the
 You can use this workflow within your customizations or your own custom workflows, allowing you to wrap custom logic around
 converting a draft order to a pending order.

+:::note
+
+If you use this workflow in another, you must acquire a lock before running it and release the lock after. Learn more in the [Locking Operations in Workflows](https://docs.medusajs.com/learn/fundamentals/workflows/locks#locks-in-nested-workflows) guide.
+
+:::
+
 <SourceCodeLink link="https://github.com/medusajs/medusa/blob/147ce2fdc35366e591f552404ec949f6a5b92a11/packages/core/core-flows/src/draft-order/workflows/convert-draft-order.ts#L99" />

 ## Examples
@@ -114,12 +120,14 @@ import { convertDraftOrderWorkflow } from "@medusajs/medusa/core-flows"
 const myWorkflow = createWorkflow(
  "my-workflow",
  () => {
+    // Acquire lock from nested workflow here
    const result = convertDraftOrderWorkflow
      .runAsStep({
        input: {
          id: "order_123",
        }
      })
+    // Release lock here
  }
 )
 ```
@@ -20,6 +20,12 @@ This workflow removes an item that was added or updated in a draft order edit. I
 You can use this workflow within your customizations or your own custom workflows, allowing you to wrap custom logic around
 removing an item from a draft order edit.

+:::note
+
+If you use this workflow in another, you must acquire a lock before running it and release the lock after. Learn more in the [Locking Operations in Workflows](https://docs.medusajs.com/learn/fundamentals/workflows/locks#locks-in-nested-workflows) guide.
+
+:::
+
 <SourceCodeLink link="https://github.com/medusajs/medusa/blob/147ce2fdc35366e591f552404ec949f6a5b92a11/packages/core/core-flows/src/draft-order/workflows/remove-draft-order-action-item.ts#L49" />

 ## Examples
@@ -117,6 +123,7 @@ import { removeDraftOrderActionItemWorkflow } from "@medusajs/medusa/core-flows"
 const myWorkflow = createWorkflow(
  "my-workflow",
  () => {
+    // Acquire lock from nested workflow here
    const result = removeDraftOrderActionItemWorkflow
      .runAsStep({
        input: {
@@ -124,6 +131,7 @@ const myWorkflow = createWorkflow(
          action_id: "action_123",
        }
      })
+    // Release lock here
  }
 )
 ```
@@ -20,6 +20,12 @@ This workflow removes a shipping method that was added to an edited draft order.
 You can use this workflow within your customizations or your own custom workflows, allowing you to wrap custom logic around
 removing a shipping method from an edited draft order.

+:::note
+
+If you use this workflow in another, you must acquire a lock before running it and release the lock after. Learn more in the [Locking Operations in Workflows](https://docs.medusajs.com/learn/fundamentals/workflows/locks#locks-in-nested-workflows) guide.
+
+:::
+
 <SourceCodeLink link="https://github.com/medusajs/medusa/blob/147ce2fdc35366e591f552404ec949f6a5b92a11/packages/core/core-flows/src/draft-order/workflows/remove-draft-order-action-shipping-method.ts#L53" />

 ## Examples
@@ -120,6 +126,7 @@ import { removeDraftOrderActionShippingMethodWorkflow } from "@medusajs/medusa/c
 const myWorkflow = createWorkflow(
  "my-workflow",
  () => {
+    // Acquire lock from nested workflow here
    const result = removeDraftOrderActionShippingMethodWorkflow
      .runAsStep({
        input: {
@@ -127,6 +134,7 @@ const myWorkflow = createWorkflow(
          action_id: "action_123",
        }
      })
+    // Release lock here
  }
 )
 ```
@@ -20,6 +20,12 @@ This workflow removes promotions from a draft order edit. It's used by the
 You can use this workflow within your customizations or your own custom workflows, allowing you to wrap custom logic around
 removing promotions from a draft order edit.

+:::note
+
+If you use this workflow in another, you must acquire a lock before running it and release the lock after. Learn more in the [Locking Operations in Workflows](https://docs.medusajs.com/learn/fundamentals/workflows/locks#locks-in-nested-workflows) guide.
+
+:::
+
 <SourceCodeLink link="https://github.com/medusajs/medusa/blob/147ce2fdc35366e591f552404ec949f6a5b92a11/packages/core/core-flows/src/draft-order/workflows/remove-draft-order-promotions.ts#L65" />

 ## Examples
@@ -117,6 +123,7 @@ import { removeDraftOrderPromotionsWorkflow } from "@medusajs/medusa/core-flows"
 const myWorkflow = createWorkflow(
  "my-workflow",
  () => {
+    // Acquire lock from nested workflow here
    const result = removeDraftOrderPromotionsWorkflow
      .runAsStep({
        input: {
@@ -124,6 +131,7 @@ const myWorkflow = createWorkflow(
          promo_codes: ["PROMO_CODE_1", "PROMO_CODE_2"],
        }
      })
+    // Release lock here
  }
 )
 ```
@@ -20,6 +20,12 @@ This workflow removes an existing shipping method from a draft order edit. It's
 You can use this workflow within your customizations or your own custom workflows, allowing you to wrap custom logic around
 removing a shipping method from a draft order edit.

+:::note
+
+If you use this workflow in another, you must acquire a lock before running it and release the lock after. Learn more in the [Locking Operations in Workflows](https://docs.medusajs.com/learn/fundamentals/workflows/locks#locks-in-nested-workflows) guide.
+
+:::
+
 <SourceCodeLink link="https://github.com/medusajs/medusa/blob/147ce2fdc35366e591f552404ec949f6a5b92a11/packages/core/core-flows/src/draft-order/workflows/remove-draft-order-shipping-method.ts#L61" />

 ## Examples
@@ -117,6 +123,7 @@ import { removeDraftOrderShippingMethodWorkflow } from "@medusajs/medusa/core-fl
 const myWorkflow = createWorkflow(
  "my-workflow",
  () => {
+    // Acquire lock from nested workflow here
    const result = removeDraftOrderShippingMethodWorkflow
      .runAsStep({
        input: {
@@ -124,6 +131,7 @@ const myWorkflow = createWorkflow(
          shipping_method_id: "sm_123",
        }
      })
+    // Release lock here
  }
 )
 ```
@@ -22,6 +22,12 @@ This workflow requests a draft order edit. It's used by the
 You can use this workflow within your customizations or your own custom workflows, allowing you to wrap custom logic around
 requesting a draft order edit.

+:::note
+
+If you use this workflow in another, you must acquire a lock before running it and release the lock after. Learn more in the [Locking Operations in Workflows](https://docs.medusajs.com/learn/fundamentals/workflows/locks#locks-in-nested-workflows) guide.
+
+:::
+
 <SourceCodeLink link="https://github.com/medusajs/medusa/blob/147ce2fdc35366e591f552404ec949f6a5b92a11/packages/core/core-flows/src/draft-order/workflows/request-draft-order-edit.ts#L72" />

 ## Examples
@@ -119,6 +125,7 @@ import { requestDraftOrderEditWorkflow } from "@medusajs/medusa/core-flows"
 const myWorkflow = createWorkflow(
  "my-workflow",
  () => {
+    // Acquire lock from nested workflow here
    const result = requestDraftOrderEditWorkflow
      .runAsStep({
        input: {
@@ -126,6 +133,7 @@ const myWorkflow = createWorkflow(
          requested_by: "user_123",
        }
      })
+    // Release lock here
  }
 )
 ```
@@ -20,6 +20,12 @@ This workflow updates a new item that was added to a draft order edit. It's used
 You can use this workflow within your customizations or your own custom workflows, allowing you to wrap custom logic around
 updating a new item in a draft order edit.

+:::note
+
+If you use this workflow in another, you must acquire a lock before running it and release the lock after. Learn more in the [Locking Operations in Workflows](https://docs.medusajs.com/learn/fundamentals/workflows/locks#locks-in-nested-workflows) guide.
+
+:::
+
 <SourceCodeLink link="https://github.com/medusajs/medusa/blob/147ce2fdc35366e591f552404ec949f6a5b92a11/packages/core/core-flows/src/draft-order/workflows/update-draft-order-action-item.ts#L52" />

 ## Examples
@@ -126,6 +132,7 @@ import { updateDraftOrderActionItemWorkflow } from "@medusajs/medusa/core-flows"
 const myWorkflow = createWorkflow(
  "my-workflow",
  () => {
+    // Acquire lock from nested workflow here
    const result = updateDraftOrderActionItemWorkflow
      .runAsStep({
        input: {
@@ -136,6 +143,7 @@ const myWorkflow = createWorkflow(
          }
        }
      })
+    // Release lock here
  }
 )
 ```
@@ -20,6 +20,12 @@ This workflow updates a new shipping method that was added to a draft order edit
 You can use this workflow within your customizations or your own custom workflows, allowing you to wrap custom logic around
 updating a new shipping method in a draft order edit.

+:::note
+
+If you use this workflow in another, you must acquire a lock before running it and release the lock after. Learn more in the [Locking Operations in Workflows](https://docs.medusajs.com/learn/fundamentals/workflows/locks#locks-in-nested-workflows) guide.
+
+:::
+
 <SourceCodeLink link="https://github.com/medusajs/medusa/blob/147ce2fdc35366e591f552404ec949f6a5b92a11/packages/core/core-flows/src/draft-order/workflows/update-draft-order-action-shipping-method.ts#L57" />

 ## Examples
@@ -129,6 +135,7 @@ import { updateDraftOrderActionShippingMethodWorkflow } from "@medusajs/medusa/c
 const myWorkflow = createWorkflow(
  "my-workflow",
  () => {
+    // Acquire lock from nested workflow here
    const result = updateDraftOrderActionShippingMethodWorkflow
      .runAsStep({
        input: {
@@ -139,6 +146,7 @@ const myWorkflow = createWorkflow(
          }
        }
      })
+    // Release lock here
  }
 )
 ```
@@ -20,6 +20,12 @@ This workflow updates an item in a draft order edit. It's used by the
 You can use this workflow within your customizations or your own custom workflows, allowing you to wrap custom logic around
 updating an item in a draft order edit.

+:::note
+
+If you use this workflow in another, you must acquire a lock before running it and release the lock after. Learn more in the [Locking Operations in Workflows](https://docs.medusajs.com/learn/fundamentals/workflows/locks#locks-in-nested-workflows) guide.
+
+:::
+
 <SourceCodeLink link="https://github.com/medusajs/medusa/blob/147ce2fdc35366e591f552404ec949f6a5b92a11/packages/core/core-flows/src/draft-order/workflows/update-draft-order-item.ts#L54" />

 ## Examples
@@ -117,6 +123,7 @@ import { updateDraftOrderItemWorkflow } from "@medusajs/medusa/core-flows"
 const myWorkflow = createWorkflow(
  "my-workflow",
  () => {
+    // Acquire lock from nested workflow here
    const result = updateDraftOrderItemWorkflow
      .runAsStep({
        input: {
@@ -124,6 +131,7 @@ const myWorkflow = createWorkflow(
          items: [{ id: "orli_123", quantity: 2 }],
        }
      })
+    // Release lock here
  }
 )
 ```
@@ -21,6 +21,12 @@ This workflow updates an existing shipping method in a draft order edit. It's us
 You can use this workflow within your customizations or your own custom workflows, allowing you to wrap custom logic around
 updating an existing shipping method in a draft order edit.

+:::note
+
+If you use this workflow in another, you must acquire a lock before running it and release the lock after. Learn more in the [Locking Operations in Workflows](https://docs.medusajs.com/learn/fundamentals/workflows/locks#locks-in-nested-workflows) guide.
+
+:::
+
 <SourceCodeLink link="https://github.com/medusajs/medusa/blob/147ce2fdc35366e591f552404ec949f6a5b92a11/packages/core/core-flows/src/draft-order/workflows/update-draft-order-shipping-method.ts#L84" />

 ## Examples
@@ -127,6 +133,7 @@ import { updateDraftOrderShippingMethodWorkflow } from "@medusajs/medusa/core-fl
 const myWorkflow = createWorkflow(
  "my-workflow",
  () => {
+    // Acquire lock from nested workflow here
    const result = updateDraftOrderShippingMethodWorkflow
      .runAsStep({
        input: {
@@ -137,6 +144,7 @@ const myWorkflow = createWorkflow(
          }
        }
      })
+    // Release lock here
  }
 )
 ```
@@ -26,6 +26,12 @@ using [requestDraftOrderEditWorkflow](../core_flows.Draft_Order.Workflows_Draft_
 You can use this workflow within your customizations or your own custom workflows, allowing you to wrap custom logic around
 updating a draft order.

+:::note
+
+If you use this workflow in another, you must acquire a lock before running it and release the lock after. Learn more in the [Locking Operations in Workflows](https://docs.medusajs.com/learn/fundamentals/workflows/locks#locks-in-nested-workflows) guide.
+
+:::
+
 <SourceCodeLink link="https://github.com/medusajs/medusa/blob/147ce2fdc35366e591f552404ec949f6a5b92a11/packages/core/core-flows/src/draft-order/workflows/update-draft-order.ts#L150" />

 ## Examples
@@ -126,6 +132,7 @@ import { updateDraftOrderWorkflow } from "@medusajs/medusa/core-flows"
 const myWorkflow = createWorkflow(
  "my-workflow",
  () => {
+    // Acquire lock from nested workflow here
    const result = updateDraftOrderWorkflow
      .runAsStep({
        input: {
@@ -134,6 +141,7 @@ const myWorkflow = createWorkflow(
          customer_id: "cus_123",
        }
      })
+    // Release lock here
  }
 )
 ```
@@ -28,6 +28,12 @@ This workflow deletes line items from a cart. It's used by the
 You can use this workflow within your customizations or your own custom workflows, allowing you to
 delete line items from a cart within your custom flows.

+:::note
+
+If you use this workflow in another, you must acquire a lock before running it and release the lock after. Learn more in the [Locking Operations in Workflows](https://docs.medusajs.com/learn/fundamentals/workflows/locks#locks-in-nested-workflows) guide.
+
+:::
+
 <SourceCodeLink link="https://github.com/medusajs/medusa/blob/147ce2fdc35366e591f552404ec949f6a5b92a11/packages/core/core-flows/src/line-item/workflows/delete-line-items.ts#L42" />

 ## Examples
@@ -125,6 +131,7 @@ import { deleteLineItemsWorkflow } from "@medusajs/medusa/core-flows"
 const myWorkflow = createWorkflow(
  "my-workflow",
  () => {
+    // Acquire lock from nested workflow here
    const result = deleteLineItemsWorkflow
      .runAsStep({
        input: {
@@ -132,6 +139,7 @@ const myWorkflow = createWorkflow(
          ids: ["li_123"]
        }
      })
+    // Release lock here
  }
 )
 ```
@@ -24,6 +24,12 @@ allows you to update custom data models linked to the fulfillment.

 You can also use this workflow within your customizations or your own custom workflows, allowing you to wrap custom logic around canceling a fulfillment.

+:::note
+
+If you use this workflow in another, you must acquire a lock before running it and release the lock after. Learn more in the [Locking Operations in Workflows](https://docs.medusajs.com/learn/fundamentals/workflows/locks#locks-in-nested-workflows) guide.
+
+:::
+
 <SourceCodeLink link="https://github.com/medusajs/medusa/blob/147ce2fdc35366e591f552404ec949f6a5b92a11/packages/core/core-flows/src/order/workflows/cancel-order-fulfillment.ts#L313" />

 ## Examples
@@ -130,6 +136,7 @@ import { cancelOrderFulfillmentWorkflow } from "@medusajs/medusa/core-flows"
 const myWorkflow = createWorkflow(
  "my-workflow",
  () => {
+    // Acquire lock from nested workflow here
    const result = cancelOrderFulfillmentWorkflow
      .runAsStep({
        input: {
@@ -140,6 +147,7 @@ const myWorkflow = createWorkflow(
          }
        }
      })
+    // Release lock here
  }
 )
 ```
@@ -26,6 +26,12 @@ This workflow confirms a requested claim. It's used by the
 You can use this workflow within your customizations or your own custom workflows, allowing you to confirm a claim
 for an order in your custom flows.

+:::note
+
+If you use this workflow in another, you must acquire a lock before running it and release the lock after. Learn more in the [Locking Operations in Workflows](https://docs.medusajs.com/learn/fundamentals/workflows/locks#locks-in-nested-workflows) guide.
+
+:::
+
 <SourceCodeLink link="https://github.com/medusajs/medusa/blob/147ce2fdc35366e591f552404ec949f6a5b92a11/packages/core/core-flows/src/order/workflows/claim/confirm-claim-request.ts#L291" />

 ## Examples
@@ -120,12 +126,14 @@ import { confirmClaimRequestWorkflow } from "@medusajs/medusa/core-flows"
 const myWorkflow = createWorkflow(
  "my-workflow",
  () => {
+    // Acquire lock from nested workflow here
    const result = confirmClaimRequestWorkflow
      .runAsStep({
        input: {
          claim_id: "claim_123",
        }
      })
+    // Release lock here
  }
 )
 ```
@@ -26,6 +26,12 @@ This workflow confirms an exchange request. It's used by the
 You can use this workflow within your customizations or your own custom workflows, allowing you to confirm an exchange
 for an order in your custom flow.

+:::note
+
+If you use this workflow in another, you must acquire a lock before running it and release the lock after. Learn more in the [Locking Operations in Workflows](https://docs.medusajs.com/learn/fundamentals/workflows/locks#locks-in-nested-workflows) guide.
+
+:::
+
 <SourceCodeLink link="https://github.com/medusajs/medusa/blob/147ce2fdc35366e591f552404ec949f6a5b92a11/packages/core/core-flows/src/order/workflows/exchange/confirm-exchange-request.ts#L285" />

 ## Examples
@@ -120,12 +126,14 @@ import { confirmExchangeRequestWorkflow } from "@medusajs/medusa/core-flows"
 const myWorkflow = createWorkflow(
  "my-workflow",
  () => {
+    // Acquire lock from nested workflow here
    const result = confirmExchangeRequestWorkflow
      .runAsStep({
        input: {
          exchange_id: "exchange_123",
        }
      })
+    // Release lock here
  }
 )
 ```
@@ -24,6 +24,12 @@ This workflow confirms an order edit request. It's used by the
 You can use this workflow within your customizations or your own custom workflows, allowing you to confirm an order edit
 in your custom flow.

+:::note
+
+If you use this workflow in another, you must acquire a lock before running it and release the lock after. Learn more in the [Locking Operations in Workflows](https://docs.medusajs.com/learn/fundamentals/workflows/locks#locks-in-nested-workflows) guide.
+
+:::
+
 <SourceCodeLink link="https://github.com/medusajs/medusa/blob/147ce2fdc35366e591f552404ec949f6a5b92a11/packages/core/core-flows/src/order/workflows/order-edit/confirm-order-edit-request.ts#L121" />

 ## Examples
@@ -118,12 +124,14 @@ import { confirmOrderEditRequestWorkflow } from "@medusajs/medusa/core-flows"
 const myWorkflow = createWorkflow(
  "my-workflow",
  () => {
+    // Acquire lock from nested workflow here
    const result = confirmOrderEditRequestWorkflow
      .runAsStep({
        input: {
          order_id: "order_123",
        }
      })
+    // Release lock here
  }
 )
 ```
@@ -25,6 +25,12 @@ This workflow confirms a return receival request. It's used by the
 You can use this workflow within your customizations or your own custom workflows, allowing you
 to confirm a return receival in your custom flow.

+:::note
+
+If you use this workflow in another, you must acquire a lock before running it and release the lock after. Learn more in the [Locking Operations in Workflows](https://docs.medusajs.com/learn/fundamentals/workflows/locks#locks-in-nested-workflows) guide.
+
+:::
+
 <SourceCodeLink link="https://github.com/medusajs/medusa/blob/147ce2fdc35366e591f552404ec949f6a5b92a11/packages/core/core-flows/src/order/workflows/return/confirm-receive-return-request.ts#L202" />

 ## Examples
@@ -119,12 +125,14 @@ import { confirmReturnReceiveWorkflow } from "@medusajs/medusa/core-flows"
 const myWorkflow = createWorkflow(
  "my-workflow",
  () => {
+    // Acquire lock from nested workflow here
    const result = confirmReturnReceiveWorkflow
      .runAsStep({
        input: {
          return_id: "return_123",
        }
      })
+    // Release lock here
  }
 )
 ```
@@ -25,6 +25,12 @@ allows you to create custom data models linked to the fulfillment.

 You can also use this workflow within your customizations or your own custom workflows, allowing you to wrap custom logic around creating a fulfillment.

+:::note
+
+If you use this workflow in another, you must acquire a lock before running it and release the lock after. Learn more in the [Locking Operations in Workflows](https://docs.medusajs.com/learn/fundamentals/workflows/locks#locks-in-nested-workflows) guide.
+
+:::
+
 <SourceCodeLink link="https://github.com/medusajs/medusa/blob/147ce2fdc35366e591f552404ec949f6a5b92a11/packages/core/core-flows/src/order/workflows/create-fulfillment.ts#L394" />

 ## Examples
@@ -140,6 +146,7 @@ import { createOrderFulfillmentWorkflow } from "@medusajs/medusa/core-flows"
 const myWorkflow = createWorkflow(
  "my-workflow",
  () => {
+    // Acquire lock from nested workflow here
    const result = createOrderFulfillmentWorkflow
      .runAsStep({
        input: {
@@ -153,6 +160,7 @@ const myWorkflow = createWorkflow(
          }
        }
      })
+    // Release lock here
  }
 )
 ```
@@ -20,6 +20,12 @@ This workflow creates one or more reservations. It's used by the
 You can use this workflow within your own customizations or custom workflows, allowing you
 to create reservations in your custom flows.

+:::note
+
+If you use this workflow in another, you must acquire a lock before running it and release the lock after. Learn more in the [Locking Operations in Workflows](https://docs.medusajs.com/learn/fundamentals/workflows/locks#locks-in-nested-workflows) guide.
+
+:::
+
 <SourceCodeLink link="https://github.com/medusajs/medusa/blob/147ce2fdc35366e591f552404ec949f6a5b92a11/packages/core/core-flows/src/reservation/workflows/create-reservations.ts#L36" />

 ## Examples
@@ -126,6 +132,7 @@ import { createReservationsWorkflow } from "@medusajs/medusa/core-flows"
 const myWorkflow = createWorkflow(
  "my-workflow",
  () => {
+    // Acquire lock from nested workflow here
    const result = createReservationsWorkflow
      .runAsStep({
        input: {
@@ -136,6 +143,7 @@ const myWorkflow = createWorkflow(
          }]
        }
      })
+    // Release lock here
  }
 )
 ```
@@ -85,6 +85,7 @@ import eventsListingHelper from "./resources/helpers/events-listing.js"
 import workflowEventsHelper from "./resources/helpers/workflow-events.js"
 import getAllChildrenHelper from "./resources/helpers/get-all-children.js"
 import reflectionBadgesHelper from "./resources/helpers/reflection-badges.js"
+import workflowNotes from "./resources/helpers/workflow-notes.js"
 import { MarkdownTheme } from "./theme.js"
 import { getDirname } from "utils"

@@ -194,11 +195,12 @@ export function registerHelpers(theme: MarkdownTheme) {
  signatureCommentHelper()
  versionHelper()
  sourceCodeLinkHelper()
-  workflowExamplesHelper()
+  workflowExamplesHelper(theme)
  stepExamplesHelper()
  ifEventsReferenceHelper(theme)
  eventsListingHelper()
  workflowEventsHelper()
  getAllChildrenHelper(theme)
  reflectionBadgesHelper()
+  workflowNotes(theme)
 }
@@ -1,68 +1,22 @@
 import Handlebars from "handlebars"
 import { MarkdownTheme } from "../../theme.js"
 import { stringify } from "yaml"
-import { replaceTemplateVariables } from "../../utils/reflection-template-strings.js"
 import { Reflection } from "typedoc"
-import { FrontmatterData, Tag } from "types"
-import { getTagComments, getTagsAsArray } from "utils"
+import { getPageFrontmatter } from "../../utils/frontmatter.js"

 export default function (theme: MarkdownTheme) {
  Handlebars.registerHelper("frontmatter", function (this: Reflection) {
    const { frontmatterData } = theme.getFormattingOptionsForLocation()

-    if (!frontmatterData) {
-      return ""
-    }
-
-    // format frontmatter data in case it has any template variables
-    const resolvedFrontmatter = resolveFrontmatterVariables(
+    const resolvedFrontmatter = getPageFrontmatter({
      frontmatterData,
-      this
-    )
-
-    // check if reflection has an `@tags` tag
-    const tagsComment = getTagComments(this)
-    if (tagsComment?.length && !("tags" in resolvedFrontmatter)) {
-      resolvedFrontmatter["tags"] = []
-    }
-    tagsComment?.forEach((tag) => {
-      const tagContent = getTagsAsArray(tag)
-      resolvedFrontmatter["tags"]?.push(...tagContent)
+      reflection: this,
    })
-    if (resolvedFrontmatter["tags"]?.length) {
-      resolvedFrontmatter["tags"] = getUniqueTags(resolvedFrontmatter["tags"])
+
+    if (!resolvedFrontmatter) {
+      return ""
    }

    return `---\n${stringify(resolvedFrontmatter).trim()}\n---\n\n`
  })
 }
-
-function resolveFrontmatterVariables(
-  frontmatterData: FrontmatterData,
-  reflection: Reflection
-): FrontmatterData {
-  const tempFrontmatterData: FrontmatterData = JSON.parse(
-    JSON.stringify(frontmatterData)
-  )
-  Object.keys(tempFrontmatterData).forEach((key) => {
-    const value = tempFrontmatterData[key]
-    if (!value || typeof value !== "string") {
-      return
-    }
-
-    tempFrontmatterData[key] = replaceTemplateVariables(reflection, value)
-  })
-
-  return tempFrontmatterData
-}
-
-function getUniqueTags(tags: Tag[]): Tag[] {
-  const tagsMap = new Map<string, Tag>()
-  tags.forEach((tag) => {
-    const tagName = typeof tag === "string" ? tag : tag.name
-
-    tagsMap.set(tagName, tag)
-  })
-
-  return Array.from(tagsMap.values())
-}
@@ -2,11 +2,24 @@ import Handlebars from "handlebars"
 import { DeclarationReflection, SignatureReflection } from "typedoc"
 import { getReflectionTypeFakeValueStr, getWorkflowInputType } from "utils"
 import beautifyCode from "../../utils/beautify-code.js"
+import { MarkdownTheme } from "../../theme.js"
+import { getPageFrontmatter } from "../../utils/frontmatter.js"

-export default function () {
+export default function (theme: MarkdownTheme) {
  Handlebars.registerHelper(
    "workflowExamples",
    function (this: SignatureReflection): string {
+      const frontmatter = getPageFrontmatter({
+        frontmatterData:
+          theme.getFormattingOptionsForLocation().frontmatterData,
+        reflection: this,
+      })
+      const hasLocking =
+        frontmatter?.tags?.some((tag) => {
+          return typeof tag === "string"
+            ? tag === "locking"
+            : tag.name === "locking"
+        }) ?? false
      const workflowReflection = this.parent
      const exampleStr: string[] = []

@@ -19,6 +32,7 @@ export default function () {
          getExecutionCodeTabs({
            exampleCode: generateWorkflowExample(workflowReflection),
            workflowName: workflowReflection.name,
+            hasLocking,
          })
        )
      } else {
@@ -42,6 +56,7 @@ export default function () {
              getExecutionCodeTabs({
                exampleCode: part.text,
                workflowName: workflowReflection.name,
+                hasLocking,
              })
            )
          })
@@ -58,9 +73,11 @@ export default function () {
 function getExecutionCodeTabs({
  exampleCode,
  workflowName,
+  hasLocking,
 }: {
  exampleCode: string
  workflowName: string
+  hasLocking: boolean
 }): string {
  exampleCode = exampleCode.replace("```ts\n", "").replace("\n```", "")

@@ -139,12 +156,14 @@ import { ${workflowName} } from "@medusajs/medusa/core-flows"

 const myWorkflow = createWorkflow(
  "my-workflow",
-  () => {
+  () => {${hasLocking ? "\n    // Acquire lock from nested workflow here" : ""}
    ${exampleCode
      .replace(`{ result }`, "result")
      .replace(`await `, "")
      .replace(`(container)`, "")
-      .replace(".run(", ".runAsStep(")}
+      .replace(".run(", ".runAsStep(")}${
+      hasLocking ? "\n    // Release lock here" : ""
+    }
  }
 )`)}
 \`\`\`
@@ -0,0 +1,36 @@
+import Handlebars from "handlebars"
+import { SignatureReflection } from "typedoc"
+import { MarkdownTheme } from "../../theme.js"
+import { getPageFrontmatter } from "../../utils/frontmatter.js"
+
+export default function (theme: MarkdownTheme) {
+  Handlebars.registerHelper(
+    "workflowNotes",
+    function (this: SignatureReflection): string {
+      const notes: string[] = []
+      const frontmatter = getPageFrontmatter({
+        frontmatterData:
+          theme.getFormattingOptionsForLocation().frontmatterData,
+        reflection: this,
+      })
+      const hasLocking =
+        frontmatter?.tags?.some((tag) => {
+          return typeof tag === "string"
+            ? tag === "locking"
+            : tag.name === "locking"
+        }) ?? false
+
+      if (hasLocking) {
+        notes.push(
+          `:::note
+
+If you use this workflow in another, you must acquire a lock before running it and release the lock after. Learn more in the [Locking Operations in Workflows](https://docs.medusajs.com/learn/fundamentals/workflows/locks#locks-in-nested-workflows) guide.
+
+:::`
+        )
+      }
+
+      return notes.join("\n\n")
+    }
+  )
+}
@@ -6,6 +6,8 @@

 {{{version this}}}

+{{{workflowNotes this}}}
+
 {{/if}}

 {{{sourceCodeLink}}}
@@ -1,46 +0,0 @@
-import Handlebars from "handlebars"
-import { PageEvent } from "typedoc"
-
-export interface FrontMatterVars {
-  [key: string]: string | number | boolean
-}
-
-/**
- * Prepends YAML block to a string
- * @param contents - the string to prepend
- * @param vars - object of required front matter variables
- */
-export const prependYAML = (contents: string, vars: FrontMatterVars) => {
-  return contents
-    .replace(/^/, toYAML(vars) + "\n\n")
-    .replace(/[\r\n]{3,}/g, "\n\n")
-}
-
-/**
- * Returns the page title as rendered in the document h1(# title)
- * @param page
- */
-export const getPageTitle = (page: PageEvent) => {
-  return Handlebars.helpers.reflectionTitle.call(page, false)
-}
-
-/**
- * Converts YAML object to a YAML string
- * @param vars
- */
-const toYAML = (vars: FrontMatterVars) => {
-  const yaml = `---
-${Object.entries(vars)
-  .map(
-    ([key, value]) =>
-      `${key}: ${
-        typeof value === "string" ? `"${escapeString(value)}"` : value
-      }`
-  )
-  .join("\n")}
---`
-  return yaml
-}
-
-// prettier-ignore
-const escapeString = (str: string) => str.replace(/"/g, "\\\"")
@@ -0,0 +1,67 @@
+import { Reflection } from "typedoc"
+import { FrontmatterData, Tag } from "types"
+import { getTagComments, getTagsAsArray } from "utils"
+import { replaceTemplateVariables } from "./reflection-template-strings.js"
+
+export function getPageFrontmatter({
+  frontmatterData,
+  reflection,
+}: {
+  frontmatterData: FrontmatterData | undefined
+  reflection: Reflection
+}): FrontmatterData | undefined {
+  if (!frontmatterData) {
+    return
+  }
+
+  // format frontmatter data in case it has any template variables
+  const resolvedFrontmatter = resolveFrontmatterVariables(
+    frontmatterData,
+    reflection
+  )
+
+  // check if reflection has an `@tags` tag
+  const tagsComment = getTagComments(reflection)
+  if (tagsComment?.length && !("tags" in resolvedFrontmatter)) {
+    resolvedFrontmatter["tags"] = []
+  }
+  tagsComment?.forEach((tag) => {
+    const tagContent = getTagsAsArray(tag)
+    resolvedFrontmatter["tags"]?.push(...tagContent)
+  })
+  if (resolvedFrontmatter["tags"]?.length) {
+    resolvedFrontmatter["tags"] = getUniqueTags(resolvedFrontmatter["tags"])
+  }
+
+  return resolvedFrontmatter
+}
+
+function resolveFrontmatterVariables(
+  frontmatterData: FrontmatterData,
+  reflection: Reflection
+): FrontmatterData {
+  const tempFrontmatterData: FrontmatterData = JSON.parse(
+    JSON.stringify(frontmatterData)
+  )
+  Object.keys(tempFrontmatterData).forEach((key) => {
+    const value = tempFrontmatterData[key]
+    if (!value || typeof value !== "string") {
+      return
+    }
+
+    tempFrontmatterData[key] = replaceTemplateVariables(reflection, value)
+  })
+
+  return tempFrontmatterData
+}
+
+function getUniqueTags(tags: Tag[]): Tag[] {
+  const tagsMap = new Map<string, Tag>()
+  tags.forEach((tag) => {
+    const tagName = typeof tag === "string" ? tag : tag.name
+
+    tagsMap.set(tagName, tag)
+  })
+
+  return Array.from(tagsMap.values())
+}
@@ -6138,9 +6138,9 @@ __metadata:
  linkType: hard

 "caniuse-lite@npm:^1.0.30001464, caniuse-lite@npm:^1.0.30001578, caniuse-lite@npm:^1.0.30001579, caniuse-lite@npm:^1.0.30001587":
-  version: 1.0.30001718
-  resolution: "caniuse-lite@npm:1.0.30001718"
-  checksum: 67f9ad09bc16443e28d14f265d6e468480cd8dc1900d0d8b982222de80c699c4f2306599c3da8a3fa7139f110d4b30d49dbac78f215470f479abb6ffe141d5d3
+  version: 1.0.30001757
+  resolution: "caniuse-lite@npm:1.0.30001757"
+  checksum: 3ccb71fa2bf1f8c96ff1bf9b918b08806fed33307e20a3ce3259155fda131eaf96cfcd88d3d309c8fd7f8285cc71d89a3b93648a1c04814da31c301f98508d42
  languageName: node
  linkType: hard