chore(core-flows): improve TSDocs for payment workflows / steps (#10998)

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

@@ -51,7 +51,7 @@ export const addShippingMethodToCartWorkflowId = "add-shipping-method-to-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.
+ * You can use this workflow within your own customizations or custom workflows, allowing you to wrap custom logic around adding a shipping method to the cart.
  * 
  * @example
  * const { result } = await addShippingMethodToCartWorkflow(container)

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

@@ -38,7 +38,7 @@ export const addToCartWorkflowId = "add-to-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.
+ * You can use this workflow within your own customizations or custom workflows, allowing you to wrap custom logic around adding an item to the cart.
  * For example, you can use this workflow to add a line item to the cart with a custom price.
  * 
  * @example

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

@@ -60,7 +60,7 @@ export const completeCartWorkflowId = "complete-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.
+ * You can use this workflow within your own customizations or 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.
  * 

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

@@ -59,7 +59,7 @@ export const confirmVariantInventoryWorkflowId = "confirm-item-inventory"
  * 
  * :::
  * 
- * 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.
+ * You can use this workflow within your own customizations or 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):

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

@@ -61,7 +61,7 @@ export const createPaymentCollectionForCartWorkflowId =
  * 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.
+ * You can use this workflow within your own customizations or custom workflows, allowing you to wrap custom logic around adding creating a payment collection for a cart.
  *
  * @example
  * const { result } = await createPaymentCollectionForCartWorkflow(container)

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

@@ -48,7 +48,7 @@ export const listShippingOptionsForCartWithPricingWorkflowId =
  * 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 
+ * You can use this workflow within your own customizations or custom workflows, allowing you to retrieve the shipping options of a cart and their prices 
  * in your custom flows.
  * 
  * @example

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

@@ -22,7 +22,7 @@ export const listShippingOptionsForCartWorkflowId =
  * 
  * :::
  * 
- * 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  
+ * You can use this workflow within your own customizations or custom workflows, allowing you to wrap custom logic around to retrieve the shipping options of a cart  
  * in your custom flows.
  * 
  * @example

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

@@ -51,7 +51,7 @@ export const refreshCartItemsWorkflowId = "refresh-cart-items"
  * 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
+ * You can use this workflow within your own customizations or custom workflows, allowing you to refresh the cart after making updates to it in your
  * custom flows.
  * 
  * @example

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

@@ -29,7 +29,7 @@ export const refreshCartShippingMethodsWorkflowId =
  * 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.
+ * You can use this workflow within your own customizations or custom workflows, allowing you to refresh the cart's shipping method after making updates to the cart.
  * 
  * @example
  * const { result } = await refreshCartShippingMethodsWorkflow(container)

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

@@ -32,7 +32,7 @@ export const refreshPaymentCollectionForCartWorkflowId =
  * 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
+ * You can use this workflow within your own customizations or custom workflows, allowing you to refresh the cart's payment collection after making updates to it in your
  * custom flows.
  * 
  * @example

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

@@ -30,7 +30,7 @@ export const transferCartCustomerWorkflowId = "transfer-cart-customer"
  * 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.
+ * You can use this workflow within your own customizations or custom workflows, allowing you to set the cart's customer within your custom flows.
  * 
  * @example
  * const { result } = await transferCartCustomerWorkflow(container)

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

@@ -48,7 +48,7 @@ export const updateCartPromotionsWorkflowId = "update-cart-promotions"
  * 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.
+ * You can use this workflow within your own customizations or custom workflows, allowing you to update a cart's promotions within your custom flows.
  * 
  * @example
  * const { result } = await updateCartPromotionsWorkflow(container)

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

@@ -27,7 +27,7 @@ export const updateLineItemInCartWorkflowId = "update-line-item-in-cart"
  * 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.
+ * You can use this workflow within your own customizations or custom workflows, allowing you to update a line item's details in your custom flows.
  * 
  * @example
  * const { result } = await updateLineItemInCartWorkflow(container)

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

@@ -101,7 +101,7 @@ export const updateTaxLinesWorkflowId = "update-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.
+ * You can use this workflow within your own customizations or custom workflows, allowing you to update a cart's tax lines in your custom flows.
  * 
  * @example
  * const { result } = await updateTaxLinesWorkflow(container)

packages/core/core-flows/src/fulfillment/workflows/batch-shipping-option-rules.ts

@@ -44,7 +44,7 @@ export const batchShippingOptionRulesWorkflowId = "batch-shipping-option-rules"
  * This workflow manages shipping option rules allowing you to create, update, or delete them. It's used by the
  * [Manage the Rules of Shipping Option Admin API Route](https://docs.medusajs.com/api/admin#shipping-options_postshippingoptionsidrulesbatch).
  * 
- * You can use this workflow within your own custom workflows, allowing you to 
+ * You can use this workflow within your own customizations or custom workflows, allowing you to 
  * manage shipping option rules within your custom flows.
  * 
  * @example

packages/core/core-flows/src/fulfillment/workflows/calculate-shipping-options-prices.ts

@@ -22,7 +22,7 @@ export const calculateShippingOptionsPricesWorkflowId =
  * 
  * :::
  * 
- * You can use this workflow within your own custom workflows, allowing you to
+ * You can use this workflow within your own customizations or custom workflows, allowing you to
  * calculate the prices of shipping options within your custom flows.
  * 
  * @example

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

@@ -16,7 +16,7 @@ export const cancelFulfillmentWorkflowId = "cancel-fulfillment-workflow"
  * This workflow cancels a fulfillment. It's used by the
  * [Cancel Fulfillment Admin API Route](https://docs.medusajs.com/api/admin#fulfillments_postfulfillmentsidcancel).
  * 
- * You can use this workflow within your own custom workflows, allowing you to
+ * You can use this workflow within your own customizations or custom workflows, allowing you to
  * cancel a fulfillment within your custom flows.
  * 
  * @example

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

@@ -17,7 +17,7 @@ export const createFulfillmentWorkflowId = "create-fulfillment-workflow"
  * This workflow creates a fulfillment, which can be used for an order, return, exchanges, and similar concepts.
  * The workflow is used by the [Create Fulfillment Admin API Route](https://docs.medusajs.com/api/admin#fulfillments_postfulfillments).
  * 
- * You can use this workflow within your own custom workflows, allowing you to
+ * You can use this workflow within your own customizations or custom workflows, allowing you to
  * create a fulfillment within your custom flows.
  * 
  * :::note

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

@@ -18,7 +18,7 @@ export const createReturnFulfillmentWorkflowId =
  * This workflow creates a fulfillment for a return. It's used by other return-related workflows,
  * such as {@link createAndCompleteReturnOrderWorkflow}.
  * 
- * You can use this workflow within your own custom workflows, allowing you to
+ * You can use this workflow within your own customizations or custom workflows, allowing you to
  * create a fulfillment for a return within your custom flows.
  * 
  * :::note

packages/core/core-flows/src/fulfillment/workflows/create-service-zones.ts

@@ -16,7 +16,7 @@ export const createServiceZonesWorkflowId = "create-service-zones-workflow"
  * This workflow creates one or more service zones. It's used by the
  * [Add Service Zone to Fulfillment Set Admin API Route](https://docs.medusajs.com/api/admin#fulfillment-sets_postfulfillmentsetsidservicezones).
  * 
- * You can use this workflow within your own custom workflows, allowing you to
+ * You can use this workflow within your own customizations or custom workflows, allowing you to
  * create service zones within your custom flows.
  * 
  * @example

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

@@ -13,7 +13,7 @@ export const createShipmentWorkflowId = "create-shipment-workflow"
  * This workflow creates shipments for a fulfillment. It's used by the
  * [Create Shipment Admin API Route](https://docs.medusajs.com/api/admin#fulfillments_postfulfillmentsidshipment).
  * 
- * You can use this workflow within your own custom workflows, allowing you to
+ * You can use this workflow within your own customizations or custom workflows, allowing you to
  * create shipments within your custom flows.
  * 
  * @example

packages/core/core-flows/src/fulfillment/workflows/create-shipping-options.ts

@@ -25,7 +25,7 @@ export const createShippingOptionsWorkflowId =
  * This workflow creates one or more shipping options. It's used by the 
  * [Create Shipping Option Admin API Route](https://docs.medusajs.com/api/admin#shipping-options_postshippingoptions).
  * 
- * You can use this workflow within your own custom workflows, allowing you to
+ * You can use this workflow within your own customizations or custom workflows, allowing you to
  * create shipping options within your custom flows.
  * 
  * @example

packages/core/core-flows/src/fulfillment/workflows/create-shipping-profiles.ts

@@ -12,7 +12,7 @@ export const createShippingProfilesWorkflowId =
  * This workflow creates one or more shipping profiles. It's used by the
  * [Create Shipping Profile Admin API Route](https://docs.medusajs.com/api/admin#shipping-profiles_postshippingprofiles).
  * 
- * You can use this workflow within your own custom workflows, allowing you to
+ * You can use this workflow within your own customizations or custom workflows, allowing you to
  * create shipping profiles within your custom flows.
  * 
  * @example

packages/core/core-flows/src/fulfillment/workflows/delete-fulfillment-sets.ts

@@ -19,7 +19,7 @@ export const deleteFulfillmentSetsWorkflowId =
  * This workflow deletes one or more fulfillment sets. It's used by the
  * [Delete Fulfillment Sets Admin API Route](https://docs.medusajs.com/api/admin#fulfillment-sets_deletefulfillmentsetsid).
  * 
- * You can use this workflow within your own custom workflows, allowing you to
+ * You can use this workflow within your own customizations or custom workflows, allowing you to
  * delete fulfillment sets within your custom flows.
  * 
  * @example

packages/core/core-flows/src/fulfillment/workflows/delete-service-zones.ts

@@ -16,7 +16,7 @@ export const deleteServiceZonesWorkflowId = "delete-service-zones-workflow"
  * This workflow deletes one or more service zones. It's used by the
  * [Remove Service Zones from Fulfillment Set Admin API Route](https://docs.medusajs.com/api/admin#fulfillment-sets_deletefulfillmentsetsidservicezoneszone_id).
  * 
- * You can use this workflow within your own custom workflows, allowing you to
+ * You can use this workflow within your own customizations or custom workflows, allowing you to
  * delete service zones within your custom flows.
  * 
  * @example

packages/core/core-flows/src/fulfillment/workflows/delete-shipping-options.ts

@@ -9,7 +9,7 @@ export const deleteShippingOptionsWorkflowId =
  * This workflow deletes one or more shipping options. It's used by the
  * [Delete Shipping Options Admin API Route](https://docs.medusajs.com/api/admin#shipping-options_deleteshippingoptionsid).
  * 
- * You can use this workflow within your own custom workflows, allowing you to
+ * You can use this workflow within your own customizations or custom workflows, allowing you to
  * delete shipping options within your custom flows.
  * 
  * @example

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

@@ -11,7 +11,7 @@ export const updateFulfillmentWorkflowId = "update-fulfillment-workflow"
  * This workflow updates a fulfillment. It's used by other workflows that update a 
  * fulfillment, such as {@link markFulfillmentAsDeliveredWorkflow}.
  * 
- * You can use this workflow within your own custom workflows, allowing you to
+ * You can use this workflow within your own customizations or custom workflows, allowing you to
  * update a fulfillment within your custom flows.
  * 
  * @example

packages/core/core-flows/src/fulfillment/workflows/update-service-zones.ts

@@ -16,7 +16,7 @@ export const updateServiceZonesWorkflowId = "update-service-zones-workflow"
  * This workflow updates one or more service zones. It's used by the
  * [Update Service Zones Admin API Route](https://docs.medusajs.com/api/admin#fulfillment-sets_postfulfillmentsetsidservicezoneszone_id).
  * 
- * You can use this workflow within your own custom workflows, allowing you to
+ * You can use this workflow within your own customizations or custom workflows, allowing you to
  * update service zones within your custom flows.
  * 
  * @example

packages/core/core-flows/src/fulfillment/workflows/update-shipping-options.ts

@@ -25,7 +25,7 @@ export const updateShippingOptionsWorkflowId =
  * This workflow updates one or more shipping options. It's used by the
  * [Update Shipping Options Admin API Route](https://docs.medusajs.com/api/admin#shipping-options_postshippingoptionsid).
  * 
- * You can use this workflow within your own custom workflows, allowing you to
+ * You can use this workflow within your own customizations or custom workflows, allowing you to
  * update shipping options within your custom flows.
  * 
  * @example

packages/core/core-flows/src/fulfillment/workflows/update-shipping-profiles.ts

@@ -17,7 +17,7 @@ export const updateShippingProfilesWorkflowId =
  * This workflow updates one or more shipping profiles. It's used by the
  * [Update Shipping Profiles Admin API Route](https://docs.medusajs.com/api/admin#shipping-profiles_postshippingprofilesid).
  * 
- * You can use this workflow within your own custom workflows, allowing you to
+ * You can use this workflow within your own customizations or custom workflows, allowing you to
  * update shipping profiles within your custom flows.
  * 
  * @example

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

@@ -6,18 +6,43 @@ import {
 import { Modules } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The data to create a payment session.
+ */
 export interface CreatePaymentSessionStepInput {
+  /**
+   * The ID of the payment collection that the session belongs to.
+   */
   payment_collection_id: string
+  /**
+   * The ID of the payment provider that the payment session is associated with.
+   */
   provider_id: string
+  /**
+   * The payment session's amount.
+   */
   amount: BigNumberInput
+  /**
+   * The currency code of the payment session.
+   * 
+   * @example
+   * usd
+   */
   currency_code: string
+  /**
+   * Additional context that's useful for the payment provider to process the payment session.
+   */
   context?: PaymentProviderContext
+  /**
+   * Custom data relevant for the payment provider to process the payment session.
+   * Learn more in [this documentation](https://docs.medusajs.com/resources/commerce-modules/payment/payment-session#data-property).
+   */
   data?: Record<string, unknown>
 }
 
 export const createPaymentSessionStepId = "create-payment-session"
 /**
- * This step creates a payment session.
+ * This step creates a payment session. 
  */
 export const createPaymentSessionStep = createStep(
   createPaymentSessionStepId,

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

@@ -5,13 +5,18 @@ import {
 import { Modules } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The refund reasons to create.
+ */
+export type CreateRefundReasonStepInput = CreateRefundReasonDTO[]
+
 export const createRefundReasonStepId = "create-refund-reason"
 /**
  * This step creates one or more refund reasons.
  */
 export const createRefundReasonStep = createStep(
   createRefundReasonStepId,
-  async (data: CreateRefundReasonDTO[], { container }) => {
+  async (data: CreateRefundReasonStepInput, { container }) => {
     const service = container.resolve<IPaymentModuleService>(Modules.PAYMENT)
 
     const refundReasons = await service.createRefundReasons(data)

packages/core/core-flows/src/payment-collection/steps/delete-payment-sessions.ts

@@ -10,7 +10,13 @@ import {
 } from "@medusajs/framework/utils"
 import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The data to delete payment sessions.
+ */
 export interface DeletePaymentSessionStepInput {
+  /**
+   * The IDs of the payment sessions to delete.
+   */
   ids: string[]
 }
 
@@ -19,7 +25,7 @@ export const deletePaymentSessionsStepId = "delete-payment-sessions"
  * This step deletes one or more payment sessions.
  *
  * Note: This step should not be used alone as it doesn't consider a revert
- * Use deletePaymentSessionsWorkflow instead that uses this step
+ * Use {@link deletePaymentSessionsWorkflow} instead, which uses this step.
  */
 export const deletePaymentSessionsStep = createStep(
   deletePaymentSessionsStepId,

packages/core/core-flows/src/payment-collection/steps/delete-refund-reasons.ts

@@ -2,13 +2,18 @@ import { IPaymentModuleService } from "@medusajs/framework/types"
 import { Modules } from "@medusajs/framework/utils"
 import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The refund reasons to delete.
+ */
+export type DeleteRefundReasonsStepInput = string[]
+
 export const deleteRefundReasonsStepId = "delete-refund-reasons"
 /**
  * This step deletes one or more refund reasons.
  */
 export const deleteRefundReasonsStep = createStep(
   deleteRefundReasonsStepId,
-  async (ids: string[], { container }) => {
+  async (ids: DeleteRefundReasonsStepInput, { container }) => {
     const service = container.resolve<IPaymentModuleService>(Modules.PAYMENT)
 
     await service.softDeleteRefundReasons(ids)

packages/core/core-flows/src/payment-collection/steps/update-payment-collection.ts

@@ -10,14 +10,33 @@ import {
 } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The data to update a payment collection.
+ */
 export interface UpdatePaymentCollectionStepInput {
+  /**
+   * The filters to select the payment collections to update.
+   */
   selector: FilterablePaymentCollectionProps
+  /**
+   * The data to update in the selected payment collections.
+   */
   update: PaymentCollectionUpdatableFields
 }
 
 export const updatePaymentCollectionStepId = "update-payment-collection"
 /**
  * This step updates payment collections matching the specified filters.
+ * 
+ * @example
+ * const data = updatePaymentCollectionStep({
+ *   selector: {
+ *     id: "paycol_123",
+ *   },
+ *   update: {
+ *     amount: 10,
+ *   }
+ * })
  */
 export const updatePaymentCollectionStep = createStep(
   updatePaymentCollectionStepId,

packages/core/core-flows/src/payment-collection/steps/update-refund-reasons.ts

@@ -9,13 +9,18 @@ import {
 } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The refund reasons to update.
+ */
+export type UpdateRefundReasonStepInput = UpdateRefundReasonDTO[]
+
 export const updateRefundReasonStepId = "update-refund-reasons"
 /**
  * This step updates one or more refund reasons.
  */
 export const updateRefundReasonsStep = createStep(
   updateRefundReasonStepId,
-  async (data: UpdateRefundReasonDTO[], { container }) => {
+  async (data: UpdateRefundReasonStepInput, { container }) => {
     const ids = data.map((d) => d.id)
     const { selects, relations } = getSelectsAndRelationsFromObjectArray(data)
     const service = container.resolve<IPaymentModuleService>(Modules.PAYMENT)

packages/core/core-flows/src/payment-collection/steps/validate-deleted-payment-sessions.ts

@@ -1,8 +1,17 @@
 import { MedusaError } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The data to validate that the specified payment session IDs were deleted.
+ */
 export interface ValidateDeletedPaymentSessionsStepInput {
+  /**
+   * The payment session IDs that were supposed to be deleted.
+   */
   idsToDelete: string[]
+  /**
+   * The payment session IDs that were actually deleted.
+   */
   idsDeleted: string[]
 }
 
@@ -10,6 +19,13 @@ export const validateDeletedPaymentSessionsStepId =
   "validate-deleted-payment-sessions"
 /**
  * This step validates that the specified payment session IDs were deleted.
+ * If not all payment sessions were deleted, the step throws an error.
+ * 
+ * @example
+ * const data = validateDeletedPaymentSessionsStep({
+ *   idsDeleted: ["pay_123"],
+ *   idsToDelete: ["pay_123"]
+ * })
  */
 export const validateDeletedPaymentSessionsStep = createStep(
   validateDeletedPaymentSessionsStepId,

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

@@ -13,16 +13,50 @@ import { useRemoteQueryStep } from "../../common"
 import { createPaymentSessionStep } from "../steps"
 import { deletePaymentSessionsWorkflow } from "./delete-payment-sessions"
 
+/**
+ * The data to create payment sessions.
+ */
 export interface CreatePaymentSessionsWorkflowInput {
+  /**
+   * The ID of the payment collection to create payment sessions for.
+   */
   payment_collection_id: string
+  /**
+   * The ID of the payment provider that the payment sessions are associated with.
+   * This provider is used to later process the payment sessions and their payments.
+   */
   provider_id: string
+  /**
+   * Custom data relevant for the payment provider to process the payment session.
+   * Learn more in [this documentation](https://docs.medusajs.com/resources/commerce-modules/payment/payment-session#data-property).
+   */
   data?: Record<string, unknown>
+  /**
+   * Additional context that's useful for the payment provider to process the payment session.
+   */
   context?: PaymentProviderContext
 }
 
 export const createPaymentSessionsWorkflowId = "create-payment-sessions"
 /**
- * This workflow creates payment sessions.
+ * This workflow creates payment sessions. It's used by the
+ * [Initialize Payment Session Store API Route](https://docs.medusajs.com/api/store#payment-collections_postpaymentcollectionsidpaymentsessions).
+ * 
+ * You can use this workflow within your own customizations or custom workflows, allowing you
+ * to create payment sessions in your custom flows.
+ * 
+ * @example
+ * const { result } = await createPaymentSessionsWorkflow(container)
+ * .run({
+ *   input: {
+ *     payment_collection_id: "paycol_123",
+ *     provider_id: "pp_system"
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Create payment sessions.
  */
 export const createPaymentSessionsWorkflow = createWorkflow(
   createPaymentSessionsWorkflowId,

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

@@ -9,14 +9,43 @@ import {
 } from "@medusajs/framework/workflows-sdk"
 import { createRefundReasonStep } from "../steps/create-refund-reasons"
 
+/**
+ * The data to create refund reasons.
+ */
+export type CreateRefundReasonsWorkflowInput = {
+  /**
+   * The refund reasons to create.
+   */
+  data: CreateRefundReasonDTO[]
+}
+
 export const createRefundReasonsWorkflowId = "create-refund-reasons-workflow"
 /**
  * This workflow creates one or more refund reasons.
+ * 
+ * You can use this workflow within your own customizations or custom workflows, allowing you
+ * to create refund reasons in your custom flows.
+ * 
+ * @example
+ * const { result } = await createRefundReasonsWorkflow(container)
+ * .run({
+ *   input: {
+ *     data: [
+ *       {
+ *         label: "damaged",
+ *       }
+ *     ]
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Create refund reasons.
  */
 export const createRefundReasonsWorkflow = createWorkflow(
   createRefundReasonsWorkflowId,
   (
-    input: WorkflowData<{ data: CreateRefundReasonDTO[] }>
+    input: WorkflowData<CreateRefundReasonsWorkflowInput>
   ): WorkflowResponse<RefundReasonDTO[]> => {
     return new WorkflowResponse(createRefundReasonStep(input.data))
   }

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

@@ -8,13 +8,35 @@ import {
   validateDeletedPaymentSessionsStep,
 } from "../steps"
 
+/**
+ * The data to delete payment sessions.
+ */
 export interface DeletePaymentSessionsWorkflowInput {
+  /**
+   * The IDs of the payment sessions to delete.
+   */
   ids: string[]
 }
 
 export const deletePaymentSessionsWorkflowId = "delete-payment-sessions"
 /**
- * This workflow deletes one or more payment sessions.
+ * This workflow deletes one or more payment sessions. It's used by other workflows, like
+ * {@link refreshPaymentCollectionForCartWorkflow} to delete payment sessions when the cart's total changes.
+ * 
+ * You can use this workflow within your own customizations or custom workflows, allowing you
+ * to delete payment sessions in your custom flows.
+ * 
+ * @example
+ * const { result } = await deletePaymentSessionsWorkflow(container)
+ * .run({
+ *   input: {
+ *     ids: ["payses_123"]
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Delete payment sessions.
  */
 export const deletePaymentSessionsWorkflow = createWorkflow(
   deletePaymentSessionsWorkflowId,

packages/core/core-flows/src/payment-collection/workflows/update-refund-reasons.ts

@@ -9,15 +9,43 @@ import {
 } from "@medusajs/framework/workflows-sdk"
 import { updateRefundReasonsStep } from "../steps"
 
+/**
+ * The refund reasons to update.
+ */
+export type UpdateRefundReasonsWorkflowInput = UpdateRefundReasonDTO[]
+
+/**
+ * The updated refund reasons.
+ */
+export type UpdateRefundReasonsWorkflowOutput = RefundReasonDTO[]
+
 export const updateRefundReasonsWorkflowId = "update-refund-reasons"
 /**
  * This workflow updates one or more refund reasons.
+ * 
+ * You can use this workflow within your own customizations or custom workflows, allowing you
+ * to update refund reasons in your custom flows.
+ * 
+ * @example
+ * const { result } = await updateRefundReasonsWorkflow(container)
+ * .run({
+ *   input: [
+ *     {
+ *       id: "refres_123",
+ *       label: "Damaged",
+ *     }
+ *   ]
+ * })
+ * 
+ * @summary
+ * 
+ * Update refund reasons.
  */
 export const updateRefundReasonsWorkflow = createWorkflow(
   updateRefundReasonsWorkflowId,
   (
-    input: WorkflowData<UpdateRefundReasonDTO[]>
-  ): WorkflowResponse<RefundReasonDTO[]> => {
+    input: WorkflowData<UpdateRefundReasonsWorkflowInput>
+  ): WorkflowResponse<UpdateRefundReasonsWorkflowOutput> => {
     return new WorkflowResponse(updateRefundReasonsStep(input))
   }
 )

packages/core/core-flows/src/payment/steps/authorize-payment-session.ts

@@ -11,14 +11,30 @@ import {
 } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The data to authorize the payment session.
+ */
 export type AuthorizePaymentSessionStepInput = {
+  /**
+   * The ID of the payment session to authorize.
+   */
   id: string
+  /**
+   * The context to authorize the payment session with.
+   * This context is passed to the payment provider associated with the payment session.
+   */
   context: Record<string, unknown>
 }
 
 export const authorizePaymentSessionStepId = "authorize-payment-session-step"
 /**
  * This step authorizes a payment session.
+ * 
+ * @example
+ * const data = authorizePaymentSessionStep({
+ *   id: "payses_123",
+ *   context: {}
+ * })
  */
 export const authorizePaymentSessionStep = createStep(
   authorizePaymentSessionStepId,

packages/core/core-flows/src/payment/steps/cancel-payment.ts

@@ -6,7 +6,13 @@ import {
 } from "@medusajs/framework/utils"
 import { createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The data to cancel one or more payments.
+ */
 export type CancelPaymentStepInput = {
+  /**
+   * The ID(s) of the payment(s) to cancel.
+   */
   paymentIds: string | string[]
 }
 

packages/core/core-flows/src/payment/steps/capture-payment.ts

@@ -5,9 +5,21 @@ import {
 import { Modules } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The data to capture a payment.
+ */
 export type CapturePaymentStepInput = {
+  /**
+   * The ID of the payment to capture.
+   */
   payment_id: string
+  /**
+   * The ID of the user that captured the payment.
+   */
   captured_by?: string
+  /**
+   * The amount to capture. If not provided, the full payment amount will be captured.
+   */
   amount?: BigNumberInput
 }
 

packages/core/core-flows/src/payment/steps/refund-payment.ts

@@ -5,9 +5,21 @@ import {
 import { Modules } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The data to refund a payment.
+ */
 export type RefundPaymentStepInput = {
+  /**
+   * The ID of the payment to refund.
+   */
   payment_id: string
+  /**
+   * The ID of the user that refunded the payment.
+   */
   created_by?: string
+  /**
+   * The amount to refund. If not provided, the full refundable amount is refunded.
+   */
   amount?: BigNumberInput
 }
 

packages/core/core-flows/src/payment/steps/refund-payments.ts

@@ -12,6 +12,24 @@ import {
 } from "@medusajs/framework/utils"
 import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The data to refund one or more payments.
+ */
+export type RefundPaymentsStepInput = {
+  /**
+   * The ID of the payment to refund.
+   */
+  payment_id: string
+  /**
+   * The amount to refund. 
+   */
+  amount: BigNumberInput
+  /**
+   * The ID of the user that refunded the payment.
+   */
+  created_by?: string
+}[]
+
 export const refundPaymentsStepId = "refund-payments-step"
 /**
  * This step refunds one or more payments.
@@ -19,11 +37,7 @@ export const refundPaymentsStepId = "refund-payments-step"
 export const refundPaymentsStep = createStep(
   refundPaymentsStepId,
   async (
-    input: {
-      payment_id: string
-      amount: BigNumberInput
-      created_by?: string
-    }[],
+    input: RefundPaymentsStepInput,
     { container }
   ) => {
     const logger = container.resolve<Logger>(ContainerRegistrationKeys.LOGGER)

packages/core/core-flows/src/payment/workflows/capture-payment.ts

@@ -11,18 +11,48 @@ import { emitEventStep, useRemoteQueryStep } from "../../common"
 import { addOrderTransactionStep } from "../../order/steps/add-order-transaction"
 import { capturePaymentStep } from "../steps/capture-payment"
 
+/**
+ * The data to capture a payment.
+ */
+export type CapturePaymentWorkflowInput = {
+  /**
+   * The ID of the payment to capture.
+   */
+  payment_id: string
+  /**
+   * The ID of the user that captured the payment.
+   */
+  captured_by?: string
+  /**
+   * The amount to capture. If not provided, the full payment amount will be captured.
+   */
+  amount?: BigNumberInput
+}
+
 export const capturePaymentWorkflowId = "capture-payment-workflow"
 /**
- * This workflow captures a payment.
+ * This workflow captures a payment. It's used by the 
+ * [Capture Payment Admin API Route](https://docs.medusajs.com/api/admin#payments_postpaymentsidcapture).
+ * 
+ * You can use this workflow within your own customizations or custom workflows, allowing you
+ * to capture a payment in your custom flows.
+ * 
+ * @example
+ * const { result } = await capturePaymentWorkflow(container)
+ * .run({
+ *   input: {
+ *     payment_id: "pay_123"
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Capture a payment.
  */
 export const capturePaymentWorkflow = createWorkflow(
   capturePaymentWorkflowId,
   (
-    input: WorkflowData<{
-      payment_id: string
-      captured_by?: string
-      amount?: BigNumberInput
-    }>
+    input: WorkflowData<CapturePaymentWorkflowInput>
   ): WorkflowResponse<PaymentDTO> => {
     const payment = capturePaymentStep(input)
 

packages/core/core-flows/src/payment/workflows/process-payment.ts

@@ -6,9 +6,36 @@ import { useQueryGraphStep } from "../../common"
 import { authorizePaymentSessionStep } from "../steps"
 import { capturePaymentWorkflow } from "./capture-payment"
 
+/**
+ * The data to process a payment from a webhook action.
+ */
 interface ProcessPaymentWorkflowInput extends WebhookActionResult {}
 
 export const processPaymentWorkflowId = "process-payment-workflow"
+/**
+ * This workflow processes a payment to either complete its associated cart,
+ * capture the payment, or authorize the payment session. It's used when a
+ * [Webhook Event is received](https://docs.medusajs.com/resources/commerce-modules/payment/webhook-events).
+ * 
+ * You can use this workflow within your own customizations or custom workflows, allowing you
+ * to process a payment in your custom flows based on a webhook action.
+ * 
+ * @example
+ * const { result } = await processPaymentWorkflow(container)
+ * .run({
+ *   input: {
+ *     action: "captured",
+ *     data: {
+ *       session_id: "payses_123",
+ *       amount: 10
+ *     }
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Process a payment based on a webhook event.
+ */
 export const processPaymentWorkflow = createWorkflow(
   processPaymentWorkflowId,
   (input: ProcessPaymentWorkflowInput) => {

packages/core/core-flows/src/payment/workflows/refund-payment.ts

@@ -13,7 +13,46 @@ import { addOrderTransactionStep } from "../../order/steps/add-order-transaction
 import { refundPaymentStep } from "../steps/refund-payment"
 
 /**
- * This step validates that the refund is valid for the order
+ * The data to validate whether the refund is valid for the order.
+ */
+export type ValidateRefundStepInput = {
+  /**
+   * The order's details.
+   */
+  order: OrderDTO
+  /**
+   * The order's payment details.
+   */
+  payment: PaymentDTO
+  /**
+   * The amound to refund.
+   */
+  amount?: BigNumberInput
+}
+
+/**
+ * This step validates that the refund is valid for the order.
+ * If the order does not have an outstanding balance to refund, the step throws an error.
+ * 
+ * :::note
+ * 
+ * You can retrieve an order or payment'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 = validateRefundStep({
+ *   order: {
+ *     id: "order_123",
+ *     // other order details...
+ *   },
+ *   payment: {
+ *     id: "payment_123",
+ *     // other payment details...
+ *   },
+ *   amount: 10
+ * })
  */
 export const validateRefundStep = createStep(
   "validate-refund-step",
@@ -21,11 +60,7 @@ export const validateRefundStep = createStep(
     order,
     payment,
     amount,
-  }: {
-    order: OrderDTO
-    payment: PaymentDTO
-    amount?: BigNumberInput
-  }) {
+  }: ValidateRefundStepInput) {
     const pendingDifference = order.summary?.raw_pending_difference!
 
     if (MathBN.gte(pendingDifference, 0)) {
@@ -47,18 +82,48 @@ export const validateRefundStep = createStep(
   }
 )
 
+/**
+ * The data to refund a payment.
+ */
+export type RefundPaymentWorkflowInput = {
+  /**
+   * The ID of the payment to refund.
+   */
+  payment_id: string
+  /**
+   * The ID of the user that refunded the payment.
+   */
+  created_by?: string
+  /**
+   * The amount to refund. If not provided, the full payment amount will be refunded.
+   */
+  amount?: BigNumberInput
+}
+
 export const refundPaymentWorkflowId = "refund-payment-workflow"
 /**
- * This workflow refunds a payment.
+ * This workflow refunds a payment. It's used by the 
+ * [Refund Payment Admin API Route](https://docs.medusajs.com/api/admin#payments_postpaymentsidrefund).
+ * 
+ * You can use this workflow within your own customizations or custom workflows, allowing you
+ * to refund a payment in your custom flows.
+ * 
+ * @example
+ * const { result } = await refundPaymentWorkflow(container)
+ * .run({
+ *   input: {
+ *     payment_id: "payment_123",
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Refund a payment.
  */
 export const refundPaymentWorkflow = createWorkflow(
   refundPaymentWorkflowId,
   (
-    input: WorkflowData<{
-      payment_id: string
-      created_by?: string
-      amount?: BigNumberInput
-    }>
+    input: WorkflowData<RefundPaymentWorkflowInput>
   ) => {
     const payment = useRemoteQueryStep({
       entry_point: "payment",

packages/core/core-flows/src/payment/workflows/refund-payments.ts

@@ -11,24 +11,52 @@ import { useQueryGraphStep } from "../../common"
 import { addOrderTransactionStep } from "../../order"
 import { refundPaymentsStep } from "../steps/refund-payments"
 
-type RefundPaymentsInput = {
-  payment_id: string
-  amount: BigNumberInput
-  created_by?: string
+/**
+ * The data to validate whether the refund is valid for the payment.
+ */
+export type ValidatePaymentsRefundStepInput = {
+  /**
+   * The payment details.
+   */
+  payments: PaymentDTO[]
+  /**
+   * The payments to refund.
+   */
+  input: RefundPaymentsWorkflowInput
 }
 
 /**
- * This step validates that the refund is valid for the payment
+ * This step validates that the refund is valid for the payment.
+ * If the payment's refundable amount is less than the amount to be refunded,
+ * the step throws an error.
+ * 
+ * :::note
+ * 
+ * You can retrieve a payment'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 = validatePaymentsRefundStep({
+ *   payment: [{
+ *     id: "payment_123",
+ *     // other payment details...
+ *   }],
+ *   input: [
+ *     {
+ *       payment_id: "payment_123",
+ *       amount: 10,
+ *     }
+ *   ]
+ * })
  */
 export const validatePaymentsRefundStep = createStep(
   "validate-payments-refund-step",
   async function ({
     payments,
     input,
-  }: {
-    payments: PaymentDTO[]
-    input: RefundPaymentsInput[]
-  }) {
+  }: ValidatePaymentsRefundStepInput) {
     const paymentIdAmountMap = new Map<string, BigNumberInput>(
       input.map(({ payment_id, amount }) => [payment_id, amount])
     )
@@ -57,13 +85,31 @@ export const validatePaymentsRefundStep = createStep(
   }
 )
 
+/**
+ * The data to refund a payment.
+ */
+export type RefundPaymentsWorkflowInput = {
+  /**
+   * The ID of the payment to refund.
+   */
+  payment_id: string
+  /**
+   * The amount to refund. Must be less than the refundable amount of the payment.
+   */
+  amount: BigNumberInput
+  /**
+   * The ID of the user that's refunding the payment.
+   */
+  created_by?: string
+}[]
+
 export const refundPaymentsWorkflowId = "refund-payments-workflow"
 /**
  * This workflow refunds a payment.
  */
 export const refundPaymentsWorkflow = createWorkflow(
   refundPaymentsWorkflowId,
-  (input: WorkflowData<RefundPaymentsInput[]>) => {
+  (input: WorkflowData<RefundPaymentsWorkflowInput>) => {
     const paymentIds = transform({ input }, ({ input }) =>
       input.map((paymentInput) => paymentInput.payment_id)
     )

packages/core/core-flows/src/product/workflows/batch-link-products-collection.ts

@@ -9,7 +9,7 @@ export const batchLinkProductsToCollectionWorkflowId =
  * This workflow manages the links between a collection and products. It's used by the
  * [Manage Products of Collection Admin API Route](https://docs.medusajs.com/api/admin#collections_postcollectionsidproducts).
  * 
- * You can use this workflow within your own custom workflows to manage the products in a collection.
+ * You can use this workflow within your own customizations or custom workflows to manage the products in a collection.
  * 
  * @example
  * const { result } = await batchLinkProductsToCollectionWorkflow(container)

packages/core/core-flows/src/product/workflows/batch-product-variants.ts

@@ -34,7 +34,7 @@ export const batchProductVariantsWorkflowId = "batch-product-variants"
  * This workflow creates, updates, and deletes product variants. It's used by the 
  * [Manage Variants in a Product Admin API Route](https://docs.medusajs.com/api/admin#products_postproductsidvariantsbatch).
  * 
- * You can use this workflow within your own custom workflows to manage the variants of a product. You can also
+ * You can use this workflow within your own customizations or custom workflows to manage the variants of a product. You can also
  * use this within a [seed script](https://docs.medusajs.com/learn/fundamentals/custom-cli-scripts/seed-data) or in a custom import script.
  * 
  * @example

packages/core/core-flows/src/product/workflows/batch-products-in-category.ts

@@ -8,7 +8,7 @@ export const batchLinkProductsToCategoryWorkflowId =
  * This workflow manages the links between a category and products. It's used by the
  * [Manage Products of Category Admin API Route](https://docs.medusajs.com/api/admin#product-categories_postproductcategoriesidproducts).
  * 
- * You can use this workflow within your own custom workflows to manage the products in a category.
+ * You can use this workflow within your own customizations or custom workflows to manage the products in a category.
  * 
  * @example
  * const { result } = await batchLinkProductsToCategoryWorkflow(container)

packages/core/core-flows/src/product/workflows/batch-products.ts

@@ -29,7 +29,7 @@ export const batchProductsWorkflowId = "batch-products"
  * This workflow creates, updates, or deletes products. It's used by the
  * [Manage Products Admin API Route](https://docs.medusajs.com/api/admin#products_postproductsbatch).
  * 
- * You can use this workflow within your own custom workflows to manage products in bulk. This is
+ * You can use this workflow within your own customizations or custom workflows to manage products in bulk. This is
  * also useful when writing a [seed script](https://docs.medusajs.com/learn/fundamentals/custom-cli-scripts/seed-data) or a custom import script.
  * 
  * @example

packages/core/core-flows/src/product/workflows/upsert-variant-prices.ts

@@ -45,7 +45,7 @@ export const upsertVariantPricesWorkflowId = "upsert-variant-prices"
  * This workflow creates, updates, or removes variants' prices. It's used by the {@link updateProductsWorkflow}
  * when updating a variant's prices.
  * 
- * You can use this workflow within your own custom workflows to manage the prices of a variant.
+ * You can use this workflow within your own customizations or custom workflows to manage the prices of a variant.
  * 
  * @example
  * const { result } = await upsertVariantPricesWorkflow(container)