diff --git a/www/apps/resources/references/core_flows/Cart/Workflows_Cart/functions/core_flows.Cart.Workflows_Cart.completeCartWorkflow/page.mdx b/www/apps/resources/references/core_flows/Cart/Workflows_Cart/functions/core_flows.Cart.Workflows_Cart.completeCartWorkflow/page.mdx
index 41e9704048..43b19bb4ab 100644
--- a/www/apps/resources/references/core_flows/Cart/Workflows_Cart/functions/core_flows.Cart.Workflows_Cart.completeCartWorkflow/page.mdx
+++ b/www/apps/resources/references/core_flows/Cart/Workflows_Cart/functions/core_flows.Cart.Workflows_Cart.completeCartWorkflow/page.mdx
@@ -176,6 +176,62 @@ Handlers consuming this hook accept the following input.
 
 <TypeList types={[{"name":"input","type":"[input](../../../core_flows.Cart.Workflows_Cart/page.mdx#__type-3)","description":"The input data for the hook.","optional":false,"defaultValue":"","expandable":false,"children":[{"name":"input","type":"[CompleteCartWorkflowInput](../../../../types/core_flows.CompleteCartWorkflowInput/page.mdx)","description":"The data to complete a cart and place an order.","optional":false,"defaultValue":"","expandable":false,"children":[{"name":"id","type":"`string`","description":"The ID of the cart to complete.","optional":false,"defaultValue":"","expandable":false,"children":[]}]},{"name":"cart","type":"`any`","description":"","optional":false,"defaultValue":"","expandable":false,"children":[]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" openedLevel={1} sectionTitle="validate"/>
 
+### beforePaymentAuthorization
+
+This step is a hook that you can inject custom functionality into.
+
+:::note
+
+This hook is nested within a [when](https://docs.medusajs.com/learn/fundamentals/workflows/conditions) condition, so it may not be executed if the when condition isn't satisfied.
+
+:::
+
+#### Example
+
+```ts
+import { completeCartWorkflow } from "@medusajs/medusa/core-flows"
+
+completeCartWorkflow.hooks.beforePaymentAuthorization(
+  (async ({}, { container }) => {
+    //TODO
+  })
+)
+```
+
+#### Input
+
+Handlers consuming this hook accept the following input.
+
+<TypeList types={[{"name":"input","type":"[input](../../../core_flows.Cart.Workflows_Cart/page.mdx#__type-3)","description":"The input data for the hook.","optional":false,"defaultValue":"","expandable":false,"children":[{"name":"input","type":"[CompleteCartWorkflowInput](../../../../types/core_flows.CompleteCartWorkflowInput/page.mdx)","description":"The data to complete a cart and place an order.","optional":false,"defaultValue":"","expandable":false,"children":[{"name":"id","type":"`string`","description":"The ID of the cart to complete.","optional":false,"defaultValue":"","expandable":false,"children":[]}]},{"name":"cart","type":"`any`","description":"","optional":false,"defaultValue":"","expandable":false,"children":[]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" openedLevel={1} sectionTitle="beforePaymentAuthorization"/>
+
+### orderCreated
+
+This step is a hook that you can inject custom functionality into.
+
+:::note
+
+This hook is nested within a [when](https://docs.medusajs.com/learn/fundamentals/workflows/conditions) condition, so it may not be executed if the when condition isn't satisfied.
+
+:::
+
+#### Example
+
+```ts
+import { completeCartWorkflow } from "@medusajs/medusa/core-flows"
+
+completeCartWorkflow.hooks.orderCreated(
+  (async ({}, { container }) => {
+    //TODO
+  })
+)
+```
+
+#### Input
+
+Handlers consuming this hook accept the following input.
+
+<TypeList types={[{"name":"input","type":"[input](../../../core_flows.Cart.Workflows_Cart/page.mdx#__type-3)","description":"The input data for the hook.","optional":false,"defaultValue":"","expandable":false,"children":[{"name":"input","type":"[CompleteCartWorkflowInput](../../../../types/core_flows.CompleteCartWorkflowInput/page.mdx)","description":"The data to complete a cart and place an order.","optional":false,"defaultValue":"","expandable":false,"children":[{"name":"id","type":"`string`","description":"The ID of the cart to complete.","optional":false,"defaultValue":"","expandable":false,"children":[]}]},{"name":"cart","type":"`any`","description":"","optional":false,"defaultValue":"","expandable":false,"children":[]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" openedLevel={1} sectionTitle="orderCreated"/>
+
 ## Emitted Events
 
 This section lists the events that are either triggered by the `emitEventStep` in the workflow, or by another workflow executed within this workflow.
diff --git a/www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/workflow-hooks.ts b/www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/workflow-hooks.ts
index 8ed959a2e3..367b9908f3 100644
--- a/www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/workflow-hooks.ts
+++ b/www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/workflow-hooks.ts
@@ -1,6 +1,10 @@
 import { MarkdownTheme } from "../../theme.js"
 import Handlebars from "handlebars"
-import { DeclarationReflection, SignatureReflection } from "typedoc"
+import {
+  DeclarationReflection,
+  DocumentReflection,
+  SignatureReflection,
+} from "typedoc"
 import { cleanUpHookInput, getHookChildren, getProjectChild } from "utils"
 import beautifyCode from "../../utils/beautify-code.js"
 
@@ -12,9 +16,30 @@ export default function (theme: MarkdownTheme) {
         return ""
       }
 
-      const hooks = this.parent.documents.filter(
-        (document) => document.comment?.modifierTags.has("@hook")
-      )
+      const hooks: {
+        hook: DocumentReflection
+        isNested: boolean
+      }[] = []
+
+      this.parent.documents.forEach((document) => {
+        if (document.comment?.modifierTags.has("@hook")) {
+          hooks.push({
+            hook: document,
+            isNested: false,
+          })
+          return
+        }
+
+        if (!document.comment?.modifierTags.has("@when")) {
+          return
+        }
+
+        const nestedHooks =
+          document.children?.filter(
+            (child) => child.comment?.modifierTags.has("@hook")
+          ) || []
+        hooks.push(...nestedHooks.map((hook) => ({ hook, isNested: true })))
+      })
 
       if (!hooks.length) {
         return ""
@@ -27,7 +52,7 @@ export default function (theme: MarkdownTheme) {
       const hooksTitleLevel = Handlebars.helpers.titleLevel()
       const hookChildren = getHookChildren(this.parent)
 
-      hooks.forEach((hook) => {
+      hooks.forEach(({ hook, isNested }) => {
         const hookReflection =
           hookChildren.find((child) => {
             if (child.name !== hook.name || !child.comment) {
@@ -70,6 +95,10 @@ export default function (theme: MarkdownTheme) {
           )}\n\n`
         }
 
+        if (isNested) {
+          str += `\n\n:::note\n\nThis hook is nested within a [when](https://docs.medusajs.com/learn/fundamentals/workflows/conditions) condition, so it may not be executed if the when condition isn't satisfied.\n\n:::\n\n`
+        }
+
         const hookExample = hookReflection.comment?.getTag(`@example`)
 
         if (hookExample) {