chore(core-flows,types): improve TSDocs of cart workflows and steps (#10962)

* chore(core-flows,types): improve TSDocs of cart workflows and steps

* fix build errors

* fix build error

* fix errors

packages/core/core-flows/src/cart/steps/add-shipping-method-to-cart.ts

@@ -5,13 +5,30 @@ import {
 import { Modules } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The details of the shipping methods to add.
+ */
 export interface AddShippingMethodToCartStepInput {
+  /**
+   * The shipping methods to add.
+   */
   shipping_methods: CreateShippingMethodDTO[]
 }
 
 export const addShippingMethodToCartStepId = "add-shipping-method-to-cart-step"
 /**
  * This step adds shipping methods to a cart.
+ * 
+ * @example
+ * const data = addShippingMethodToCartStep({
+ *   shipping_methods: [
+ *     {
+ *       name: "Standard Shipping",
+ *       cart_id: "cart_123",
+ *       amount: 10,
+ *     }
+ *   ]
+ * })
  */
 export const addShippingMethodToCartStep = createStep(
   addShippingMethodToCartStepId,

packages/core/core-flows/src/cart/steps/confirm-inventory.ts

@@ -7,19 +7,55 @@ import {
 } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The details of the cart items to confirm their inventory availability.
+ */
 export interface ConfirmVariantInventoryStepInput {
+  /**
+   * The items to confirm inventory for.
+   */
   items: {
+    /**
+     * The ID of the inventory item associated with the line item's variant.
+     */
     inventory_item_id: string
+    /**
+     * The number of units a single quantity is equivalent to. For example, if a customer orders one quantity of the variant, Medusa checks the availability of the quantity multiplied by the
+     * value set for `required_quantity`. When the customer orders the quantity, Medusa reserves the ordered quantity multiplied by the value set for `required_quantity`.
+     */
     required_quantity: number
+    /**
+     * Whether the variant can be ordered even if it's out of stock. If a variant has this enabled, the step doesn't throw an error.
+     */
     allow_backorder: boolean
+    /**
+     * The quantity in the cart.
+     */
     quantity: BigNumberInput
+    /**
+     * The ID of the stock locations that the inventory quantity is available in.
+     */
     location_ids: string[]
   }[]
 }
 
 export const confirmInventoryStepId = "confirm-inventory-step"
 /**
- * This step confirms for one or more variants that their inventory has a required quantity.
+ * This step validates that items in the cart have sufficient inventory quantity.
+ * If an item doesn't have sufficient inventory, an error is thrown.
+ * 
+ * @example
+ * confirmInventoryStep({
+ *   items: [
+ *     {
+ *       inventory_item_id: "iitem_123",
+ *       required_quantity: 1,
+ *       allow_backorder: false,
+ *       quantity: 1,
+ *       location_ids: ["sloc_123"]
+ *     }
+ *   ]
+ * })
  */
 export const confirmInventoryStep = createStep(
   confirmInventoryStepId,

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

@@ -2,13 +2,18 @@ import { CreateCartDTO, ICartModuleService } from "@medusajs/framework/types"
 import { Modules } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The details of the carts to create.
+ */
+export type CreateCartsStepInput = CreateCartDTO[]
+
 export const createCartsStepId = "create-carts"
 /**
  * This step creates a cart.
  */
 export const createCartsStep = createStep(
   createCartsStepId,
-  async (data: CreateCartDTO[], { container }) => {
+  async (data: CreateCartsStepInput, { container }) => {
     const service = container.resolve<ICartModuleService>(Modules.CART)
 
     const createdCarts = await service.createCarts(data)

packages/core/core-flows/src/cart/steps/create-line-item-adjustments.ts

@@ -5,13 +5,30 @@ import {
 import { Modules } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The details of the line item adjustments to create.
+ */
 export interface CreateLineItemAdjustmentsCartStepInput {
+  /**
+   * The line item adjustments to create.
+   */
   lineItemAdjustmentsToCreate: CreateLineItemAdjustmentDTO[]
 }
 
 export const createLineItemAdjustmentsStepId = "create-line-item-adjustments"
 /**
- * This step creates line item adjustments in a cart.
+ * This step creates line item adjustments in a cart, such as when a promotion is applied.
+ * 
+ * @example
+ * createLineItemAdjustmentsStep({
+ *   lineItemAdjustmentsToCreate: [
+ *     {
+ *       item_id: "litem_123",
+ *       code: "10OFF",
+ *       amount: 10,
+ *     }
+ *   ]
+ * })
  */
 export const createLineItemAdjustmentsStep = createStep(
   createLineItemAdjustmentsStepId,

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

@@ -5,14 +5,34 @@ import {
 import { Modules } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The details of the line items to create.
+ */
 export interface CreateLineItemsCartStepInput {
+  /**
+   * The ID of the cart to create line items for.
+   */
   id: string
+  /**
+   * The line items to create.
+   */
   items: CreateLineItemForCartDTO[]
 }
 
 export const createLineItemsStepId = "create-line-items-step"
 /**
  * This step creates line item in a cart.
+ * 
+ * @example
+ * const data = createLineItemsStep({
+ *   "id": "cart_123",
+ *   "items": [{
+ *     "title": "Shirt",
+ *     "quantity": 1,
+ *     "unit_price": 20,
+ *     "cart_id": "cart_123",
+ *   }]
+ * })
  */
 export const createLineItemsStep = createStep(
   createLineItemsStepId,

packages/core/core-flows/src/cart/steps/create-payment-collection.ts

@@ -5,20 +5,42 @@ import {
 import { Modules } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The details of the payment collections to create.
+ */
 export type CreatePaymentCollectionCartStepInput = {
+  /**
+   * The ID of the region that the payment collection belongs to.
+   */
   region_id: string
+  /**
+   * The payment collection's curency code.
+   */
   currency_code: string
+  /**
+   * The payment collection's amount.
+   */
   amount: BigNumberInput
+  /**
+   * Custom key-value pairs to store in the payment collection.
+   */
   metadata?: Record<string, unknown>
-}
+}[]
 
 export const createPaymentCollectionsStepId = "create-payment-collections"
 /**
  * This step creates payment collections in a cart.
+ * 
+ * @example
+ * const data = createPaymentCollectionsStep([{
+ *   "region_id": "region_123",
+ *   "currency_code": "usd",
+ *   "amount": 40
+ * }])
  */
 export const createPaymentCollectionsStep = createStep(
   createPaymentCollectionsStepId,
-  async (data: CreatePaymentCollectionCartStepInput[], { container }) => {
+  async (data: CreatePaymentCollectionCartStepInput, { container }) => {
     const service = container.resolve<IPaymentModuleService>(Modules.PAYMENT)
 
     const created = await service.createPaymentCollections(data)

packages/core/core-flows/src/cart/steps/create-shipping-method-adjustments.ts

@@ -5,7 +5,13 @@ import {
 import { Modules } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The details of the shipping method adjustments to create.
+ */
 export interface CreateShippingMethodAdjustmentsStepInput {
+  /**
+   * The shipping method adjustments to create.
+   */
   shippingMethodAdjustmentsToCreate: CreateShippingMethodAdjustmentDTO[]
 }
 
@@ -13,6 +19,15 @@ export const createShippingMethodAdjustmentsStepId =
   "create-shipping-method-adjustments"
 /**
  * This step creates shipping method adjustments for a cart.
+ * 
+ * @example
+ * const data = createShippingMethodAdjustmentsStep({
+ *   "shippingMethodAdjustmentsToCreate": [{
+ *     "shipping_method_id": "sm_123",
+ *     "code": "10OFF",
+ *     "amount": 10
+ *   }]
+ * })
  */
 export const createShippingMethodAdjustmentsStep = createStep(
   createShippingMethodAdjustmentsStepId,

packages/core/core-flows/src/cart/steps/find-one-or-any-region.ts

@@ -5,13 +5,23 @@ import {
 import { MedusaError, Modules } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The details of the region to find.
+ */
+export type FindOneOrAnyRegionStepInput = {
+  /**
+   * The ID of the region to find.
+   */
+  regionId?: string
+}
+
 export const findOneOrAnyRegionStepId = "find-one-or-any-region"
 /**
  * This step retrieves a region either by the provided ID or the first region in the first store.
  */
 export const findOneOrAnyRegionStep = createStep(
   findOneOrAnyRegionStepId,
-  async (data: { regionId?: string }, { container }) => {
+  async (data: FindOneOrAnyRegionStepInput, { container }) => {
     const service = container.resolve<IRegionModuleService>(Modules.REGION)
 
     const storeModule = container.resolve<IStoreModuleService>(Modules.STORE)

packages/core/core-flows/src/cart/steps/find-or-create-customer.ts

@@ -2,13 +2,32 @@ import { CustomerDTO, ICustomerModuleService } from "@medusajs/framework/types"
 import { isDefined, Modules, validateEmail } from "@medusajs/framework/utils"
 import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The details of the customer to find or create.
+ */
 export interface FindOrCreateCustomerStepInput {
+  /**
+   * The ID of the customer to find.
+   */
   customerId?: string | null
+  /**
+   * If the `customerId` isn't specified,
+   * find a customer with this email or create a new customer having this email.
+   */
   email?: string | null
 }
 
+/**
+ * The details of the customer found or created.
+ */
 export interface FindOrCreateCustomerOutputStepOutput {
+  /**
+   * The customer found or created, if any.
+   */
   customer?: CustomerDTO | null
+  /**
+   * The email of the customer found or created, if any.
+   */
   email?: string | null
 }
 

packages/core/core-flows/src/cart/steps/find-sales-channel.ts

@@ -6,7 +6,13 @@ import {
 import { MedusaError, Modules, isDefined } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The details of the sales channel to find.
+ */
 export interface FindSalesChannelStepInput {
+  /**
+   * The ID of the sales channel to find.
+   */
   salesChannelId?: string | null
 }
 

packages/core/core-flows/src/cart/steps/get-actions-to-compute-from-promotions.ts

@@ -2,8 +2,17 @@ import { CartDTO, IPromotionModuleService } from "@medusajs/framework/types"
 import { Modules } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The details of the cart and its applied promotions.
+ */
 export interface GetActionsToComputeFromPromotionsStepInput {
+  /**
+   * The cart to compute the actions for.
+   */
   cart: CartDTO
+  /**
+   * The promotion codes applied on the cart.
+   */
   promotionCodesToApply: string[]
 }
 
@@ -12,6 +21,20 @@ export const getActionsToComputeFromPromotionsStepId =
 /**
  * This step retrieves the actions to compute based on the promotions
  * applied on a cart.
+ * 
+ * :::tip
+ * 
+ * You can use the {@link retrieveCartStep} to retrieve a cart's details.
+ * 
+ * :::
+ * 
+ * @example
+ * const data = getActionsToComputeFromPromotionsStep({
+ *   // retrieve the details of the cart from another workflow
+ *   // or in another step using the Cart Module's service
+ *   cart,
+ *   promotionCodesToApply: ["10OFF"]
+ * })
  */
 export const getActionsToComputeFromPromotionsStep = createStep(
   getActionsToComputeFromPromotionsStepId,

packages/core/core-flows/src/cart/steps/get-line-item-actions.ts

@@ -12,15 +12,46 @@ import {
 } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The details of the line items to create or update.
+ */
 export interface GetLineItemActionsStepInput {
+  /**
+   * The ID of the cart to create line items for.
+   */
   id: string
+  /**
+   * The line items to create or update.
+   */
   items: CreateLineItemForCartDTO[]
 }
 
+export interface GetLineItemActionsStepOutput {
+  /**
+   * The line items to create.
+   */
+  itemsToCreate: CreateLineItemForCartDTO[]
+  /**
+   * The line items to update.
+   */
+  itemsToUpdate: UpdateLineItemWithSelectorDTO[]
+}
+
 export const getLineItemActionsStepId = "get-line-item-actions-step"
 /**
  * This step returns lists of cart line items to create or update based on the
  * provided input.
+ * 
+ * @example
+ * const data = getLineItemActionsStep({
+ *   "id": "cart_123",
+ *   "items": [{
+ *     "title": "Shirt",
+ *     "quantity": 1,
+ *     "unit_price": 50,
+ *     "cart_id": "cart_123",
+ *   }]
+ * })
  */
 export const getLineItemActionsStep = createStep(
   getLineItemActionsStepId,
@@ -67,6 +98,8 @@ export const getLineItemActionsStep = createStep(
       }
     }
 
-    return new StepResponse({ itemsToCreate, itemsToUpdate }, null)
+    return new StepResponse(
+      { itemsToCreate, itemsToUpdate } as GetLineItemActionsStepOutput
+    , null)
   }
 )

packages/core/core-flows/src/cart/steps/get-promotion-codes-to-apply.ts

@@ -2,21 +2,66 @@ import { IPromotionModuleService } from "@medusajs/framework/types"
 import { Modules, PromotionActions } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The details of the promotion codes to apply on a cart.
+ */
 export interface GetPromotionCodesToApplyStepInput {
+  /**
+   * The cart containing items and shipping methods.
+   */
   cart: {
+    /**
+     * The cart's items and the promotion adjustments applied to them.
+     */
     items?: { adjustments?: { code?: string }[] }[]
+    /**
+     * The cart's shipping methods and the promotion adjustments applied to them.
+     */
     shipping_methods?: { adjustments?: { code?: string }[] }[]
   }
+  /**
+   * the promotion codes to be applied to the cart.
+   */
   promo_codes?: string[]
+  /**
+   * Whether to add, remove, or replace promotion codes.
+   */
   action?:
     | PromotionActions.ADD
     | PromotionActions.REMOVE
     | PromotionActions.REPLACE
 }
 
+/**
+ * The promotion codes to apply on the cart.
+ * 
+ * @example ["PRO10", "SHIPFREE", "NEWYEAR20"]
+ */
+export type GetPromotionCodesToApplyStepOutput = string[]
+
 export const getPromotionCodesToApplyId = "get-promotion-codes-to-apply"
 /**
  * This step retrieves the promotion codes to apply on a cart.
+ * 
+ * @example
+ * const data = getPromotionCodesToApply(
+ *   {
+ *     cart: {
+ *       items: [
+ *         {
+ *           adjustments: [{ code: "PROMO10" }]
+ *         }
+ *       ],
+ *       shipping_methods: [
+ *         {
+ *           adjustments: [{ code: "SHIPFREE" }]
+ *         }
+ *       ]
+ *     },
+ *     promo_codes: ["NEWYEAR20"],
+ *     action: PromotionActions.ADD
+ *   },
+ * )
  */
 export const getPromotionCodesToApply = createStep(
   getPromotionCodesToApplyId,
@@ -60,6 +105,8 @@ export const getPromotionCodesToApply = createStep(
       promo_codes.forEach((code) => promotionCodesToApply.add(code))
     }
 
-    return new StepResponse(Array.from(promotionCodesToApply))
+    return new StepResponse(
+      Array.from(promotionCodesToApply) as GetPromotionCodesToApplyStepOutput
+    )
   }
 )

packages/core/core-flows/src/cart/steps/get-variant-price-sets.ts

@@ -1,15 +1,53 @@
-import { IPricingModuleService } from "@medusajs/framework/types"
+import { CalculatedPriceSet, IPricingModuleService } from "@medusajs/framework/types"
 import { MedusaError, Modules } from "@medusajs/framework/utils"
 import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The details of the variants to get price sets for.
+ */
 export interface GetVariantPriceSetsStepInput {
+  /**
+   * The IDs of the variants to get price sets for.
+   */
   variantIds: string[]
+  /**
+   * The context to use when calculating the price sets.
+   * 
+   * Learn more in [this documentation](https://docs.medusajs.com/resources/commerce-modules/product/guides/price#retrieve-calculated-price-for-a-context).
+   */
   context?: Record<string, unknown>
 }
 
+/**
+ * The calculated price sets of the variants. The object's keys are the variant IDs.
+ */
+export interface GetVariantPriceSetsStepOutput {
+  [k: string]: CalculatedPriceSet
+}
+
 export const getVariantPriceSetsStepId = "get-variant-price-sets"
 /**
  * This step retrieves the calculated price sets of the specified variants.
+ * 
+ * @example
+ * To retrieve a variant's price sets:
+ * 
+ * ```ts
+ * const data = getVariantPriceSetsStep({
+ *   variantIds: ["variant_123"],
+ * })
+ * ```
+ * 
+ * To retrieve the calculated price sets of a variant:
+ * 
+ * ```ts
+ * const data = getVariantPriceSetsStep({
+ *   variantIds: ["variant_123"],
+ *   context: {
+ *     currency_code: "usd"
+ *   }
+ * })
+ * ```
  */
 export const getVariantPriceSetsStep = createStep(
   getVariantPriceSetsStepId,
@@ -71,6 +109,8 @@ export const getVariantPriceSetsStep = createStep(
       {}
     )
 
-    return new StepResponse(variantToCalculatedPriceSets)
+    return new StepResponse(
+      variantToCalculatedPriceSets as GetVariantPriceSetsStepOutput
+    )
   }
 )

packages/core/core-flows/src/cart/steps/get-variants.ts

@@ -7,6 +7,9 @@ import {
 import { Modules } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The details of the variants to retrieve.
+ */
 export interface GetVariantsStepInput {
   filter?: FilterableProductVariantProps
   config?: FindConfig<ProductVariantDTO>
@@ -15,6 +18,13 @@ export interface GetVariantsStepInput {
 export const getVariantsStepId = "get-variants"
 /**
  * This step retrieves variants matching the specified filters.
+ * 
+ * @example
+ * const data = getVariantsStep({
+ *   filter: {
+ *     id: "variant_123"
+ *   }
+ * })
  */
 export const getVariantsStep = createStep(
   getVariantsStepId,

packages/core/core-flows/src/cart/steps/index.ts

@@ -23,6 +23,11 @@ export * from "./set-tax-lines-for-items"
 export * from "./update-cart-promotions"
 export * from "./update-carts"
 export * from "./update-line-items"
+export * from "./update-shipping-methods"
 export * from "./validate-cart-payments"
 export * from "./validate-cart-shipping-options"
 export * from "./validate-variant-prices"
+export * from "./validate-cart"
+export * from "./validate-line-item-prices"
+export * from "./validate-shipping-methods-data"
+export * from "./validate-shipping-options-price"

packages/core/core-flows/src/cart/steps/prepare-adjustments-from-promotion-actions.ts

@@ -10,15 +10,91 @@ import {
 import { ComputedActions, Modules } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The details of the actions computed by the Promotion Module.
+ */
 export interface PrepareAdjustmentsFromPromotionActionsStepInput {
+  /**
+   * The actions computed by the Promotion Module.
+   */
   actions: ComputeActions[]
 }
 
+/**
+ * The details of the adjustments to create and remove.
+ */
+export interface PrepareAdjustmentsFromPromotionActionsStepOutput {
+  /**
+   * The line item adjustments to create.
+   */
+  lineItemAdjustmentsToCreate: {
+    /**
+     * The promotion code that computed the adjustment.
+     */
+    code: string
+    /**
+     * The amount of the adjustment.
+     */
+    amount: number
+    /**
+     * The ID of the line item to adjust.
+     */
+    item_id: string
+    /**
+     * The ID of the applied promotion.
+     */
+    promotion_id?: string
+  }[]
+  /**
+   * The line item adjustment IDs to remove.
+   */
+  lineItemAdjustmentIdsToRemove: string[]
+  /**
+   * The shipping method adjustments to create.
+   */
+  shippingMethodAdjustmentsToCreate: {
+    /**
+     * The promotion code that computed the adjustment.
+     */
+    code: string
+    /**
+     * The amount of the adjustment.
+     */
+    amount: number
+    /**
+     * The ID of the shipping method to adjust.
+     */
+    shipping_method_id: string
+    /**
+     * The ID of the applied promotion.
+     */
+    promotion_id?: string
+  }[]
+  /**
+   * The shipping method adjustment IDs to remove.
+   */
+  shippingMethodAdjustmentIdsToRemove: string[]
+  /**
+   * The promotion codes that were computed.
+   */
+  computedPromotionCodes: string[]
+}
+
 export const prepareAdjustmentsFromPromotionActionsStepId =
   "prepare-adjustments-from-promotion-actions"
 /**
  * This step prepares the line item or shipping method adjustments using
  * actions computed by the Promotion Module.
+ * 
+ * @example
+ * const data = prepareAdjustmentsFromPromotionActionsStep({
+ *   "actions": [{
+ *     "action": "addItemAdjustment",
+ *     "item_id": "litem_123",
+ *     "amount": 10,
+ *     "code": "10OFF",
+ *   }]
+ * })
  */
 export const prepareAdjustmentsFromPromotionActionsStep = createStep(
   prepareAdjustmentsFromPromotionActionsStepId,
@@ -82,6 +158,6 @@ export const prepareAdjustmentsFromPromotionActionsStep = createStep(
       shippingMethodAdjustmentsToCreate,
       shippingMethodAdjustmentIdsToRemove,
       computedPromotionCodes,
-    })
+    } as PrepareAdjustmentsFromPromotionActionsStepOutput)
   }
 )

packages/core/core-flows/src/cart/steps/remove-line-item-adjustments.ts

@@ -2,7 +2,13 @@ import { ICartModuleService } from "@medusajs/framework/types"
 import { Modules } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The details of the line item adjustments to remove.
+ */
 export interface RemoveLineItemAdjustmentsStepInput {
+  /**
+   * The IDs of the line item adjustments to remove.
+   */
   lineItemAdjustmentIdsToRemove: string[]
 }
 

packages/core/core-flows/src/cart/steps/remove-shipping-method-adjustments.ts

@@ -2,7 +2,13 @@ import { ICartModuleService } from "@medusajs/framework/types"
 import { Modules } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The details of the shipping method adjustments to remove.
+ */
 export interface RemoveShippingMethodAdjustmentsStepInput {
+  /**
+   * The IDs of the shipping method adjustments to remove.
+   */
   shippingMethodAdjustmentIdsToRemove: string[]
 }
 

packages/core/core-flows/src/cart/steps/remove-shipping-method-from-cart.ts

@@ -2,10 +2,22 @@ import { ICartModuleService } from "@medusajs/framework/types"
 import { Modules } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The details of the shipping methods to remove.
+ */
 export interface RemoveShippingMethodFromCartStepInput {
+  /**
+   * The IDs of the shipping methods to remove.
+   */
   shipping_method_ids: string[]
 }
 
+/**
+ * The shipping methods removed from the cart, along with IDs of related records
+ * that were removed.
+ */
+export type RemoveShippingMethodFromCartStepOutput = Record<string, string[]> | void
+
 export const removeShippingMethodFromCartStepId =
   "remove-shipping-method-to-cart-step"
 /**
@@ -24,7 +36,10 @@ export const removeShippingMethodFromCartStep = createStep(
       data.shipping_method_ids
     )
 
-    return new StepResponse(methods, data.shipping_method_ids)
+    return new StepResponse(
+      methods as RemoveShippingMethodFromCartStepOutput, 
+      data.shipping_method_ids
+    )
   },
   async (ids, { container }) => {
     if (!ids?.length) {

packages/core/core-flows/src/cart/steps/reserve-inventory.ts

@@ -2,13 +2,41 @@ import { MathBN, Modules } from "@medusajs/framework/utils"
 import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk"
 import { BigNumberInput } from "@medusajs/types"
 
+
+/**
+ * The details of the items and their quantity to reserve.
+ */
 export interface ReserveVariantInventoryStepInput {
   items: {
+    /**
+     * The ID for the line item.
+     */
     id?: string
+
+    /**
+     * The ID of the inventory item to reserve quantities from.
+     */
     inventory_item_id: string
+
+    /**
+     * The number of units a single quantity is equivalent to. For example, if a customer orders one quantity of the variant, Medusa checks the availability of the quantity multiplied by the
+     * value set for `required_quantity`. When the customer orders the quantity, Medusa reserves the ordered quantity multiplied by the value set for `required_quantity`.
+     */
     required_quantity: number
+
+    /**
+     * Whether the variant can be ordered even if it's out of stock.
+     */
     allow_backorder: boolean
+
+    /**
+     * The quantity to reserve.
+     */
     quantity: BigNumberInput
+
+    /**
+     * The IDs of stock locations to reserve the item's quantity in.
+     */
     location_ids: string[]
   }[]
 }
@@ -17,6 +45,19 @@ export const reserveInventoryStepId = "reserve-inventory-step"
 /**
  * This step reserves the quantity of line items from the associated
  * variant's inventory.
+ * 
+ * @example
+ * const data = reserveInventoryStep({
+ *   "items": [{
+ *     "inventory_item_id": "iitem_123",
+ *     "required_quantity": 1,
+ *     "allow_backorder": false,
+ *     "quantity": 1,
+ *     "location_ids": [
+ *       "sloc_123"
+ *     ]
+ *   }]
+ * })
  */
 export const reserveInventoryStep = createStep(
   reserveInventoryStepId,

packages/core/core-flows/src/cart/steps/retrieve-cart.ts

@@ -6,7 +6,13 @@ import {
 import { Modules } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The details of the cart to retrieve.
+ */
 export interface RetrieveCartStepInput {
+  /**
+   * The ID of the cart to retrieve.
+   */
   id: string
   config?: FindConfig<CartDTO>
 }

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

@@ -9,15 +9,54 @@ import {
 import { Modules } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The details of the tax lines to set in a cart.
+ */
 export interface SetTaxLinesForItemsStepInput {
+  /**
+   * The cart's details.
+   */
   cart: CartWorkflowDTO
+  /**
+   * The tax lines to set for line items.
+   */
   item_tax_lines: ItemTaxLineDTO[]
+  /**
+   * The tax lines to set for shipping methods.
+   */
   shipping_tax_lines: ShippingTaxLineDTO[]
 }
 
 export const setTaxLinesForItemsStepId = "set-tax-lines-for-items"
 /**
  * This step sets the tax lines of shipping methods and line items in a cart.
+ * 
+ * :::tip
+ * 
+ * You can use the {@link retrieveCartStep} to retrieve a cart's details.
+ * 
+ * :::
+ * 
+ * @example
+ * const data = setTaxLinesForItemsStep({
+ *   // retrieve the details of the cart from another workflow
+ *   // or in another step using the Cart Module's service
+ *   cart,
+ *   "item_tax_lines": [{
+ *     "rate": 48,
+ *     "code": "CODE123",
+ *     "name": "Tax rate 2",
+ *     "provider_id": "provider_1",
+ *     "line_item_id": "litem_123"
+ *   }],
+ *   "shipping_tax_lines": [{
+ *     "rate": 49,
+ *     "code": "CODE456",
+ *     "name": "Tax rate 1",
+ *     "provider_id": "provider_1",
+ *     "shipping_line_id": "sm_123"
+ *   }]
+ * })
  */
 export const setTaxLinesForItemsStep = createStep(
   setTaxLinesForItemsStepId,

packages/core/core-flows/src/cart/steps/update-cart-promotions.ts

@@ -6,9 +6,21 @@ import {
 } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The details of the promotion codes to apply on a cart.
+ */
 export interface UpdateCartPromotionStepInput {
+  /**
+   * The ID of the cart to update promotions for.
+   */
   id: string
+  /**
+   * The promotion codes to apply on the cart.
+   */
   promo_codes?: string[]
+  /**
+   * Whether to add, remove, or replace promotion codes.
+   */
   action?:
     | PromotionActions.ADD
     | PromotionActions.REMOVE

packages/core/core-flows/src/cart/steps/update-carts.ts

@@ -9,13 +9,24 @@ import {
 } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The details of the carts to update.
+ */
+export type UpdateCartsStepInput = UpdateCartWorkflowInputDTO[]
+
 export const updateCartsStepId = "update-carts"
 /**
  * This step updates a cart.
+ * 
+ * @example
+ * const data = updateCartsStep([{
+ *   id: "cart_123",
+ *   email: "customer@gmail.com",
+ * }])
  */
 export const updateCartsStep = createStep(
   updateCartsStepId,
-  async (data: UpdateCartWorkflowInputDTO[], { container }) => {
+  async (data: UpdateCartsStepInput, { container }) => {
     const cartModule = container.resolve<ICartModuleService>(Modules.CART)
 
     const { selects, relations } = getSelectsAndRelationsFromObjectArray(data)

packages/core/core-flows/src/cart/steps/update-line-items.ts

@@ -8,14 +8,38 @@ import {
 } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The details of the line items to update.
+ */
 export interface UpdateLineItemsStepInput {
+  /**
+   * The ID of the cart that the line items belong to.
+   */
   id: string
+  /**
+   * The line items to update.
+   */
   items: UpdateLineItemWithSelectorDTO[]
 }
 
 export const updateLineItemsStepId = "update-line-items-step"
 /**
  * This step updates a cart's line items.
+ * 
+ * @example
+ * const data = updateLineItemsStep({
+ *   id: "cart_123",
+ *   items: [
+ *     {
+ *       selector: {
+ *         id: "line_item_123"
+ *       },
+ *       data: {
+ *         quantity: 2
+ *       }
+ *     }
+ *   ]
+ * })
  */
 export const updateLineItemsStep = createStep(
   updateLineItemsStepId,

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

@@ -8,13 +8,26 @@ import {
 } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The details of the shipping methods to update.
+ */
+export type UpdateShippingMethodsStepInput = UpdateShippingMethodDTO[]
+
 export const updateShippingMethodsStepId = "update-shipping-methods-step"
 /**
  * This step updates a cart's shipping methods.
+ * 
+ * @example
+ * const data = updateOrderShippingMethodsStep([
+ *   {
+ *     id: "sm_123",
+ *     amount: 10
+ *   }
+ * ])
  */
 export const updateShippingMethodsStep = createStep(
   updateShippingMethodsStepId,
-  async (data: UpdateShippingMethodDTO[], { container }) => {
+  async (data: UpdateShippingMethodsStepInput, { container }) => {
     if (!data?.length) {
       return new StepResponse([], [])
     }

packages/core/core-flows/src/cart/steps/validate-cart-payments.ts

@@ -6,14 +6,33 @@ import {
 } from "@medusajs/framework/utils"
 import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The cart's details.
+ */
 export interface ValidateCartPaymentsStepInput {
+  /**
+   * The cart to validate payment sessions for.
+   */
   cart: CartWorkflowDTO
 }
 
 export const validateCartPaymentsStepId = "validate-cart-payments"
 /**
  * This step validates a cart's payment sessions. Their status must
- * be `pending` or `requires_more`.
+ * be `pending` or `requires_more`. If not valid, the step throws an error.
+ * 
+ * :::tip
+ * 
+ * You can use the {@link retrieveCartStep} to retrieve a cart's details.
+ * 
+ * :::
+ * 
+ * @example
+ * const data = validateCartPaymentsStep({
+ *   // retrieve the details of the cart from another workflow
+ *   // or in another step using the Cart Module's service
+ *   cart
+ * })
  */
 export const validateCartPaymentsStep = createStep(
   validateCartPaymentsStepId,

packages/core/core-flows/src/cart/steps/validate-cart-shipping-options.ts

@@ -6,12 +6,30 @@ import {
 } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The details of the cart and its shipping options context.
+ */
 export interface ValidateCartShippingOptionsStepInput {
+  /**
+   * The cart to validate shipping options for.
+   */
   cart: CartDTO
+  /**
+   * The context to validate the shipping options.
+   */
   shippingOptionsContext: {
+    /**
+     * Validate whether the shipping options are enabled in the store.
+     */
     enabled_in_store?: "true" | "false"
+    /**
+     * Validate whether the shipping options are used for returns.
+     */
     is_return?: "true" | "false"
   }
+  /**
+   * The IDs of the shipping options to validate.
+   */
   option_ids: string[]
 }
 
@@ -19,6 +37,16 @@ export const validateCartShippingOptionsStepId =
   "validate-cart-shipping-options"
 /**
  * This step validates shipping options to ensure they can be applied on a cart.
+ * If not valid, the step throws an error.
+ * 
+ * @example
+ * const data = validateCartShippingOptionsStep({
+ *   // retrieve the details of the cart from another workflow
+ *   // or in another step using the Cart Module's service
+ *   cart,
+ *   option_ids: ["so_123"],
+ *   shippingOptionsContext: {}
+ * })
  */
 export const validateCartShippingOptionsStep = createStep(
   validateCartShippingOptionsStepId,

packages/core/core-flows/src/cart/steps/validate-cart.ts

@@ -2,13 +2,33 @@ import { CartDTO, CartWorkflowDTO } from "@medusajs/framework/types"
 import { MedusaError } from "@medusajs/framework/utils"
 import { createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The details of the cart to validate.
+ */
 export interface ValidateCartStepInput {
+  /**
+   * The cart to validate.
+   */
   cart: CartWorkflowDTO | CartDTO
 }
 
 export const validateCartStepId = "validate-cart"
 /**
- * This step validates a cart's before editing it.
+ * This step validates a cart to ensure it exists and is not completed.
+ * If not valid, the step throws an error.
+ * 
+ * :::tip
+ * 
+ * You can use the {@link retrieveCartStep} to retrieve a cart's details.
+ * 
+ * :::
+ * 
+ * @example
+ * const data = validateCartStep({
+ *   // retrieve the details of the cart from another workflow
+ *   // or in another step using the Cart Module's service
+ *   cart,
+ * })
  */
 export const validateCartStep = createStep(
   validateCartStepId,

packages/core/core-flows/src/cart/steps/validate-line-item-prices.ts

@@ -1,9 +1,21 @@
 import { MedusaError, isPresent } from "@medusajs/framework/utils"
 import { createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The details of the line items to validate.
+ */
 export interface ValidateLineItemPricesStepInput {
+  /**
+   * The line items to validate.
+   */
   items: {
+    /**
+     * The price of the line item.
+     */
     unit_price?: number | null
+    /**
+     * The title of the line item.
+     */
     title: string
   }[]
 }
@@ -11,6 +23,20 @@ export interface ValidateLineItemPricesStepInput {
 export const validateLineItemPricesStepId = "validate-line-item-prices"
 /**
  * This step validates the specified line item objects to ensure they have prices.
+ * If an item doesn't have a price, the step throws an error.
+ * 
+ * @example
+ * const data = validateLineItemPricesStep({
+ *   items: [
+ *     {
+ *       unit_price: 10,
+ *       title: "Shirt"
+ *     },
+ *     {
+ *       title: "Pants"
+ *     }
+ *   ]
+ * })
  */
 export const validateLineItemPricesStep = createStep(
   validateLineItemPricesStepId,

packages/core/core-flows/src/cart/steps/validate-shipping-methods-data.ts

@@ -5,18 +5,96 @@ import {
 } from "@medusajs/types"
 import { createStep, StepResponse } from "@medusajs/workflows-sdk"
 
+/**
+ * The details of the shipping methods to validate.
+ */
 export type ValidateShippingMethodsDataInput = {
+  /**
+   * The shipping method's ID.
+   */
   id: string
+  /**
+   * The fulfillment provider ID that associated with the shipping option
+   * that the method was created from.
+   */
   provider_id: string
+  /**
+   * The `data` property of the shipping option that the shipping method was 
+   * created from.
+   */
   option_data: Record<string, unknown>
+  /**
+   * The `data` property of the shipping method.
+   */
   method_data: Record<string, unknown>
+  /**
+   * The context to validate the shipping method.
+   */
   context: ValidateFulfillmentDataContext
 }[]
 
+/**
+ * The validated data of the shipping methods.
+ */
+export type ValidateShippingMethodsDataOutput = void | {
+  [x: string]: Record<string, unknown>;
+}[]
+
 export const validateAndReturnShippingMethodsDataStepId =
   "validate-and-return-shipping-methods-data"
 /**
  * This step validates shipping options to ensure they can be applied on a cart.
+ * The step either returns the validated data or void.
+ * 
+ * @example
+ * const data = validateAndReturnShippingMethodsDataStep({
+ *   id: "sm_123",
+ *   provider_id: "my_provider",
+ *   option_data: {},
+ *   method_data: {},
+ *   context: {
+ *     id: "cart_123",
+ *     shipping_address: {
+ *       id: "saddr_123",
+ *       first_name: "Jane",
+ *       last_name: "Smith",
+ *       address_1: "456 Elm St",
+ *       city: "Shelbyville",
+ *       country_code: "us",
+ *       postal_code: "67890",
+ *     },
+ *     items: [
+ *       {
+ *         variant: {
+ *           id: "variant_123",
+ *           weight: 1,
+ *           length: 1,
+ *           height: 1,
+ *           width: 1,
+ *           material: "wood",
+ *           product: {
+ *             id: "prod_123"
+ *           }
+ *         }
+ *       }
+ *     ],
+ *     product: {
+ *       id: "prod_123",
+ *       collection_id: "pcol_123",
+ *       categories: [],
+ *       tags: []
+ *     },
+ *     from_location: {
+ *       id: "sloc_123",
+ *       first_name: "John",
+ *       last_name: "Doe",
+ *       address_1: "123 Main St",
+ *       city: "Springfield",
+ *       country_code: "us",
+ *       postal_code: "12345",
+ *     },
+ *   }
+ * })
  */
 export const validateAndReturnShippingMethodsDataStep = createStep(
   validateAndReturnShippingMethodsDataStepId,

packages/core/core-flows/src/cart/steps/validate-shipping-options-price.ts

@@ -1,14 +1,41 @@
 import { isDefined, MedusaError } from "@medusajs/framework/utils"
 import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk"
 
-export const validateCartShippingOptionsStepId =
+/**
+ * The details of the shipping options to validate.
+ */
+export type ValidateCartShippingOptionsPriceInput = {
+  /**
+   * The shipping option's details. Should have a `calculated_price.calculated_amount`
+   * to be considered valid.
+   */
+  shippingOptions: any[]
+}
+
+export const validateCartShippingOptionsPriceStepId =
   "validate-cart-shipping-options"
 /**
  * This step validates shipping options to ensure they have a price.
+ * If not valid, the step throws an error.
+ * 
+ * @example
+ * const data = validateCartShippingOptionsPriceStep({
+ *   shippingOptions: [
+ *     {
+ *       id: "so_123",
+ *     },
+ *     {
+ *       id: "so_321",
+ *       calculated_price: {
+ *         calculated_amount: 10,
+ *       }
+ *     }
+ *   ]
+ * })
  */
 export const validateCartShippingOptionsPriceStep = createStep(
   "validate-cart-shipping-options-price",
-  async (data: { shippingOptions: any[] }, { container }) => {
+  async (data: ValidateCartShippingOptionsPriceInput, { container }) => {
     const { shippingOptions = [] } = data
     const optionsMissingPrices: string[] = []
 

packages/core/core-flows/src/cart/steps/validate-variant-prices.ts

@@ -2,10 +2,25 @@ import { BigNumberInput } from "@medusajs/framework/types"
 import { MedusaError, isPresent } from "@medusajs/framework/utils"
 import { createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The details of the variants to validate.
+ */
 export interface ValidateVariantPricesStepInput {
+  /**
+   * The variants to validate.
+   */
   variants: {
+    /**
+     * The ID of the variant.
+     */
     id: string
+    /**
+     * The calculated price of the variant.
+     */
     calculated_price?: {
+      /**
+       * The calculated amount of the price.
+       */
       calculated_amount?: BigNumberInput | null
     }
   }[]
@@ -14,6 +29,22 @@ export interface ValidateVariantPricesStepInput {
 export const validateVariantPricesStepId = "validate-variant-prices"
 /**
  * This step validates the specified variant objects to ensure they have prices.
+ * If not valid, the step throws an error.
+ * 
+ * @example
+ * const data = validateVariantPricesStep({
+ *   variants: [
+ *     {
+ *       id: "variant_123",
+ *     },
+ *     {
+ *       id: "variant_321",
+ *       calculated_price: {
+ *         calculated_amount: 10,
+ *       }
+ *     }
+ *   ]
+ * })
  */
 export const validateVariantPricesStep = createStep(
   validateVariantPricesStepId,

packages/core/core-flows/src/cart/workflows/add-shipping-method-to-cart.ts

@@ -21,17 +21,60 @@ import { cartFieldsForRefreshSteps } from "../utils/fields"
 import { listShippingOptionsForCartWithPricingWorkflow } from "./list-shipping-options-for-cart-with-pricing"
 import { refreshCartItemsWorkflow } from "./refresh-cart-items"
 
+/**
+ * The data to add a shipping method to a cart.
+ */
 export interface AddShippingMethodToCartWorkflowInput {
+  /**
+   * The ID of the cart to add the shipping method to.
+   */
   cart_id: string
+  /**
+   * The shipping options to create the shipping methods from and add to the cart.
+   */
   options: {
+    /**
+     * The ID of the shipping option.
+     */
     id: string
+    /**
+     * Custom data useful for the fulfillment provider processing the shipping option or method.
+     * 
+     * Learn more in [this documentation](https://docs.medusajs.com/resources/commerce-modules/fulfillment/shipping-option#data-property).
+     */
     data?: Record<string, unknown>
   }[]
 }
 
 export const addShippingMethodToCartWorkflowId = "add-shipping-method-to-cart"
 /**
- * This workflow adds shipping methods to a cart.
+ * This workflow adds a shipping method to a cart. It's executed by the 
+ * [Add Shipping Method Store API Route](https://docs.medusajs.com/api/store#carts_postcartsidshippingmethods).
+ * 
+ * You can use this workflow within your own custom workflows, allowing you to wrap custom logic around adding a shipping method to the cart.
+ * 
+ * @example
+ * const { result } = await addShippingMethodToCartWorkflow(container)
+ * .run({
+ *   input: {
+ *     cart_id: "cart_123",
+ *     options: [
+ *       {
+ *         id: "so_123",
+ *       },
+ *       {
+ *         id: "so_124",
+ *         data: {
+ *           carrier_code: "fedex",
+ *         }
+ *       }
+ *     ]
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Add a shipping method to a cart.
  */
 export const addShippingMethodToCartWorkflow = createWorkflow(
   addShippingMethodToCartWorkflowId,

packages/core/core-flows/src/cart/workflows/add-to-cart.ts

@@ -35,7 +35,34 @@ const cartFields = ["completed_at"].concat(cartFieldsForPricingContext)
 
 export const addToCartWorkflowId = "add-to-cart"
 /**
- * This workflow adds items to a cart.
+ * This workflow adds a product variant to a cart as a line item. It's executed by the 
+ * [Add Line Item Store API Route](https://docs.medusajs.com/api/store#carts_postcartsidlineitems).
+ * 
+ * You can use this workflow within your own custom workflows, allowing you to wrap custom logic around adding an item to the cart.
+ * For example, you can use this workflow to add a line item to the cart with a custom price.
+ * 
+ * @example
+ * const { result } = await addToCartWorkflow(container)
+ * .run({
+ *   input: {
+ *     cart_id: "cart_123",
+ *     items: [
+ *       {
+ *         variant_id: "variant_123",
+ *         quantity: 1,
+ *       },
+ *       {
+ *         variant_id: "variant_456",
+ *         quantity: 1,
+ *         unit_price: 20
+ *       }
+ *     ]
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Add a line item to a cart.
  */
 export const addToCartWorkflow = createWorkflow(
   addToCartWorkflowId,

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

@@ -36,7 +36,20 @@ import {
   prepareTaxLinesData,
 } from "../utils/prepare-line-item-data"
 
+/**
+ * The data to complete a cart and place an order.
+ */
 export type CompleteCartWorkflowInput = {
+  /**
+   * The ID of the cart to complete.
+   */
+  id: string
+}
+
+export type CompleteCartWorkflowOutput = {
+  /**
+   * The ID of the order that was created.
+   */
   id: string
 }
 
@@ -44,7 +57,24 @@ export const THREE_DAYS = 60 * 60 * 24 * 3
 
 export const completeCartWorkflowId = "complete-cart"
 /**
- * This workflow completes a cart.
+ * This workflow completes a cart and places an order for the customer. It's executed by the 
+ * [Complete Cart Store API Route](https://docs.medusajs.com/api/store#carts_postcartsidcomplete).
+ * 
+ * You can use this workflow within your own custom workflows, allowing you to wrap custom logic around completing a cart.
+ * For example, in the [Subscriptions recipe](https://docs.medusajs.com/resources/recipes/subscriptions/examples/standard#create-workflow), 
+ * this workflow is used within another workflow that creates a subscription order.
+ * 
+ * @example
+ * const { result } = await completeCartWorkflow(container)
+ * .run({
+ *   input: {
+ *     id: "cart_123"
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Complete a cart and place an order.
  */
 export const completeCartWorkflow = createWorkflow(
   {
@@ -268,7 +298,7 @@ export const completeCartWorkflow = createWorkflow(
     })
 
     const result = transform({ order, orderId }, ({ order, orderId }) => {
-      return { id: order?.id ?? orderId }
+      return { id: order?.id ?? orderId } as CompleteCartWorkflowOutput
     })
 
     return new WorkflowResponse(result, {

packages/core/core-flows/src/cart/workflows/confirm-variant-inventory.ts

@@ -9,20 +9,136 @@ import { BigNumberInput } from "@medusajs/types"
 import { confirmInventoryStep } from "../steps"
 import { prepareConfirmInventoryInput } from "../utils/prepare-confirm-inventory-input"
 
+/**
+ * The details of the cart items with inventory result computed for the specified input.
+ */
 export interface ConfirmVariantInventoryWorkflowOutput {
+  /**
+   * The cart's line items with the computed inventory result.
+   */
   items: {
+    /**
+     * The line item's ID.
+     */
     id?: string
+    /**
+     * The ID of the inventory item used to retrieve the item's available quantity.
+     */
     inventory_item_id: string
+    /**
+     * The number of units a single quantity is equivalent to. For example, if a customer orders one quantity of the variant, Medusa checks the availability of the quantity multiplied by the
+     * value set for `required_quantity`. When the customer orders the quantity, Medusa reserves the ordered quantity multiplied by the value set for `required_quantity`.
+     */
     required_quantity: number
+    /**
+     * Whether the variant can be ordered even if it's out of stock. If a variant has this enabled, the workflow doesn't throw an error.
+     */
     allow_backorder: boolean
+    /**
+     * The quantity in the cart. If you provided `itemsToUpdate` in the input, this will be the updated quantity.
+     */
     quantity: BigNumberInput
+    /**
+     * The ID of the stock locations that the computed inventory quantity is available in.
+     */
     location_ids: string[]
   }[]
 }
 
 export const confirmVariantInventoryWorkflowId = "confirm-item-inventory"
 /**
- * This workflow confirms for one or more variants that their inventory has a required quantity.
+ * This workflow validates that product variants are in-stock at the specified sales channel, before adding them or updating their quantity in the cart. If a variant doesn't have sufficient quantity in-stock,
+ * the workflow throws an error. If all variants have sufficient inventory, the workflow returns the cart's items with their inventory details.
+ * 
+ * This workflow is useful when confirming that a product variant has sufficient quantity to be added to or updated in the cart. It's executed
+ * by other cart-related workflows, such as {@link addToCartWorkflow}, to confirm that a product variant can be added to the cart at the specified quantity.
+ * 
+ * :::note
+ * 
+ * Learn more about the links between the product variant and sales channels and inventory items in [this documentation](https://docs.medusajs.com/resources/commerce-modules/product/links-to-other-modules).
+ * 
+ * :::
+ * 
+ * You can use this workflow within your own custom workflows, allowing you to check whether a product variant has enough inventory quantity before adding them to the cart.
+ * 
+ * @example
+ * You can retrieve a variant's required details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query):
+ * 
+ * ```ts workflow={false}
+ * const { data: variants } = await query.graph({
+ *   entity: "variant",
+ *   fields: [
+ *     "id",
+ *     "manage_inventory",
+ *     "inventory_items.inventory_item_id",
+ *     "inventory_items.required_quantity",
+ *     "inventory_items.inventory.requires_shipping",
+ *     "inventory_items.inventory.location_levels.stock_locations.id",
+ *     "inventory_items.inventory.location_levels.stock_locations.name",
+ *     "inventory_items.inventory.location_levels.stock_locations.sales_channels.id",
+ *     "inventory_items.inventory.location_levels.stock_locations.sales_channels.name",
+ *   ],
+ *   filters: {
+ *     id: ["variant_123"]
+ *   }
+ * })
+ * ```
+ * 
+ * :::note
+ * 
+ * In a workflow, use [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep) instead.
+ * 
+ * :::
+ * 
+ * Then, pass the variant's data with the other required data to the workflow:
+ * 
+ * ```ts
+ * const { result } = await confirmVariantInventoryWorkflow(container)
+ *   .run({
+ *     input: {
+ *       sales_channel_id: "sc_123",
+ *       // @ts-ignore
+ *       variants,
+ *       items: [
+ *         {
+ *           variant_id: "variant_123",
+ *           quantity: 1
+ *         }
+ *       ]
+ *     }
+ *   })
+ * ```
+ * 
+ * When updating an item quantity:
+ * 
+ * ```ts
+ * const { result } = await confirmVariantInventoryWorkflow(container)
+ *  .run({
+ *    input: {
+ *      sales_channel_id: "sc_123",
+ *      // @ts-ignore
+ *      variants,
+ *      items: [
+ *        {
+ *          variant_id: "variant_123",
+ *          quantity: 1
+ *        }
+ *      ],
+ *      itemsToUpdate: [
+ *        {
+ *          data: {
+ *            variant_id: "variant_123",
+ *            quantity: 2
+ *          }
+ *        }
+ *      ]
+ *    }
+ *  })
+ * ```
+ * 
+ * @summary
+ * 
+ * Validate that a variant is in-stock before adding to the cart.
  */
 export const confirmVariantInventoryWorkflow = createWorkflow(
   confirmVariantInventoryWorkflowId,

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

@@ -15,12 +15,40 @@ import { useRemoteQueryStep } from "../../common/steps/use-remote-query"
 import { createPaymentCollectionsStep } from "../steps/create-payment-collection"
 import { validateCartStep } from "../steps/validate-cart"
 
+/**
+ * The details of the cart to validate its payment collection.
+ */
+export type ValidateExistingPaymentCollectionStepInput = {
+  /**
+   * The cart to validate.
+   */
+  cart: CartDTO & { payment_collection?: any }
+}
+
 /**
  * This step validates that a cart doesn't have a payment collection.
+ * If the cart has a payment collection, the step throws an error.
+ * 
+ * :::tip
+ * 
+ * You can use the {@link retrieveCartStep} to retrieve a cart's details.
+ * 
+ * :::
+ * 
+ * @example
+ * const data = validateExistingPaymentCollectionStep({
+ *   cart: {
+ *     // other cart details...
+ *     payment_collection: {
+ *       id: "paycol_123",
+ *       // other payment collection details.
+ *     }
+ *   }
+ * })
  */
 export const validateExistingPaymentCollectionStep = createStep(
   "validate-existing-payment-collection",
-  ({ cart }: { cart: CartDTO & { payment_collection?: any } }) => {
+  ({ cart }: ValidateExistingPaymentCollectionStepInput) => {
     if (cart.payment_collection) {
       throw new Error(`Cart ${cart.id} already has a payment collection`)
     }
@@ -30,7 +58,25 @@ export const validateExistingPaymentCollectionStep = createStep(
 export const createPaymentCollectionForCartWorkflowId =
   "create-payment-collection-for-cart"
 /**
- * This workflow creates a payment collection for a cart.
+ * This workflow creates a payment collection for a cart. It's executed by the 
+ * [Create Payment Collection Store API Route](https://docs.medusajs.com/api/store#payment-collections_postpaymentcollections).
+ * 
+ * You can use this workflow within your own custom workflows, allowing you to wrap custom logic around adding creating a payment collection for a cart.
+ * 
+ * @example
+ * const { result } = await createPaymentCollectionForCartWorkflow(container)
+ * .run({
+ *   input: {
+ *     cart_id: "cart_123",
+ *     metadata: {
+ *       sandbox: true
+ *     }
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Create payment collection for cart.
  */
 export const createPaymentCollectionForCartWorkflow = createWorkflow(
   createPaymentCollectionForCartWorkflowId,

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

@@ -7,6 +7,8 @@ export * from "./create-payment-collection-for-cart"
 export * from "./list-shipping-options-for-cart"
 export * from "./list-shipping-options-for-cart-with-pricing"
 export * from "./refresh-payment-collection"
+export * from "./refresh-cart-items"
+export * from "./refresh-cart-shipping-methods"
 export * from "./transfer-cart-customer"
 export * from "./update-cart"
 export * from "./update-cart-promotions"

packages/core/core-flows/src/cart/workflows/list-shipping-options-for-cart-with-pricing.ts

@@ -6,7 +6,10 @@ import {
   WorkflowData,
   WorkflowResponse,
 } from "@medusajs/framework/workflows-sdk"
-import { CalculateShippingOptionPriceDTO } from "@medusajs/types"
+import { 
+  CalculateShippingOptionPriceDTO, 
+  ListShippingOptionsForCartWithPricingWorkflowInput,
+} from "@medusajs/types"
 
 import { useQueryGraphStep, validatePresenceOfStep } from "../../common"
 import { useRemoteQueryStep } from "../../common/steps/use-remote-query"
@@ -39,17 +42,39 @@ const COMMON_OPTIONS_FIELDS = [
 export const listShippingOptionsForCartWithPricingWorkflowId =
   "list-shipping-options-for-cart-with-pricing"
 /**
- * This workflow lists the shipping options of a cart.
+ * This workflow lists shipping options that can be used during checkout for a cart. It also retrieves the prices
+ * of these shipping options, including calculated prices that may be retrieved from third-party providers.
+ * 
+ * This workflow is executed in other cart-related workflows, such as {@link addShippingMethodToCartWorkflow} to retrieve the
+ * price of the shipping method being added to the cart.
+ * 
+ * You can use this workflow within your own custom workflows, allowing you to retrieve the shipping options of a cart and their prices 
+ * in your custom flows.
+ * 
+ * @example
+ * const { result } = await listShippingOptionsForCartWithPricingWorkflow(container)
+ * .run({
+ *   input: {
+ *     cart_id: "cart_123",
+ *     options: [
+ *       {
+ *         id: "so_123",
+ *         data: {
+ *           carrier_code: "fedex"
+ *         }
+ *       }
+ *     ]
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * List a cart's shipping options with prices.
  */
 export const listShippingOptionsForCartWithPricingWorkflow = createWorkflow(
   listShippingOptionsForCartWithPricingWorkflowId,
   (
-    input: WorkflowData<{
+    input: WorkflowData<ListShippingOptionsForCartWithPricingWorkflowInput>
-      cart_id: string
-      options?: { id: string; data?: Record<string, unknown> }[]
-      is_return?: boolean
-      enabled_in_store?: boolean
-    }>
   ) => {
     const optionIds = transform({ input }, ({ input }) =>
       (input.options ?? []).map(({ id }) => id)

packages/core/core-flows/src/cart/workflows/list-shipping-options-for-cart.ts

@@ -7,21 +7,41 @@ import {
 import { useQueryGraphStep, validatePresenceOfStep } from "../../common"
 import { useRemoteQueryStep } from "../../common/steps/use-remote-query"
 import { cartFieldsForPricingContext } from "../utils/fields"
+import { ListShippingOptionsForCartWorkflowInput } from "@medusajs/types"
 
 export const listShippingOptionsForCartWorkflowId =
   "list-shipping-options-for-cart"
 /**
- * This workflow lists the shipping options of a cart.
+ * This workflow lists the shipping options of a cart. It's executed by the 
+ * [List Shipping Options Store API Route](https://docs.medusajs.com/api/store#shipping-options_getshippingoptions).
+ * 
+ * :::note
+ * 
+ * This workflow doesn't retrieve the calculated prices of the shipping options. If you need to retrieve the prices of the shipping options,
+ * use the {@link listShippingOptionsForCartWithPricingWorkflow} workflow.
+ * 
+ * :::
+ * 
+ * You can use this workflow within your own custom workflows, allowing you to wrap custom logic around to retrieve the shipping options of a cart  
+ * in your custom flows.
+ * 
+ * @example
+ * const { result } = await listShippingOptionsForCartWorkflow(container)
+ * .run({
+ *   input: {
+ *     cart_id: "cart_123",
+ *     option_ids: ["so_123"]
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * List a cart's shipping options.
  */
 export const listShippingOptionsForCartWorkflow = createWorkflow(
   listShippingOptionsForCartWorkflowId,
   (
-    input: WorkflowData<{
+    input: WorkflowData<ListShippingOptionsForCartWorkflowInput>
-      cart_id: string
-      option_ids?: string[]
-      is_return?: boolean
-      enabled_in_store?: boolean
-    }>
   ) => {
     const cartQuery = useQueryGraphStep({
       entity: "cart",

packages/core/core-flows/src/cart/workflows/refresh-cart-items.ts

@@ -28,17 +28,48 @@ import { refreshPaymentCollectionForCartWorkflow } from "./refresh-payment-colle
 import { updateCartPromotionsWorkflow } from "./update-cart-promotions"
 import { updateTaxLinesWorkflow } from "./update-tax-lines"
 
+/**
+ * The details of the cart to refresh.
+ */
+export type RefreshCartItemsWorkflowInput = {
+  /**
+   * The cart's ID.
+   */
+  cart_id: string
+  /**
+   * The promotion codes applied on the cart.
+   * These promotion codes will replace previously applied codes.
+   */
+  promo_codes?: string[]
+}
+
 export const refreshCartItemsWorkflowId = "refresh-cart-items"
 /**
- * This workflow refreshes a cart's items
+ * This workflow refreshes a cart to ensure its prices, promotion codes, taxes, and other details are applied correctly. It's useful
+ * after making a chnge to a cart, such as after adding an item to the cart or adding a promotion code.
+ * 
+ * This workflow is used by other cart-related workflows, such as the {@link addToCartWorkflow} after an item
+ * is added to the cart.
+ * 
+ * You can use this workflow within your own custom workflows, allowing you to refresh the cart after making updates to it in your
+ * custom flows.
+ * 
+ * @example
+ * const { result } = await refreshCartItemsWorkflow(container)
+ * .run({
+ *   input: {
+ *     cart_id: "cart_123",
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Refresh a cart's details after an update.
  */
 export const refreshCartItemsWorkflow = createWorkflow(
   refreshCartItemsWorkflowId,
   (
-    input: WorkflowData<{
+    input: WorkflowData<RefreshCartItemsWorkflowInput>
-      cart_id: string
-      promo_codes?: string[]
-    }>
   ) => {
     const cart = useRemoteQueryStep({
       entry_point: "cart",

packages/core/core-flows/src/cart/workflows/refresh-cart-shipping-methods.ts

@@ -13,14 +13,39 @@ import { removeShippingMethodFromCartStep } from "../steps"
 import { updateShippingMethodsStep } from "../steps/update-shipping-methods"
 import { listShippingOptionsForCartWithPricingWorkflow } from "./list-shipping-options-for-cart-with-pricing"
 
+/**
+ * The details of the cart to refresh.
+ */
+export type RefreshCartShippingMethodsWorkflowInput = { 
+  /**
+   * The cart's ID.
+   */
+  cart_id: string
+}
+
 export const refreshCartShippingMethodsWorkflowId =
   "refresh-cart-shipping-methods"
 /**
- * This workflow refreshes a cart's shipping methods
+ * This workflow refreshes a cart's shipping methods, ensuring that their associated shipping options can still be used on the cart,
+ * and retrieve their correct pricing after a cart update. This workflow is used by the {@link refreshCartItemsWorkflow}.
+ * 
+ * You can use this workflow within your own custom workflows, allowing you to refresh the cart's shipping method after making updates to the cart.
+ * 
+ * @example
+ * const { result } = await refreshCartShippingMethodsWorkflow(container)
+ * .run({
+ *   input: {
+ *     cart_id: "cart_123",
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Refresh a cart's shipping methods after an update.
  */
 export const refreshCartShippingMethodsWorkflow = createWorkflow(
   refreshCartShippingMethodsWorkflowId,
-  (input: WorkflowData<{ cart_id: string }>) => {
+  (input: WorkflowData<RefreshCartShippingMethodsWorkflowInput>) => {
     const cartQuery = useQueryGraphStep({
       entity: "cart",
       filters: { id: input.cart_id },

packages/core/core-flows/src/cart/workflows/refresh-payment-collection.ts

@@ -12,14 +12,40 @@ import { useRemoteQueryStep } from "../../common/steps/use-remote-query"
 import { updatePaymentCollectionStep } from "../../payment-collection"
 import { deletePaymentSessionsWorkflow } from "../../payment-collection/workflows/delete-payment-sessions"
 
+/**
+ * The details of the cart to refresh.
+ */
 export type RefreshPaymentCollectionForCartWorklowInput = {
+  /**
+   * The cart's ID.
+   */
   cart_id: string
 }
 
 export const refreshPaymentCollectionForCartWorkflowId =
   "refresh-payment-collection-for-cart"
 /**
- * This workflow refreshes the payment collections of a cart.
+ * This workflow refreshes a cart's payment collection, which is useful once the cart is created or when its details
+ * are updated. If the cart's total changes to the amount in its payment collection, the payment collection's payment sessions are 
+ * deleted. It also syncs the payment collection's amount, currency code, and other details with the details in the cart.
+ * 
+ * This workflow is used by other cart-related workflows, such as the {@link refreshCartItemsWorkflow} to refresh the cart's
+ * payment collection after an update.
+ * 
+ * You can use this workflow within your own custom workflows, allowing you to refresh the cart's payment collection after making updates to it in your
+ * custom flows.
+ * 
+ * @example
+ * const { result } = await refreshPaymentCollectionForCartWorkflow(container)
+ * .run({
+ *   input: {
+ *     cart_id: "cart_123",
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Refresh a cart's payment collection details.
  */
 export const refreshPaymentCollectionForCartWorkflow = createWorkflow(
   refreshPaymentCollectionForCartWorkflowId,

packages/core/core-flows/src/cart/workflows/transfer-cart-customer.ts

@@ -10,13 +10,44 @@ import { useQueryGraphStep } from "../../common"
 import { updateCartsStep } from "../steps"
 import { refreshCartItemsWorkflow } from "./refresh-cart-items"
 
+/**
+ * The cart ownership transfer details.
+ */
+export type TransferCartCustomerWorkflowInput = { 
+  /**
+   * The cart's ID.
+   */
+  id: string; 
+  /**
+   * The ID of the customer to transfer the cart to.
+   */
+  customer_id: string
+}
+
 export const transferCartCustomerWorkflowId = "transfer-cart-customer"
 /**
- * This workflow transfers cart's customer.
+ * This workflow transfers a cart's customer ownership to another customer. It's useful if a customer logs in after
+ * adding the items to their cart, allowing you to transfer the cart's ownership to the logged-in customer. This workflow is used
+ * by the [Set Cart's Customer Store API Route](https://docs.medusajs.com/api/store#carts_postcartsidcustomer).
+ * 
+ * You can use this workflow within your own custom workflows, allowing you to set the cart's customer within your custom flows.
+ * 
+ * @example
+ * const { result } = await transferCartCustomerWorkflow(container)
+ * .run({
+ *   input: {
+ *     id: "cart_123",
+ *     customer_id: "cus_123"
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Refresh a cart's payment collection details.
  */
 export const transferCartCustomerWorkflow = createWorkflow(
   transferCartCustomerWorkflowId,
-  (input: WorkflowData<{ id: string; customer_id: string }>) => {
+  (input: WorkflowData<TransferCartCustomerWorkflowInput>) => {
     const cartQuery = useQueryGraphStep({
       entity: "cart",
       filters: { id: input.id },

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

@@ -20,9 +20,22 @@ import {
 import { updateCartPromotionsStep } from "../steps/update-cart-promotions"
 import { cartFieldsForRefreshSteps } from "../utils/fields"
 
+/**
+ * The details of the promotion updates on a cart.
+ */
 export type UpdateCartPromotionsWorkflowInput = {
+  /**
+   * The cart's ID.
+   */
   cart_id: string
+  /**
+   * The promotion codes to add to the cart, remove from the cart,
+   * or replace all existing promotions in the cart.
+   */
   promo_codes?: string[]
+  /**
+   * The action to perform with the specified promotion codes.
+   */
   action?:
     | PromotionActions.ADD
     | PromotionActions.REMOVE
@@ -31,7 +44,26 @@ export type UpdateCartPromotionsWorkflowInput = {
 
 export const updateCartPromotionsWorkflowId = "update-cart-promotions"
 /**
- * This workflow updates a cart's promotions.
+ * This workflow updates a cart's promotions, applying or removing promotion codes from the cart. It also computes the adjustments
+ * that need to be applied to the cart's line items and shipping methods based on the promotions applied. This workflow is used by
+ * [Add Promotions Store API Route](https://docs.medusajs.com/api/store#carts_postcartsidpromotions).
+ * 
+ * You can use this workflow within your own custom workflows, allowing you to update a cart's promotions within your custom flows.
+ * 
+ * @example
+ * const { result } = await updateCartPromotionsWorkflow(container)
+ * .run({
+ *   input: {
+ *     cart_id: "cart_123",
+ *     promo_codes: ["10OFF"],
+ *     // imported from @medusajs/framework/utils
+ *     action: PromotionActions.ADD,
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Update a cart's applied promotions to add, replace, or remove them.
  */
 export const updateCartPromotionsWorkflow = createWorkflow(
   updateCartPromotionsWorkflowId,

packages/core/core-flows/src/cart/workflows/update-line-item-in-cart.ts

@@ -24,7 +24,26 @@ const cartFields = cartFieldsForPricingContext.concat(["items.*"])
 
 export const updateLineItemInCartWorkflowId = "update-line-item-in-cart"
 /**
- * This workflow updates a cart's line item.
+ * This workflow updates a line item's details in a cart. You can update the line item's quantity, unit price, and more. This workflow is executed
+ * by the [Update Line Item Store API Route](https://docs.medusajs.com/api/store#carts_postcartsidlineitemsline_id).
+ * 
+ * You can use this workflow within your own custom workflows, allowing you to update a line item's details in your custom flows.
+ * 
+ * @example
+ * const { result } = await updateLineItemInCartWorkflow(container)
+ * .run({
+ *   input: {
+ *     cart_id: "cart_123",
+ *     item_id: "item_123",
+ *     update: {
+ *       quantity: 2
+ *     }
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Update a cart's line item.
  */
 export const updateLineItemInCartWorkflow = createWorkflow(
   updateLineItemInCartWorkflowId,

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

@@ -60,16 +60,60 @@ const cartFields = [
   "shipping_address.metadata",
 ]
 
+/**
+ * The details of the cart to update tax lines for.
+ */
 export type UpdateTaxLinesWorkflowInput = {
+  /**
+   * The cart's ID.
+   */
   cart_id: string
+  /**
+   * The items to update their tax lines.
+   * If not specified, taxes are updated for all of the cart's
+   * line items.
+   * 
+   * @privateRemarks
+   * This doesn't seem to be used?
+   */
   items?: CartLineItemDTO[]
+  /**
+   * The shipping methods to update their tax lines.
+   * If not specified, taxes are updated for all of the cart's
+   * shipping methods.
+   * 
+   * @privateRemarks
+   * This doesn't seem to be used?
+   */
   shipping_methods?: CartShippingMethodDTO[]
+  /**
+   * Whether to force re-calculating tax amounts, which
+   * may include sending requests to a third-part tax provider, depending
+   * on the configurations of the cart's tax region.
+   * 
+   * @defaultValue false
+   */
   force_tax_calculation?: boolean
 }
 
 export const updateTaxLinesWorkflowId = "update-tax-lines"
 /**
- * This workflow updates a cart's tax lines.
+ * This workflow updates a cart's tax lines that are applied on line items and shipping methods. You can update the line item's quantity, unit price, and more. This workflow is executed
+ * by the [Calculate Taxes Store API Route](https://docs.medusajs.com/api/store#carts_postcartsidtaxes).
+ * 
+ * You can use this workflow within your own custom workflows, allowing you to update a cart's tax lines in your custom flows.
+ * 
+ * @example
+ * const { result } = await updateTaxLinesWorkflow(container)
+ * .run({
+ *   input: {
+ *     cart_id: "cart_123",
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Update a cart's tax lines.
  */
 export const updateTaxLinesWorkflow = createWorkflow(
   updateTaxLinesWorkflowId,

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

@@ -3,6 +3,7 @@ import {
   CreateCustomerAddressDTO,
 } from "@medusajs/framework/types"
 import {
+  WorkflowData,
   WorkflowResponse,
   createHook,
   createWorkflow,
@@ -73,7 +74,7 @@ export const createCustomerAddressesWorkflowId = "create-customer-addresses"
  */
 export const createCustomerAddressesWorkflow = createWorkflow(
   createCustomerAddressesWorkflowId,
-  (input: CreateCustomerAddressesWorkflowInput) => {
+  (input: WorkflowData<CreateCustomerAddressesWorkflowInput>) => {
     const unsetInput = transform(input, (data) => ({
       create: data.addresses,
     }))

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

@@ -1,6 +1,7 @@
 import { AdditionalData, CreateCustomerDTO } from "@medusajs/framework/types"
 import { CustomerWorkflowEvents } from "@medusajs/framework/utils"
 import {
+  WorkflowData,
   WorkflowResponse,
   createHook,
   createWorkflow,
@@ -52,7 +53,7 @@ export const createCustomersWorkflowId = "create-customers"
  */
 export const createCustomersWorkflow = createWorkflow(
   createCustomersWorkflowId,
-  (input: CreateCustomersWorkflowInput) => {
+  (input: WorkflowData<CreateCustomersWorkflowInput>) => {
     const createdCustomers = createCustomersStep(input.customersData)
     const customersCreated = createHook("customersCreated", {
       customers: createdCustomers,

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

@@ -4,6 +4,7 @@ import {
   AdditionalData,
 } from "@medusajs/framework/types"
 import {
+  WorkflowData,
   WorkflowResponse,
   createHook,
   createWorkflow,
@@ -64,7 +65,7 @@ export const updateCustomerAddressesWorkflowId = "update-customer-addresses"
  */
 export const updateCustomerAddressesWorkflow = createWorkflow(
   updateCustomerAddressesWorkflowId,
-  (input: UpdateCustomerAddressesWorkflowInput) => {
+  (input: WorkflowData<UpdateCustomerAddressesWorkflowInput>) => {
     const unsetInput = transform(input, (data) => ({
       update: data,
     }))

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

@@ -14,6 +14,7 @@ import {
   OrderWorkflowEvents,
 } from "@medusajs/framework/utils"
 import {
+  WorkflowData,
   WorkflowResponse,
   createHook,
   createStep,
@@ -309,7 +310,7 @@ export const createOrderFulfillmentWorkflowId = "create-order-fulfillment"
 export const createOrderFulfillmentWorkflow = createWorkflow(
   createOrderFulfillmentWorkflowId,
   (
-    input: CreateOrderFulfillmentWorkflowInput
+    input: WorkflowData<CreateOrderFulfillmentWorkflowInput>
   ) => {
     const order: OrderDTO = useRemoteQueryStep({
       entry_point: "orders",

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

@@ -1,6 +1,7 @@
 import { AdditionalData, CreateOrderDTO } from "@medusajs/framework/types"
 import { MedusaError, isDefined, isPresent } from "@medusajs/framework/utils"
 import {
+  WorkflowData,
   WorkflowResponse,
   createHook,
   createWorkflow,
@@ -76,6 +77,9 @@ function getOrderInput(data) {
   return data_
 }
 
+/**
+ * The data to create an order, along with custom data that's passed to the workflow's hooks.
+ */
 export type CreateOrderWorkflowInput = CreateOrderDTO & AdditionalData
 
 export const createOrdersWorkflowId = "create-orders"
@@ -126,7 +130,7 @@ export const createOrdersWorkflowId = "create-orders"
  */
 export const createOrderWorkflow = createWorkflow(
   createOrdersWorkflowId,
-  (input: CreateOrderWorkflowInput) => {
+  (input: WorkflowData<CreateOrderWorkflowInput>) => {
     const variantIds = transform({ input }, (data) => {
       return (data.input.items ?? [])
         .map((item) => item.variant_id)

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

@@ -6,6 +6,7 @@ import {
 } from "@medusajs/framework/types"
 import { FulfillmentEvents, Modules } from "@medusajs/framework/utils"
 import {
+  WorkflowData,
   WorkflowResponse,
   createHook,
   createStep,
@@ -154,7 +155,7 @@ export const createOrderShipmentWorkflowId = "create-order-shipment"
 export const createOrderShipmentWorkflow = createWorkflow(
   createOrderShipmentWorkflowId,
   (
-    input: CreateOrderShipmentWorkflowInput
+    input: WorkflowData<CreateOrderShipmentWorkflowInput>
   ) => {
     const order: OrderDTO = useRemoteQueryStep({
       entry_point: "orders",

packages/core/core-flows/src/promotion/workflows/create-campaigns.ts

@@ -1,5 +1,6 @@
 import { AdditionalData, CreateCampaignDTO } from "@medusajs/framework/types"
 import {
+  WorkflowData,
   WorkflowResponse,
   createHook,
   createWorkflow,
@@ -55,7 +56,7 @@ export const createCampaignsWorkflowId = "create-campaigns"
  */
 export const createCampaignsWorkflow = createWorkflow(
   createCampaignsWorkflowId,
-  (input: CreateCampaignsWorkflowInput) => {
+  (input: WorkflowData<CreateCampaignsWorkflowInput>) => {
     const createdCampaigns = createCampaignsStep(input.campaignsData)
     const campaignsCreated = createHook("campaignsCreated", {
       campaigns: createdCampaigns,

packages/core/core-flows/src/promotion/workflows/create-promotions.ts

@@ -1,5 +1,6 @@
 import { AdditionalData, CreatePromotionDTO } from "@medusajs/framework/types"
 import {
+  WorkflowData,
   WorkflowResponse,
   createHook,
   createWorkflow,
@@ -56,7 +57,7 @@ export const createPromotionsWorkflowId = "create-promotions"
  */
 export const createPromotionsWorkflow = createWorkflow(
   createPromotionsWorkflowId,
-  (input: CreatePromotionsWorkflowInput) => {
+  (input: WorkflowData<CreatePromotionsWorkflowInput>) => {
     const createdPromotions = createPromotionsStep(input.promotionsData)
     const promotionsCreated = createHook("promotionsCreated", {
       promotions: createdPromotions,

packages/core/core-flows/src/promotion/workflows/update-campaigns.ts

@@ -1,5 +1,6 @@
 import { AdditionalData, UpdateCampaignDTO } from "@medusajs/framework/types"
 import {
+  WorkflowData,
   WorkflowResponse,
   createHook,
   createWorkflow,
@@ -50,7 +51,7 @@ export const updateCampaignsWorkflowId = "update-campaigns"
  */
 export const updateCampaignsWorkflow = createWorkflow(
   updateCampaignsWorkflowId,
-  (input: UpdateCampaignsWorkflowInput) => {
+  (input: WorkflowData<UpdateCampaignsWorkflowInput>) => {
     const updatedCampaigns = updateCampaignsStep(input.campaignsData)
     const campaignsUpdated = createHook("campaignsUpdated", {
       campaigns: updatedCampaigns,

packages/core/core-flows/src/promotion/workflows/update-promotions.ts

@@ -1,5 +1,6 @@
 import { AdditionalData, UpdatePromotionDTO } from "@medusajs/framework/types"
 import {
+  WorkflowData,
   WorkflowResponse,
   createHook,
   createWorkflow,
@@ -49,7 +50,7 @@ export const updatePromotionsWorkflowId = "update-promotions"
  */
 export const updatePromotionsWorkflow = createWorkflow(
   updatePromotionsWorkflowId,
-  (input: UpdatePromotionsWorkflowInput) => {
+  (input: WorkflowData<UpdatePromotionsWorkflowInput>) => {
     const updatedPromotions = updatePromotionsStep(input.promotionsData)
     const promotionsUpdated = createHook("promotionsUpdated", {
       promotions: updatedPromotions,

packages/core/types/src/cart/workflows.ts

@@ -132,9 +132,21 @@ export interface CreateCartCreateLineItemDTO {
   metadata?: Record<string, unknown> | null
 }
 
+/**
+ * The details of the line item to update.
+ */
 export interface UpdateLineItemInCartWorkflowInputDTO {
+  /**
+   * The ID of the cart that the line item belongs to.
+   */
   cart_id: string
+  /**
+   * The ID of the line item to update.
+   */
   item_id: string
+  /**
+   * The details to update in the line item.
+   */
   update: Partial<UpdateLineItemDTO>
 }
 
@@ -267,8 +279,17 @@ export interface CreateCartWorkflowInputDTO {
   promo_codes?: string[]
 }
 
+/**
+ * The details of adding items to the cart.
+ */
 export interface AddToCartWorkflowInputDTO {
+  /**
+   * The ID of the cart to add items to.
+   */
   cart_id: string
+  /**
+   * The items to add to the cart.
+   */
   items: CreateCartCreateLineItemDTO[]
 }
 
@@ -329,14 +350,36 @@ export interface UpdateCartWorkflowInputDTO {
   billing_address?: CreateAddressDTO | UpdateAddressDTO | null
 }
 
+/**
+ * The details to create the payment collection.
+ */
 export interface CreatePaymentCollectionForCartWorkflowInputDTO {
+  /**
+   * The ID of the cart to create a payment collection for.
+   */
   cart_id: string
+
+  /**
+   * Custom key-value pairs to store in the payment collection.
+   */
   metadata?: Record<string, unknown>
 }
 
+/**
+ * A cart's details.
+ */
 export interface CartWorkflowDTO extends CartDTO {
+  /**
+   * The cart's customer.
+   */
   customer?: CustomerDTO
+  /**
+   * The cart's product to be added.
+   */
   product?: ProductDTO
+  /**
+   * The cart's region.
+   */
   region?: RegionDTO
 }
 
@@ -361,20 +404,67 @@ export interface CompleteCartWorkflowInputDTO {
   id: string
 }
 
+/**
+ * The details necessary to check whether the variant has sufficient inventory.
+ */
 export interface ConfirmVariantInventoryWorkflowInputDTO {
+  /**
+   * The ID of the sales channel to check the inventory availability in.
+   */
   sales_channel_id: string
+  /**
+   * The variants to confirm they have sufficient in-stock quantity.
+   */
   variants: {
+    /**
+     * The variant's ID.
+     */
     id: string
+    /**
+     * Whether Medusa manages the inventory of the variant. If disabled, the
+     * variant is always considered in stock.
+     */
     manage_inventory: boolean
+    /**
+     * The variant's inventory items, if {@link manage_inventory} is enabled.
+     */
     inventory_items: {
+      /**
+       * The ID of the inventory item.
+       */
       inventory_item_id: string
+      /**
+       * The ID of the variant.
+       */
       variant_id: string
+      /**
+       * The number of units a single quantity is equivalent to. For example, if a customer orders one quantity of the variant, Medusa checks the availability of the quantity multiplied by the
+       * value set for `required_quantity`. When the customer orders the quantity, Medusa reserves the ordered quantity multiplied by the value set for `required_quantity`.
+       */
       required_quantity: BigNumberInput
+      /**
+       * The inventory details.
+       */
       inventory: {
+        /**
+         * The inventory details at specified stock locations.
+         */
         location_levels: {
+          /**
+           * The stock location's details.
+           */
           stock_locations: {
+            /**
+             * The stock location's ID.
+             */
             id: string
+            /**
+             * The associated sales channel's details.
+             */
             sales_channels: {
+              /**
+               * The sales channel's ID.
+               */
               id: string
             }[]
           }[]
@@ -382,14 +472,39 @@ export interface ConfirmVariantInventoryWorkflowInputDTO {
       }[]
     }[]
   }[]
+  /**
+   * The items in the cart, or to be added.
+   */
   items: {
+    /**
+     * The ID of the associated variant.
+     */
     variant_id?: string | null
+    /**
+     * The quantity in the cart.
+     */
     quantity: BigNumberInput
+    /**
+     * The ID of the line item if it's already in the cart.
+     */
     id?: string
   }[]
+  /**
+   * The new quantity of the variant to be added to the cart.
+   * This is useful when updating a variant's quantity in the cart.
+   */
   itemsToUpdate?: {
+    /**
+     * The item update's details.
+     */
     data: {
+      /**
+       * The ID of the associated variant.
+       */
       variant_id?: string
+      /**
+       * The variant's quantity.
+       */
       quantity?: BigNumberInput
     }
   }[]

packages/core/types/src/fulfillment/common/cart.ts

@@ -1,27 +1,87 @@
 import { CartDTO } from "../.."
 
+/**
+ * A cart's details relevant for fulfillment.
+ */
 export type CartPropsForFulfillment = {
+  /**
+   * The cart's ID.
+   */
   id: CartDTO["id"]
+  /**
+   * The cart's shipping address.
+   */
   shipping_address: CartDTO["shipping_address"]
+  /**
+   * The cart's items
+   */
   items: CartDTO["items"] & {
+    /**
+     * The item's variant.
+     */
     variant: {
+      /**
+       * The variant's ID.
+       */
       id: string
+      /**
+       * The variant's weight.
+       */
       weight: number
+      /**
+       * The variant's length.
+       */
       length: number
+      /**
+       * The variant's height.
+       */
       height: number
+      /**
+       * The variant's width.
+       */
       width: number
+      /**
+       * The variant's material.
+       */
       material: string
+      /**
+       * The variant's associated product.
+       */
       product: {
+        /**
+         * The product's ID.
+         */
         id: string
       }
     }
+    /**
+     * The item's product.
+     */
     product: {
+      /**
+       * The product's ID.
+       */
       id: string
+      /**
+       * The ID of the collection that the product belongs to.
+       */
       collection_id: string
+      /**
+       * The product's categories.
+       */
       categories: {
+        /**
+         * The category's ID.
+         */
         id: string
       }[]
+      /**
+       * The product's tags.
+       */
       tags: {
+        /**
+         * The tag's ID.
+         */
         id: string
       }[]
     }

packages/core/types/src/fulfillment/provider.ts

@@ -39,6 +39,9 @@ export type CalculatedShippingOptionPrice = {
   is_calculated_price_tax_inclusive: boolean
 }
 
+/**
+ * The context for validating fulfillment data.
+ */
 export type ValidateFulfillmentDataContext = CartPropsForFulfillment & {
   /**
    * Details about the location that items are being shipped from.

packages/core/types/src/fulfillment/workflows.ts

@@ -1,3 +1,5 @@
+import { CalculatedShippingOptionPrice, StockLocationAddressDTO } from ".."
+import { ShippingOptionPriceType, ShippingOptionTypeDTO } from "./common"
 import {
   CreateShippingOptionRuleDTO,
   UpdateShippingOptionRuleDTO,
@@ -14,3 +16,212 @@ export type RemoveFulfillmentShippingOptionRulesWorkflowDTO = {
 export type UpdateFulfillmentShippingOptionRulesWorkflowDTO = {
   data: UpdateShippingOptionRuleDTO[]
 }
+
+/**
+ * The context for retrieving the shipping options.
+ */
+export type ListShippingOptionsForCartWithPricingWorkflowInput = {
+  /**
+   * The cart's ID.
+   */
+  cart_id: string
+  /**
+   * Specify the shipping options to retrieve their details and prices.
+   * If not provided, all applicable shipping options are retrieved.
+   */
+  options?: { 
+    /**
+     * The shipping option's ID.
+     */
+    id: string; 
+    /**
+     * Custom data relevant for the fulfillment provider that processes this shipping option.
+     * It can be data relevant to calculate the shipping option's price.
+     * 
+     * Learn more in [this documentation](https://docs.medusajs.com/resources/commerce-modules/fulfillment/shipping-option#data-property).
+     */
+    data?: Record<string, unknown>
+  }[]
+  /**
+   * Whether to retrieve return shipping options.
+   * By default, non-return shipping options are retrieved.
+   * 
+   * @defaultValue false
+   */
+  is_return?: boolean
+  /**
+   * Whether to retrieve the shipping option's enabled in the store, which is the default.
+   * 
+   * @defaultValue true
+   */
+  enabled_in_store?: boolean
+}
+
+/**
+ * The retrieved shipping options with prices.
+ */
+export type ListShippingOptionsForCartWithPricingWorkflowOutput = {
+  /**
+   * The shipping option's ID.
+   */
+  id: string
+
+  /**
+   * The name of the shipping option.
+   */
+  name: string
+
+  /**
+   * The shipping option's price type.
+   */
+  price_type: ShippingOptionPriceType
+
+  /**
+   * The associated service zone's ID.
+   */
+  service_zone_id: string
+
+  /**
+   * The service zone details.
+   */
+  service_zone: {
+    /**
+     * The ID of the fulfillment set associated with the service zone.
+     */
+    fulfillment_set_id: string
+  }
+
+  /**
+   * The ID of the associated shipping profile.
+   */
+  shipping_profile_id: string
+
+  /**
+   * The ID of the associated fulfillment provider. It's used to calculate
+   * the shipping option's price, if it's price type is `calculated`, and later
+   * it processes shipments created from this shipping option.
+   */
+  provider_id: string
+
+  /**
+   * Custom additional data related to the shipping option, useful for the fulfillment provider
+   * to process the shipping option and calculate its price.
+   * 
+   * Learn more in [this documentation](https://docs.medusajs.com/resources/commerce-modules/fulfillment/shipping-option#data-property).
+   */
+  data: Record<string, unknown>
+
+  /**
+   * The shipping option's type.
+   */
+  type: Omit<ShippingOptionTypeDTO, "shipping_option_id" | "shipping_option" | "created_at" | "updated_at" | "deleted_at">
+
+  /**
+   * The associated fulfillment provider details.
+   */
+  provider: {
+    /**
+     * The ID of the provider.
+     */
+    id: string
+
+    /**
+     * Whether the provider is enabled.
+     */
+    is_enabled: boolean
+  }
+
+  /**
+   * The shipping option rules associated with the shipping option.
+   */
+  rules: {
+    /**
+     * The name of a property or table that the rule applies to.
+     * 
+     * @example 
+     * customer_group
+     */
+    attribute: string
+
+    /**
+     * The value of the rule.
+     */
+    value: string
+
+    /**
+     * The operator of the rule.
+     * 
+     * @example 
+     * in
+     */
+    operator: string
+  }[]
+
+  /**
+   * The amount for the shipping option, which can be flat rate or calculated.
+   */
+  amount: number | undefined
+
+  /**
+   * Indicates whether taxes are included in the shipping option amount.
+   */
+  is_tax_inclusive: boolean | undefined
+
+  /**
+   * The calculated price for the shipping option, if its `price_type` is `calculated`.
+   */
+  calculated_price?: CalculatedShippingOptionPrice
+
+  /**
+   * The details of the associated stock location, which is set if the shipping option's `price_type` is `calculated`.
+   */
+  stock_location?: {
+    /**
+     * The ID of the stock location.
+     */
+    id: string
+
+    /**
+     * The name of the stock location.
+     */
+    name: string
+
+    /**
+     * The address of the stock location.
+     */
+    address: StockLocationAddressDTO
+
+    /**
+     * The ID of the fulfillment set associated with the stock location.
+     */
+    fulfillment_set_id: string
+  }
+}[]
+
+/**
+ * The context for retrieving the shipping options.
+ */
+export type ListShippingOptionsForCartWorkflowInput = {
+  /**
+   * The cart's ID.
+   */
+  cart_id: string
+  /**
+   * Specify the shipping options to retrieve their details.
+   * If not specified, all applicable shipping options are retrieved.
+   */
+  option_ids?: string[]
+  /**
+   * Whether to retrieve return shipping options.
+   * By default, non-return shipping options are retrieved.
+   * 
+   * @defaultValue false
+   */
+  is_return?: boolean
+  /**
+   * Whether to retrieve the shipping option's enabled in the store, which is the default.
+   * 
+   * @defaultValue true
+   */
+  enabled_in_store?: boolean
+}