chore(core-flows,types): improve TSDocs of order workflows (#10983)

packages/core/core-flows/src/cart/workflows/create-carts.ts

@@ -48,7 +48,7 @@ export const createCartWorkflowId = "create-cart"
  * 
  * This workflow has a hook that allows you to perform custom actions on the created cart. You can see an example in [this guide](https://docs.medusajs.com/resources/commerce-modules/cart/extend#step-4-consume-cartcreated-workflow-hook).
  * 
- * You can also use this workflow within your own custom workflows, allowing you to wrap custom logic around cart creation.
+ * You can also use this workflow within your customizations or your own custom workflows, allowing you to wrap custom logic around cart creation.
  * 
  * @example
  * const { result } = await createCartWorkflow(container)

packages/core/core-flows/src/cart/workflows/update-cart.ts

@@ -48,7 +48,7 @@ export const updateCartWorkflowId = "update-cart"
  * This workflow has a hook that allows you to perform custom actions on the updated cart. For example, you can pass custom data under the `additional_data` property of the Update Cart API route, 
  * then update any associated details related to the cart in the workflow's hook.
  * 
- * You can also use this workflow within your own custom workflows, allowing you to wrap custom logic around updating a cart.
+ * You can also use this workflow within your customizations or your own custom workflows, allowing you to wrap custom logic around updating a cart.
  * 
  * @example
  * const { result } = await updateCartWorkflow(container)

packages/core/core-flows/src/customer/workflows/create-addresses.ts

@@ -33,7 +33,7 @@ export const createCustomerAddressesWorkflowId = "create-customer-addresses"
  * This workflow has a hook that allows you to perform custom actions on the created customer addresses. For example, you can pass under `additional_data` custom data that
  * allows you to create custom data models linked to the addresses.
  * 
- * You can also use this workflow within your own custom workflows, allowing you to wrap custom logic around creating customer addresses.
+ * You can also use this workflow within your customizations or your own custom workflows, allowing you to wrap custom logic around creating customer addresses.
  * 
  * @example
  * const { result } = await createCustomerAddressesWorkflow(container)

packages/core/core-flows/src/customer/workflows/create-customers.ts

@@ -25,7 +25,7 @@ export const createCustomersWorkflowId = "create-customers"
  * 
  * This workflow has a hook that allows you to perform custom actions on the created customer. You can see an example in [this guide](https://docs.medusajs.com/resources/commerce-modules/customer/extend).
  * 
- * You can also use this workflow within your own custom workflows, allowing you to wrap custom logic around creating customers.
+ * You can also use this workflow within your customizations or your own custom workflows, allowing you to wrap custom logic around creating customers.
  * 
  * @example
  * const { result } = await createCustomersWorkflow(container)

packages/core/core-flows/src/customer/workflows/update-addresses.ts

@@ -38,7 +38,7 @@ export const updateCustomerAddressesWorkflowId = "update-customer-addresses"
  * This workflow has a hook that allows you to perform custom actions on the updated customer addresses. For example, you can pass under `additional_data` custom data that
  * allows you to update custom data models linked to the addresses.
  * 
- * You can also use this workflow within your own custom workflows, allowing you to wrap custom logic around updating customer addresses.
+ * You can also use this workflow within your customizations or your own custom workflows, allowing you to wrap custom logic around updating customer addresses.
  * 
  * @example
  * const { result } = await updateCustomerAddressesWorkflow(container)

packages/core/core-flows/src/customer/workflows/update-customers.ts

@@ -36,7 +36,7 @@ export const updateCustomersWorkflowId = "update-customers"
  * This workflow has a hook that allows you to perform custom actions on the updated customer. For example, you can pass under `additional_data` custom data to update
  * custom data models linked to the customers.
  * 
- * You can also use this workflow within your own custom workflows, allowing you to wrap custom logic around updating customers.
+ * You can also use this workflow within your customizations or your own custom workflows, allowing you to wrap custom logic around updating customers.
  * 
  * @example
  * const { result } = await updateCustomersWorkflow(container)

packages/core/core-flows/src/order/steps/add-order-transaction.ts

@@ -2,6 +2,16 @@ import { CreateOrderTransactionDTO } from "@medusajs/framework/types"
 import { Modules } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The transaction(s) to add to the order.
+ */
+export type AddOrderTransactionStepInput = CreateOrderTransactionDTO | CreateOrderTransactionDTO[]
+
+/**
+ * The added order transaction(s).
+ */
+export type AddOrderTransactionStepOutput = CreateOrderTransactionDTO | CreateOrderTransactionDTO[]
+
 export const addOrderTransactionStepId = "add-order-transaction"
 /**
  * This step creates order transactions.
@@ -9,7 +19,7 @@ export const addOrderTransactionStepId = "add-order-transaction"
 export const addOrderTransactionStep = createStep(
   addOrderTransactionStepId,
   async (
-    data: CreateOrderTransactionDTO | CreateOrderTransactionDTO[],
+    data: AddOrderTransactionStepInput,
     { container }
   ) => {
     const service = container.resolve(Modules.ORDER)
@@ -36,7 +46,7 @@ export const addOrderTransactionStep = createStep(
     const created = await service.addOrderTransactions(trxsData)
 
     return new StepResponse(
-      Array.isArray(data) ? created : created[0],
+      (Array.isArray(data) ? created : created[0]) as AddOrderTransactionStepOutput,
       created.map((c) => c.id)
     )
   },

packages/core/core-flows/src/order/steps/archive-orders.ts

@@ -2,7 +2,13 @@ import { IOrderModuleService } from "@medusajs/framework/types"
 import { Modules } from "@medusajs/framework/utils"
 import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The details of archiving the orders.
+ */
 export type ArchiveOrdersStepInput = {
+  /**
+   * The IDs of the orders to archive.
+   */
   orderIds: string[]
 }
 

packages/core/core-flows/src/order/steps/cancel-fulfillment.ts

@@ -8,6 +8,17 @@ import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 export const cancelOrderFulfillmentStepId = "cancel-order-fulfillment"
 /**
  * This step cancels an order's fulfillment.
+ * 
+ * @example
+ * const data = cancelOrderFulfillmentStep({
+ *   order_id: "order_123",
+ *   items: [
+ *     {
+ *       id: "item_123",
+ *       quantity: 1
+ *     }
+ *   ]
+ * })
  */
 export const cancelOrderFulfillmentStep = createStep(
   cancelOrderFulfillmentStepId,

packages/core/core-flows/src/order/steps/cancel-orders.ts

@@ -2,8 +2,17 @@ import { IOrderModuleService } from "@medusajs/framework/types"
 import { Modules } from "@medusajs/framework/utils"
 import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The details of canceling the orders.
+ */
 export type CancelOrdersStepInput = {
+  /**
+   * The IDs of the orders to cancel.
+   */
   orderIds: string[]
+  /**
+   * The ID of the user canceling the orders.
+   */
   canceled_by?: string
 }
 

packages/core/core-flows/src/order/steps/claim/create-claim-items-from-actions.ts

@@ -5,13 +5,40 @@ import {
 import { ChangeActionType, Modules } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The details of creating the claim items from a change action.
+ */
 export type CreateOrderClaimItemsFromActionsInput = {
+  /**
+   * The change actions to create claim items from.
+   */
   changes: OrderChangeActionDTO[]
+  /**
+   * The ID of the claim to create the items for.
+   */
   claimId: string
 }
 
 /**
  * This step creates claim items from a change action.
+ * 
+ * :::note
+ * 
+ * You can retrieve an order change action details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query),
+ * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep).
+ * 
+ * :::
+ * 
+ * @example
+ * const data = createOrderClaimItemsFromActionsStep({
+ *   claimId: "claim_123",
+ *   changes: [
+ *     {
+ *       id: "orchact_123",
+ *       // other order change action details...
+ *     }
+ *   ]
+ * })
  */
 export const createOrderClaimItemsFromActionsStep = createStep(
   "create-claim-items-from-change-actions",

packages/core/core-flows/src/order/steps/claim/delete-claims.ts

@@ -2,13 +2,23 @@ import { IOrderModuleService } from "@medusajs/framework/types"
 import { Modules } from "@medusajs/framework/utils"
 import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The details of deleting one or more claims.
+ */
+export type DeleteOrderClaimsInput = {
+  /**
+   * The IDs of the claims to delete.
+   */
+  ids: string[]
+}
+
 export const deleteClaimsStepId = "delete-claims"
 /**
  * This step deletes one or more order claims.
  */
 export const deleteClaimsStep = createStep(
   deleteClaimsStepId,
-  async (data: { ids: string[] }, { container }) => {
+  async (data: DeleteOrderClaimsInput, { container }) => {
     const service = container.resolve<IOrderModuleService>(Modules.ORDER)
 
     const deleted = await service.softDeleteOrderClaims(data.ids)

packages/core/core-flows/src/order/steps/complete-orders.ts

@@ -2,7 +2,13 @@ import { IOrderModuleService } from "@medusajs/framework/types"
 import { Modules } from "@medusajs/framework/utils"
 import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The details of completing the orders.
+ */
 export type CompleteOrdersStepInput = {
+  /**
+   * The IDs of the orders to complete.
+   */
   orderIds: string[]
 }
 

packages/core/core-flows/src/order/steps/confirm-order-changes.ts

@@ -2,9 +2,21 @@ import { OrderChangeDTO } from "@medusajs/framework/types"
 import { Modules } from "@medusajs/framework/utils"
 import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The input for the confirm order changes step.
+ */
 export type ConfirmOrderChangesInput = {
+  /**
+   * The ID of the order to confirm changes for.
+   */
   orderId: string
+  /**
+   * The changes to confirm.
+   */
   changes: OrderChangeDTO[]
+  /**
+   * The ID of the user confirming the changes.
+   */
   confirmed_by?: string
 }
 

packages/core/core-flows/src/order/steps/create-line-items.ts

@@ -2,13 +2,32 @@ import { CreateOrderLineItemDTO } from "@medusajs/framework/types"
 import { Modules } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The details of creating order line items.
+ */
 export interface CreateOrderLineItemsStepInput {
+  /**
+   * The items to create.
+   */
   items: CreateOrderLineItemDTO[]
 }
 
 export const createOrderLineItemsStepId = "create-order-line-items-step"
 /**
  * This step creates order line items.
+ * 
+ * @example
+ * const data = createOrderLineItemsStep({
+ *   items: [
+ *     {
+ *       variant_id: "variant_123",
+ *       quantity: 1,
+ *       unit_price: 10,
+ *       title: "Shirt",
+ *       order_id: "order_123"
+ *     }
+ *   ]
+ * })
  */
 export const createOrderLineItemsStep = createStep(
   createOrderLineItemsStepId,

packages/core/core-flows/src/order/steps/create-order-shipping-methods.ts

@@ -5,7 +5,13 @@ import {
 import { Modules } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The details of creating order shipping methods.
+ */
 export interface CreateOrderShippingMethodsStepInput {
+  /**
+   * The shipping methods to create.
+   */
   shipping_methods: CreateOrderShippingMethodDTO[]
 }
 

packages/core/core-flows/src/order/steps/create-orders.ts

@@ -2,9 +2,28 @@ import { CreateOrderDTO, IOrderModuleService } from "@medusajs/framework/types"
 import { Modules } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The orders to create.
+ */
+export type CreateOrdersStepInput = CreateOrderDTO[]
+
 export const createOrdersStepId = "create-orders"
 /**
  * This step creates one or more orders.
+ * 
+ * @example
+ * const data = createOrdersStep([{
+ *   region_id: "region_123",
+ *   customer_id: "customer_123",
+ *   items: [
+ *     {
+ *       variant_id: "variant_123",
+ *       quantity: 1,
+ *       title: "Shirt",
+ *       unit_price: 10,
+ *     }
+ *   ]
+ * }])
  */
 export const createOrdersStep = createStep(
   createOrdersStepId,

packages/core/core-flows/src/order/steps/delete-line-items.ts

@@ -2,7 +2,13 @@ import { IOrderModuleService } from "@medusajs/framework/types"
 import { Modules } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The details of deleting order line items.
+ */
 export interface DeleteOrderLineItemsStepInput {
+  /**
+   * The IDs of the order line items to delete.
+   */
   ids: string[]
 }
 

packages/core/core-flows/src/order/steps/delete-order-change-actions.ts

@@ -2,13 +2,23 @@ import { IOrderModuleService } from "@medusajs/framework/types"
 import { Modules } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The details of deleting order change actions.
+ */
+export interface DeleteOrderChangeActionsStepInput {
+  /**
+   * The IDs of the order change actions to delete.
+   */
+  ids: string[]
+}
+
 export const deleteOrderChangeActionsStepId = "delete-order-change-actions"
 /**
  * This step deletes order change actions.
  */
 export const deleteOrderChangeActionsStep = createStep(
   deleteOrderChangeActionsStepId,
-  async (data: { ids: string[] }, { container }) => {
+  async (data: DeleteOrderChangeActionsStepInput, { container }) => {
     const service = container.resolve<IOrderModuleService>(Modules.ORDER)
 
     await service.softDeleteOrderChangeActions(data.ids)

packages/core/core-flows/src/order/steps/delete-order-changes.ts

@@ -2,13 +2,23 @@ import { IOrderModuleService } from "@medusajs/framework/types"
 import { Modules } from "@medusajs/framework/utils"
 import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The details of deleting order changes.
+ */
+export interface DeleteOrderChangesStepInput {
+  /**
+   * The IDs of the order changes to delete.
+   */
+  ids: string[]
+}
+
 export const deleteOrderChangesStepId = "delete-order-change"
 /**
  * This step deletes order changes.
  */
 export const deleteOrderChangesStep = createStep(
   deleteOrderChangesStepId,
-  async (data: { ids: string[] }, { container }) => {
+  async (data: DeleteOrderChangesStepInput, { container }) => {
     const service = container.resolve<IOrderModuleService>(Modules.ORDER)
 
     const deleted = await service.softDeleteOrderChanges(data.ids)

packages/core/core-flows/src/order/steps/delete-order-shipping-methods.ts

@@ -2,7 +2,13 @@ import { IOrderModuleService } from "@medusajs/framework/types"
 import { Modules } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The details of deleting order shipping methods.
+ */
 export interface DeleteOrderShippingMethodsStepInput {
+  /**
+   * The IDs of the order shipping methods to delete.
+   */
   ids: string[]
 }
 

packages/core/core-flows/src/order/steps/exchange/create-exchange-items-from-actions.ts

@@ -6,13 +6,40 @@ import {
 import { Modules } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The details of creating exchange items from change actions.
+ */
 export type CreateOrderExchangeItemsFromActionsInput = {
+  /**
+   * The change actions to create exchange items from.
+   */
   changes: OrderChangeActionDTO[]
+  /**
+   * The ID of the exchange to create the items for.
+   */
   exchangeId: string
 }
 
 /**
  * This step creates exchange items from change actions.
+ * 
+ * :::note
+ * 
+ * You can retrieve an order change action details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query),
+ * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep).
+ * 
+ * :::
+ * 
+ * @example
+ * const data = createOrderExchangeItemsFromActionsStep({
+ *   exchangeId: "exchange_123",
+ *   changes: [
+ *     {
+ *       id: "orchact_123",
+ *       // other order change action details...
+ *     }
+ *   ]
+ * })
  */
 export const createOrderExchangeItemsFromActionsStep = createStep(
   "create-exchange-items-from-change-actions",

packages/core/core-flows/src/order/steps/exchange/delete-exchanges.ts

@@ -2,13 +2,23 @@ import { IOrderModuleService } from "@medusajs/framework/types"
 import { Modules } from "@medusajs/framework/utils"
 import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The details of deleting one or more exchanges.
+ */
+export type DeleteOrderExchangesInput = {
+  /**
+   * The IDs of the exchanges to delete.
+   */
+  ids: string[]
+}
+
 export const deleteExchangesStepId = "delete-exchanges"
 /**
  * This step deletes one or more exchanges.
  */
 export const deleteExchangesStep = createStep(
   deleteExchangesStepId,
-  async (data: { ids: string[] }, { container }) => {
+  async (data: DeleteOrderExchangesInput, { container }) => {
     const service = container.resolve<IOrderModuleService>(Modules.ORDER)
 
     const deleted = await service.softDeleteOrderExchanges(data.ids)

packages/core/core-flows/src/order/steps/exchange/update-order-exchanges.ts

@@ -11,6 +11,12 @@ import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 export const updateOrderExchangesStepId = "update-order-exchange"
 /**
  * This step updates one or more exchanges.
+ * 
+ * @example
+ * const data = updateOrderExchangesStep([{
+ *   "id": "exchange_123",
+ *   no_notification: true
+ * }])
  */
 export const updateOrderExchangesStep = createStep(
   updateOrderExchangesStepId,

packages/core/core-flows/src/order/steps/preview-order-change.ts

@@ -2,13 +2,18 @@ import { IOrderModuleService } from "@medusajs/framework/types"
 import { Modules } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The ID of the order to retrieve its preview.
+ */
+export type PreviewOrderChangeStepInput = string
+
 export const previewOrderChangeStepId = "preview-order-change"
 /**
  * This step retrieves a preview of an order change.
  */
 export const previewOrderChangeStep = createStep(
   previewOrderChangeStepId,
-  async (orderId: string, { container }) => {
+  async (orderId: PreviewOrderChangeStepInput, { container }) => {
     const service = container.resolve<IOrderModuleService>(Modules.ORDER)
 
     const preview = await service.previewOrderChange(orderId)

packages/core/core-flows/src/order/steps/register-fulfillment.ts

@@ -8,6 +8,15 @@ import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 export const registerOrderFulfillmentStepId = "register-order-fullfillment"
 /**
  * This step registers a fulfillment for an order.
+ * 
+ * @example
+ * const data = registerOrderFulfillmentStep({
+ *   order_id: "order_123",
+ *   items: [{
+ *     id: "item_123",
+ *     quantity: 1
+ *   }],
+ * })
  */
 export const registerOrderFulfillmentStep = createStep(
   registerOrderFulfillmentStepId,

packages/core/core-flows/src/order/steps/register-order-changes.ts

@@ -5,6 +5,11 @@ import {
 import { ModuleRegistrationName } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The input of the register order changes step.
+ */
+export type RegisterOrderChangeStepInput = RegisterOrderChangeDTO[]
+
 export const registerOrderChangeStepId = "register-order-change"
 
 /**
@@ -12,7 +17,7 @@ export const registerOrderChangeStepId = "register-order-change"
  */
 export const registerOrderChangesStep = createStep(
   registerOrderChangeStepId,
-  async (data: RegisterOrderChangeDTO[], { container }) => {
+  async (data: RegisterOrderChangeStepInput, { container }) => {
     const service = container.resolve<IOrderModuleService>(
       ModuleRegistrationName.ORDER
     )

packages/core/core-flows/src/order/steps/return/create-complete-return.ts

@@ -7,7 +7,7 @@ import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
 export const createCompleteReturnStepId = "create-complete-return"
 /**
- * This step creates a return.
+ * This step creates a complete return.
  */
 export const createCompleteReturnStep = createStep(
   createCompleteReturnStepId,

packages/core/core-flows/src/order/steps/return/delete-returns.ts

@@ -2,13 +2,23 @@ import { IOrderModuleService } from "@medusajs/framework/types"
 import { Modules } from "@medusajs/framework/utils"
 import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The details of deleting the returns.
+ */
+export type DeleteReturnStepInput = {
+  /**
+   * The IDs of the returns to delete.
+   */
+  ids: string[]
+}
+
 export const deleteReturnsStepId = "delete-return"
 /**
  * This step deletes one or more returns.
  */
 export const deleteReturnsStep = createStep(
   deleteReturnsStepId,
-  async (data: { ids: string[] }, { container }) => {
+  async (data: DeleteReturnStepInput, { container }) => {
     const service = container.resolve<IOrderModuleService>(Modules.ORDER)
 
     const ids = data.ids.filter(Boolean)

packages/core/core-flows/src/order/steps/return/update-return-items.ts

@@ -4,18 +4,35 @@ import {
 } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
-export interface UpdateReturnItemBySelector {
+/**
+ * The details of updating the return items.
+ */
+export type UpdateReturnItemBySelector = {
+  /**
+   * The ID of the return item to update.
+   */
   id: string
+  /**
+   * The data to update in the return item.
+   */
   [key: string]: any
-}
+}[]
 
 export const updateReturnItemsStepId = "update-return-items"
 /**
  * This step updates return items.
+ * 
+ * @example
+ * const data = updateReturnItemsStep([
+ *   {
+ *     id: "orli_123",
+ *     quantity: 2
+ *   }
+ * ])
  */
 export const updateReturnItemsStep = createStep(
   updateReturnItemsStepId,
-  async (data: UpdateReturnItemBySelector[], { container }) => {
+  async (data: UpdateReturnItemBySelector, { container }) => {
     const service = container.resolve(Modules.ORDER) as any
 
     const { selects, relations } = getSelectsAndRelationsFromObjectArray(data, {

packages/core/core-flows/src/order/steps/return/update-returns.ts

@@ -5,13 +5,18 @@ import {
 } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The returns to update.
+ */
+export type UpdateReturnsStepInput = UpdateReturnDTO[]
+
 export const updateReturnsStepId = "update-returns"
 /**
  * This step updates one or more returns.
  */
 export const updateReturnsStep = createStep(
   updateReturnsStepId,
-  async (data: UpdateReturnDTO[], { container }) => {
+  async (data: UpdateReturnsStepInput, { container }) => {
     const service = container.resolve(Modules.ORDER) as any
 
     const { selects, relations } = getSelectsAndRelationsFromObjectArray(data, {

packages/core/core-flows/src/order/steps/set-tax-lines-for-items.ts

@@ -9,15 +9,51 @@ import {
 import { Modules, promiseAll } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The details of setting tax lines for an order's items and shipping methods.
+ */
 export interface SetOrderTaxLinesForItemsStepInput {
+  /**
+   * The order's details.
+   */
   order: OrderDTO
+  /**
+   * The tax lines to set for the order's items.
+   */
   item_tax_lines: ItemTaxLineDTO[]
+  /**
+   * The tax lines to set for the order's shipping methods.
+   */
   shipping_tax_lines: ShippingTaxLineDTO[]
 }
 
 export const setOrderTaxLinesForItemsStepId = "set-order-tax-lines-for-items"
 /**
  * This step sets the tax lines of an order's items and shipping methods.
+ * 
+ * :::note
+ * 
+ * You can retrieve an order's details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query),
+ * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep).
+ * 
+ * :::
+ * 
+ * @example
+ * const data = setOrderTaxLinesForItemsStep({
+ *   order: {
+ *     id: "order_123",
+ *     // other order details...
+ *   },
+ *   item_tax_lines: [
+ *     {
+ *       line_item_id: "orli_123",
+ *       rate: 0.25,
+ *       code: "VAT",
+ *       name: "VAT",
+ *       provider_id: "tax_provider_123",
+ *     }
+ *   ]
+ * })
  */
 export const setOrderTaxLinesForItemsStep = createStep(
   setOrderTaxLinesForItemsStepId,

packages/core/core-flows/src/order/steps/update-order-change-actions.ts

@@ -9,13 +9,18 @@ import {
 } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The order change actions to update.
+ */
+export type UpdateOrderChangeActionsStepInput = UpdateOrderChangeActionDTO[]
+
 export const updateOrderChangeActionsStepId = "update-order-change-actions"
 /**
  * This step updates order change actions.
  */
 export const updateOrderChangeActionsStep = createStep(
   updateOrderChangeActionsStepId,
-  async (data: UpdateOrderChangeActionDTO[], { container }) => {
+  async (data: UpdateOrderChangeActionsStepInput, { container }) => {
     const service = container.resolve<IOrderModuleService>(Modules.ORDER)
 
     const { selects, relations } = getSelectsAndRelationsFromObjectArray(data, {

packages/core/core-flows/src/order/steps/update-order-changes.ts

@@ -8,13 +8,18 @@ import {
 } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The order changes to update.
+ */
+export type UpdateOrderChangesStepInput = UpdateOrderChangeDTO[]
+
 export const updateOrderChangesStepId = "update-order-shopping-methods"
 /**
  * This step updates order change.
  */
 export const updateOrderChangesStep = createStep(
   updateOrderChangesStepId,
-  async (data: UpdateOrderChangeDTO[], { container }) => {
+  async (data: UpdateOrderChangesStepInput, { container }) => {
     const service = container.resolve<IOrderModuleService>(Modules.ORDER)
 
     const { selects, relations } = getSelectsAndRelationsFromObjectArray(data, {

packages/core/core-flows/src/order/steps/update-order-exchanges.ts

@@ -8,13 +8,18 @@ import {
 } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The order exchanges to update.
+ */
+export type UpdateOrderExchangesStepInput = UpdateOrderExchangeDTO[]
+
 export const updateOrderExchangesStepId = "update-order-exchange"
 /**
  * This step update order changes.
  */
 export const updateOrderExchangesStep = createStep(
   updateOrderExchangesStepId,
-  async (data: UpdateOrderExchangeDTO[], { container }) => {
+  async (data: UpdateOrderExchangesStepInput, { container }) => {
     const service = container.resolve<IOrderModuleService>(Modules.ORDER)
 
     const { selects, relations } = getSelectsAndRelationsFromObjectArray(data, {

packages/core/core-flows/src/order/steps/update-orders.ts

@@ -9,14 +9,33 @@ import {
 } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The details of updating the orders.
+ */
 export type UpdateOrdersStepInput = {
+  /**
+   * The filters to select the orders to update.
+   */
   selector: FilterableOrderProps
+  /**
+   * The data to update in the orders.
+   */
   update: UpdateOrderDTO // TODO: Update to UpdateOrderDTO[]
 }
 
 export const updateOrdersStepId = "update-orders"
 /**
  * This step updates orders matching the specified filters.
+ * 
+ * @example
+ * const data = updateOrdersStep({
+ *   selector: {
+ *     id: "order_123"
+ *   },
+ *   update: {
+ *     region_id: "region_123"
+ *   }
+ * })
  */
 export const updateOrdersStep = createStep(
   updateOrdersStepId,

packages/core/core-flows/src/order/steps/update-shipping-methods.ts

@@ -8,13 +8,18 @@ import {
 } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The order shipping methods to update.
+ */
+export type UpdateOrderShippingMethodsStepInput = UpdateOrderShippingMethodDTO[]
+
 export const updateOrderShippingMethodsStepId = "update-order-shopping-methods"
 /**
  * This step updates order shipping methods.
  */
 export const updateOrderShippingMethodsStep = createStep(
   updateOrderShippingMethodsStepId,
-  async (data: UpdateOrderShippingMethodDTO[], { container }) => {
+  async (data: UpdateOrderShippingMethodsStepInput, { container }) => {
     const service = container.resolve<IOrderModuleService>(Modules.ORDER)
 
     const { selects, relations } = getSelectsAndRelationsFromObjectArray(data, {

packages/core/core-flows/src/order/workflows/add-line-items.ts

@@ -48,15 +48,42 @@ function prepareLineItems(data) {
   return items
 }
 
+/**
+ * The created order line items.
+ */
+export type OrderAddLineItemWorkflowOutput = OrderLineItemDTO[]
+
 export const addOrderLineItemsWorkflowId = "order-add-line-items"
 /**
- * This workflow adds line items to an order.
+ * This workflow adds line items to an order. This is useful when making edits to 
+ * an order. It's used by other workflows, such as {@link orderEditAddNewItemWorkflow}.
+ * 
+ * You can use this workflow within your customizations or your own custom workflows, allowing you to wrap custom logic around adding items to
+ * an order.
+ * 
+ * @example
+ * const { result } = await addOrderLineItemsWorkflow(container)
+ * .run({
+ *   input: {
+ *     order_id: "order_123",
+ *     items: [
+ *       {
+ *         variant_id: "variant_123",
+ *         quantity: 1,
+ *       }
+ *     ]
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Add line items to an order.
  */
 export const addOrderLineItemsWorkflow = createWorkflow(
   addOrderLineItemsWorkflowId,
   (
     input: WorkflowData<OrderWorkflow.OrderAddLineItemWorkflowInput>
-  ): WorkflowResponse<OrderLineItemDTO[]> => {
+  ): WorkflowResponse<OrderAddLineItemWorkflowOutput> => {
     const order = useRemoteQueryStep({
       entry_point: "orders",
       fields: [

packages/core/core-flows/src/order/workflows/archive-orders.ts

@@ -9,19 +9,45 @@ import {
 import { emitEventStep } from "../../common/steps/emit-event"
 import { archiveOrdersStep } from "../steps"
 
+/**
+ * The details of the orders to archive.
+ */
 export type ArchiveOrdersWorkflowInput = {
+  /**
+   * The IDs of the orders to archive.
+   */
   orderIds: string[]
 }
 
+/**
+ * The archived orders.
+ */
+export type ArchiveOrdersWorkflowOutput = OrderDTO[]
+
 export const archiveOrderWorkflowId = "archive-order-workflow"
 /**
- * This workflow archives an order.
+ * This workflow archives one or more orders. It's used by the 
+ * [Archive Order Admin API Route](https://docs.medusajs.com/api/admin#orders_postordersidarchive).
+ * 
+ * You can use this workflow within your customizations or your own custom workflows, allowing you to wrap custom logic around archiving orders.
+ * 
+ * @example
+ * const { result } = await archiveOrderWorkflow(container)
+ * .run({
+ *   input: {
+ *     orderIds: ["order_123"]
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Archive one or more orders.
  */
 export const archiveOrderWorkflow = createWorkflow(
   archiveOrderWorkflowId,
   (
     input: WorkflowData<ArchiveOrdersWorkflowInput>
-  ): WorkflowResponse<OrderDTO[]> => {
+  ): WorkflowResponse<ArchiveOrdersWorkflowOutput> => {
     const eventData = transform({ input }, (data) => {
       return data.input.orderIds.map((id) => ({ id }))
     })

packages/core/core-flows/src/order/workflows/cancel-order-change.ts

@@ -5,6 +5,13 @@ import { cancelOrderChangeStep } from "../steps"
 export const cancelOrderChangeWorkflowId = "cancel-order-change"
 /**
  * This workflow cancels an order change.
+ * 
+ * You can use this workflow within your customizations or your own custom workflows, allowing you to wrap custom logic around 
+ * canceling an order change.
+ * 
+ * @summary
+ * 
+ * Cancel an order change.
  */
 export const cancelOrderChangeWorkflow = createWorkflow(
   cancelOrderChangeWorkflowId,

packages/core/core-flows/src/order/workflows/cancel-order-fulfillment.ts

@@ -29,17 +29,59 @@ import {
 } from "../utils/order-validation"
 
 /**
- * This step validates that an order fulfillment can be canceled.
+ * The data to validate the order fulfillment cancelation.
+ */
+export type CancelOrderFulfillmentValidateOrderStep = {
+  /**
+   * The order to cancel the fulfillment for.
+   */
+  order: OrderDTO & {
+    /**
+     * The order's fulfillments.
+     */ 
+    fulfillments: FulfillmentDTO[]
+  }
+  /**
+   * The cancelation details.
+   */
+  input: OrderWorkflow.CancelOrderFulfillmentWorkflowInput
+}
+
+/**
+ * This step validates that an order fulfillment can be canceled. If 
+ * the fulfillment doesn't exist, or it has already been shipped, the step throws an error.
+ * 
+ * :::note
+ * 
+ * You can retrieve an order and fulfillment details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query),
+ * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep).
+ * 
+ * :::
+ * 
+ * @example
+ * const data = cancelOrderFulfillmentValidateOrder({
+ *   order: {
+ *     id: "order_123",
+ *     fulfillments: [
+ *       {
+ *         id: "ful_123",
+ *         // other fulfillment details...
+ *       }
+ *     ]
+ *     // other order details...
+ *   },
+ *   input: {
+ *     order_id: "order_123",
+ *     fulfillment_id: "ful_123"
+ *   }
+ * })
  */
 export const cancelOrderFulfillmentValidateOrder = createStep(
   "cancel-fulfillment-validate-order",
   ({
     order,
     input,
-  }: {
-    order: OrderDTO & { fulfillments: FulfillmentDTO[] }
-    input: OrderWorkflow.CancelOrderFulfillmentWorkflowInput
-  }) => {
+  }: CancelOrderFulfillmentValidateOrderStep) => {
     throwIfOrderIsCancelled({ order })
 
     const fulfillment = order.fulfillments.find(
@@ -127,7 +169,7 @@ export const cancelOrderFulfillmentWorkflowId = "cancel-order-fulfillment"
  * This workflow has a hook that allows you to perform custom actions on the canceled fulfillment. For example, you can pass under `additional_data` custom data that 
  * allows you to update custom data models linked to the fulfillment.
  * 
- * You can also use this workflow within your own custom workflows, allowing you to wrap custom logic around canceling a 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.
  * 
  * @example
  * const { result } = await cancelOrderFulfillmentWorkflow(container)

packages/core/core-flows/src/order/workflows/cancel-order.ts

@@ -31,16 +31,46 @@ import { createOrderRefundCreditLinesWorkflow } from "./payments/create-order-re
 import { refundCapturedPaymentsWorkflow } from "./payments/refund-captured-payments"
 
 /**
- * This step validates that an order can be canceled.
+ * The data to validate the order's cancelation.
+ */
+export type CancelValidateOrderStepInput = {
+  /**
+   * The order to cancel.
+   */
+  order: OrderDTO
+  /**
+   * The cancelation details.
+   */
+  input: OrderWorkflow.CancelOrderWorkflowInput
+}
+
+/**
+ * This step validates that an order can be canceled. If the order has fulfillments that
+ * aren't canceled, or the order was canceled previously, the step throws an error.
+ * 
+ * :::note
+ * 
+ * You can retrieve an order's details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query),
+ * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep).
+ * 
+ * :::
+ * 
+ * @example
+ * const data = cancelValidateOrder({
+ *   order: {
+ *     id: "order_123",
+ *     // other order details...
+ *   },
+ *   input: {
+ *     order_id: "order_123",
+ *   }
+ * })
  */
 export const cancelValidateOrder = createStep(
   "cancel-validate-order",
   ({
     order,
-  }: {
-    order: OrderDTO
-    input: OrderWorkflow.CancelOrderWorkflowInput
-  }) => {
+  }: CancelValidateOrderStepInput) => {
     const order_ = order as OrderDTO & {
       payment_collections: PaymentCollectionDTO[]
       fulfillments: FulfillmentDTO[]
@@ -69,7 +99,30 @@ export const cancelValidateOrder = createStep(
 
 export const cancelOrderWorkflowId = "cancel-order"
 /**
- * This workflow cancels an order.
+ * This workflow cancels an order. An order can only be canceled if it doesn't have
+ * any fulfillments, or if all fulfillments are canceled. The workflow will also cancel
+ * any uncaptured payments, and refund any captured payments.
+ * 
+ * This workflow is used by the [Cancel Order Admin API Route](https://docs.medusajs.com/api/admin#orders_postordersidcancel).
+ * 
+ * This workflow has a hook that allows you to perform custom actions on the canceled order. For example, you can 
+ * make changes to custom models linked to the order.
+ * 
+ * You can also use this workflow within your customizations or your own custom workflows, allowing you to wrap custom logic around canceling an order.
+ * 
+ * @example
+ * const { result } = await cancelOrderWorkflow(container)
+ * .run({
+ *   input: {
+ *     order_id: "order_123",
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Cancel an order.
+ * 
+ * @property hooks.orderCanceled - This hook is executed after the order is canceled. You can consume this hook to perform custom actions on the canceled order.
  */
 export const cancelOrderWorkflow = createWorkflow(
   cancelOrderWorkflowId,

packages/core/core-flows/src/order/workflows/claim/begin-order-claim.ts

@@ -15,19 +15,62 @@ import { createOrderClaimsStep } from "../../steps/claim/create-claims"
 import { createOrderChangeStep } from "../../steps/create-order-change"
 import { throwIfIsCancelled } from "../../utils/order-validation"
 
+/**
+ * The data to validate that an order can have a claim
+ */
+export type BeginClaimOrderValidationStepInput = {
+  /**
+   * The order's details.
+   */
+  order: OrderDTO
+}
+
 /**
  * This step validates that the order associated with the claim isn't canceled.
+ * If not valid, the step will throw an error.
+ * 
+ * :::note
+ * 
+ * You can retrieve an order's details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query),
+ * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep).
+ * 
+ * :::
+ * 
+ * @example
+ * const data = beginClaimOrderValidationStep({
+ *   order: {
+ *     id: "order_123",
+ *     // other order details...
+ *   },
+ * })
  */
 export const beginClaimOrderValidationStep = createStep(
   "begin-claim-order-validation",
-  async function ({ order }: { order: OrderDTO }) {
+  async function ({ order }: BeginClaimOrderValidationStepInput) {
     throwIfIsCancelled(order, "Order")
   }
 )
 
 export const beginClaimOrderWorkflowId = "begin-claim-order"
 /**
- * This workflow creates an order claim in requested state.
+ * This workflow creates an order claim in requested state. It's used by the 
+ * [Create Claim Admin API Route](https://docs.medusajs.com/api/admin#claims_postclaims).
+ * 
+ * You can use this workflow within your customizations or your own custom workflows, allowing you to create a claim
+ * for an order in your custom flows.
+ * 
+ * @example
+ * const { result } = await beginClaimOrderWorkflow(container)
+ * .run({
+ *   input: {
+ *     order_id: "order_123",
+ *     type: "refund",
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Create an order claim in requested state.
  */
 export const beginClaimOrderWorkflow = createWorkflow(
   beginClaimOrderWorkflowId,

packages/core/core-flows/src/order/workflows/claim/cancel-begin-order-claim.ts

@@ -23,13 +23,50 @@ import {
   throwIfOrderChangeIsNotActive,
 } from "../../utils/order-validation"
 
-export type CancelBeginOrderClaimWorkflowInput = {
-  claim_id: string
+/**
+ * The data to validate the cancelation of a requested order claim.
+ */
+export type CancelBeginOrderClaimValidationStepInput = {
+  /**
+   * The order's details.
+   */
+  order: OrderDTO
+  /**
+   * The order claim's details.
+   */
+  orderClaim: OrderClaimDTO
+  /**
+   * The order change's details.
+   */
+  orderChange: OrderChangeDTO
 }
 
 /**
  * This step validates that the requested claim can be canceled by checking that it's not canceled,
- * its order isn't canceled, and it hasn't been confirmed.
+ * its order isn't canceled, and it hasn't been confirmed. If not valid, the step will throw an error.
+ * 
+ * :::note
+ * 
+ * You can retrieve an order, order claim, and order change details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query),
+ * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep).
+ * 
+ * :::
+ * 
+ * @example
+ * const data = cancelBeginOrderClaimValidationStep({
+ *   order: {
+ *     id: "order_123",
+ *     // other order details...
+ *   },
+ *   orderChange: {
+ *     id: "orch_123",
+ *     // other order change details...
+ *   },
+ *   orderClaim: {
+ *     id: "claim_123",
+ *     // other order claim details...
+ *   }
+ * })
  */
 export const cancelBeginOrderClaimValidationStep = createStep(
   "validate-cancel-begin-order-claim",
@@ -37,20 +74,42 @@ export const cancelBeginOrderClaimValidationStep = createStep(
     order,
     orderChange,
     orderClaim,
-  }: {
-    order: OrderDTO
-    orderClaim: OrderClaimDTO
-    orderChange: OrderChangeDTO
-  }) {
+  }: CancelBeginOrderClaimValidationStepInput) {
     throwIfIsCancelled(order, "Order")
     throwIfIsCancelled(orderClaim, "Claim")
     throwIfOrderChangeIsNotActive({ orderChange })
   }
 )
 
+/**
+ * The data to cancel a requested order claim.
+ */
+export type CancelBeginOrderClaimWorkflowInput = {
+  /**
+   * The ID of the claim to cancel.
+   */
+  claim_id: string
+}
+
 export const cancelBeginOrderClaimWorkflowId = "cancel-begin-order-claim"
 /**
- * This workflow cancels a requested order claim.
+ * This workflow cancels a requested order claim. It's used by the
+ * [Cancel Claim Request Admin API Route](https://docs.medusajs.com/api/admin#claims_deleteclaimsidrequest).
+ * 
+ * You can use this workflow within your customizations or your own custom workflows, allowing you to cancel a claim
+ * for an order in your custom flows.
+ * 
+ * @example
+ * const { result } = await cancelBeginOrderClaimWorkflow(container)
+ * .run({
+ *   input: {
+ *     claim_id: "claim_123",
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Cancel a requested order claim.
  */
 export const cancelBeginOrderClaimWorkflow = createWorkflow(
   cancelBeginOrderClaimWorkflowId,

packages/core/core-flows/src/order/workflows/claim/cancel-claim.ts

@@ -19,16 +19,46 @@ import { throwIfIsCancelled } from "../../utils/order-validation"
 import { cancelReturnWorkflow } from "../return/cancel-return"
 
 /**
- * This step validates that a confirmed claim can be canceled.
+ * The data to validate the cancelation of a confirmed order claim.
+ */
+export type CancelClaimValidateOrderStepInput = {
+  /**
+   * The order claim's details.
+   */
+  orderClaim: OrderClaimDTO
+  /**
+   * The cancelation details.
+   */
+  input: OrderWorkflow.CancelOrderClaimWorkflowInput
+}
+
+/**
+ * This step validates that a confirmed claim can be canceled. If the claim is canceled,
+ * or the claim's fulfillments are not canceled, the step will throw an error.
+ * 
+ * :::note
+ * 
+ * You can retrieve an order claim's details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query),
+ * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep).
+ * 
+ * :::
+ * 
+ * @example
+ * const data = cancelClaimValidateOrderStep({
+ *   orderClaim: {
+ *     id: "claim_123",
+ *     // other order claim details...
+ *   },
+ *   input: {
+ *     claim_id: "claim_123",
+ *   }
+ * })
  */
 export const cancelClaimValidateOrderStep = createStep(
   "validate-claim",
   ({
     orderClaim,
-  }: {
-    orderClaim: OrderClaimDTO
-    input: OrderWorkflow.CancelOrderClaimWorkflowInput
-  }) => {
+  }: CancelClaimValidateOrderStepInput) => {
     const orderClaim_ = orderClaim as OrderClaimDTO & {
       fulfillments: FulfillmentDTO[]
     }
@@ -57,7 +87,23 @@ export const cancelClaimValidateOrderStep = createStep(
 
 export const cancelOrderClaimWorkflowId = "cancel-claim"
 /**
- * This workflow cancels a confirmed order claim.
+ * This workflow cancels a confirmed order claim. It's used by the
+ * [Cancel Claim API Route](https://docs.medusajs.com/api/admin#claims_postclaimsidcancel).
+ * 
+ * You can use this workflow within your customizations or your own custom workflows, allowing you to cancel a claim
+ * for an order in your custom flows.
+ * 
+ * @example
+ * const { result } = await cancelOrderClaimWorkflow(container)
+ * .run({
+ *   input: {
+ *     claim_id: "claim_123",
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Cancel a confirmed order claim.
  */
 export const cancelOrderClaimWorkflow = createWorkflow(
   cancelOrderClaimWorkflowId,

packages/core/core-flows/src/order/workflows/claim/claim-add-new-item.ts

@@ -24,7 +24,49 @@ import { createOrderChangeActionsWorkflow } from "../create-order-change-actions
 import { updateOrderTaxLinesWorkflow } from "../update-tax-lines"
 
 /**
- * This step validates that a new item can be added to the claim.
+ * The data to validate adding new items to a claim.
+ */
+export type OrderClaimAddNewItemValidationStepInput = {
+  /**
+   * The order's details.
+   */
+  order: OrderDTO
+  /**
+   * The order claim's details.
+   */
+  orderClaim: OrderClaimDTO
+  /**
+   * The order change's details.
+   */
+  orderChange: OrderChangeDTO
+}
+
+/**
+ * This step validates that new items can be added to the claim. If the 
+ * order or claim is canceled, or the order change is not active, the step will throw an error.
+ * 
+ * :::note
+ * 
+ * You can retrieve an order, order claim, and order change details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query),
+ * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep).
+ * 
+ * :::
+ * 
+ * @example
+ * const data = orderClaimAddNewItemValidationStep({
+ *   order: {
+ *     id: "order_123",
+ *     // other order details...
+ *   },
+ *   orderChange: {
+ *     id: "orch_123",
+ *     // other order change details...
+ *   },
+ *   orderClaim: {
+ *     id: "claim_123",
+ *     // other order claim details...
+ *   }
+ * })
  */
 export const orderClaimAddNewItemValidationStep = createStep(
   "claim-add-new-item-validation",
@@ -32,11 +74,7 @@ export const orderClaimAddNewItemValidationStep = createStep(
     order,
     orderChange,
     orderClaim,
-  }: {
-    order: OrderDTO
-    orderClaim: OrderClaimDTO
-    orderChange: OrderChangeDTO
-  }) {
+  }: OrderClaimAddNewItemValidationStepInput) {
     throwIfIsCancelled(order, "Order")
     throwIfIsCancelled(orderClaim, "Claim")
     throwIfOrderChangeIsNotActive({ orderChange })
@@ -45,7 +83,29 @@ export const orderClaimAddNewItemValidationStep = createStep(
 
 export const orderClaimAddNewItemWorkflowId = "claim-add-new-item"
 /**
- * This workflow adds a new item to a claim.
+ * This workflow adds outbound (or new) items to a claim. It's used by the
+ * [Add Outbound Items Admin API Route](https://docs.medusajs.com/api/admin#claims_postclaimsidoutbounditems).
+ * 
+ * You can use this workflow within your customizations or your own custom workflows, allowing you to add outbound items to a claim
+ * in your custom flows.
+ * 
+ * @example
+ * const { result } = await orderClaimAddNewItemWorkflow(container)
+ * .run({
+ *   input: {
+ *     claim_id: "claim_123",
+ *     items: [
+ *       {
+ *         variant_id: "variant_123",
+ *         quantity: 1
+ *       }
+ *     ]
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Add outbound or new items to a claim.
  */
 export const orderClaimAddNewItemWorkflow = createWorkflow(
   orderClaimAddNewItemWorkflowId,

packages/core/core-flows/src/order/workflows/claim/claim-item.ts

@@ -22,7 +22,49 @@ import {
 import { createOrderChangeActionsWorkflow } from "../create-order-change-actions"
 
 /**
- * This step validates that claim items can be added to a claim.
+ * The data to validate that claim items can be added to a claim.
+ */
+export type OrderClaimItemValidationStepInput = {
+  /**
+   * The order's details.
+   */
+  order: OrderDTO
+  /**
+   * The order claim's details.
+   */
+  orderClaim: OrderClaimDTO
+  /**
+   * The order change's details.
+   */
+  orderChange: OrderChangeDTO
+}
+
+/**
+ * This step validates that claim items can be added to a claim. If the
+ * order or claim is canceled, or the order change is not active, the step will throw an error.
+ * 
+ * :::note
+ * 
+ * You can retrieve an order, order claim, and order change details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query),
+ * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep).
+ * 
+ * :::
+ * 
+ * @example
+ * const data = orderClaimItemValidationStep({
+ *   order: {
+ *     id: "order_123",
+ *     // other order details...
+ *   },
+ *   orderChange: {
+ *     id: "orch_123",
+ *     // other order change details...
+ *   },
+ *   orderClaim: {
+ *     id: "claim_123",
+ *     // other order claim details...
+ *   }
+ * })
  */
 export const orderClaimItemValidationStep = createStep(
   "claim-item-validation",
@@ -43,7 +85,29 @@ export const orderClaimItemValidationStep = createStep(
 
 export const orderClaimItemWorkflowId = "claim-item"
 /**
- * This workflow adds claim items to a claim.
+ * This workflow adds order items to a claim as claim items. It's used by the 
+ * [Add Claim Items Admin API Route](https://docs.medusajs.com/api/admin#claims_postclaimsidclaimitems).
+ * 
+ * You can use this workflow within your customizations or your own custom workflows, allowing you to add items to a claim
+ * for an order in your custom flows.
+ * 
+ * @example
+ * const { result } = await orderClaimItemWorkflow(container)
+ * .run({
+ *   input: {
+ *     claim_id: "claim_123",
+ *     items: [
+ *       {
+ *         id: "orli_123",
+ *         quantity: 1
+ *       }
+ *     ]
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Add order items to a claim as claim items.
  */
 export const orderClaimItemWorkflow = createWorkflow(
   orderClaimItemWorkflowId,

packages/core/core-flows/src/order/workflows/claim/claim-request-item-return.ts

@@ -27,8 +27,68 @@ import {
 } from "../../utils/order-validation"
 import { createOrderChangeActionsWorkflow } from "../create-order-change-actions"
 
+/**
+ * The data to validate that items can be requested to return as part of a claim.
+ */
+export type OrderClaimRequestItemReturnValidationStepInput = {
+  /**
+   * The order's details.
+   */
+  order: OrderDTO
+  /**
+   * The order return's details.
+   */
+  orderReturn: ReturnDTO
+  /**
+   * The order claim's details.
+   */
+  orderClaim: OrderClaimDTO
+  /**
+   * The order change's details.
+   */
+  orderChange: OrderChangeDTO
+  /**
+   * The items requested to return.
+   */
+  items: OrderWorkflow.OrderClaimRequestItemReturnWorkflowInput["items"]
+}
+
 /**
  * This step validates that items can be requested to return as part of a claim.
+ * If the order, claim, or return is canceled, or the order change is not active, the step will throw an error.
+ * 
+ * :::note
+ * 
+ * You can retrieve an order, order claim, order return, and order change details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query),
+ * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep).
+ * 
+ * :::
+ * 
+ * @example
+ * const data = orderClaimRequestItemReturnValidationStep({
+ *   order: {
+ *     id: "order_123",
+ *     // other order details...
+ *   },
+ *   orderChange: {
+ *     id: "orch_123",
+ *     // other order change details...
+ *   },
+ *   orderClaim: {
+ *     id: "claim_123",
+ *     // other order claim details...
+ *   },
+ *   orderReturn: {
+ *     id: "return_123",
+ *     // other order return details...
+ *   },
+ *   items: [
+ *     {
+ *       id: "orli_123",
+ *       quantity: 1
+ *     }
+ *   ]
+ * })
  */
 export const orderClaimRequestItemReturnValidationStep = createStep(
   "claim-request-item-return-validation",
@@ -38,13 +98,7 @@ export const orderClaimRequestItemReturnValidationStep = createStep(
     orderReturn,
     orderClaim,
     items,
-  }: {
-    order: OrderDTO
-    orderReturn: ReturnDTO
-    orderClaim: OrderClaimDTO
-    orderChange: OrderChangeDTO
-    items: OrderWorkflow.OrderClaimRequestItemReturnWorkflowInput["items"]
-  }) {
+  }: OrderClaimRequestItemReturnValidationStepInput) {
     throwIfIsCancelled(order, "Order")
     throwIfIsCancelled(orderClaim, "Claim")
     throwIfIsCancelled(orderReturn, "Return")
@@ -55,7 +109,31 @@ export const orderClaimRequestItemReturnValidationStep = createStep(
 
 export const orderClaimRequestItemReturnWorkflowId = "claim-request-item-return"
 /**
- * This workflow requests one or more items to be returned as part of a claim.
+ * This workflow requests one or more items to be returned as part of a claim. The
+ * items are added to the claim as inbound items. The workflow is used by the
+ * [Add Inbound Items to Claim Admin API Route](https://docs.medusajs.com/api/admin#claims_postclaimsidinbounditems).
+ * 
+ * You can use this workflow within your customizations or your own custom workflows, allowing you to request items to be returned
+ * as part of a claim in your custom flows.
+ * 
+ * @example
+ * const { result } = await orderClaimRequestItemReturnWorkflow(container)
+ * .run({
+ *   input: {
+ *     claim_id: "claim_123",
+ *     return_id: "return_123",
+ *     items: [
+ *       {
+ *         id: "orli_123",
+ *         quantity: 1
+ *       }
+ *     ]
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Request one or more items to be returned as part of a claim.
  */
 export const orderClaimRequestItemReturnWorkflow = createWorkflow(
   orderClaimRequestItemReturnWorkflowId,

packages/core/core-flows/src/order/workflows/claim/confirm-claim-request.ts

@@ -42,11 +42,6 @@ import {
 } from "../../utils/order-validation"
 import { createOrUpdateOrderPaymentCollectionWorkflow } from "../create-or-update-order-payment-collection"
 
-export type ConfirmClaimRequestWorkflowInput = {
-  claim_id: string
-  confirmed_by?: string
-}
-
 function getUpdateReturnData({ returnId }: { returnId: string }) {
   return transform({ returnId }, ({ returnId }) => {
     return [
@@ -60,7 +55,49 @@ function getUpdateReturnData({ returnId }: { returnId: string }) {
 }
 
 /**
- * This step validates that a requested claim can be confirmed.
+ * The data to validate confirming a claim request.
+ */
+export type ConfirmClaimRequestValidationStepInput = {
+  /**
+   * The order's details.
+   */
+  order: OrderDTO
+  /**
+   * The order claim's details.
+   */
+  orderClaim: OrderClaimDTO
+  /**
+   * The order change's details.
+   */
+  orderChange: OrderChangeDTO
+}
+
+/**
+ * This step validates that a requested claim can be confirmed. If the order or claim is canceled,
+ * or the order change is not active, the step will throw an error.
+ * 
+ * :::note
+ * 
+ * You can retrieve an order, order claim, and order change details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query),
+ * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep).
+ * 
+ * :::
+ * 
+ * @example
+ * const data = confirmClaimRequestValidationStep({
+ *   order: {
+ *     id: "order_123",
+ *     // other order details...
+ *   },
+ *   orderChange: {
+ *     id: "orch_123",
+ *     // other order change details...
+ *   },
+ *   orderClaim: {
+ *     id: "claim_123",
+ *     // other order claim details...
+ *   },
+ * })
  */
 export const confirmClaimRequestValidationStep = createStep(
   "validate-confirm-claim-request",
@@ -68,11 +105,7 @@ export const confirmClaimRequestValidationStep = createStep(
     order,
     orderChange,
     orderClaim,
-  }: {
-    order: OrderDTO
-    orderClaim: OrderClaimDTO
-    orderChange: OrderChangeDTO
-  }) {
+  }: ConfirmClaimRequestValidationStepInput) {
     throwIfIsCancelled(order, "Order")
     throwIfIsCancelled(orderClaim, "Claim")
     throwIfOrderChangeIsNotActive({ orderChange })
@@ -221,9 +254,39 @@ function extractShippingOption({ orderPreview, orderClaim, returnId }) {
   }
 }
 
+/**
+ * The details of confirming the claim request.
+ */
+export type ConfirmClaimRequestWorkflowInput = {
+  /**
+   * The ID of the claim to confirm.
+   */
+  claim_id: string
+  /**
+   * The ID of the user confirming the claim.
+   */
+  confirmed_by?: string
+}
+
 export const confirmClaimRequestWorkflowId = "confirm-claim-request"
 /**
- * This workflow confirms a requested claim.
+ * This workflow confirms a requested claim. It's used by the 
+ * [Confirm Claim Request API Route](https://docs.medusajs.com/api/admin#claims_postclaimsidrequest).
+ * 
+ * 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.
+ * 
+ * @example
+ * const { result } = await confirmClaimRequestWorkflow(container)
+ * .run({
+ *   input: {
+ *     claim_id: "claim_123",
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Confirm a requested claim.
  */
 export const confirmClaimRequestWorkflow = createWorkflow(
   confirmClaimRequestWorkflowId,

packages/core/core-flows/src/order/workflows/claim/create-claim-shipping-method.ts

@@ -23,8 +23,50 @@ import { prepareShippingMethod } from "../../utils/prepare-shipping-method"
 import { createOrderChangeActionsWorkflow } from "../create-order-change-actions"
 import { updateOrderTaxLinesWorkflow } from "../update-tax-lines"
 
+/**
+ * The data to validate that a shipping method can be created for a claim.
+ */
+export type CreateClaimShippingMethodValidationStepInput = {
+  /**
+   * The order's details.
+   */
+  order: OrderDTO
+  /**
+   * The order claim's details.
+   */
+  orderClaim: OrderClaimDTO
+  /**
+   * The order change's details.
+   */
+  orderChange: OrderChangeDTO
+}
+
 /**
  * This step confirms that a shipping method can be created for a claim.
+ * If the order or claim is canceled, or the order change is not active, the step will throw an error.
+ * 
+ * :::note
+ * 
+ * You can retrieve an order, order claim, and order change details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query),
+ * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep).
+ * 
+ * :::
+ * 
+ * @example
+ * const data = createClaimShippingMethodValidationStep({
+ *   order: {
+ *     id: "order_123",
+ *     // other order details...
+ *   },
+ *   orderChange: {
+ *     id: "orch_123",
+ *     // other order change details...
+ *   },
+ *   orderClaim: {
+ *     id: "claim_123",
+ *     // other order claim details...
+ *   },
+ * })
  */
 export const createClaimShippingMethodValidationStep = createStep(
   "validate-create-claim-shipping-method",
@@ -32,30 +74,80 @@ export const createClaimShippingMethodValidationStep = createStep(
     order,
     orderChange,
     orderClaim,
-  }: {
-    order: OrderDTO
-    orderClaim: OrderClaimDTO
-    orderChange: OrderChangeDTO
-  }) {
+  }: CreateClaimShippingMethodValidationStepInput) {
     throwIfIsCancelled(order, "Order")
     throwIfIsCancelled(orderClaim, "Claim")
     throwIfOrderChangeIsNotActive({ orderChange })
   }
 )
 
+/**
+ * The data to create a shipping method for a claim.
+ */
+export type CreateClaimShippingMethodWorkflowInput = {
+  /**
+   * The ID of the return associated with the claim.
+   * If this is set, the shipping method will be created as an inbound (return) shipping method.
+   * If not set, the shipping method will be created as an outbound (delivering new items) shipping method.
+   */
+  return_id?: string
+  /**
+   * The ID of the claim to create the shipping method for.
+   */
+  claim_id?: string
+  /**
+   * The ID of the shipping option to create the shipping method from.
+   */
+  shipping_option_id: string
+  /**
+   * A custom amount to set for the shipping method. If not set, the shipping option's amount is used.
+   */
+  custom_amount?: BigNumberInput | null
+}
+
 export const createClaimShippingMethodWorkflowId =
   "create-claim-shipping-method"
 /**
- * This workflow creates a shipping method for a claim.
+ * This workflow creates an inbound (return) or outbound (delivering new items) shipping method for a claim.
+ * It's used by the [Add Inbound Shipping Admin API Route](https://docs.medusajs.com/api/admin#claims_postclaimsidinboundshippingmethod),
+ * and the [Add Outbound Shipping Admin API Route](https://docs.medusajs.com/api/admin#claims_postclaimsidoutboundshippingmethod).
+ * 
+ * You can use this workflow within your customizations or your own custom workflows, allowing you to create a shipping method
+ * for a claim in your custom flows.
+ * 
+ * @example
+ * To create an outbound shipping method for a claim:
+ * 
+ * ```ts
+ * const { result } = await createClaimShippingMethodWorkflow(container)
+ * .run({
+ *   input: {
+ *     claim_id: "claim_123",
+ *     shipping_option_id: "so_123",
+ *   }
+ * })
+ * ```
+ * 
+ * To create an inbound shipping method for a claim, specify the ID of the return associated with the claim:
+ * 
+ * ```ts
+ * const { result } = await createClaimShippingMethodWorkflow(container)
+ * .run({
+ *   input: {
+ *     claim_id: "claim_123",
+ *     return_id: "return_123",
+ *     shipping_option_id: "so_123",
+ *   }
+ * })
+ * ```
+ * 
+ * @summary
+ * 
+ * Create an inbound or outbound shipping method for a claim.
  */
 export const createClaimShippingMethodWorkflow = createWorkflow(
   createClaimShippingMethodWorkflowId,
-  function (input: {
-    return_id?: string
-    claim_id?: string
-    shipping_option_id: string
-    custom_amount?: BigNumberInput | null
-  }): WorkflowResponse<OrderPreviewDTO> {
+  function (input: CreateClaimShippingMethodWorkflowInput): WorkflowResponse<OrderPreviewDTO> {
     const orderClaim: OrderClaimDTO = useRemoteQueryStep({
       entry_point: "order_claim",
       fields: ["id", "status", "order_id", "canceled_at"],

packages/core/core-flows/src/order/workflows/claim/remove-claim-add-item-action.ts

@@ -27,7 +27,57 @@ import {
 import { removeClaimShippingMethodWorkflow } from "./remove-claim-shipping-method"
 
 /**
- * This step validates that new items can be removed from a claim.
+ * The data to validate that outbound (new) items can be removed from a claim.
+ */
+export type RemoveClaimAddItemActionValidationStepInput = {
+  /**
+   * The order's details.
+   */
+  order: OrderDTO
+  /**
+   * The order claim's details.
+   */
+  orderClaim: OrderClaimDTO
+  /**
+   * The order change's details.
+   */
+  orderChange: OrderChangeDTO
+  /**
+   * The details of removing the outbound items.
+   */
+  input: OrderWorkflow.DeleteOrderClaimItemActionWorkflowInput
+}
+
+/**
+ * This step validates that outbound (new) items can be removed from a claim.
+ * If the order, claim, or order change is canceled, or the action is not adding an item, the step will throw an error.
+ * 
+ * :::note
+ * 
+ * You can retrieve an order, order claim, and order change details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query),
+ * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep).
+ * 
+ * :::
+ * 
+ * @example
+ * const data = removeClaimAddItemActionValidationStep({
+ *   order: {
+ *     id: "order_123",
+ *     // other order details...
+ *   },
+ *   orderChange: {
+ *     id: "orch_123",
+ *     // other order change details...
+ *   },
+ *   orderClaim: {
+ *     id: "claim_123",
+ *     // other order claim details...
+ *   },
+ *   input: {
+ *     claim_id: "claim_123",
+ *     action_id: "orchact_123",
+ *   }
+ * })
  */
 export const removeClaimAddItemActionValidationStep = createStep(
   "remove-item-claim-add-action-validation",
@@ -36,12 +86,7 @@ export const removeClaimAddItemActionValidationStep = createStep(
     orderChange,
     orderClaim,
     input,
-  }: {
-    order: OrderDTO
-    orderClaim: OrderClaimDTO
-    orderChange: OrderChangeDTO
-    input: OrderWorkflow.DeleteOrderClaimItemActionWorkflowInput
-  }) {
+  }: RemoveClaimAddItemActionValidationStepInput) {
     throwIfIsCancelled(order, "Order")
     throwIfIsCancelled(orderClaim, "Claim")
     throwIfOrderChangeIsNotActive({ orderChange })
@@ -60,9 +105,36 @@ export const removeClaimAddItemActionValidationStep = createStep(
   }
 )
 
+/**
+ * The data to remove outbound (new) items from a claim.
+ * 
+ * @property action_id - The ID of the action associated with the outbound items.
+ * Every item has an `actions` property, whose value is an array of actions. 
+ * You can find the action name `ITEM_ADD` using its `action` property, 
+ * and use the value of its `id` property.
+ */
+export type RemoveAddItemClaimActionWorkflowInput = OrderWorkflow.DeleteOrderClaimItemActionWorkflowInput
+
 export const removeAddItemClaimActionWorkflowId = "remove-item-claim-add-action"
 /**
- * This workflow removes new items from a claim.
+ * This workflow removes outbound (new) items from a claim. It's used by the
+ * [Remove Outbound Items Admin API Route](https://docs.medusajs.com/api/admin#claims_deleteclaimsidoutbounditemsaction_id).
+ * 
+ * You can use this workflow within your customizations or your own custom workflows, allowing you to remove outbound items from a claim
+ * in your custom flows.
+ * 
+ * @example
+ * const { result } = await removeAddItemClaimActionWorkflow(container)
+ * .run({
+ *   input: {
+ *     claim_id: "claim_123",
+ *     action_id: "orchact_123",
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Remove outbound (new) items from a claim.
  */
 export const removeAddItemClaimActionWorkflow = createWorkflow(
   removeAddItemClaimActionWorkflowId,

packages/core/core-flows/src/order/workflows/claim/remove-claim-item-action.ts

@@ -24,7 +24,57 @@ import {
 } from "../../utils/order-validation"
 
 /**
- * This step confirms that a claim's items can be removed.
+ * The data to validate that claim items can be removed.
+ */
+export type RemoveClaimItemActionValidationStepInput = {
+  /**
+   * The order's details.
+   */
+  order: OrderDTO
+  /**
+   * The order claim's details.
+   */
+  orderClaim: OrderClaimDTO
+  /**
+   * The order change's details.
+   */
+  orderChange: OrderChangeDTO
+  /**
+   * The details of removing the claim items.
+   */
+  input: OrderWorkflow.DeleteOrderClaimItemActionWorkflowInput
+}
+
+/**
+ * This step confirms that a claim's items, added as order items, can be removed.
+ * If the order, claim, or order change is canceled, or the action is not claiming an item, the step will throw an error.
+ * 
+ * :::note
+ * 
+ * You can retrieve an order, order claim, and order change details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query),
+ * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep).
+ * 
+ * :::
+ * 
+ * @example
+ * const data = removeClaimItemActionValidationStep({
+ *   order: {
+ *     id: "order_123",
+ *     // other order details...
+ *   },
+ *   orderChange: {
+ *     id: "orch_123",
+ *     // other order change details...
+ *   },
+ *   orderClaim: {
+ *     id: "claim_123",
+ *     // other order claim details...
+ *   },
+ *   input: {
+ *     claim_id: "claim_123",
+ *     action_id: "orchact_123",
+ *   }
+ * })
  */
 export const removeClaimItemActionValidationStep = createStep(
   "remove-item-claim-action-validation",
@@ -33,12 +83,7 @@ export const removeClaimItemActionValidationStep = createStep(
     orderChange,
     orderClaim,
     input,
-  }: {
-    order: OrderDTO
-    orderClaim: OrderClaimDTO
-    orderChange: OrderChangeDTO
-    input: OrderWorkflow.DeleteOrderClaimItemActionWorkflowInput
-  }) {
+  }: RemoveClaimItemActionValidationStepInput) {
     throwIfIsCancelled(order, "Order")
     throwIfIsCancelled(orderClaim, "Claim")
     throwIfOrderChangeIsNotActive({ orderChange })
@@ -57,14 +102,37 @@ export const removeClaimItemActionValidationStep = createStep(
   }
 )
 
+/**
+ * The data to remove order items from a claim.
+ * 
+ * @property action_id - The ID of the action associated with the outbound items.
+ * Every item has an `actions` property, whose value is an array of actions. 
+ * You can find the action name `WRITE_OFF_ITEM` using its `action` property, 
+ * and use the value of its `id` property.
+ */
+export type RemoveItemClaimActionWorkflowInput = OrderWorkflow.DeleteOrderClaimItemActionWorkflowInput
+
 export const removeItemClaimActionWorkflowId = "remove-item-claim-action"
 /**
- * This workflow removes claim items.
+ * This workflow removes order items from a claim. It's used by the
+ * [Remove Claim Item Admin API Route](https://docs.medusajs.com/api/admin#claims_deleteclaimsidclaimitemsaction_id).
+ * 
+ * You can use this workflow within your customizations or your own custom workflows, allowing you to remove order items from a claim
+ * in your custom flows.
+ * 
+ * @example
+ * const { result } = await removeItemClaimActionWorkflow(container)
+ * .run({
+ *   input: {
+ *     claim_id: "claim_123",
+ *     action_id: "orchact_123",
+ *   }
+ * })
  */
 export const removeItemClaimActionWorkflow = createWorkflow(
   removeItemClaimActionWorkflowId,
   function (
-    input: WorkflowData<OrderWorkflow.DeleteOrderClaimItemActionWorkflowInput>
+    input: WorkflowData<RemoveItemClaimActionWorkflowInput>
   ): WorkflowResponse<OrderPreviewDTO> {
     const orderClaim: OrderClaimDTO = useRemoteQueryStep({
       entry_point: "order_claim",

packages/core/core-flows/src/order/workflows/claim/remove-claim-shipping-method.ts

@@ -23,8 +23,51 @@ import {
   throwIfOrderChangeIsNotActive,
 } from "../../utils/order-validation"
 
+/**
+ * The data to validate that a claim's shipping method can be removed.
+ */
+export type RemoveClaimShippingMethodValidationStepInput = {
+  /**
+   * The order claim's details.
+   */
+  orderClaim: OrderClaimDTO
+  /**
+   * The order change's details.
+   */
+  orderChange: OrderChangeDTO
+  /**
+   * The details of removing the shipping method.
+   */
+  input: Pick<OrderWorkflow.DeleteClaimShippingMethodWorkflowInput, "claim_id" | "action_id">
+}
+
 /**
  * This step validates that a claim's shipping method can be removed.
+ * If the claim or order change is canceled, the shipping method doesn't
+ * exist in the claim, or the action is not adding a shipping method, the step will throw an error.
+ * 
+ * :::note
+ * 
+ * You can retrieve an order claim and order change details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query),
+ * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep).
+ * 
+ * :::
+ * 
+ * @example
+ * const data = removeClaimShippingMethodValidationStep({
+ *   orderChange: {
+ *     id: "orch_123",
+ *     // other order change details...
+ *   },
+ *   orderClaim: {
+ *     id: "claim_123",
+ *     // other order claim details...
+ *   },
+ *   input: {
+ *     claim_id: "claim_123",
+ *     action_id: "orchact_123",
+ *   }
+ * })
  */
 export const removeClaimShippingMethodValidationStep = createStep(
   "validate-remove-claim-shipping-method",
@@ -32,11 +75,7 @@ export const removeClaimShippingMethodValidationStep = createStep(
     orderChange,
     orderClaim,
     input,
-  }: {
-    input: { claim_id: string; action_id: string }
-    orderClaim: OrderClaimDTO
-    orderChange: OrderChangeDTO
-  }) {
+  }: RemoveClaimShippingMethodValidationStepInput) {
     throwIfIsCancelled(orderClaim, "Claim")
     throwIfOrderChangeIsNotActive({ orderChange })
 
@@ -59,7 +98,25 @@ export const removeClaimShippingMethodValidationStep = createStep(
 export const removeClaimShippingMethodWorkflowId =
   "remove-claim-shipping-method"
 /**
- * This workflow removes the shipping method of a claim.
+ * This workflow removes an inbound (return) or outbound (delivery of new items) shipping method of a claim.
+ * It's used by the [Remove Inbound Shipping Method](https://docs.medusajs.com/api/admin#claims_deleteclaimsidinboundshippingmethodaction_id),
+ * or [Remove Outbound Shipping Method](https://docs.medusajs.com/api/admin#claims_deleteclaimsidoutboundshippingmethodaction_id) Admin API Routes.
+ * 
+ * You can use this workflow within your customizations or your own custom workflows, allowing you to remove shipping methods from a claim
+ * in your own custom flows.
+ * 
+ * @example
+ * const { result } = await removeClaimShippingMethodWorkflow(container)
+ * .run({
+ *   input: {
+ *     claim_id: "claim_123",
+ *     action_id: "orchact_123",
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Remove an inbound or outbound shipping method from a claim.
  */
 export const removeClaimShippingMethodWorkflow = createWorkflow(
   removeClaimShippingMethodWorkflowId,

packages/core/core-flows/src/order/workflows/claim/update-claim-add-item.ts

@@ -25,7 +25,61 @@ import {
 } from "../../utils/order-validation"
 
 /**
- * This step validates that a claim's new item can be updated.
+ * The data to validate that a claim's outbound item can be updated.
+ */
+export type UpdateClaimAddNewItemValidationStepInput = {
+  /**
+   * The order's details.
+   */
+  order: OrderDTO
+  /**
+   * The order claim's details.
+   */
+  orderClaim: OrderClaimDTO
+  /**
+   * The order change's details.
+   */
+  orderChange: OrderChangeDTO
+  /**
+   * The details of updating the outbound item.
+   */
+  input: OrderWorkflow.UpdateClaimAddNewItemWorkflowInput
+}
+
+/**
+ * This step validates that a claim's new or outbound item can be updated.
+ * If the order, claim, or order change is canceled, no action is adding the item,
+ *  or the action is not adding an outbound item, the step will throw an error.
+ * 
+ * :::note
+ * 
+ * You can retrieve an order, order claim, and order change details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query),
+ * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep).
+ * 
+ * :::
+ * 
+ * @example
+ * const data = updateClaimAddItemValidationStep({
+ *   order: {
+ *     id: "order_123",
+ *     // other order details...
+ *   },
+ *   orderChange: {
+ *     id: "orch_123",
+ *     // other order change details...
+ *   },
+ *   orderClaim: {
+ *     id: "claim_123",
+ *     // other order claim details...
+ *   },
+ *   input: {
+ *     claim_id: "claim_123",
+ *     action_id: "orchact_123",
+ *     data: {
+ *       quantity: 1,
+ *     }
+ *   }
+ * })
  */
 export const updateClaimAddItemValidationStep = createStep(
   "update-claim-add-item-validation",
@@ -35,12 +89,7 @@ export const updateClaimAddItemValidationStep = createStep(
       orderChange,
       orderClaim,
       input,
-    }: {
-      order: OrderDTO
-      orderClaim: OrderClaimDTO
-      orderChange: OrderChangeDTO
-      input: OrderWorkflow.UpdateClaimAddNewItemWorkflowInput
-    },
+    }: UpdateClaimAddNewItemValidationStepInput,
     context
   ) {
     throwIfIsCancelled(order, "Order")
@@ -63,7 +112,27 @@ export const updateClaimAddItemValidationStep = createStep(
 
 export const updateClaimAddItemWorkflowId = "update-claim-add-item"
 /**
- * This workflow updates a claim's new item.
+ * This workflow updates a claim's new or outbound item. It's used by the
+ * [Update Outbound Item API Route](https://docs.medusajs.com/api/admin#claims_postclaimsidoutbounditemsaction_id).
+ * 
+ * You can use this workflow within your customizations or your own custom workflows, allowing you to update a claim's new or outbound item
+ * in your custom flows.
+ * 
+ * @example
+ * const { result } = await updateClaimAddItemWorkflow(container)
+ * .run({
+ *   input: {
+ *     claim_id: "claim_123",
+ *     action_id: "orchact_123",
+ *     data: {
+ *       quantity: 1,
+ *     }
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Update a claim's new or outbound item.
  */
 export const updateClaimAddItemWorkflow = createWorkflow(
   updateClaimAddItemWorkflowId,

packages/core/core-flows/src/order/workflows/claim/update-claim-item.ts

@@ -25,7 +25,61 @@ import {
 } from "../../utils/order-validation"
 
 /**
- * This step validates that a claim's item can be updated.
+ * The data to validate that a claim's item can be updated.
+ */
+export type UpdateClaimItemValidationStepInput = {
+  /**
+   * The order's details.
+   */
+  order: OrderDTO
+  /**
+   * The order claim's details.
+   */
+  orderClaim: OrderClaimDTO
+  /**
+   * The order change's details.
+   */
+  orderChange: OrderChangeDTO
+  /**
+   * The details of updating the item.
+   */
+  input: OrderWorkflow.UpdateClaimItemWorkflowInput
+}
+
+/**
+ * This step validates that a claim's item (added as an order item) can be updated.
+ * If the order, claim, or order change is canceled, no action is claiming the item,
+ * or the action is not claiming the item, the step will throw an error.
+ * 
+ * :::note
+ * 
+ * You can retrieve an order, order claim, and order change details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query),
+ * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep).
+ * 
+ * :::
+ * 
+ * @example
+ * const data = updateClaimItemValidationStep({
+ *   order: {
+ *     id: "order_123",
+ *     // other order details...
+ *   },
+ *   orderChange: {
+ *     id: "orch_123",
+ *     // other order change details...
+ *   },
+ *   orderClaim: {
+ *     id: "claim_123",
+ *     // other order claim details...
+ *   },
+ *   input: {
+ *     claim_id: "claim_123",
+ *     action_id: "orchact_123",
+ *     data: {
+ *       quantity: 1,
+ *     }
+ *   }
+ * })
  */
 export const updateClaimItemValidationStep = createStep(
   "update-claim-item-validation",
@@ -35,12 +89,7 @@ export const updateClaimItemValidationStep = createStep(
       orderChange,
       orderClaim,
       input,
-    }: {
-      order: OrderDTO
-      orderClaim: OrderClaimDTO
-      orderChange: OrderChangeDTO
-      input: OrderWorkflow.UpdateClaimItemWorkflowInput
-    },
+    }: UpdateClaimItemValidationStepInput,
     context
   ) {
     throwIfIsCancelled(order, "Order")
@@ -63,7 +112,27 @@ export const updateClaimItemValidationStep = createStep(
 
 export const updateClaimItemWorkflowId = "update-claim-item"
 /**
- * This workflow updates a claim item.
+ * This workflow updates a claim item, added to the claim from an order item.
+ * It's used by the [Update Claim Item Admin API Route](https://docs.medusajs.com/api/admin#claims_postclaimsidclaimitemsaction_id).
+ * 
+ * You can use this workflow within your customizations or your own custom workflows, allowing you to update a claim item
+ * in your custom flows.
+ * 
+ * @example
+ * const { result } = await updateClaimItemWorkflow(container)
+ * .run({
+ *   input: {
+ *     claim_id: "claim_123",
+ *     action_id: "orchact_123",
+ *     data: {
+ *       quantity: 1,
+ *     }
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Update a claim item, added to the claim from an order item.
  */
 export const updateClaimItemWorkflow = createWorkflow(
   updateClaimItemWorkflowId,

packages/core/core-flows/src/order/workflows/claim/update-claim-shipping-method.ts

@@ -27,8 +27,51 @@ import {
 } from "../../utils/order-validation"
 import { prepareShippingMethodUpdate } from "../../utils/prepare-shipping-method"
 
+/**
+ * The data to validate that a claim's shipping method can be updated.
+ */
+export type UpdateClaimShippingMethodValidationStepInput = {
+  /**
+   * The order claim's details.
+   */
+  orderClaim: OrderClaimDTO
+  /**
+   * The order change's details.
+   */
+  orderChange: OrderChangeDTO
+  /**
+   * The details of updating the shipping method.
+   */
+  input: Pick<OrderWorkflow.UpdateClaimShippingMethodWorkflowInput, "claim_id" | "action_id">
+}
+
 /**
  * This step validates that a claim's shipping method can be updated.
+ * If the claim is canceled, the order change is not active, the shipping method isn't added to the claim,
+ * or the action is not adding a shipping method, the step will throw an error.
+ * 
+ * :::note
+ * 
+ * You can retrieve an order claim and order change details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query),
+ * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep).
+ * 
+ * :::
+ * 
+ * @example
+ * const data = updateClaimShippingMethodValidationStep({
+ *   orderChange: {
+ *     id: "orch_123",
+ *     // other order change details...
+ *   },
+ *   orderClaim: {
+ *     id: "claim_123",
+ *     // other order claim details...
+ *   },
+ *   input: {
+ *     claim_id: "claim_123",
+ *     action_id: "orchact_123",
+ *   }
+ * })
  */
 export const updateClaimShippingMethodValidationStep = createStep(
   "validate-update-claim-shipping-method",
@@ -36,11 +79,7 @@ export const updateClaimShippingMethodValidationStep = createStep(
     orderChange,
     orderClaim,
     input,
-  }: {
-    input: { claim_id: string; action_id: string }
-    orderClaim: OrderClaimDTO
-    orderChange: OrderChangeDTO
-  }) {
+  }: UpdateClaimShippingMethodValidationStepInput) {
     throwIfIsCancelled(orderClaim, "Claim")
     throwIfOrderChangeIsNotActive({ orderChange })
 
@@ -63,7 +102,28 @@ export const updateClaimShippingMethodValidationStep = createStep(
 export const updateClaimShippingMethodWorkflowId =
   "update-claim-shipping-method"
 /**
- * This workflow updates a claim's shipping method.
+ * This workflow updates a claim's inbound (return) or outbound (delivery of new items) shipping method.
+ * It's used by the [Update Inbound Shipping Admin API Route](https://docs.medusajs.com/api/admin#claims_postclaimsidinboundshippingmethodaction_id),
+ * and the [Update Outbound Shipping Admin API Route](https://docs.medusajs.com/api/admin#claims_postclaimsidoutboundshippingmethodaction_id).
+ * 
+ * You can use this workflow within your customizations or your own custom workflows, allowing you to update a claim's shipping method
+ * in your own custom flows.
+ * 
+ * @example
+ * const { result } = await updateClaimShippingMethodWorkflow(container)
+ * .run({
+ *   input: {
+ *     claim_id: "claim_123",
+ *     action_id: "orchact_123",
+ *     data: {
+ *       custom_amount: 10,
+ *     }
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Update an inbound or outbound shipping method of a claim.
  */
 export const updateClaimShippingMethodWorkflow = createWorkflow(
   updateClaimShippingMethodWorkflowId,

packages/core/core-flows/src/order/workflows/complete-orders.ts

@@ -27,7 +27,7 @@ export const completeOrderWorkflowId = "complete-order-workflow"
  * This workflow has a hook that allows you to perform custom actions on the completed orders. For example, you can pass under `additional_data` custom data that 
  * allows you to update custom data models linked to the orders.
  * 
- * You can also use this workflow within your own custom workflows, allowing you to wrap custom logic around order completion.
+ * You can also use this workflow within your customizations or your own custom workflows, allowing you to wrap custom logic around order completion.
  * 
  * @example
  * const { result } = await completeOrderWorkflow(container)

packages/core/core-flows/src/order/workflows/create-fulfillment.ts

@@ -40,17 +40,51 @@ import {
 } from "../utils/order-validation"
 
 /**
- * This step validates that a fulfillment can be created for an order.
+ * The data to validate the order fulfillment creation.
+ */
+export type CreateFulfillmentValidateOrderStepInput = {
+  /**
+   * The order to create the fulfillment for.
+   */
+  order: OrderDTO
+  /**
+   * The items to fulfill.
+   */
+  inputItems: OrderWorkflow.CreateOrderFulfillmentWorkflowInput["items"]
+}
+
+/**
+ * This step validates that a fulfillment can be created for an order. If the order
+ * is canceled, the items don't exist in the order, or the items aren't grouped by
+ * shipping requirement, the step throws an error.
+ * 
+ * :::note
+ * 
+ * You can retrieve an order's details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query),
+ * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep).
+ * 
+ * :::
+ * 
+ * @example
+ * const data = createFulfillmentValidateOrder({
+ *   order: {
+ *     id: "order_123",
+ *     // other order details...
+ *   },
+ *   inputItems: [
+ *     {
+ *       id: "orli_123",
+ *       quantity: 1,
+ *     }
+ *   ]
+ * })
  */
 export const createFulfillmentValidateOrder = createStep(
   "create-fulfillment-validate-order",
   ({
     order,
     inputItems,
-  }: {
-    order: OrderDTO
-    inputItems: OrderWorkflow.CreateOrderFulfillmentWorkflowInput["items"]
-  }) => {
+  }: CreateFulfillmentValidateOrderStepInput) => {
     throwIfOrderIsCancelled({ order })
     throwIfItemsDoesNotExistsInOrder({ order, inputItems })
     throwIfItemsAreNotGroupedByShippingRequirement({ order, inputItems })
@@ -247,7 +281,7 @@ export const createOrderFulfillmentWorkflowId = "create-order-fulfillment"
  * This workflow has a hook that allows you to perform custom actions on the created fulfillment. For example, you can pass under `additional_data` custom data that 
  * allows you to create custom data models linked to the fulfillment.
  * 
- * You can also use this workflow within your own custom workflows, allowing you to wrap custom logic around creating a 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.
  * 
  * @example
  * const { result } = await createOrderFulfillmentWorkflow(container)

packages/core/core-flows/src/order/workflows/create-or-update-order-payment-collection.ts

@@ -15,10 +15,40 @@ import { useRemoteQueryStep } from "../../common"
 import { updatePaymentCollectionStep } from "../../payment-collection"
 import { createOrderPaymentCollectionWorkflow } from "./create-order-payment-collection"
 
+/**
+ * The details of the order payment collection to create or update.
+ */
+export type CreateOrUpdateOrderPaymentCollectionInput = {
+  /**
+   * The order to create or update payment collection for.
+   */
+  order_id: string
+  /**
+   * The amount to charge. It can't be greater than the
+   * pending amount of the order. The order's payment collection
+   * will be created or updated with this amount.
+   * If no amount is set, the payment collection's amount is set to `0`.
+   */
+  amount?: number
+}
+
 export const createOrUpdateOrderPaymentCollectionWorkflowId =
   "create-or-update-order-payment-collection"
 /**
- * This workflow creates or updates payment collection for an order.
+ * This workflow creates or updates payment collection for an order. It's used by other order-related workflows,
+ * such as {@link createOrderPaymentCollectionWorkflow} to update an order's payment collections based on changes made to the order.
+ * 
+ * You can use this workflow within your customizations or your own custom workflows, allowing you to wrap custom logic around
+ * creating or updating payment collections for an order.
+ * 
+ * @example
+ * const { result } = await createOrUpdateOrderPaymentCollectionWorkflow(container)
+ * .run({
+ *   input: {
+ *     order_id: "order_123",
+ *     amount: 20
+ *   }
+ * })
  */
 export const createOrUpdateOrderPaymentCollectionWorkflow = createWorkflow(
   createOrUpdateOrderPaymentCollectionWorkflowId,

packages/core/core-flows/src/order/workflows/create-order-change-actions.ts

@@ -12,7 +12,15 @@ import { createEntitiesStep } from "../../common/steps/create-entities"
 
 export const createOrderChangeActionsWorkflowId = "create-order-change-actions"
 /**
- * This workflow creates order change actions.
+ * This workflow creates order change actions. It's used by other order-related workflows,
+ * such as {@link requestItemReturnWorkflow} to create an order change action based on changes made to the order.
+ * 
+ * You can use this workflow within your customizations or your own custom workflows, allowing you to wrap custom logic around 
+ * creating an order change action.
+ * 
+ * @summary
+ * 
+ * Create an order change action.
  */
 export const createOrderChangeActionsWorkflow = createWorkflow(
   createOrderChangeActionsWorkflowId,

packages/core/core-flows/src/order/workflows/create-order-change.ts

@@ -9,6 +9,13 @@ import { createOrderChangeStep } from "../steps"
 export const createOrderChangeWorkflowId = "create-order-change"
 /**
  * This workflow creates an order change.
+ * 
+ * You can use this workflow within your customizations or your own custom workflows, allowing you to wrap custom logic around 
+ * creating an order change.
+ * 
+ * @summary
+ * 
+ * Create an order change.
  */
 export const createOrderChangeWorkflow = createWorkflow(
   createOrderChangeWorkflowId,

packages/core/core-flows/src/order/workflows/create-order-payment-collection.ts

@@ -8,18 +8,46 @@ import {
 import { createRemoteLinkStep, useRemoteQueryStep } from "../../common"
 import { createPaymentCollectionsStep } from "../../cart"
 
+/**
+ * The details of the payment collection to create.
+ */
+export type CreateOrderPaymentCollectionWorkflowInput = {
+  /**
+   * The id of the order for which to create a payment collection.
+   */
+  order_id: string
+  /**
+   * The amount of the payment collection.
+   */
+  amount: number
+}
+
 export const createOrderPaymentCollectionWorkflowId =
   "create-order-payment-collection"
 /**
- * This workflow creates a payment collection for an order.
+ * This workflow creates a payment collection for an order. It's used by the
+ * [Create Payment Collection Admin API Route](https://docs.medusajs.com/api/admin#payment-collections_postpaymentcollections).
+ * 
+ * You can use this workflow within your customizations or your own custom workflows, allowing you to wrap custom logic around
+ * creating a payment collection for an order.
+ * 
+ * @example
+ * const { result } = await createOrderPaymentCollectionWorkflow(container)
+ * .run({
+ *   input: {
+ *     order_id: "order_123",
+ *     amount: 10,
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Create a payment collection for an order.
  */
 export const createOrderPaymentCollectionWorkflow = createWorkflow(
   createOrderPaymentCollectionWorkflowId,
   (
-    input: WorkflowData<{
-      order_id: string
-      amount: number
-    }>
+    input: WorkflowData<CreateOrderPaymentCollectionWorkflowInput>
   ) => {
     const order = useRemoteQueryStep({
       entry_point: "order",

packages/core/core-flows/src/order/workflows/create-order.ts

@@ -86,7 +86,7 @@ export const createOrdersWorkflowId = "create-orders"
  * This workflow has a hook that allows you to perform custom actions on the created order. For example, you can pass under `additional_data` custom data that 
  * allows you to create custom data models linked to the order.
  * 
- * You can also use this workflow within your own custom workflows, allowing you to wrap custom logic around creating an order. For example,
+ * You can also use this workflow within your customizations or your own custom workflows, allowing you to wrap custom logic around creating an order. For example,
  * you can create a workflow that imports orders from an external system, then uses this workflow to create the orders in Medusa.
  * 
  * @example

packages/core/core-flows/src/order/workflows/create-shipment.ts

@@ -22,17 +22,55 @@ import {
 } from "../utils/order-validation"
 
 /**
- * This step validates that a shipment can be created for an order.
+ * The data to validate the order shipment creation.
+ */
+export type CreateShipmentValidateOrderStepInput = {
+  /**
+   * The order to create the shipment for.
+   */
+  order: OrderDTO
+  /**
+   * The shipment creation details.
+   */
+  input: OrderWorkflow.CreateOrderShipmentWorkflowInput
+}
+
+/**
+ * This step validates that a shipment can be created for an order. If the order is cancelled,
+ * the items don't exist in the order, or the fulfillment doesn't exist in the order, 
+ * the step will throw an error.
+ * 
+ * :::note
+ * 
+ * You can retrieve an order's details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query),
+ * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep).
+ * 
+ * :::
+ * 
+ * @example
+ * const data = createShipmentValidateOrder({
+ *   order: {
+ *     id: "order_123",
+ *     // other order details...
+ *   },
+ *   input: {
+ *     order_id: "order_123",
+ *     fulfillment_id: "ful_123",
+ *     items: [
+ *       {
+ *         id: "orli_123",
+ *         quantity: 1
+ *       }
+ *     ]
+ *   }
+ * })
  */
 export const createShipmentValidateOrder = createStep(
   "create-shipment-validate-order",
   ({
     order,
     input,
-  }: {
-    order: OrderDTO
-    input: OrderWorkflow.CreateOrderShipmentWorkflowInput
-  }) => {
+  }: CreateShipmentValidateOrderStepInput) => {
     const inputItems = input.items
 
     throwIfOrderIsCancelled({ order })
@@ -87,7 +125,7 @@ export const createOrderShipmentWorkflowId = "create-order-shipment"
  * This workflow has a hook that allows you to perform custom actions on the created shipment. For example, you can pass under `additional_data` custom data that 
  * allows you to create custom data models linked to the shipment.
  * 
- * You can also use this workflow within your own custom workflows, allowing you to wrap custom logic around creating a shipment.
+ * You can also use this workflow within your customizations or your own custom workflows, allowing you to wrap custom logic around creating a shipment.
  * 
  * @example
  * const { result } = await createOrderShipmentWorkflow(container)

packages/core/core-flows/src/order/workflows/decline-order-change.ts

@@ -5,6 +5,13 @@ import { declineOrderChangeStep } from "../steps"
 export const declineOrderChangeWorkflowId = "decline-order-change"
 /**
  * This workflow declines an order change.
+ * 
+ * You can use this workflow within your customizations or your own custom workflows, allowing you to wrap custom logic around
+ * declining an order change.
+ * 
+ * @summary
+ * 
+ * Decline an order change.
  */
 export const declineOrderChangeWorkflow = createWorkflow(
   declineOrderChangeWorkflowId,

packages/core/core-flows/src/order/workflows/delete-order-change-actions.ts

@@ -1,13 +1,30 @@
 import { WorkflowData, createWorkflow } from "@medusajs/framework/workflows-sdk"
 import { deleteOrderChangeActionsStep } from "../steps"
 
+/**
+ * The details of the order change actions to delete.
+ */
+export type DeleteOrderChangeActionsWorkflowInput = {
+  /**
+   * The IDs of the order change actions to delete.
+   */
+  ids: string[]
+}
+
 export const deleteOrderChangeActionsWorkflowId = "delete-order-change-actions"
 /**
  * This workflow deletes one or more order change actions.
+ * 
+ * You can use this workflow within your customizations or your own custom workflows, allowing you to wrap custom logic around
+ * deleting an order change action.
+ * 
+ * @summary
+ * 
+ * Delete one or more order change actions.
  */
 export const deleteOrderChangeActionsWorkflow = createWorkflow(
   deleteOrderChangeActionsWorkflowId,
-  (input: WorkflowData<{ ids: string[] }>): WorkflowData<void> => {
+  (input: WorkflowData<DeleteOrderChangeActionsWorkflowInput>): WorkflowData<void> => {
     deleteOrderChangeActionsStep(input)
   }
 )

packages/core/core-flows/src/order/workflows/delete-order-change.ts

@@ -1,13 +1,30 @@
 import { WorkflowData, createWorkflow } from "@medusajs/framework/workflows-sdk"
 import { deleteOrderChangesStep } from "../steps"
 
+/**
+ * The details of the order changes to delete.
+ */
+export type DeleteOrderChangeWorkflowInput = {
+  /**
+   * The IDs of the order changes to delete.
+   */
+  ids: string[]
+}
+
 export const deleteOrderChangeWorkflowId = "delete-order-change"
 /**
  * This workflow deletes one or more order changes.
+ * 
+ * You can use this workflow within your customizations or your own custom workflows, allowing you to wrap custom logic around
+ * deleting an order change.
+ * 
+ * @summary
+ * 
+ * Delete one or more order changes.
  */
 export const deleteOrderChangeWorkflow = createWorkflow(
   deleteOrderChangeWorkflowId,
-  (input: WorkflowData<{ ids: string[] }>): WorkflowData<void> => {
+  (input: WorkflowData<DeleteOrderChangeWorkflowInput>): WorkflowData<void> => {
     deleteOrderChangesStep(input)
   }
 )

packages/core/core-flows/src/order/workflows/delete-order-payment-collection.ts

@@ -26,14 +26,40 @@ export const throwUnlessStatusIsNotPaid = createStep(
   }
 )
 
+/**
+ * The details of the payment collection to delete.
+ */
+export type DeleteOrderPaymentCollectionsInput = {
+  /**
+   * The ID of the payment collection to delete.
+   */
+  id: string
+}
+
 export const deleteOrderPaymentCollectionsId =
   "delete-order-payment-collectionworkflow"
 /**
- * This workflow deletes one or more invites.
+ * This workflow deletes one or more payment collections of an order. It's used by the 
+ * [Delete Payment Collection API Route](https://docs.medusajs.com/api/admin#payment-collections_deletepaymentcollectionsid).
+ * 
+ * You can use this workflow within your customizations or your own custom workflows, allowing you to wrap custom logic around
+ * deleting a payment collection of an order.
+ * 
+ * @example
+ * const { result } = await deleteOrderPaymentCollections(container)
+ * .run({
+ *   input: {
+ *     id: "order_123"
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Delete a payment collection of an order.
  */
 export const deleteOrderPaymentCollections = createWorkflow(
   deleteOrderPaymentCollectionsId,
-  (input: WorkflowData<{ id: string }>): WorkflowData<void> => {
+  (input: WorkflowData<DeleteOrderPaymentCollectionsInput>): WorkflowData<void> => {
     const paymentCollection = useRemoteQueryStep({
       entry_point: "payment_collection",
       fields: ["id", "status"],

packages/core/core-flows/src/order/workflows/exchange/begin-order-exchange.ts

@@ -15,19 +15,61 @@ import { createOrderChangeStep } from "../../steps/create-order-change"
 import { createOrderExchangesStep } from "../../steps/exchange/create-exchange"
 import { throwIfOrderIsCancelled } from "../../utils/order-validation"
 
+/**
+ * The data to validate that an exchange can be requested for an order.
+ */
+export type BeginOrderExchangeValidationStepInput = {
+  /**
+   * The order's details.
+   */
+  order: OrderDTO
+}
+
 /**
  * This step validates that an exchange can be requested for an order.
+ * If the order is canceled, the step will throw an error.
+ * 
+ * :::note
+ * 
+ * You can retrieve an order's details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query),
+ * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep).
+ * 
+ * :::
+ * 
+ * @example
+ * const data = beginOrderExchangeValidationStep({
+ *   order: {
+ *     id: "order_123",
+ *     // other order details...
+ *   },
+ * })
  */
 export const beginOrderExchangeValidationStep = createStep(
   "begin-exchange-order-validation",
-  async function ({ order }: { order: OrderDTO }) {
+  async function ({ order }: BeginOrderExchangeValidationStepInput) {
     throwIfOrderIsCancelled({ order })
   }
 )
 
 export const beginExchangeOrderWorkflowId = "begin-exchange-order"
 /**
- * This workflow requests an order exchange.
+ * This workflow requests an order exchange. It's used by the 
+ * [Create Exchange Admin API Route](https://docs.medusajs.com/api/admin#exchanges_postexchanges).
+ * 
+ * You can use this workflow within your customizations or your own custom workflows, allowing you to request an exchange
+ * for an order in your custom flow.
+ * 
+ * @example
+ * const { result } = await beginExchangeOrderWorkflow(container)
+ * .run({
+ *   input: {
+ *     order_id: "order_123",
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Request an order exchange.
  */
 export const beginExchangeOrderWorkflow = createWorkflow(
   beginExchangeOrderWorkflowId,

packages/core/core-flows/src/order/workflows/exchange/cancel-begin-order-exchange.ts

@@ -23,12 +23,50 @@ import {
   throwIfOrderChangeIsNotActive,
 } from "../../utils/order-validation"
 
-export type CancelBeginOrderExchangeWorkflowInput = {
-  exchange_id: string
+/**
+ * The data to validate that a requested exchange can be canceled.
+ */
+export type CancelBeginOrderExchangeValidationStepInput = {
+  /**
+   * The order's details.
+   */
+  order: OrderDTO
+  /**
+   * The order exchange's details.
+   */
+  orderExchange: OrderExchangeDTO
+  /**
+   * The order change's details.
+   */
+  orderChange: OrderChangeDTO
 }
 
 /**
  * This step validates that a requested exchange can be canceled.
+ * If the order or exchange is canceled, or the order change is not active, the step will throw an error.
+ * 
+ * :::note
+ * 
+ * You can retrieve an order, order exchange, and order change details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query),
+ * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep).
+ * 
+ * :::
+ * 
+ * @example
+ * const data = cancelBeginOrderExchangeValidationStep({
+ *   order: {
+ *     id: "order_123",
+ *     // other order details...
+ *   },
+ *   orderChange: {
+ *     id: "orch_123",
+ *     // other order change details...
+ *   },
+ *   orderExchange: {
+ *     id: "exchange_123",
+ *     // other order exchange details...
+ *   },
+ * })
  */
 export const cancelBeginOrderExchangeValidationStep = createStep(
   "validate-cancel-begin-order-exchange",
@@ -36,20 +74,42 @@ export const cancelBeginOrderExchangeValidationStep = createStep(
     order,
     orderChange,
     orderExchange,
-  }: {
-    order: OrderDTO
-    orderExchange: OrderExchangeDTO
-    orderChange: OrderChangeDTO
-  }) {
+  }: CancelBeginOrderExchangeValidationStepInput) {
     throwIfIsCancelled(order, "Order")
     throwIfIsCancelled(orderExchange, "Exchange")
     throwIfOrderChangeIsNotActive({ orderChange })
   }
 )
 
+/**
+ * The details to cancel a requested order exchange.
+ */
+export type CancelBeginOrderExchangeWorkflowInput = {
+  /**
+   * The ID of the exchange to cancel.
+   */
+  exchange_id: string
+}
+
 export const cancelBeginOrderExchangeWorkflowId = "cancel-begin-order-exchange"
 /**
- * This workflow cancels a requested order exchange.
+ * This workflow cancels a requested order exchange. It's used by the
+ * [Cancel Exchange Admin API Route](https://docs.medusajs.com/api/admin#exchanges_deleteexchangesidrequest).
+ * 
+ * You can use this workflow within your customizations or your own custom workflows, allowing you to cancel an exchange
+ * for an order in your custom flow.
+ * 
+ * @example
+ * const { result } = await cancelBeginOrderExchangeWorkflow(container)
+ * .run({
+ *   input: {
+ *     exchange_id: "exchange_123",
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Cancel a requested order exchange.
  */
 export const cancelBeginOrderExchangeWorkflow = createWorkflow(
   cancelBeginOrderExchangeWorkflowId,

packages/core/core-flows/src/order/workflows/exchange/cancel-exchange.ts

@@ -18,17 +18,47 @@ import { cancelOrderExchangeStep } from "../../steps"
 import { throwIfIsCancelled } from "../../utils/order-validation"
 import { cancelReturnWorkflow } from "../return/cancel-return"
 
+/**
+ * The data to validate that an exchange can be canceled.
+ */
+export type CancelExchangeValidateOrderStepInput = {
+  /**
+   * The order exchange's details.
+   */
+  orderExchange: OrderExchangeDTO
+  /**
+   * The details of canceling the exchange.
+   */
+  input: OrderWorkflow.CancelOrderExchangeWorkflowInput
+}
+
 /**
  * This step validates that an exchange can be canceled.
+ * If the exchange is canceled, or any of the fulfillments are not canceled, the step will throw an error.
+ * 
+ * :::note
+ * 
+ * You can retrieve an order exchange's details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query),
+ * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep).
+ * 
+ * :::
+ * 
+ * @example
+ * const data = cancelExchangeValidateOrder({
+ *   orderExchange: {
+ *     id: "exchange_123",
+ *     // other order exchange details...
+ *   },
+ *   input: {
+ *     exchange_id: "exchange_123",
+ *   }
+ * })
  */
 export const cancelExchangeValidateOrder = createStep(
   "validate-exchange",
   ({
     orderExchange,
-  }: {
-    orderExchange: OrderExchangeDTO
-    input: OrderWorkflow.CancelOrderExchangeWorkflowInput
-  }) => {
+  }: CancelExchangeValidateOrderStepInput) => {
     const orderExchange_ = orderExchange as OrderExchangeDTO & {
       fulfillments: FulfillmentDTO[]
     }
@@ -57,7 +87,23 @@ export const cancelExchangeValidateOrder = createStep(
 
 export const cancelOrderExchangeWorkflowId = "cancel-exchange"
 /**
- * This workflow cancels a confirmed exchange.
+ * This workflow cancels a confirmed exchange. It's used by the
+ * [Cancel Exchange Admin API Route](https://docs.medusajs.com/api/admin#exchanges_postexchangesidcancel).
+ * 
+ * You can use this workflow within your customizations or your own custom workflows, allowing you to cancel an exchange
+ * for an order in your custom flow.
+ * 
+ * @example
+ * const { result } = await cancelOrderExchangeWorkflow(container)
+ * .run({
+ *   input: {
+ *     exchange_id: "exchange_123",
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Cancel an exchange for an order.
  */
 export const cancelOrderExchangeWorkflow = createWorkflow(
   cancelOrderExchangeWorkflowId,

packages/core/core-flows/src/order/workflows/exchange/confirm-exchange-request.ts

@@ -42,13 +42,50 @@ import {
 } from "../../utils/order-validation"
 import { createOrUpdateOrderPaymentCollectionWorkflow } from "../create-or-update-order-payment-collection"
 
-export type ConfirmExchangeRequestWorkflowInput = {
-  exchange_id: string
-  confirmed_by?: string
+/**
+ * The data to validate that a requested exchange can be confirmed.
+ */
+export type ConfirmExchangeRequestValidationStepInput = {
+  /**
+   * The order's details.
+   */
+  order: OrderDTO
+  /**
+   * The order exchange's details.
+   */
+  orderExchange: OrderExchangeDTO
+  /**
+   * The order change's details.
+   */
+  orderChange: OrderChangeDTO
 }
 
 /**
  * This step validates that a requested exchange can be confirmed.
+ * If the order or exchange is canceled, or the order change is not active, the step will throw an error.
+ * 
+ * :::note
+ * 
+ * You can retrieve an order, order exchange, and order change details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query),
+ * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep).
+ * 
+ * :::
+ * 
+ * @example
+ * const data = confirmExchangeRequestValidationStep({
+ *   order: {
+ *     id: "order_123",
+ *     // other order details...
+ *   },
+ *   orderChange: {
+ *     id: "orch_123",
+ *     // other order change details...
+ *   },
+ *   orderExchange: {
+ *     id: "exchange_123",
+ *     // other order exchange details...
+ *   },
+ * })
  */
 export const confirmExchangeRequestValidationStep = createStep(
   "validate-confirm-exchange-request",
@@ -56,11 +93,7 @@ export const confirmExchangeRequestValidationStep = createStep(
     order,
     orderChange,
     orderExchange,
-  }: {
-    order: OrderDTO
-    orderExchange: OrderExchangeDTO
-    orderChange: OrderChangeDTO
-  }) {
+  }: ConfirmExchangeRequestValidationStepInput) {
     throwIfIsCancelled(order, "Order")
     throwIfIsCancelled(orderExchange, "Exchange")
     throwIfOrderChangeIsNotActive({ orderChange })
@@ -215,9 +248,39 @@ function getUpdateReturnData({ returnId }: { returnId: string }) {
   })
 }
 
+/**
+ * The details to confirm an exchange request.
+ */
+export type ConfirmExchangeRequestWorkflowInput = {
+  /**
+   * The ID of the exchange to confirm.
+   */
+  exchange_id: string
+  /**
+   * The ID of the user that's confirming the exchange.
+   */
+  confirmed_by?: string
+}
+
 export const confirmExchangeRequestWorkflowId = "confirm-exchange-request"
 /**
- * This workflow confirms an exchange request.
+ * This workflow confirms an exchange request. It's used by the
+ * [Confirm Exchange Admin API Route](https://docs.medusajs.com/api/admin#exchanges_postexchangesidrequest).
+ * 
+ * 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.
+ * 
+ * @example
+ * const { result } = await confirmExchangeRequestWorkflow(container)
+ * .run({
+ *   input: {
+ *     exchange_id: "exchange_123",
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Confirm an exchange request.
  */
 export const confirmExchangeRequestWorkflow = createWorkflow(
   confirmExchangeRequestWorkflowId,

packages/core/core-flows/src/order/workflows/exchange/create-exchange-shipping-method.ts

@@ -24,7 +24,49 @@ import { createOrderChangeActionsWorkflow } from "../create-order-change-actions
 import { updateOrderTaxLinesWorkflow } from "../update-tax-lines"
 
 /**
- * This step validates that a shipping method can be created for an exchange.
+ * The data to validate that a shipping method can be created for an exchange.
+ */
+export type CreateExchangeShippingMethodValidationStepInput = {
+  /**
+   * The order's details.
+   */
+  order: OrderDTO
+  /**
+   * The order exchange's details.
+   */
+  orderExchange: OrderExchangeDTO
+  /**
+   * The order change's details.
+   */
+  orderChange: OrderChangeDTO
+}
+
+/**
+ * This step validates that an inbound or outbound shipping method can be created for an exchange.
+ * If the order or exchange is canceled, or the order change is not active, the step will throw an error.
+ * 
+ * :::note
+ * 
+ * You can retrieve an order, order exchange, and order change details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query),
+ * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep).
+ * 
+ * :::
+ * 
+ * @example
+ * const data = createExchangeShippingMethodValidationStep({
+ *   order: {
+ *     id: "order_123",
+ *     // other order details...
+ *   },
+ *   orderChange: {
+ *     id: "orch_123",
+ *     // other order change details...
+ *   },
+ *   orderExchange: {
+ *     id: "exchange_123",
+ *     // other order exchange details...
+ *   },
+ * })
  */
 export const createExchangeShippingMethodValidationStep = createStep(
   "validate-create-exchange-shipping-method",
@@ -32,30 +74,81 @@ export const createExchangeShippingMethodValidationStep = createStep(
     order,
     orderChange,
     orderExchange,
-  }: {
-    order: OrderDTO
-    orderExchange: OrderExchangeDTO
-    orderChange: OrderChangeDTO
-  }) {
+  }: CreateExchangeShippingMethodValidationStepInput) {
     throwIfIsCancelled(order, "Order")
     throwIfIsCancelled(orderExchange, "Exchange")
     throwIfOrderChangeIsNotActive({ orderChange })
   }
 )
 
+/**
+ * The details to create the shipping method for the exchange.
+ */
+export type CreateExchangeShippingMethodWorkflowInput = {
+  /**
+   * The ID of the return associated with the exchange.
+   * If set, an inbound shipping method will be created for the return.
+   * If not set, an outbound shipping method will be created for the exchange.
+   */
+  return_id?: string
+  /**
+   * The ID of the exchange to create the shipping method for.
+   */
+  exchange_id?: string
+  /**
+   * The ID of the shipping option to create the shipping method from.
+   */
+  shipping_option_id: string
+  /**
+   * The custom amount to charge for the shipping method.
+   * If not set, the shipping option's amount is used.
+   */
+  custom_amount?: BigNumberInput | null
+}
+
 export const createExchangeShippingMethodWorkflowId =
   "create-exchange-shipping-method"
 /**
- * This workflow creates a shipping method for an exchange.
+ * This workflow creates an inbound (return) or outbound (delivery of new items) shipping method for an exchange.
+ * It's used by the [Add Inbound Shipping Admin API Route](https://docs.medusajs.com/api/admin#exchanges_postexchangesidinboundshippingmethod)
+ * and the [Add Outbound Shipping Admin API Route](https://docs.medusajs.com/api/admin#exchanges_postexchangesidoutboundshippingmethod).
+ * 
+ * You can use this workflow within your customizations or your own custom workflows, allowing you to create a shipping method
+ * for an exchange in your custom flow.
+ * 
+ * @example
+ * To create an outbound shipping method for the exchange:
+ * 
+ * ```ts
+ * const { result } = await createExchangeShippingMethodWorkflow(container)
+ * .run({
+ *   input: {
+ *     exchange_id: "exchange_123",
+ *     shipping_option_id: "so_123"
+ *   }
+ * })
+ * ```
+ * 
+ * To create an inbound shipping method, pass the ID of the return associated with the exchange:
+ * 
+ * ```ts
+ * const { result } = await createExchangeShippingMethodWorkflow(container)
+ * .run({
+ *   input: {
+ *     exchange_id: "exchange_123",
+ *     return_id: "return_123",
+ *     shipping_option_id: "so_123"
+ *   }
+ * })
+ * ```
+ * 
+ * @summary
+ * 
+ * Create an inbound or outbound shipping method for an exchange.
  */
 export const createExchangeShippingMethodWorkflow = createWorkflow(
   createExchangeShippingMethodWorkflowId,
-  function (input: {
-    return_id?: string
-    exchange_id?: string
-    shipping_option_id: string
-    custom_amount?: BigNumberInput | null
-  }): WorkflowResponse<OrderPreviewDTO> {
+  function (input: CreateExchangeShippingMethodWorkflowInput): WorkflowResponse<OrderPreviewDTO> {
     const orderExchange: OrderExchangeDTO = useRemoteQueryStep({
       entry_point: "order_exchange",
       fields: ["id", "status", "order_id", "canceled_at"],

packages/core/core-flows/src/order/workflows/exchange/exchange-add-new-item.ts

@@ -24,7 +24,49 @@ import { createOrderChangeActionsWorkflow } from "../create-order-change-actions
 import { updateOrderTaxLinesWorkflow } from "../update-tax-lines"
 
 /**
- * This step validates that new items can be added to an exchange.
+ * The data to validate that new or outbound items can be added to an exchange.
+ */
+export type ExchangeAddNewItemValidationStepInput = {
+  /**
+   * The order's details.
+   */
+  order: OrderDTO
+  /**
+   * The order exchange's details.
+   */
+  orderExchange: OrderExchangeDTO
+  /**
+   * The order change's details.
+   */
+  orderChange: OrderChangeDTO
+}
+
+/**
+ * This step validates that new or outbound items can be added to an exchange.
+ * If the order or exchange is canceled, or the order change is not active, the step will throw an error.
+ * 
+ * :::note
+ * 
+ * You can retrieve an order, order exchange, and order change details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query),
+ * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep).
+ * 
+ * :::
+ * 
+ * @example
+ * const data = exchangeAddNewItemValidationStep({
+ *   order: {
+ *     id: "order_123",
+ *     // other order details...
+ *   },
+ *   orderChange: {
+ *     id: "orch_123",
+ *     // other order change details...
+ *   },
+ *   orderExchange: {
+ *     id: "exchange_123",
+ *     // other order exchange details...
+ *   },
+ * })
  */
 export const exchangeAddNewItemValidationStep = createStep(
   "exchange-add-new-item-validation",
@@ -32,11 +74,7 @@ export const exchangeAddNewItemValidationStep = createStep(
     order,
     orderChange,
     orderExchange,
-  }: {
-    order: OrderDTO
-    orderExchange: OrderExchangeDTO
-    orderChange: OrderChangeDTO
-  }) {
+  }: ExchangeAddNewItemValidationStepInput) {
     throwIfIsCancelled(order, "Order")
     throwIfIsCancelled(orderExchange, "Exchange")
     throwIfOrderChangeIsNotActive({ orderChange })
@@ -45,7 +83,29 @@ export const exchangeAddNewItemValidationStep = createStep(
 
 export const orderExchangeAddNewItemWorkflowId = "exchange-add-new-item"
 /**
- * This workflow adds new items to an exchange.
+ * This workflow adds new or outbound items to an exchange. It's used by the
+ * [Add Outbound Items Admin API Route](https://docs.medusajs.com/api/admin#exchanges_postexchangesidoutbounditems).
+ * 
+ * You can use this workflow within your customizations or your own custom workflows, allowing you to add new or outbound items
+ * to an exchange in your custom flow.
+ * 
+ * @example
+ * const { result } = await orderExchangeAddNewItemWorkflow(container)
+ * .run({
+ *   input: {
+ *     exchange_id: "exchange_123",
+ *     items: [
+ *       {
+ *         variant_id: "variant_123",
+ *         quantity: 1,
+ *       }
+ *     ]
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Add new or outbound items to an exchange.
  */
 export const orderExchangeAddNewItemWorkflow = createWorkflow(
   orderExchangeAddNewItemWorkflowId,

packages/core/core-flows/src/order/workflows/exchange/exchange-request-item-return.ts

@@ -27,8 +27,69 @@ import {
 } from "../../utils/order-validation"
 import { createOrderChangeActionsWorkflow } from "../create-order-change-actions"
 
+/**
+ * The data to validate that items can be returned as part of an exchange.
+ */
+export type ExchangeRequestItemReturnValidationStepInput = {
+  /**
+   * The order's details.
+   */
+  order: OrderDTO
+  /**
+   * The order exchange's details.
+   */
+  orderExchange: OrderExchangeDTO
+  /**
+   * The order change's details.
+   */
+  orderChange: OrderChangeDTO
+  /**
+   * The order return's details.
+   */
+  orderReturn: ReturnDTO
+  /**
+   * The items to be returned.
+   */
+  items: OrderWorkflow.OrderExchangeRequestItemReturnWorkflowInput["items"]
+}
+
 /**
  * This step validates that items can be returned as part of an exchange.
+ * If the order, exchange, or return is canceled, the order change is not active, 
+ * or the item doesn't exist in the order, the step will throw an error.
+ * 
+ * :::note
+ * 
+ * You can retrieve an order, order exchange, and order return details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query),
+ * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep).
+ * 
+ * :::
+ * 
+ * @example
+ * const data = exchangeRequestItemReturnValidationStep({
+ *   order: {
+ *     id: "order_123",
+ *     // other order details...
+ *   },
+ *   orderChange: {
+ *     id: "orch_123",
+ *     // other order change details...
+ *   },
+ *   orderExchange: {
+ *     id: "exchange_123",
+ *     // other order exchange details...
+ *   },
+ *   orderReturn: {
+ *     id: "return_123",
+ *     // other order return details...
+ *   },
+ *   items: [
+ *     {
+ *       id: "orli_123",
+ *       quantity: 1,
+ *     }
+ *   ]
+ * })
  */
 export const exchangeRequestItemReturnValidationStep = createStep(
   "exchange-request-item-return-validation",
@@ -38,13 +99,7 @@ export const exchangeRequestItemReturnValidationStep = createStep(
     orderReturn,
     orderExchange,
     items,
-  }: {
-    order: OrderDTO
-    orderReturn: ReturnDTO
-    orderExchange: OrderExchangeDTO
-    orderChange: OrderChangeDTO
-    items: OrderWorkflow.OrderExchangeRequestItemReturnWorkflowInput["items"]
-  }) {
+  }: ExchangeRequestItemReturnValidationStepInput) {
     throwIfIsCancelled(order, "Order")
     throwIfIsCancelled(orderExchange, "Exchange")
     throwIfIsCancelled(orderReturn, "Return")
@@ -56,7 +111,30 @@ export const exchangeRequestItemReturnValidationStep = createStep(
 export const orderExchangeRequestItemReturnWorkflowId =
   "exchange-request-item-return"
 /**
- * This workflow adds items to be retuned as part of the exchange.
+ * This workflow adds inbound items to be retuned as part of the exchange. It's used
+ * by the [Add Inbound Items Admin API Route](https://docs.medusajs.com/api/admin#exchanges_postexchangesidinbounditems).
+ * 
+ * You can use this workflow within your customizations or your own custom workflows, allowing you to add inbound items
+ * to be returned as part of an exchange in your custom flow.
+ * 
+ * @example
+ * const { result } = await orderExchangeRequestItemReturnWorkflow(container)
+ * .run({
+ *   input: {
+ *     exchange_id: "exchange_123",
+ *     return_id: "return_123",
+ *     items: [
+ *       {
+ *         id: "orli_123",
+ *         quantity: 1,
+ *       }
+ *     ]
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Add inbound items to be returned as part of the exchange.
  */
 export const orderExchangeRequestItemReturnWorkflow = createWorkflow(
   orderExchangeRequestItemReturnWorkflowId,

packages/core/core-flows/src/order/workflows/exchange/remove-exchange-item-action.ts

@@ -27,7 +27,59 @@ import {
 import { removeExchangeShippingMethodWorkflow } from "./remove-exchange-shipping-method"
 
 /**
- * This step validates that a new item can be removed from an exchange.
+ * The data to validate that an outbound item can be removed from an exchange.
+ */
+export type RemoveExchangeItemActionValidationStepInput = {
+  /**
+   * The order's details.
+   */
+  order: OrderDTO
+  /**
+   * The order exchange's details.
+   */
+  orderExchange: OrderExchangeDTO
+  /**
+   * The order change's details.
+   */
+  orderChange: OrderChangeDTO
+  /**
+   * The details of the item to remove.
+   */
+  input: OrderWorkflow.DeleteOrderExchangeItemActionWorkflowInput
+}
+
+/**
+ * This step validates that an outbound item can be removed from an exchange.
+ * If the order or exchange is canceled, the item is not found,
+ * or the order change is not active, the step will throw an error.
+ * 
+ * :::note
+ * 
+ * You can retrieve an order, order exchange, and order change details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query),
+ * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep).
+ * 
+ * :::
+ * 
+ * @example
+ * const data = removeExchangeItemActionValidationStep({
+ *   order: {
+ *     id: "order_123",
+ *     // other order details...
+ *   },
+ *   orderChange: {
+ *     id: "orch_123",
+ *     // other order change details...
+ *   },
+ *   orderExchange: {
+ *     id: "exchange_123",
+ *     // other order exchange details...
+ *   },
+ *   input: {
+ *     exchange_id: "exchange_123",
+ *     action_id: "orchact_123",
+ *   }
+ * })
+ * 
  */
 export const removeExchangeItemActionValidationStep = createStep(
   "remove-item-exchange-action-validation",
@@ -36,12 +88,7 @@ export const removeExchangeItemActionValidationStep = createStep(
     orderChange,
     orderExchange,
     input,
-  }: {
-    order: OrderDTO
-    orderExchange: OrderExchangeDTO
-    orderChange: OrderChangeDTO
-    input: OrderWorkflow.DeleteOrderExchangeItemActionWorkflowInput
-  }) {
+  }: RemoveExchangeItemActionValidationStepInput) {
     throwIfIsCancelled(order, "Order")
     throwIfIsCancelled(orderExchange, "Exchange")
     throwIfOrderChangeIsNotActive({ orderChange })
@@ -62,7 +109,24 @@ export const removeExchangeItemActionValidationStep = createStep(
 
 export const removeItemExchangeActionWorkflowId = "remove-item-exchange-action"
 /**
- * This workflow removes a new item in an exchange.
+ * This workflow removes an outbound or new item from an exchange. It's used by
+ * the [Remove Outbound Item API Route](https://docs.medusajs.com/api/admin#exchanges_deleteexchangesidoutbounditemsaction_id).
+ * 
+ * You can use this workflow within your customizations or your own custom workflows, allowing you to remove an outbound or new item
+ * from an exchange in your custom flow.
+ * 
+ * @example
+ * const { result } = await removeItemExchangeActionWorkflow(container)
+ * .run({
+ *   input: {
+ *     exchange_id: "exchange_123",
+ *     action_id: "orchact_123",
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Remove an outbound or new item from an exchange.
  */
 export const removeItemExchangeActionWorkflow = createWorkflow(
   removeItemExchangeActionWorkflowId,

packages/core/core-flows/src/order/workflows/exchange/remove-exchange-shipping-method.ts

@@ -23,8 +23,51 @@ import {
   throwIfOrderChangeIsNotActive,
 } from "../../utils/order-validation"
 
+/**
+ * The data to validate that a shipping method can be removed from an exchange.
+ */
+export type RemoveExchangeShippingMethodValidationStepInput = {
+  /**
+   * The order exchange's details.
+   */
+  orderExchange: OrderExchangeDTO
+  /**
+   * The order change's details.
+   */
+  orderChange: OrderChangeDTO
+  /**
+   * The details of the action.
+   */
+  input: Pick<OrderWorkflow.DeleteExchangeShippingMethodWorkflowInput, "exchange_id" | "action_id">
+}
+
 /**
  * This step validates that a shipping method can be removed from an exchange.
+ * If the exchange is canceled, the order change is not active, the shipping method
+ * doesn't exist, or the action isn't adding a shipping method, the step will throw an error.
+ * 
+ * :::note
+ * 
+ * You can retrieve an order exchange and order change details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query),
+ * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep).
+ * 
+ * :::
+ * 
+ * @example
+ * const data = removeExchangeShippingMethodValidationStep({
+ *   orderChange: {
+ *     id: "orch_123",
+ *     // other order change details...
+ *   },
+ *   orderExchange: {
+ *     id: "exchange_123",
+ *     // other order exchange details...
+ *   },
+ *   input: {
+ *     exchange_id: "exchange_123",
+ *     action_id: "orchact_123",
+ *   }
+ * })
  */
 export const removeExchangeShippingMethodValidationStep = createStep(
   "validate-remove-exchange-shipping-method",
@@ -32,11 +75,7 @@ export const removeExchangeShippingMethodValidationStep = createStep(
     orderChange,
     orderExchange,
     input,
-  }: {
-    input: { exchange_id: string; action_id: string }
-    orderExchange: OrderExchangeDTO
-    orderChange: OrderChangeDTO
-  }) {
+  }: RemoveExchangeShippingMethodValidationStepInput) {
     throwIfIsCancelled(orderExchange, "Exchange")
     throwIfOrderChangeIsNotActive({ orderChange })
 
@@ -59,7 +98,25 @@ export const removeExchangeShippingMethodValidationStep = createStep(
 export const removeExchangeShippingMethodWorkflowId =
   "remove-exchange-shipping-method"
 /**
- * This workflow removes a shipping method of an exchange.
+ * This workflow removes an inbound or outbound shipping method of an exchange. It's used by the
+ * [Remove Inbound Shipping Admin API Route](https://docs.medusajs.com/api/admin#exchanges_deleteexchangesidinboundshippingmethodaction_id) or
+ * the [Remove Outbound Shipping Admin API Route](https://docs.medusajs.com/api/admin#exchanges_deleteexchangesidoutboundshippingmethodaction_id).
+ * 
+ * You can use this workflow within your customizations or your own custom workflows, allowing you to remove an inbound or outbound shipping method
+ * from an exchange in your custom flow.
+ * 
+ * @example
+ * const { result } = await removeExchangeShippingMethodWorkflow(container)
+ * .run({
+ *   input: {
+ *     exchange_id: "exchange_123",
+ *     action_id: "orchact_123",
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Remove an inbound or outbound shipping method from an exchange.
  */
 export const removeExchangeShippingMethodWorkflow = createWorkflow(
   removeExchangeShippingMethodWorkflowId,

packages/core/core-flows/src/order/workflows/exchange/update-exchange-add-item.ts

@@ -25,7 +25,61 @@ import {
 } from "../../utils/order-validation"
 
 /**
- * This step validates that a new item can be removed from an exchange.
+ * The data to validate that an outbound or new item in an exchange can be updated.
+ */
+export type UpdateExchangeAddItemValidationStepInput = {
+  /**
+   * The order's details.
+   */
+  order: OrderDTO
+  /**
+   * The order exchange's details.
+   */
+  orderExchange: OrderExchangeDTO
+  /**
+   * The order change's details.
+   */
+  orderChange: OrderChangeDTO
+  /**
+   * The details of the item update.
+   */
+  input: OrderWorkflow.UpdateExchangeAddNewItemWorkflowInput
+}
+
+/**
+ * This step validates that an outbound or new item can be removed from an exchange.
+ * If the order or exchange is canceled, the item is not found in the exchange,
+ * or the order change is not active, the step will throw an error.
+ * 
+ * :::note
+ * 
+ * You can retrieve an order, order exchange, and order change details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query),
+ * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep).
+ * 
+ * :::
+ * 
+ * @example
+ * const data = updateExchangeAddItemValidationStep({
+ *   order: {
+ *     id: "order_123",
+ *     // other order details...
+ *   },
+ *   orderChange: {
+ *     id: "orch_123",
+ *     // other order change details...
+ *   },
+ *   orderExchange: {
+ *     id: "exchange_123",
+ *     // other order exchange details...
+ *   },
+ *   input: {
+ *     exchange_id: "exchange_123",
+ *     action_id: "orchact_123",
+ *     data: {
+ *       quantity: 1
+ *     }
+ *   }
+ * })
  */
 export const updateExchangeAddItemValidationStep = createStep(
   "update-exchange-add-item-validation",
@@ -35,12 +89,7 @@ export const updateExchangeAddItemValidationStep = createStep(
       orderChange,
       orderExchange,
       input,
-    }: {
-      order: OrderDTO
-      orderExchange: OrderExchangeDTO
-      orderChange: OrderChangeDTO
-      input: OrderWorkflow.UpdateExchangeAddNewItemWorkflowInput
-    },
+    }: UpdateExchangeAddItemValidationStepInput,
     context
   ) {
     throwIfIsCancelled(order, "Order")
@@ -63,7 +112,27 @@ export const updateExchangeAddItemValidationStep = createStep(
 
 export const updateExchangeAddItemWorkflowId = "update-exchange-add-item"
 /**
- * This workflow updates a new item in the exchange.
+ * This workflow updates an outbound or new item in the exchange. It's used by the
+ * [Update Outbound Item Admin API Route](https://docs.medusajs.com/api/admin#exchanges_postexchangesidoutbounditemsaction_id).
+ * 
+ * You can use this workflow within your customizations or your own custom workflows, allowing you to update an outbound or new item
+ * in an exchange in your custom flow.
+ * 
+ * @example
+ * const { result } = await updateExchangeAddItemWorkflow(container)
+ * .run({
+ *   input: {
+ *     exchange_id: "exchange_123",
+ *     action_id: "orchact_123",
+ *     data: {
+ *       quantity: 1
+ *     }
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Update an outbound or new item in an exchange.
  */
 export const updateExchangeAddItemWorkflow = createWorkflow(
   updateExchangeAddItemWorkflowId,

packages/core/core-flows/src/order/workflows/exchange/update-exchange-shipping-method.ts

@@ -27,8 +27,55 @@ import {
 } from "../../utils/order-validation"
 import { prepareShippingMethodUpdate } from "../../utils/prepare-shipping-method"
 
+/**
+ * The data to validate that an exchange's shipping method can be updated.
+ */
+export type UpdateExchangeShippingMethodValidationStepInput = {
+  /**
+   * The order exchange's details.
+   */
+  orderExchange: OrderExchangeDTO
+  /**
+   * The order change's details.
+   */
+  orderChange: OrderChangeDTO
+  /**
+   * The details of the shipping method update.
+   */
+  input: Pick<OrderWorkflow.UpdateExchangeShippingMethodWorkflowInput, "exchange_id" | "action_id">
+}
+
 /**
  * This step validates that an exchange's shipping method can be updated.
+ * If the exchange is canceled, the order change is not active, the shipping method
+ * doesn't exist in the exchange, or the action isn't adding a shipping method,
+ * the step will throw an error.
+ * 
+ * :::note
+ * 
+ * You can retrieve an order exchange and order change details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query),
+ * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep).
+ * 
+ * :::
+ * 
+ * @example
+ * const data = updateExchangeShippingMethodValidationStep({
+ *   orderChange: {
+ *     id: "orch_123",
+ *     // other order change details...
+ *   },
+ *   orderExchange: {
+ *     id: "exchange_123",
+ *     // other order exchange details...
+ *   },
+ *   input: {
+ *     exchange_id: "exchange_123",
+ *     action_id: "orchact_123",
+ *     data: {
+ *       custom_amount: 10,
+ *     }
+ *   }
+ * })
  */
 export const updateExchangeShippingMethodValidationStep = createStep(
   "validate-update-exchange-shipping-method",
@@ -36,11 +83,7 @@ export const updateExchangeShippingMethodValidationStep = createStep(
     orderChange,
     orderExchange,
     input,
-  }: {
-    input: { exchange_id: string; action_id: string }
-    orderExchange: OrderExchangeDTO
-    orderChange: OrderChangeDTO
-  }) {
+  }: UpdateExchangeShippingMethodValidationStepInput) {
     throwIfIsCancelled(orderExchange, "Exchange")
     throwIfOrderChangeIsNotActive({ orderChange })
 
@@ -63,7 +106,28 @@ export const updateExchangeShippingMethodValidationStep = createStep(
 export const updateExchangeShippingMethodWorkflowId =
   "update-exchange-shipping-method"
 /**
- * This workflow updates an exchange's shipping method.
+ * This workflow updates an exchange's inbound or outbound shipping method. It's used by the
+ * [Update Inbound Shipping Admin API Route](https://docs.medusajs.com/api/admin#exchanges_postexchangesidinboundshippingmethodaction_id)
+ * or the [Outbound Inbound Shipping Admin API Route](https://docs.medusajs.com/api/admin#exchanges_postexchangesidoutboundshippingmethodaction_id).
+ * 
+ * You can use this workflow within your customizations or your own custom workflows, allowing you to update an exchange's
+ * inbound or outbound shipping method in your custom flow.
+ * 
+ * @example
+ * const { result } = await updateExchangeShippingMethodWorkflow(container)
+ * .run({
+ *   input: {
+ *     exchange_id: "exchange_123",
+ *     action_id: "orchact_123",
+ *     data: {
+ *       custom_amount: 10,
+ *     }
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Update an exchange's inbound or outbound shipping method.
  */
 export const updateExchangeShippingMethodWorkflow = createWorkflow(
   updateExchangeShippingMethodWorkflowId,

packages/core/core-flows/src/order/workflows/get-order-detail.ts

@@ -12,19 +12,66 @@ import {
   getLastPaymentStatus,
 } from "../utils/aggregate-status"
 
+/**
+ * The data to retrieve an order's details.
+ */
+export type GetOrderDetailWorkflowInput = {
+  /**
+   * Additional filters to apply on the retrieved order.
+   */
+  filters?: { 
+    /**
+     * Whether to retrieve a draft order.
+     */
+    is_draft_order?: boolean
+    /**
+     * The ID of the customer that the order belongs to.
+     */
+    customer_id?: string
+  }
+  /**
+   * The fields and relations to retrieve in the order. These fields
+   * are passed to [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query),
+   * so you can pass names of custom models linked to the order.
+   */
+  fields: string[]
+  /**
+   * The ID of the order to retrieve.
+   */
+  order_id: string
+  /**
+   * The version of the order to retrieve. If not provided, the latest version
+   * of the order will be retrieved.
+   */
+  version?: number
+}
+
 export const getOrderDetailWorkflowId = "get-order-detail"
 /**
- * This workflow retrieves an order's details.
+ * This workflow retrieves an order's details. It's used by many API routes, including
+ * [Get an Order Admin API Route](https://docs.medusajs.com/api/admin#orders_getordersid), and
+ * [Get an Order Store API Route](https://docs.medusajs.com/api/store#orders_getordersid).
+ * 
+ * You can use this workflow within your customizations or your own custom workflows, allowing you to retrieve an 
+ * order's details in your custom flows.
+ * 
+ * @example
+ * const { result } = await getOrderDetailWorkflow(container)
+ * .run({
+ *   input: {
+ *     order_id: "order_123",
+ *     fields: ["id", "status", "items"]
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Retrieve an order's details.
  */
 export const getOrderDetailWorkflow = createWorkflow(
   getOrderDetailWorkflowId,
   (
-    input: WorkflowData<{
-      filters?: { is_draft_order?: boolean; customer_id?: string }
-      fields: string[]
-      order_id: string
-      version?: number
-    }>
+    input: WorkflowData<GetOrderDetailWorkflowInput>
   ): WorkflowResponse<OrderDetailDTO> => {
     const fields = transform(input, ({ fields }) => {
       return deduplicate([

packages/core/core-flows/src/order/workflows/get-orders-list.ts

@@ -12,24 +12,109 @@ import {
   getLastPaymentStatus,
 } from "../utils/aggregate-status"
 
+/**
+ * The retrieved list of orders. If you passed pagination configurations in the 
+ * input, the response will return an object that includes the list of
+ * orders and their pagination details. Otherwise, only the list of orders are returned.
+ */
 export type GetOrdersListWorkflowOutput =
   | OrderDTO[]
   | {
+    /**
+     * The list of orders.
+     */
       rows: OrderDTO[]
-      metadata: any
+      /**
+       * Pagination details.
+       */
+      metadata: {
+        /**
+         * The total number of orders.
+         */
+        count: number
+        /**
+         * The number of items skipped before retrieving the returned orders.
+         */
+        skip: number
+        /**
+         * The number of items to retrieve.
+         */
+        take: number
+      }
     }
 
+export type GetOrdersListWorkflowInput = {
+  /**
+   * The fields and relations to retrieve in the order. These fields
+   * are passed to [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query),
+   * so you can pass names of custom models linked to the order.
+   */
+  fields: string[]
+  /**
+   * Filters and pagination configurations to apply on the retrieved orders.
+   */
+  variables?: Record<string, any> & {
+    /**
+     * The number of items to skip before retrieving the orders.
+     */
+    skip?: number
+    /**
+     * The number of items to retrieve.
+     */
+    take?: number
+    /**
+     * Fields to sort the orders by. The key is the field name, and the value is either
+     * `ASC` for ascending order or `DESC` for descending order.
+     */
+    order?: Record<string, string>
+  }
+}
+
 export const getOrdersListWorkflowId = "get-orders-list"
 /**
- * This workflow retrieves a list of orders.
+ * This workflow retrieves a list of orders. It's used by the 
+ * [List Orders Admin API Route](https://docs.medusajs.com/api/admin#orders_getorders), and the
+ * [List Orders Store API Route](https://docs.medusajs.com/api/store#orders_getorders).
+ * 
+ * You can use this workflow within your customizations or your own custom workflows, allowing you to retrieve a list of
+ * orders in your custom flows. For example, you can retrieve the list of orders to export them
+ * to a third-party system.
+ * 
+ * @example
+ * To retrieve the list of orders:
+ * 
+ * ```ts
+ * const { result } = await getOrdersListWorkflow(container)
+ * .run({
+ *   input: {
+ *     fields: ["id", "status", "items"],
+ *   }
+ * })
+ * ```
+ * 
+ * To retrieve the list of orders with pagination:
+ * 
+ * ```ts
+ * const { result } = await getOrdersListWorkflow(container)
+ * .run({
+ *   input: {
+ *     fields: ["id", "status", "items"],
+ *     variables: {
+ *       skip: 0,
+ *       take: 15,
+ *     }
+ *   }
+ * })
+ * ```
+ * 
+ * @summary
+ * 
+ * Retrieve a list of orders.
  */
 export const getOrdersListWorkflow = createWorkflow(
   getOrdersListWorkflowId,
   (
-    input: WorkflowData<{
-      fields: string[]
-      variables?: Record<string, any>
-    }>
+    input: WorkflowData<GetOrdersListWorkflowInput>
   ): WorkflowResponse<GetOrdersListWorkflowOutput> => {
     const fields = transform(input, ({ fields }) => {
       return deduplicate([

packages/core/core-flows/src/order/workflows/index.ts

@@ -83,3 +83,4 @@ export * from "./transfer/accept-order-transfer"
 export * from "./transfer/cancel-order-transfer"
 export * from "./transfer/decline-order-transfer"
 export * from "./update-order"
+export * from "./create-or-update-order-payment-collection"

packages/core/core-flows/src/order/workflows/mark-order-fulfillment-as-delivered.ts

@@ -20,10 +20,56 @@ import {
   throwIfOrderIsCancelled,
 } from "../utils/order-validation"
 
+/**
+ * The data to validate the order fulfillment deliverability.
+ */
+export type OrderFulfillmentDeliverabilityValidationStepInput = {
+  /**
+   * The order to validate the fulfillment deliverability for.
+   */
+  order: OrderDTO & { 
+    /**
+     * The fulfillments in the order.
+     */
+    fulfillments: FulfillmentDTO[]
+  }
+  /**
+   * The fulfillment to validate the deliverability for.
+   */
+  fulfillment: FulfillmentDTO
+}
+
 export const orderFulfillmentDeliverablilityValidationStepId =
   "order-fulfillment-deliverability-validation"
 /**
- * This step validates that order & fulfillment are valid
+ * This step validates that the order fulfillment can be delivered. If the order is cancelled,
+ * the items to mark as delivered don't exist in the order, or the fulfillment doesn't exist in the order,
+ * the step will throw an error.
+ * 
+ * :::note
+ * 
+ * You can retrieve an order and fulfillment's details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query),
+ * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep).
+ * 
+ * :::
+ * 
+ * @example
+ * const data = orderFulfillmentDeliverablilityValidationStep({
+ *   order: {
+ *     id: "order_123",
+ *     fulfillments: [
+ *       {
+ *         id: "ful_123",
+ *         // other fulfillment details...
+ *       }
+ *     ]
+ *     // other order details...
+ *   },
+ *   fulfillment: {
+ *     id: "ful_123",
+ *     // other fulfillment details...
+ *   }
+ * })
  */
 export const orderFulfillmentDeliverablilityValidationStep = createStep(
   orderFulfillmentDeliverablilityValidationStepId,
@@ -80,14 +126,45 @@ function prepareRegisterDeliveryData({
   }
 }
 
+/**
+ * The details to mark a fulfillment in an order as delivered.
+ */
+export type MarkOrderFulfillmentAsDeliveredWorkflowInput = {
+  /**
+   * The ID of the order to mark the fulfillment as delivered in.
+   */
+  orderId: string
+  /**
+   * The ID of the fulfillment to mark as delivered.
+   */
+  fulfillmentId: string
+}
+
 export const markOrderFulfillmentAsDeliveredWorkflowId =
   "mark-order-fulfillment-as-delivered-workflow"
 /**
- * This workflow marks a fulfillment in an order as delivered.
+ * This workflow marks a fulfillment in an order as delivered. It's used by the
+ * [Mark Fulfillment as Delivered Admin API Route](https://docs.medusajs.com/api/admin#orders_postordersidfulfillmentsfulfillment_idmarkasdelivered).
+ * 
+ * You can use this workflow within your customizations or your own custom workflows, allowing you to wrap custom logic around
+ * marking a fulfillment as delivered.
+ * 
+ * @example
+ * const { result } = await markOrderFulfillmentAsDeliveredWorkflow(container)
+ * .run({
+ *   input: {
+ *     orderId: "order_123",
+ *     fulfillmentId: "ful_123",
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Mark a fulfillment in an order as delivered.
  */
 export const markOrderFulfillmentAsDeliveredWorkflow = createWorkflow(
   markOrderFulfillmentAsDeliveredWorkflowId,
-  (input: WorkflowData<{ orderId: string; fulfillmentId: string }>) => {
+  (input: WorkflowData<MarkOrderFulfillmentAsDeliveredWorkflowInput>) => {
     const { fulfillmentId, orderId } = input
     const fulfillment = useRemoteQueryStep({
       entry_point: "fulfillment",

packages/core/core-flows/src/order/workflows/mark-payment-collection-as-paid.ts

@@ -14,11 +14,37 @@ import {
 import { createPaymentSessionsWorkflow } from "../../payment-collection"
 
 /**
- * This step validates that the payment collection is not_paid
+ * The details of the payment collection to validate.
+ */
+export type ThrowUnlessPaymentCollectionNotePaidInput = {
+  /**
+   * The payment collection to validate.
+   */
+  paymentCollection: PaymentCollectionDTO
+}
+
+/**
+ * This step validates that the payment collection is not paid. If not valid,
+ * the step will throw an error.
+ * 
+ * :::note
+ * 
+ * You can retrieve a payment collection's details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query),
+ * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep).
+ * 
+ * :::
+ * 
+ * @example
+ * const data = throwUnlessPaymentCollectionNotPaid({
+ *   paymentCollection: {
+ *     id: "paycol_123",
+ *     // other payment details...
+ *   }
+ * })
  */
 export const throwUnlessPaymentCollectionNotPaid = createStep(
   "validate-existing-payment-collection",
-  ({ paymentCollection }: { paymentCollection: PaymentCollectionDTO }) => {
+  ({ paymentCollection }: ThrowUnlessPaymentCollectionNotePaidInput) => {
     if (paymentCollection.status !== "not_paid") {
       throw new MedusaError(
         MedusaError.Types.NOT_ALLOWED,
@@ -28,19 +54,50 @@ export const throwUnlessPaymentCollectionNotPaid = createStep(
   }
 )
 
+/**
+ * The data to mark a payment collection as paid.
+ */
+export type MarkPaymentCollectionAsPaidInput = {
+  /**
+   * The ID of the payment collection to mark as paid.
+   */
+  payment_collection_id: string
+  /**
+   * The ID of the order that the payment collection belongs to.
+   */
+  order_id: string
+  /**
+   * The ID of the user marking the payment collection as completed.
+   */
+  captured_by?: string
+}
+
 const systemPaymentProviderId = "pp_system_default"
 export const markPaymentCollectionAsPaidId = "mark-payment-collection-as-paid"
 /**
- * This workflow marks a payment collection for an order as paid.
+ * This workflow marks a payment collection for an order as paid. It's used by the
+ * [Mark Payment Collection as Paid Admin API Route](https://docs.medusajs.com/api/admin#payment-collections_postpaymentcollectionsidmarkaspaid).
+ * 
+ * You can use this workflow within your customizations or your own custom workflows, allowing you to wrap custom logic around
+ * marking a payment collection for an order as paid.
+ * 
+ * @example
+ * const { result } = await markPaymentCollectionAsPaid(container)
+ * .run({
+ *   input: {
+ *     order_id: "order_123",
+ *     payment_collection_id: "paycol_123",
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Mark a payment collection for an order as paid.
  */
 export const markPaymentCollectionAsPaid = createWorkflow(
   markPaymentCollectionAsPaidId,
   (
-    input: WorkflowData<{
-      payment_collection_id: string
-      order_id: string
-      captured_by?: string
-    }>
+    input: WorkflowData<MarkPaymentCollectionAsPaidInput>
   ) => {
     const paymentCollection = useRemoteQueryStep({
       entry_point: "payment_collection",

packages/core/core-flows/src/order/workflows/order-edit/begin-order-edit.ts

@@ -14,19 +14,64 @@ import { useRemoteQueryStep } from "../../../common"
 import { createOrderChangeStep } from "../../steps/create-order-change"
 import { throwIfOrderIsCancelled } from "../../utils/order-validation"
 
+/**
+ * The data to validate that an order-edit can be requested for an order.
+ */
+export type BeginOrderEditValidationStepInput = {
+  /**
+   * The order's details.
+   */
+  order: OrderDTO
+}
+
 /**
  * This step validates that an order-edit can be requested for an order.
+ * If the order is canceled, the step will throw an error.
+ * 
+ * :::note
+ * 
+ * You can retrieve an order's details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query),
+ * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep).
+ * 
+ * :::
+ * 
+ * @example
+ * const data = beginOrderEditValidationStep({
+ *   order: {
+ *     id: "order_123",
+ *     // other order details...
+ *   }
+ * })
  */
 export const beginOrderEditValidationStep = createStep(
   "begin-order-edit-validation",
-  async function ({ order }: { order: OrderDTO }) {
+  async function ({ order }: BeginOrderEditValidationStepInput) {
     throwIfOrderIsCancelled({ order })
   }
 )
 
 export const beginOrderEditOrderWorkflowId = "begin-order-edit-order"
 /**
- * This workflow requests an order order-edit.
+ * This workflow creates an order edit request. It' used by the
+ * [Create Order Edit Admin API Route](https://docs.medusajs.com/api/admin#order-edits_postorderedits).
+ * 
+ * To request the order edit, use the {@link requestOrderEditRequestWorkflow}. The order edit is then only applied after the 
+ * order edit is confirmed using the {@link confirmOrderEditRequestWorkflow}.
+ * 
+ * You can use this workflow within your customizations or your own custom workflows, allowing you to create an order edit
+ * for an order in your custom flows.
+ * 
+ * @example
+ * const { result } = await beginOrderEditOrderWorkflow(container)
+ * .run({
+ *   input: {
+ *     order_id: "order_123",
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Create an order edit request.
  */
 export const beginOrderEditOrderWorkflow = createWorkflow(
   beginOrderEditOrderWorkflowId,

packages/core/core-flows/src/order/workflows/order-edit/cancel-begin-order-edit.ts

@@ -14,30 +14,83 @@ import {
   throwIfOrderChangeIsNotActive,
 } from "../../utils/order-validation"
 
-export type CancelBeginOrderEditWorkflowInput = {
-  order_id: string
+/**
+ * The data to validate that a requested order edit can be canceled.
+ */
+export type CancelBeginOrderEditValidationStepInput = {
+  /**
+   * The order's details.
+   */
+  order: OrderDTO
+  /**
+   * The order change's details.
+   */
+  orderChange: OrderChangeDTO
 }
 
 /**
  * This step validates that a requested order edit can be canceled.
+ * If the order is canceled or the order change is not active, the step will throw an error.
+ * 
+ * :::note
+ * 
+ * You can retrieve an order and order change details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query),
+ * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep).
+ * 
+ * :::
+ * 
+ * @example
+ * const data = cancelBeginOrderEditValidationStep({
+ *   order: {
+ *     id: "order_123",
+ *     // other order details...
+ *   },
+ *   orderChange: {
+ *     id: "orch_123",
+ *     // other order change details...
+ *   }
+ * })
  */
 export const cancelBeginOrderEditValidationStep = createStep(
   "validate-cancel-begin-order-edit",
   async function ({
     order,
     orderChange,
-  }: {
-    order: OrderDTO
-    orderChange: OrderChangeDTO
-  }) {
+  }: CancelBeginOrderEditValidationStepInput) {
     throwIfIsCancelled(order, "Order")
     throwIfOrderChangeIsNotActive({ orderChange })
   }
 )
 
+/**
+ * The data to cancel a requested order edit.
+ */
+export type CancelBeginOrderEditWorkflowInput = {
+  /**
+   * The ID of the order to cancel the edit for.
+   */
+  order_id: string
+}
+
 export const cancelBeginOrderEditWorkflowId = "cancel-begin-order-edit"
 /**
- * This workflow cancels a requested order edit.
+ * This workflow cancels a requested edit for an order. It's used by the
+ * [Cancel Order Edit Admin API Route](https://docs.medusajs.com/api/admin#order-edits_deleteordereditsid).
+ * 
+ * You can use this workflow within your customizations or your own custom workflows, allowing you to cancel an order edit
+ * in your custom flow.
+ * 
+ * @example
+ * const { result } = await cancelBeginOrderEditWorkflow(container)
+ * .run({
+ *   input: {
+ *     order_id: "order_123",
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Cancel a requested order edit.
  */
 export const cancelBeginOrderEditWorkflow = createWorkflow(
   cancelBeginOrderEditWorkflowId,

packages/core/core-flows/src/order/workflows/order-edit/confirm-order-edit-request.ts

@@ -27,31 +27,87 @@ import {
 } from "../../utils/order-validation"
 import { createOrUpdateOrderPaymentCollectionWorkflow } from "../create-or-update-order-payment-collection"
 
-export type ConfirmOrderEditRequestWorkflowInput = {
-  order_id: string
-  confirmed_by?: string
+/**
+ * The data to validate that a requested order edit can be confirmed.
+ */
+export type ConfirmOrderEditRequestValidationStepInput = {
+  /**
+   * The order's details.
+   */
+  order: OrderDTO
+  /**
+   * The order change's details.
+   */
+  orderChange: OrderChangeDTO
 }
 
 /**
  * This step validates that a requested order edit can be confirmed.
+ * If the order is canceled or the order change is not active, the step will throw an error.
+ * 
+ * :::note
+ * 
+ * You can retrieve an order and order change details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query),
+ * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep).
+ * 
+ * :::
+ * 
+ * @example
+ * const data = confirmOrderEditRequestValidationStep({
+ *   order: {
+ *     id: "order_123",
+ *     // other order details...
+ *   },
+ *   orderChange: {
+ *     id: "orch_123",
+ *     // other order change details...
+ *   }
+ * })
  */
 export const confirmOrderEditRequestValidationStep = createStep(
   "validate-confirm-order-edit-request",
   async function ({
     order,
     orderChange,
-  }: {
-    order: OrderDTO
-    orderChange: OrderChangeDTO
-  }) {
+  }: ConfirmOrderEditRequestValidationStepInput) {
     throwIfIsCancelled(order, "Order")
     throwIfOrderChangeIsNotActive({ orderChange })
   }
 )
 
+/**
+ * The data to confirm an order edit request.
+ */
+export type ConfirmOrderEditRequestWorkflowInput = {
+  /**
+   * The ID of the order to confirm the edit for.
+   */
+  order_id: string
+  /**
+   * The ID of the user confirming the edit.
+   */
+  confirmed_by?: string
+}
+
 export const confirmOrderEditRequestWorkflowId = "confirm-order-edit-request"
 /**
- * This workflow confirms an order edit request.
+ * This workflow confirms an order edit request. It's used by the
+ * [Confirm Order Edit Admin API Route](https://docs.medusajs.com/api/admin#order-edits_postordereditsidconfirm).
+ * 
+ * You can use this workflow within your customizations or your own custom workflows, allowing you to confirm an order edit
+ * in your custom flow.
+ * 
+ * @example
+ * const { result } = await confirmOrderEditRequestWorkflow(container)
+ * .run({
+ *   input: {
+ *     order_id: "order_123",
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Confirm an order edit request.
  */
 export const confirmOrderEditRequestWorkflow = createWorkflow(
   confirmOrderEditRequestWorkflowId,

packages/core/core-flows/src/order/workflows/order-edit/create-order-edit-shipping-method.ts

@@ -22,35 +22,98 @@ import { prepareShippingMethod } from "../../utils/prepare-shipping-method"
 import { createOrderChangeActionsWorkflow } from "../create-order-change-actions"
 import { updateOrderTaxLinesWorkflow } from "../update-tax-lines"
 
+/**
+ * The data to validate that a shipping method can be created for an order edit.
+ */
+export type CreateOrderEditShippingMethodValidationStepInput = {
+  /**
+   * The order's details.
+   */
+  order: OrderDTO
+  /**
+   * The order change's details.
+   */
+  orderChange: OrderChangeDTO
+}
+
 /**
  * This step validates that a shipping method can be created for an order edit.
+ * If the order is canceled or the order change is not active, the step will throw an error.
+ * 
+ * :::note
+ * 
+ * You can retrieve an order and order change details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query),
+ * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep).
+ * 
+ * :::
+ * 
+ * @example
+ * const data = createOrderEditShippingMethodValidationStep({
+ *   order: {
+ *     id: "order_123",
+ *     // other order details...
+ *   },
+ *   orderChange: {
+ *     id: "orch_123",
+ *     // other order change details...
+ *   }
+ * })
  */
 export const createOrderEditShippingMethodValidationStep = createStep(
   "validate-create-order-edit-shipping-method",
   async function ({
     order,
     orderChange,
-  }: {
-    order: OrderDTO
-    orderChange: OrderChangeDTO
-  }) {
+  }: CreateOrderEditShippingMethodValidationStepInput) {
     throwIfIsCancelled(order, "Order")
     throwIfOrderChangeIsNotActive({ orderChange })
   }
 )
 
+/**
+ * The data to create a shipping method for an order edit.
+ */
+export type CreateOrderEditShippingMethodWorkflowInput = {
+  /**
+   * The ID of the order to create the shipping method for.
+   */
+  order_id: string
+  /**
+   * The ID of the shipping option to create the shipping method from.
+   */
+  shipping_option_id: string
+  /**
+   * The custom amount to create the shipping method with.
+   * If not provided, the shipping option's amount is used.
+   */
+  custom_amount?: BigNumberInput | null
+}
+
 export const createOrderEditShippingMethodWorkflowId =
   "create-order-edit-shipping-method"
 /**
- * This workflow creates a shipping method for an order edit.
+ * This workflow creates a shipping method for an order edit. It's used by the
+ * [Add Shipping Method API Route](https://docs.medusajs.com/api/admin#order-edits_postordereditsidshippingmethod).
+ * 
+ * You can use this workflow within your customizations or your own custom workflows, allowing you to create a shipping method
+ * for an order edit in your in your own custom flows.
+ * 
+ * @example
+ * const { result } = await createOrderEditShippingMethodWorkflow(container)
+ * .run({
+ *   input: {
+ *     order_id: "order_123",
+ *     shipping_option_id: "so_123",
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Create a shipping method for an order edit.
  */
 export const createOrderEditShippingMethodWorkflow = createWorkflow(
   createOrderEditShippingMethodWorkflowId,
-  function (input: {
-    order_id: string
-    shipping_option_id: string
-    custom_amount?: BigNumberInput | null
-  }): WorkflowResponse<OrderPreviewDTO> {
+  function (input: CreateOrderEditShippingMethodWorkflowInput): WorkflowResponse<OrderPreviewDTO> {
     const order: OrderDTO = useRemoteQueryStep({
       entry_point: "orders",
       fields: ["id", "status", "currency_code", "canceled_at"],

packages/core/core-flows/src/order/workflows/order-edit/order-edit-add-new-item.ts

@@ -22,18 +22,49 @@ import { addOrderLineItemsWorkflow } from "../add-line-items"
 import { createOrderChangeActionsWorkflow } from "../create-order-change-actions"
 import { updateOrderTaxLinesWorkflow } from "../update-tax-lines"
 
+/**
+ * The data to validate that new items can be added to an order edit.
+ */
+export type OrderEditAddNewItemValidationStepInput = {
+  /**
+   * The order's details.
+   */
+  order: OrderDTO
+  /**
+   * The order change's details.
+   */
+  orderChange: OrderChangeDTO
+}
+
 /**
  * This step validates that new items can be added to an order edit.
+ * If the order is canceled or the order change is not active, the step will throw an error.
+ * 
+ * :::note
+ * 
+ * You can retrieve an order and order change details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query),
+ * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep).
+ * 
+ * :::
+ * 
+ * @example
+ * const data = orderEditAddNewItemValidationStep({
+ *   order: {
+ *     id: "order_123",
+ *     // other order details...
+ *   },
+ *   orderChange: {
+ *     id: "orch_123",
+ *     // other order change details...
+ *   }
+ * })
  */
 export const orderEditAddNewItemValidationStep = createStep(
   "order-edit-add-new-item-validation",
   async function ({
     order,
     orderChange,
-  }: {
-    order: OrderDTO
-    orderChange: OrderChangeDTO
-  }) {
+  }: OrderEditAddNewItemValidationStepInput) {
     throwIfIsCancelled(order, "Order")
     throwIfOrderChangeIsNotActive({ orderChange })
   }
@@ -41,7 +72,29 @@ export const orderEditAddNewItemValidationStep = createStep(
 
 export const orderEditAddNewItemWorkflowId = "order-edit-add-new-item"
 /**
- * This workflow adds new items to an order edit.
+ * This workflow adds new items to an order edit. It's used by the
+ * [Add Items to Order Edit Admin API Route](https://docs.medusajs.com/api/admin#order-edits_postordereditsiditems).
+ * 
+ * You can use this workflow within your customizations or your own custom workflows, allowing you to add new items to an order edit
+ * in your custom flows.
+ * 
+ * @example
+ * const { result } = await orderEditAddNewItemWorkflow(container)
+ * .run({
+ *   input: {
+ *     order_id: "order_123",
+ *     items: [
+ *       {
+ *         variant_id: "variant_123",
+ *         quantity: 1,
+ *       }
+ *     ]
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Add new items to an order edit.
  */
 export const orderEditAddNewItemWorkflow = createWorkflow(
   orderEditAddNewItemWorkflowId,

packages/core/core-flows/src/order/workflows/order-edit/order-edit-update-item-quantity.ts

@@ -26,17 +26,48 @@ import {
 import { createOrderChangeActionsWorkflow } from "../create-order-change-actions"
 
 /**
- * This step validates that item quantity updated can be added to an order edit.
+ * The data to validate that the quantity of an existing item in an order can be updated in an order edit.
+ */
+export type OrderEditUpdateItemQuantityValidationStepInput = {
+  /**
+   * The order's details.
+   */
+  order: OrderDTO
+  /**
+   * The order change's details.
+   */
+  orderChange: OrderChangeDTO
+}
+
+/**
+ * This step validates that the quantity of an existing item in an order can be updated in an order edit.
+ * If the order is canceled or the order change is not active, the step will throw an error.
+ * 
+ * :::note
+ * 
+ * You can retrieve an order and order change details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query),
+ * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep).
+ * 
+ * :::
+ * 
+ * @example
+ * const data = orderEditUpdateItemQuantityValidationStep({
+ *   order: {
+ *     id: "order_123",
+ *     // other order details...
+ *   },
+ *   orderChange: {
+ *     id: "orch_123",
+ *     // other order change details...
+ *   }
+ * })
  */
 export const orderEditUpdateItemQuantityValidationStep = createStep(
   "order-edit-update-item-quantity-validation",
   async function ({
     order,
     orderChange,
-  }: {
-    order: OrderDTO
-    orderChange: OrderChangeDTO
-  }) {
+  }: OrderEditUpdateItemQuantityValidationStepInput) {
     throwIfIsCancelled(order, "Order")
     throwIfOrderChangeIsNotActive({ orderChange })
   }
@@ -45,7 +76,29 @@ export const orderEditUpdateItemQuantityValidationStep = createStep(
 export const orderEditUpdateItemQuantityWorkflowId =
   "order-edit-update-item-quantity"
 /**
- * This workflow update item's quantity of an order.
+ * This workflow updates the quantity of an existing item in an order's edit. It's used by the
+ * [Update Order Item Quantity Admin API Route](https://docs.medusajs.com/api/admin#order-edits_postordereditsiditemsitemitem_id).
+ * 
+ * You can use this workflow within your customizations or your own custom workflows, allowing you to update the quantity of an existing 
+ * item in an order's edit in your custom flow.
+ * 
+ * @example
+ * const { result } = await orderEditUpdateItemQuantityWorkflow(container)
+ * .run({
+ *   input: {
+ *     order_id: "order_123",
+ *     items: [
+ *       {
+ *         id: "orli_123",
+ *         quantity: 2,
+ *       }
+ *     ]
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Update the quantity of an existing order item in the order's edit.
  */
 export const orderEditUpdateItemQuantityWorkflow = createWorkflow(
   orderEditUpdateItemQuantityWorkflowId,

packages/core/core-flows/src/order/workflows/order-edit/remove-order-edit-item-action.ts

@@ -23,7 +23,50 @@ import {
 } from "../../utils/order-validation"
 
 /**
- * This step validates that a new item can be removed from an order edit.
+ * The data to validate that an item that was added in an order edit can be removed.
+ */
+export type RemoveOrderEditItemActionValidationStepInput = {
+  /**
+   * The order's details.
+   */
+  order: OrderDTO
+  /**
+   * The order change's details.
+   */
+  orderChange: OrderChangeDTO
+  /**
+   * The details of the item to be removed.
+   */
+  input: OrderWorkflow.DeleteOrderEditItemActionWorkflowInput
+}
+
+/**
+ * This step validates that an item that was added in the order edit can be removed 
+ * from the order edit. If the order is canceled or the order change is not active,
+ * the step will throw an error.
+ * 
+ * :::note
+ * 
+ * You can retrieve an order and order change details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query),
+ * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep).
+ * 
+ * :::
+ * 
+ * @example
+ * const data = removeOrderEditItemActionValidationStep({
+ *   order: {
+ *     id: "order_123",
+ *     // other order details...
+ *   },
+ *   orderChange: {
+ *     id: "orch_123",
+ *     // other order change details...
+ *   },
+ *   input: {
+ *     order_id: "order_123",
+ *     action_id: "orchact_123",
+ *   }
+ * })
  */
 export const removeOrderEditItemActionValidationStep = createStep(
   "remove-item-order-edit-action-validation",
@@ -31,11 +74,7 @@ export const removeOrderEditItemActionValidationStep = createStep(
     order,
     orderChange,
     input,
-  }: {
-    order: OrderDTO
-    orderChange: OrderChangeDTO
-    input: OrderWorkflow.DeleteOrderEditItemActionWorkflowInput
-  }) {
+  }: RemoveOrderEditItemActionValidationStepInput) {
     throwIfIsCancelled(order, "Order")
     throwIfOrderChangeIsNotActive({ orderChange })
 
@@ -62,7 +101,24 @@ export const removeOrderEditItemActionValidationStep = createStep(
 export const removeItemOrderEditActionWorkflowId =
   "remove-item-order edit-action"
 /**
- * This workflow removes a new item in an order edit.
+ * This workflow removes an item that was added to an order edit. It's used by the
+ * [Remove Item from Order Edit Admin API Route](https://docs.medusajs.com/api/admin#order-edits_deleteordereditsiditemsaction_id).
+ * 
+ * You can use this workflow within your customizations or your own custom workflows, allowing you to remove an item that was 
+ * added to an order edit in your custom flow.
+ * 
+ * @example
+ * const { result } = await removeItemOrderEditActionWorkflow(container)
+ * .run({
+ *   input: {
+ *     order_id: "order_123",
+ *     action_id: "orchact_123",
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Remove an item that was added to an order edit.
  */
 export const removeItemOrderEditActionWorkflow = createWorkflow(
   removeItemOrderEditActionWorkflowId,

packages/core/core-flows/src/order/workflows/order-edit/remove-order-edit-shipping-method.ts

@@ -19,18 +19,50 @@ import { deleteOrderChangeActionsStep } from "../../steps/delete-order-change-ac
 import { previewOrderChangeStep } from "../../steps/preview-order-change"
 import { throwIfOrderChangeIsNotActive } from "../../utils/order-validation"
 
+/**
+ * The data to validate that a shipping method can be removed from an order edit.
+ */
+export type RemoveOrderEditShippingMethodValidationStepInput = {
+  /**
+   * The order change's details.
+   */
+  orderChange: OrderChangeDTO
+  /**
+   * The details of the shipping method to be removed.
+   */
+  input: Pick<OrderWorkflow.DeleteOrderEditShippingMethodWorkflowInput, "order_id" | "action_id">
+}
+
 /**
  * This step validates that a shipping method can be removed from an order edit.
+ * If the order change is not active, the shipping method isn't in the exchange,
+ * or the action doesn't add a shipping method, the step will throw an error.
+ * 
+ * :::note
+ * 
+ * You can retrieve an order change details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query),
+ * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep).
+ * 
+ * :::
+ * 
+ * @example
+ * const data = removeOrderEditShippingMethodValidationStep({
+ *   orderChange: {
+ *     id: "orch_123",
+ *     // other order change details...
+ *   },
+ *   input: {
+ *     order_id: "order_123",
+ *     action_id: "orchact_123",
+ *   }
+ * })
  */
 export const removeOrderEditShippingMethodValidationStep = createStep(
   "validate-remove-order-edit-shipping-method",
   async function ({
     orderChange,
     input,
-  }: {
-    input: { order_id: string; action_id: string }
-    orderChange: OrderChangeDTO
-  }) {
+  }: RemoveOrderEditShippingMethodValidationStepInput) {
     throwIfOrderChangeIsNotActive({ orderChange })
 
     const associatedAction = (orderChange.actions ?? []).find(
@@ -52,7 +84,24 @@ export const removeOrderEditShippingMethodValidationStep = createStep(
 export const removeOrderEditShippingMethodWorkflowId =
   "remove-order-edit-shipping-method"
 /**
- * This workflow removes a shipping method of an order edit.
+ * This workflow removes a shipping method of an order edit. It's used by the 
+ * [Remove Shipping Method Admin API Route](https://docs.medusajs.com/api/admin#order-edits_deleteordereditsidshippingmethodaction_id).
+ * 
+ * You can use this workflow within your customizations or your own custom workflows, allowing you to remove a 
+ * shipping method from an order edit in your custom flows.
+ * 
+ * @example
+ * const { result } = await removeOrderEditShippingMethodWorkflow(container)
+ * .run({
+ *   input: {
+ *     order_id: "order_123",
+ *     action_id: "orchact_123",
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Remove a shipping method from an order edit.
  */
 export const removeOrderEditShippingMethodWorkflow = createWorkflow(
   removeOrderEditShippingMethodWorkflowId,

packages/core/core-flows/src/order/workflows/order-edit/request-order-edit.ts

@@ -19,11 +19,6 @@ import {
 } from "../../utils/order-validation"
 import { createOrUpdateOrderPaymentCollectionWorkflow } from "../create-or-update-order-payment-collection"
 
-export type OrderEditRequestWorkflowInput = {
-  order_id: string
-  requested_by?: string
-}
-
 function getOrderChangesData({
   input,
   orderChange,
@@ -43,26 +38,87 @@ function getOrderChangesData({
   })
 }
 
+/**
+ * The data to validate that an order edit can be requested.
+ */
+export type RequestOrderEditRequestValidationStepInput = {
+  /**
+   * The order's details.
+   */
+  order: OrderDTO
+  /**
+   * The order change's details.
+   */
+  orderChange: OrderChangeDTO
+}
+
 /**
  * This step validates that a order edit can be requested.
+ * If the order is canceled or the order change is not active, the step will throw an error.
+ * 
+ * :::note
+ * 
+ * You can retrieve an order and order change details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query),
+ * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep).
+ * 
+ * :::
+ * 
+ * @example
+ * const data = requestOrderEditRequestValidationStep({
+ *   order: {
+ *     id: "order_123",
+ *     // other order details...
+ *   },
+ *   orderChange: {
+ *     id: "orch_123",
+ *     // other order change details...
+ *   },
+ * })
  */
 export const requestOrderEditRequestValidationStep = createStep(
   "validate-order-edit-request",
   async function ({
     order,
     orderChange,
-  }: {
-    order: OrderDTO
-    orderChange: OrderChangeDTO
-  }) {
+  }: RequestOrderEditRequestValidationStepInput) {
     throwIfIsCancelled(order, "Order")
     throwIfOrderChangeIsNotActive({ orderChange })
   }
 )
 
+/**
+ * The data to request an order edit.
+ */
+export type OrderEditRequestWorkflowInput = {
+  /**
+   * The ID of the order to request the edit for.
+   */
+  order_id: string
+  /**
+   * The ID of the user requesting the edit.
+   */
+  requested_by?: string
+}
+
 export const requestOrderEditRequestWorkflowId = "order-edit-request"
 /**
- * This workflow requests an order edit request.
+ * This workflow requests a previously created order edit request by {@link beginOrderEditOrderWorkflow}. This workflow is used by
+ * the [Request Order Edit Admin API Route](https://docs.medusajs.com/api/admin#order-edits_postordereditsidrequest).
+ * 
+ * You can use this workflow within your customizations or your own custom workflows, allowing you to request an order edit
+ * in your custom flows.
+ * 
+ * @example
+ * const { result } = await requestOrderEditRequestWorkflow(container)
+ * .run({
+ *   input: {
+ *     order_id: "order_123",
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Request an order edit.
  */
 export const requestOrderEditRequestWorkflow = createWorkflow(
   requestOrderEditRequestWorkflowId,

packages/core/core-flows/src/order/workflows/order-edit/update-order-edit-add-item.ts

@@ -24,7 +24,54 @@ import {
 } from "../../utils/order-validation"
 
 /**
- * This step validates that a new item can be updated from an order edit.
+ * The data to validate that a new item can be updated in an order edit.
+ */
+export type UpdateOrderEditAddItemValidationStepInput = {
+  /**
+   * The order's details.
+   */
+  order: OrderDTO
+  /**
+   * The order change's details.
+   */
+  orderChange: OrderChangeDTO
+  /**
+   * The details of the item to be updated.
+   */
+  input: OrderWorkflow.UpdateOrderEditAddNewItemWorkflowInput
+}
+
+/**
+ * This step validates that a new item can be updated in an order edit.
+ * If the order is canceled, the order change is not active, 
+ * the item isn't in the order edit, or the action isn't adding an item,
+ * the step will throw an error.
+ * 
+ * :::note
+ * 
+ * You can retrieve an order and order change details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query),
+ * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep).
+ * 
+ * :::
+ * 
+ * @example
+ * const data = updateOrderEditAddItemValidationStep({
+ *   order: {
+ *     id: "order_123",
+ *     // other order details...
+ *   },
+ *   orderChange: {
+ *     id: "orch_123",
+ *     // other order change details...
+ *   },
+ *   input: {
+ *     order_id: "order_123",
+ *     action_id: "orchac_123",
+ *     data: {
+ *       quantity: 1,
+ *     }
+ *   }
+ * })
  */
 export const updateOrderEditAddItemValidationStep = createStep(
   "update-order-edit-add-item-validation",
@@ -33,11 +80,7 @@ export const updateOrderEditAddItemValidationStep = createStep(
       order,
       orderChange,
       input,
-    }: {
-      order: OrderDTO
-      orderChange: OrderChangeDTO
-      input: OrderWorkflow.UpdateOrderEditAddNewItemWorkflowInput
-    },
+    }: UpdateOrderEditAddItemValidationStepInput,
     context
   ) {
     throwIfIsCancelled(order, "Order")
@@ -59,7 +102,27 @@ export const updateOrderEditAddItemValidationStep = createStep(
 
 export const updateOrderEditAddItemWorkflowId = "update-order-edit-add-item"
 /**
- * This workflow updates a new item in the order edit.
+ * This workflow updates a new item in an order edit. It's used by the
+ * [Update Item Admin API Route](https://docs.medusajs.com/api/admin#order-edits_postordereditsiditemsaction_id).
+ * 
+ * You can use this workflow within your customizations or your own custom workflows, allowing you to update a new item in an order edit
+ * in your custom flows.
+ * 
+ * @example
+ * const { result } = await updateOrderEditAddItemWorkflow(container)
+ * .run({
+ *   input: {
+ *     order_id: "order_123",
+ *     action_id: "orchac_123",
+ *     data: {
+ *       quantity: 1,
+ *     }
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Update a new item in an order edit.
  */
 export const updateOrderEditAddItemWorkflow = createWorkflow(
   updateOrderEditAddItemWorkflowId,

packages/core/core-flows/src/order/workflows/order-edit/update-order-edit-item-quantity.ts

@@ -24,7 +24,54 @@ import {
 } from "../../utils/order-validation"
 
 /**
- * This step validates that an item can be updated from an order edit.
+ * The data to validate that an existing order item can be updated in an order edit.
+ */
+export type UpdateOrderEditItemQuantityValidationStepInput = {
+  /**
+   * The order's details.
+   */
+  order: OrderDTO
+  /**
+   * The order change's details.
+   */
+  orderChange: OrderChangeDTO
+  /**
+   * The details of the item to be updated.
+   */
+  input: OrderWorkflow.UpdateOrderEditItemQuantityWorkflowInput
+}
+
+/**
+ * This step validates that an existing order item can be updated in an order edit.
+ * If the order is canceled, the order change is not active,
+ * the item isn't in the order edit, or the action isn't updating an existing item,
+ * the step will throw an error.
+ * 
+ * :::note
+ * 
+ * You can retrieve an order and order change details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query),
+ * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep).
+ * 
+ * :::
+ * 
+ * @example
+ * const data = updateOrderEditItemQuantityValidationStep({
+ *   order: {
+ *     id: "order_123",
+ *     // other order details...
+ *   },
+ *   orderChange: {
+ *     id: "orch_123",
+ *     // other order change details...
+ *   },
+ *   input: {
+ *     order_id: "order_123",
+ *     action_id: "orchac_123",
+ *     data: {
+ *       quantity: 1,
+ *     }
+ *   }
+ * })
  */
 export const updateOrderEditItemQuantityValidationStep = createStep(
   "update-order-edit-update-quantity-validation",
@@ -33,11 +80,7 @@ export const updateOrderEditItemQuantityValidationStep = createStep(
       order,
       orderChange,
       input,
-    }: {
-      order: OrderDTO
-      orderChange: OrderChangeDTO
-      input: OrderWorkflow.UpdateOrderEditItemQuantityWorkflowInput
-    },
+    }: UpdateOrderEditItemQuantityValidationStepInput,
     context
   ) {
     throwIfIsCancelled(order, "Order")
@@ -60,7 +103,26 @@ export const updateOrderEditItemQuantityValidationStep = createStep(
 export const updateOrderEditItemQuantityWorkflowId =
   "update-order-edit-update-quantity"
 /**
- * This workflow updates a new item in the order edit.
+ * This workflow updates an existing order item that was previously added to the order edit.
+ * 
+ * You can use this workflow within your customizations or your own custom workflows, allowing you to update the quantity 
+ * of an existing item in an order edit in your custom flows.
+ * 
+ * @example
+ * const { result } = await updateOrderEditItemQuantityWorkflow(container)
+ * .run({
+ *   input: {
+ *     order_id: "order_123",
+ *     action_id: "orchac_123",
+ *     data: {
+ *       quantity: 1,
+ *     }
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Update an existing order item previously added to an order edit.
  */
 export const updateOrderEditItemQuantityWorkflow = createWorkflow(
   updateOrderEditItemQuantityWorkflowId,

packages/core/core-flows/src/order/workflows/order-edit/update-order-edit-shipping-method.ts

@@ -24,18 +24,53 @@ import { previewOrderChangeStep } from "../../steps/preview-order-change"
 import { throwIfOrderChangeIsNotActive } from "../../utils/order-validation"
 import { prepareShippingMethodUpdate } from "../../utils/prepare-shipping-method"
 
+/**
+ * The data to validate that an order edit's shipping method can be updated.
+ */
+export type UpdateOrderEditShippingMethodValidationStepInput = {
+  /**
+   * The order change's details.
+   */
+  orderChange: OrderChangeDTO
+  /**
+   * The details of the shipping method to be updated.
+   */
+  input: Pick<OrderWorkflow.UpdateOrderEditShippingMethodWorkflowInput, "order_id" | "action_id">
+}
+
 /**
  * This step validates that an order edit's shipping method can be updated.
+ * If the order change is not active, the shipping method isn't in the order edit,
+ * or the action is not adding a shipping method, the step will throw an error.
+ * 
+ * :::note
+ * 
+ * You can retrieve an order change details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query),
+ * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep).
+ * 
+ * :::
+ * 
+ * @example
+ * const data = updateOrderEditShippingMethodValidationStep({
+ *   orderChange: {
+ *     id: "orch_123",
+ *     // other order change details...
+ *   },
+ *   input: {
+ *     order_id: "order_123",
+ *     action_id: "orchac_123",
+ *     data: {
+ *       custom_amount: 10,
+ *     }
+ *   }
+ * })
  */
 export const updateOrderEditShippingMethodValidationStep = createStep(
   "validate-update-order-edit-shipping-method",
   async function ({
     orderChange,
     input,
-  }: {
-    input: { order_id: string; action_id: string }
-    orderChange: OrderChangeDTO
-  }) {
+  }: UpdateOrderEditShippingMethodValidationStepInput) {
     throwIfOrderChangeIsNotActive({ orderChange })
 
     const associatedAction = (orderChange.actions ?? []).find(
@@ -57,7 +92,27 @@ export const updateOrderEditShippingMethodValidationStep = createStep(
 export const updateOrderEditShippingMethodWorkflowId =
   "update-order-edit-shipping-method"
 /**
- * This workflow updates an order edit's shipping method.
+ * This workflow updates an order edit's shipping method. It's used by the 
+ * [Update Shipping Method Admin API Route](https://docs.medusajs.com/api/admin#order-edits_postordereditsidshippingmethodaction_id).
+ * 
+ * You can use this workflow within your customizations or your own custom workflows, allowing you to update an order edit's shipping method
+ * in your custom flow.
+ * 
+ * @example
+ * const { result } = await updateOrderEditShippingMethodWorkflow(container)
+ * .run({
+ *   input: {
+ *     order_id: "order_123",
+ *     action_id: "orchac_123",
+ *     data: {
+ *       custom_amount: 10,
+ *     }
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Update a shipping method of an order edit.
  */
 export const updateOrderEditShippingMethodWorkflow = createWorkflow(
   updateOrderEditShippingMethodWorkflowId,

packages/core/core-flows/src/order/workflows/return/begin-receive-return.ts

@@ -15,8 +15,42 @@ import { useRemoteQueryStep } from "../../../common"
 import { createOrderChangeStep } from "../../steps"
 import { throwIfIsCancelled } from "../../utils/order-validation"
 
+/**
+ * The data to validate that a return can be received.
+ */
+export type BeginReceiveReturnValidationStepInput = {
+  /**
+   * The order return's details.
+   */
+  orderReturn: ReturnDTO
+  /**
+   * The order's details.
+   */
+  order: OrderDTO
+}
+
 /**
  * This step validates that a return can be received.
+ * If the order or return is canceled, the step will throw an error.
+ * 
+ * :::note
+ * 
+ * You can retrieve an order and return details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query),
+ * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep).
+ * 
+ * :::
+ * 
+ * @example
+ * const data = beginReceiveReturnValidationStep({
+ *   orderReturn: {
+ *     id: "return_123",
+ *     // other order return details...
+ *   },
+ *   order: {
+ *     id: "order_123",
+ *     // other order details...
+ *   }
+ * })
  */
 export const beginReceiveReturnValidationStep = createStep(
   "begin-receive-return-validation",
@@ -24,10 +58,7 @@ export const beginReceiveReturnValidationStep = createStep(
     {
       orderReturn,
       order,
-    }: {
-      orderReturn: ReturnDTO
-      order: OrderDTO
-    },
+    }: BeginReceiveReturnValidationStepInput,
     context
   ) {
     throwIfIsCancelled(order, "Order")
@@ -37,7 +68,25 @@ export const beginReceiveReturnValidationStep = createStep(
 
 export const beginReceiveReturnWorkflowId = "begin-receive-return"
 /**
- * This workflow requests return receival.
+ * This workflow requests return receival. It's used by the
+ * [Start Return Receival Admin API Route](https://docs.medusajs.com/api/admin#returns_postreturnsidreceive).
+ * 
+ * You can confirm the return receival using the {@link confirmReturnRequestWorkflow}.
+ * 
+ * You can use this workflow within your customizations or your own custom workflows, allowing you
+ * to receive a return in your custom flows.
+ * 
+ * @example
+ * const { result } = await beginReceiveReturnWorkflow(container)
+ * .run({
+ *   input: {
+ *     return_id: "return_123",
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Request a return receival.
  */
 export const beginReceiveReturnWorkflow = createWorkflow(
   beginReceiveReturnWorkflowId,

packages/core/core-flows/src/order/workflows/return/begin-return.ts

@@ -14,19 +14,63 @@ import { useRemoteQueryStep } from "../../../common"
 import { createOrderChangeStep, createReturnsStep } from "../../steps"
 import { throwIfOrderIsCancelled } from "../../utils/order-validation"
 
+/**
+ * The data to validate that a return can be created for an order.
+ */
+export type BeginReturnOrderValidationStepInput = {
+  /**
+   * The order's details.
+   */
+  order: OrderDTO
+}
+
 /**
  * This step validates that a return can be created for an order.
+ * If the order is canceled, the step will throw an error.
+ * 
+ * :::note
+ * 
+ * You can retrieve an order details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query),
+ * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep).
+ * 
+ * :::
+ * 
+ * @example
+ * const data = beginReturnOrderValidationStep({
+ *   order: {
+ *     id: "order_123",
+ *     // other order details...
+ *   }
+ * })
  */
 export const beginReturnOrderValidationStep = createStep(
   "begin-return-order-validation",
-  async function ({ order }: { order: OrderDTO }) {
+  async function ({ order }: BeginReturnOrderValidationStepInput) {
     throwIfOrderIsCancelled({ order })
   }
 )
 
 export const beginReturnOrderWorkflowId = "begin-return-order"
 /**
- * This workflow requests a return.
+ * This workflow creates an order return that can be later requested or confirmed.
+ * It's used by the [Create Return Admin API Route](https://docs.medusajs.com/api/admin#returns_postreturns).
+ * 
+ * You can start the return receival using the {@link beginReceiveReturnWorkflow}.
+ * 
+ * You can use this workflow within your customizations or your own custom workflows, allowing you
+ * to create a return for an order in your custom flow.
+ * 
+ * @example
+ * const { result } = await beginReturnOrderWorkflow(container)
+ * .run({
+ *   input: {
+ *     order_id: "order_123"
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Create a return for an order.
  */
 export const beginReturnOrderWorkflow = createWorkflow(
   beginReturnOrderWorkflowId,

packages/core/core-flows/src/order/workflows/return/cancel-receive-return.ts

@@ -12,8 +12,50 @@ import {
   throwIfOrderChangeIsNotActive,
 } from "../../utils/order-validation"
 
+/**
+ * The data to validate that a return receival can be canceled.
+ */
+export type CancelReceiveReturnValidationStepInput = {
+  /**
+   * The order's details.
+   */
+  order: OrderDTO
+  /**
+   * The order change's details.
+   */
+  orderChange: OrderChangeDTO
+  /**
+   * The order return's details.
+   */
+  orderReturn: ReturnDTO
+}
+
 /**
  * This step validates that a return receival can be canceled.
+ * If the order or return is canceled, or the order change is not active, the step will throw an error.
+ * 
+ * :::note
+ * 
+ * You can retrieve an order, return, and order change details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query),
+ * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep).
+ * 
+ * :::
+ * 
+ * @example
+ * const data = cancelReceiveReturnValidationStep({
+ *   order: {
+ *     id: "order_123",
+ *     // other order details...
+ *   },
+ *   orderChange: {
+ *     id: "orch_123",
+ *     // other order change details...
+ *   },
+ *   orderReturn: {
+ *     id: "return_123",
+ *     // other order return details...
+ *   }
+ * })
  */
 export const cancelReceiveReturnValidationStep = createStep(
   "validate-cancel-return-shipping-method",
@@ -21,24 +63,46 @@ export const cancelReceiveReturnValidationStep = createStep(
     order,
     orderChange,
     orderReturn,
-  }: {
-    order: OrderDTO
-    orderReturn: ReturnDTO
-    orderChange: OrderChangeDTO
-  }) {
+  }: CancelReceiveReturnValidationStepInput) {
     throwIfIsCancelled(order, "Order")
     throwIfIsCancelled(orderReturn, "Return")
     throwIfOrderChangeIsNotActive({ orderChange })
   }
 )
 
+/**
+ * The data to cancel a return receival.
+ */
+export type CancelReturnReceiveWorkflowInput = {
+  /**
+   * The ID of the return to cancel the receival for.
+   */
+  return_id: string
+}
+
 export const cancelReturnReceiveWorkflowId = "cancel-receive-return"
 /**
- * This workflow cancels a return receival.
+ * This workflow cancels a return receival. It's used by the
+ * [Cancel Return Receival Admin API Route](https://docs.medusajs.com/api/admin#returns_deletereturnsidreceive).
+ * 
+ * You can use this workflow within your customizations or your own custom workflows, allowing you
+ * to cancel a return receival in your custom flow.
+ * 
+ * @example
+ * const { result } = await cancelReturnReceiveWorkflow(container)
+ * .run({
+ *   input: {
+ *     return_id: "return_123",
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Cancel a return receival.
  */
 export const cancelReturnReceiveWorkflow = createWorkflow(
   cancelReturnReceiveWorkflowId,
-  function (input: { return_id: string }): WorkflowData<void> {
+  function (input: CancelReturnReceiveWorkflowInput): WorkflowData<void> {
     const orderReturn: ReturnDTO = useRemoteQueryStep({
       entry_point: "return",
       fields: ["id", "status", "order_id", "canceled_at"],

packages/core/core-flows/src/order/workflows/return/cancel-request-return.ts

@@ -18,12 +18,51 @@ import {
   throwIfOrderChangeIsNotActive,
 } from "../../utils/order-validation"
 
-export type CancelRequestReturnWorkflowInput = {
-  return_id: string
+/**
+ * The data to validate that a requested return can be canceled.
+ */
+export type CancelRequestReturnValidationStepInput = {
+  /**
+   * The order's details.
+   */
+  order: OrderDTO
+  /**
+   * The order change's details.
+   */
+  orderChange: OrderChangeDTO
+  /**
+   * The order return's details.
+   */
+  orderReturn: ReturnDTO
 }
 
 /**
  * This step validates that a requested return can be canceled.
+ * If the order or return is canceled, or the order change is not active, 
+ * the step will throw an error.
+ * 
+ * :::note
+ * 
+ * You can retrieve an order, return, and order change details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query),
+ * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep).
+ * 
+ * :::
+ * 
+ * @example
+ * const data = cancelRequestReturnValidationStep({
+ *   order: {
+ *     id: "order_123",
+ *     // other order details...
+ *   },
+ *   orderChange: {
+ *     id: "orch_123",
+ *     // other order change details...
+ *   },
+ *   orderReturn: {
+ *     id: "return_123",
+ *     // other order return details...
+ *   }
+ * })
  */
 export const cancelRequestReturnValidationStep = createStep(
   "validate-cancel-return-shipping-method",
@@ -31,20 +70,42 @@ export const cancelRequestReturnValidationStep = createStep(
     order,
     orderChange,
     orderReturn,
-  }: {
-    order: OrderDTO
-    orderReturn: ReturnDTO
-    orderChange: OrderChangeDTO
-  }) {
+  }: CancelRequestReturnValidationStepInput) {
     throwIfIsCancelled(order, "Order")
     throwIfIsCancelled(orderReturn, "Return")
     throwIfOrderChangeIsNotActive({ orderChange })
   }
 )
 
+/**
+ * The data to cancel a requested return.
+ */
+export type CancelRequestReturnWorkflowInput = {
+  /**
+   * The ID of the return to cancel.
+   */
+  return_id: string
+}
+
 export const cancelReturnRequestWorkflowId = "cancel-return-request"
 /**
- * This workflow cancels a requested return.
+ * This workflow cancels a requested return. It's used by the
+ * [Cancel Return Request API Route](https://docs.medusajs.com/api/admin#returns_deletereturnsidrequest).
+ * 
+ * You can use this workflow within your customizations or your own custom workflows, allowing you
+ * to cancel a return request in your custom flow.
+ * 
+ * @example
+ * const { result } = await cancelReturnRequestWorkflow(container)
+ * .run({
+ *   input: {
+ *     return_id: "return_123",
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Cancel a requested return.
  */
 export const cancelReturnRequestWorkflow = createWorkflow(
   cancelReturnRequestWorkflowId,