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
@@ -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
  }
 )
 ```