feat(core-flows,payment,medusa,types): Refund reasons management API (#8436)

* feat(core-flows,payment,medusa,types): add ability to set and manage refund reasons

* fix(payment): validate total amount when refunding payment (#8437)

Co-authored-by: Carlos R. L. Rodrigues <37986729+carlos-r-l-rodrigues@users.noreply.github.com>

* feature: introduce additional_data to the product endpoints (#8405)

* chore(docs): Generated References (#8440)

Generated the following references:
- `product`

* chore: align payment database schema

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

Co-authored-by: Oli Juhl <59018053+olivermrbl@users.noreply.github.com>

* chore: address review

---------

Co-authored-by: Carlos R. L. Rodrigues <37986729+carlos-r-l-rodrigues@users.noreply.github.com>
Co-authored-by: Harminder Virk <virk.officials@gmail.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: Oli Juhl <59018053+olivermrbl@users.noreply.github.com>

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

@@ -0,0 +1,31 @@
+import { CreateRefundReasonDTO, IPaymentModuleService } from "@medusajs/types"
+import { ModuleRegistrationName } from "@medusajs/utils"
+import { StepResponse, createStep } from "@medusajs/workflows-sdk"
+
+export const createRefundReasonStepId = "create-refund-reason"
+export const createRefundReasonStep = createStep(
+  createRefundReasonStepId,
+  async (data: CreateRefundReasonDTO[], { container }) => {
+    const service = container.resolve<IPaymentModuleService>(
+      ModuleRegistrationName.PAYMENT
+    )
+
+    const refundReasons = await service.createRefundReasons(data)
+
+    return new StepResponse(
+      refundReasons,
+      refundReasons.map((rr) => rr.id)
+    )
+  },
+  async (ids, { container }) => {
+    if (!ids?.length) {
+      return
+    }
+
+    const service = container.resolve<IPaymentModuleService>(
+      ModuleRegistrationName.PAYMENT
+    )
+
+    await service.deleteRefundReasons(ids)
+  }
+)

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

@@ -0,0 +1,28 @@
+import { IPaymentModuleService } from "@medusajs/types"
+import { ModuleRegistrationName } from "@medusajs/utils"
+import { createStep, StepResponse } from "@medusajs/workflows-sdk"
+
+export const deleteRefundReasonsStepId = "delete-refund-reasons"
+export const deleteRefundReasonsStep = createStep(
+  deleteRefundReasonsStepId,
+  async (ids: string[], { container }) => {
+    const service = container.resolve<IPaymentModuleService>(
+      ModuleRegistrationName.PAYMENT
+    )
+
+    await service.softDeleteRefundReasons(ids)
+
+    return new StepResponse(void 0, ids)
+  },
+  async (prevCustomerIds, { container }) => {
+    if (!prevCustomerIds?.length) {
+      return
+    }
+
+    const service = container.resolve<IPaymentModuleService>(
+      ModuleRegistrationName.PAYMENT
+    )
+
+    await service.restoreRefundReasons(prevCustomerIds)
+  }
+)

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

@@ -1,4 +1,7 @@
 export * from "./create-payment-session"
+export * from "./create-refund-reasons"
 export * from "./delete-payment-sessions"
+export * from "./delete-refund-reasons"
 export * from "./update-payment-collection"
+export * from "./update-refund-reasons"
 export * from "./validate-deleted-payment-sessions"

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

@@ -0,0 +1,43 @@
+import { IPaymentModuleService, UpdateRefundReasonDTO } from "@medusajs/types"
+import {
+  ModuleRegistrationName,
+  getSelectsAndRelationsFromObjectArray,
+  promiseAll,
+} from "@medusajs/utils"
+import { StepResponse, createStep } from "@medusajs/workflows-sdk"
+
+export const updateRefundReasonStepId = "update-refund-reasons"
+export const updateRefundReasonsStep = createStep(
+  updateRefundReasonStepId,
+  async (data: UpdateRefundReasonDTO[], { container }) => {
+    const ids = data.map((d) => d.id)
+    const { selects, relations } = getSelectsAndRelationsFromObjectArray(data)
+    const service = container.resolve<IPaymentModuleService>(
+      ModuleRegistrationName.PAYMENT
+    )
+
+    const prevRefundReasons = await service.listRefundReasons(
+      { id: ids },
+      { select: selects, relations }
+    )
+
+    const reasons = await service.updateRefundReasons(data)
+
+    return new StepResponse(reasons, prevRefundReasons)
+  },
+  async (previousData, { container }) => {
+    if (!previousData) {
+      return
+    }
+
+    const service = container.resolve<IPaymentModuleService>(
+      ModuleRegistrationName.PAYMENT
+    )
+
+    await promiseAll(
+      previousData.map((refundReason) =>
+        service.updateRefundReasons(refundReason)
+      )
+    )
+  }
+)

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

@@ -0,0 +1,17 @@
+import { CreateRefundReasonDTO, RefundReasonDTO } from "@medusajs/types"
+import {
+  WorkflowData,
+  WorkflowResponse,
+  createWorkflow,
+} from "@medusajs/workflows-sdk"
+import { createRefundReasonStep } from "../steps/create-refund-reasons"
+
+export const createRefundReasonsWorkflowId = "create-refund-reasons-workflow"
+export const createRefundReasonsWorkflow = createWorkflow(
+  createRefundReasonsWorkflowId,
+  (
+    input: WorkflowData<{ data: CreateRefundReasonDTO[] }>
+  ): WorkflowResponse<RefundReasonDTO[]> => {
+    return new WorkflowResponse(createRefundReasonStep(input.data))
+  }
+)

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

@@ -0,0 +1,14 @@
+import {
+  WorkflowData,
+  WorkflowResponse,
+  createWorkflow,
+} from "@medusajs/workflows-sdk"
+import { deleteRefundReasonsStep } from "../steps"
+
+export const deleteRefundReasonsWorkflowId = "delete-refund-reasons-workflow"
+export const deleteRefundReasonsWorkflow = createWorkflow(
+  deleteRefundReasonsWorkflowId,
+  (input: WorkflowData<{ ids: string[] }>): WorkflowResponse<void> => {
+    return new WorkflowResponse(deleteRefundReasonsStep(input.ids))
+  }
+)

packages/core/core-flows/src/payment-collection/workflows/index.ts

@@ -1 +1,3 @@
 export * from "./create-payment-session"
+export * from "./create-refund-reasons"
+export * from "./update-refund-reasons"

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

@@ -0,0 +1,17 @@
+import { RefundReasonDTO, UpdateRefundReasonDTO } from "@medusajs/types"
+import {
+  WorkflowData,
+  WorkflowResponse,
+  createWorkflow,
+} from "@medusajs/workflows-sdk"
+import { updateRefundReasonsStep } from "../steps"
+
+export const updateRefundReasonsWorkflowId = "update-refund-reasons"
+export const updateRefundReasonsWorkflow = createWorkflow(
+  updateRefundReasonsWorkflowId,
+  (
+    input: WorkflowData<UpdateRefundReasonDTO[]>
+  ): WorkflowResponse<RefundReasonDTO[]> => {
+    return new WorkflowResponse(updateRefundReasonsStep(input))
+  }
+)

packages/core/types/src/http/payment/admin.ts

@@ -1,3 +1,4 @@
+import { BaseFilterable } from "../../dal"
 import {
   BasePayment,
   BasePaymentCollection,
@@ -7,6 +8,7 @@ import {
   BasePaymentProviderFilters,
   BasePaymentSession,
   BasePaymentSessionFilters,
+  RefundReason,
 } from "./common"
 
 export interface AdminPaymentProvider extends BasePaymentProvider {
@@ -42,3 +44,23 @@ export interface AdminPaymentsResponse {
 }
 
 export interface AdminPaymentFilters extends BasePaymentFilters {}
+
+// Refund reason
+
+export interface AdminRefundReason extends RefundReason {}
+export interface RefundReasonFilters extends BaseFilterable<AdminRefundReason> {
+  id?: string | string[]
+}
+
+export interface RefundReasonResponse {
+  refund_reason: AdminRefundReason
+}
+
+export interface RefundReasonsResponse {
+  refund_reasons: AdminRefundReason[]
+}
+
+export interface AdminCreateRefundReason {
+  label: string
+  description?: string
+}

packages/core/types/src/http/payment/common.ts

@@ -262,6 +262,21 @@ export interface BaseRefund {
    */
   amount: BigNumberValue
 
+  /**
+   * The id of the refund_reason that is associated with the refund
+   */
+  refund_reason_id?: string | null
+
+  /**
+   * The id of the refund_reason that is associated with the refund
+   */
+  refund_reason?: RefundReason | null
+
+  /**
+   * A field to add some additional information about the refund
+   */
+  note?: string | null
+
   /**
    * The creation date of the refund.
    */
@@ -338,6 +353,33 @@ export interface BasePaymentSession {
   payment?: BasePayment
 }
 
+export interface RefundReason {
+  /**
+   * The ID of the refund reason
+   */
+  id: string
+  /**
+   * The label of the refund reason
+   */
+  label: string
+  /**
+   * The description of the refund reason
+   */
+  description?: string | null
+  /**
+   * The metadata of the refund reason
+   */
+  metadata: Record<string, unknown> | null
+  /**
+   * When the refund reason was created
+   */
+  created_at: Date | string
+  /**
+   * When the refund reason was updated
+   */
+  updated_at: Date | string
+}
+
 /**
  * The filters to apply on the retrieved payment collection.
  */

packages/core/types/src/payment/common.ts

@@ -477,6 +477,21 @@ export interface RefundDTO {
    */
   amount: BigNumberValue
 
+  /**
+   * The id of the refund_reason that is associated with the refund
+   */
+  refund_reason_id?: string | null
+
+  /**
+   * The id of the refund_reason that is associated with the refund
+   */
+  refund_reason?: RefundReasonDTO | null
+
+  /**
+   * A field to add some additional information about the refund
+   */
+  note?: string | null
+
   /**
    * The creation date of the refund.
    */
@@ -583,3 +598,38 @@ export interface FilterablePaymentProviderProps
    */
   is_enabled?: boolean
 }
+
+export interface FilterableRefundReasonProps
+  extends BaseFilterable<FilterableRefundReasonProps> {
+  /**
+   * The IDs to filter the refund reasons by.
+   */
+  id?: string | string[]
+}
+
+export interface RefundReasonDTO {
+  /**
+   * The ID of the refund reason
+   */
+  id: string
+  /**
+   * The label of the refund reason
+   */
+  label: string
+  /**
+   * The description of the refund reason
+   */
+  description?: string | null
+  /**
+   * The metadata of the refund reason
+   */
+  metadata: Record<string, unknown> | null
+  /**
+   * When the refund reason was created
+   */
+  created_at: Date | string
+  /**
+   * When the refund reason was updated
+   */
+  updated_at: Date | string
+}

packages/core/types/src/payment/mutations.ts

@@ -212,6 +212,16 @@ export interface CreateRefundDTO {
    */
   payment_id: string
 
+  /**
+   * The associated refund reason's ID.
+   */
+  refund_reason_id?: string | null
+
+  /**
+   * A text field that adds some information about the refund
+   */
+  note?: string
+
   /**
    * Who refunded the payment. For example,
    * a user's ID.
@@ -323,3 +333,37 @@ export interface ProviderWebhookPayload {
     headers: Record<string, unknown>
   }
 }
+
+export interface CreateRefundReasonDTO {
+  /**
+   * The label of the refund reason
+   */
+  label: string
+  /**
+   * The description of the refund reason
+   */
+  description?: string | null
+  /**
+   * The metadata of the refund reason
+   */
+  metadata?: Record<string, unknown> | null
+}
+
+export interface UpdateRefundReasonDTO {
+  /**
+   * The id of the refund reason
+   */
+  id: string
+  /**
+   * The label of the refund reason
+   */
+  label?: string
+  /**
+   * The description of the refund reason
+   */
+  description?: string | null
+  /**
+   * The metadata of the refund reason
+   */
+  metadata?: Record<string, unknown> | null
+}

packages/core/types/src/payment/service.ts

@@ -1,4 +1,5 @@
 import { FindConfig } from "../common"
+import { RestoreReturn, SoftDeleteReturn } from "../dal"
 import { IModuleService } from "../modules-sdk"
 import { Context } from "../shared-context"
 import {
@@ -9,21 +10,25 @@ import {
   FilterablePaymentProviderProps,
   FilterablePaymentSessionProps,
   FilterableRefundProps,
+  FilterableRefundReasonProps,
   PaymentCollectionDTO,
   PaymentDTO,
   PaymentProviderDTO,
   PaymentSessionDTO,
   RefundDTO,
+  RefundReasonDTO,
 } from "./common"
 import {
   CreateCaptureDTO,
   CreatePaymentCollectionDTO,
   CreatePaymentSessionDTO,
   CreateRefundDTO,
+  CreateRefundReasonDTO,
   PaymentCollectionUpdatableFields,
   ProviderWebhookPayload,
   UpdatePaymentDTO,
   UpdatePaymentSessionDTO,
+  UpdateRefundReasonDTO,
   UpsertPaymentCollectionDTO,
 } from "./mutations"
 
@@ -817,6 +822,199 @@ export interface IPaymentModuleService extends IModuleService {
     sharedContext?: Context
   ): Promise<RefundDTO[]>
 
+  /**
+   * This method creates refund reasons.
+   *
+   * @param {CreateRefundReasonDTO[]} data - The refund reasons to create.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<RefundReasonDTO[]>} The created refund reasons.
+   *
+   * @example
+   * const refundReasons =
+   *   await paymentModuleService.createRefundReasons([
+   *     {
+   *       label: "Too big",
+   *     },
+   *     {
+   *       label: "Too big",
+   *     },
+   *   ])
+   */
+  createRefundReasons(
+    data: CreateRefundReasonDTO[],
+    sharedContext?: Context
+  ): Promise<RefundReasonDTO[]>
+
+  /**
+   * This method creates a refund reason.
+   *
+   * @param {CreateRefundReasonDTO} data - The refund reason to create.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<RefundReasonDTO>} The created refund reason.
+   *
+   * @example
+   * const refundReason =
+   *   await paymentModuleService.createRefundReasons({
+   *     label: "Too big",
+   *   })
+   */
+  createRefundReasons(
+    data: CreateRefundReasonDTO,
+    sharedContext?: Context
+  ): Promise<RefundReasonDTO>
+
+  /**
+   * This method deletes a refund reason by its ID.
+   *
+   * @param {string[]} refundReasonId - The refund reason's ID.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<void>} Resolves when the refund reason is deleted successfully.
+   *
+   * @example
+   * await paymentModuleService.deleteRefundReasons([
+   *   "refr_123",
+   *   "refr_321",
+   * ])
+   */
+  deleteRefundReasons(
+    refundReasonId: string[],
+    sharedContext?: Context
+  ): Promise<void>
+
+  /**
+   * This method deletes a refund reason by its ID.
+   *
+   * @param {string} refundReasonId - The refund reason's ID.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<void>} Resolves when the refund reason is deleted successfully.
+   *
+   * @example
+   * await paymentModuleService.deleteRefundReasons(
+   *   "refr_123"
+   * )
+   */
+  deleteRefundReasons(
+    refundReasonId: string,
+    sharedContext?: Context
+  ): Promise<void>
+
+  /**
+   * This method soft deletes refund reasons by their IDs.
+   *
+   * @param {string[]} refundReasonId - The IDs of refund reasons.
+   * @param {SoftDeleteReturn<TReturnableLinkableKeys>} config - An object that is used to specify an entity's related entities that should be soft-deleted when the main entity is soft-deleted.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<void | Record<TReturnableLinkableKeys, string[]>>} An object that includes the IDs of related records that were also soft deleted.
+   * If there are no related records, the promise resolves to `void`.
+   *
+   * @example
+   * await paymentModule.softDeleteRefundReasons(["cus_123"])
+   */
+  softDeleteRefundReasons<TReturnableLinkableKeys extends string = string>(
+    refundReasonId: string[],
+    config?: SoftDeleteReturn<TReturnableLinkableKeys>,
+    sharedContext?: Context
+  ): Promise<Record<TReturnableLinkableKeys, string[]> | void>
+
+  /**
+   * This method restores soft deleted refund reason by their IDs.
+   *
+   * @param {string[]} refundReasonId - The IDs of refund reasons.
+   * @param {RestoreReturn<TReturnableLinkableKeys>} config - Configurations determining which relations to restore along with each of the refund reason. You can pass to its `returnLinkableKeys`
+   * property any of the refund reason's relation attribute names.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<void | Record<TReturnableLinkableKeys, string[]>>} An object that includes the IDs of related records that were restored.
+   * If there are no related records restored, the promise resolves to `void`.
+   *
+   * @example
+   * await paymentModule.restoreRefundReasons(["cus_123"])
+   */
+  restoreRefundReasons<TReturnableLinkableKeys extends string = string>(
+    refundReasonId: string[],
+    config?: RestoreReturn<TReturnableLinkableKeys>,
+    sharedContext?: Context
+  ): Promise<Record<TReturnableLinkableKeys, string[]> | void>
+
+  /**
+   * This method updates an existing refund reason.
+   *
+   * @param {UpdateRefundReasonDTO} data - The attributes to update in the refund reason.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<RefundReasonDTO>} The updated refund reason.
+   *
+   * @example
+   * const refundReason =
+   *   await paymentModuleService.updateRefundReasons(
+   *     [{
+   *       id: "refr_test1",
+   *       amount: 3000,
+   *     }]
+   *   )
+   */
+  updateRefundReasons(
+    data: UpdateRefundReasonDTO[],
+    sharedContext?: Context
+  ): Promise<RefundReasonDTO[]>
+
+  updateRefundReasons(
+    data: UpdateRefundReasonDTO,
+    sharedContext?: Context
+  ): Promise<RefundReasonDTO>
+
+  /**
+   * This method retrieves a paginated list of refund reasons based on optional filters and configuration.
+   *
+   * @param {FilterableRefundReasonProps} filters - The filters to apply on the retrieved refund reason.
+   * @param {FindConfig<RefundReasonDTO>} config - The configurations determining how the refund reason is retrieved. Its properties, such as `select` or `relations`, accept the
+   * attributes or relations associated with a refund reason.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<RefundReasonDTO[]>} The list of refund reasons.
+   *
+   * @example
+   * To retrieve a list of refund reasons using their IDs:
+   *
+   * ```ts
+   * const refundReasons =
+   *   await paymentModuleService.listRefundReasons({
+   *     id: ["refr_123", "refr_321"],
+   *   })
+   * ```
+   *
+   * To specify relations that should be retrieved within the refund :
+   *
+   * ```ts
+   * const refundReasons =
+   *   await paymentModuleService.listRefundReasons(
+   *     {
+   *       id: ["refr_123", "refr_321"],
+   *     },
+   *     {}
+   *   )
+   * ```
+   *
+   * By default, only the first `15` records are retrieved. You can control pagination by specifying the `skip` and `take` properties of the `config` parameter:
+   *
+   * ```ts
+   * const refundReasons =
+   *   await paymentModuleService.listRefundReasons(
+   *     {
+   *       id: ["refr_123", "refr_321"],
+   *     },
+   *     {
+   *       take: 20,
+   *       skip: 2,
+   *     }
+   *   )
+   * ```
+   *
+   *
+   */
+  listRefundReasons(
+    filters?: FilterableRefundReasonProps,
+    config?: FindConfig<RefundReasonDTO>,
+    sharedContext?: Context
+  ): Promise<RefundReasonDTO[]>
+
   /* ********** HOOKS ********** */
 
   /**