From 5e827ec95d0f721e62c0d4e8c603bda7ddc0929c Mon Sep 17 00:00:00 2001
From: William Bouchard <46496014+willbouch@users.noreply.github.com>
Date: Tue, 23 Sep 2025 11:51:40 -0400
Subject: [PATCH] feat(admin-shared,dashboard,js-sdk,types): refund reasons in
 dashboard (#13575)

CLOSES CORE-1209

This PR just adds the stuff necessary to support refund reasons in the dashboard. It adds the option in the settings tab and allows viewing, creating, editing and deleting refund reasons. I hate to open such a big PR but most of it is copy pasted from the return reasons. Major difference is only the fact that refund reasons don't have a `value` field
---
 .changeset/quick-rice-deny.md                 |   9 +
 .../src/extensions/widgets/constants.ts       |   6 +
 .../settings-layout/settings-layout.tsx       |   4 +
 .../dashboard-app/routes/get-route.map.tsx    |  36 +++
 .../src/hooks/api/refund-reasons.tsx          | 119 ++++++++-
 .../src/hooks/table/columns/index.ts          |   1 +
 .../use-refund-reason-table-columns.tsx       |  32 +++
 .../dashboard/src/hooks/table/query/index.ts  |   1 +
 .../query/use-refund-reason-table-query.tsx   |  32 +++
 .../src/i18n/translations/$schema.json        | 252 +++++++++++++-----
 .../dashboard/src/i18n/translations/en.json   |  32 +++
 .../refund-reason-create-form/index.ts        |   1 +
 .../refund-reason-create-form.tsx             | 131 +++++++++
 .../refund-reason-create/index.ts             |   1 +
 .../refund-reason-create.tsx                  |  10 +
 .../refund-reason-edit-form/index.ts          |   1 +
 .../refund-reason-edit-form.tsx               | 119 +++++++++
 .../refund-reason-edit/index.ts               |   1 +
 .../refund-reason-edit/refund-reason-edit.tsx |  33 +++
 .../refund-reason-list-table/index.ts         |   1 +
 .../refund-reason-list-table.tsx              | 130 +++++++++
 .../refund-reason-list/index.ts               |   2 +
 .../refund-reason-list/loader.ts              |  16 ++
 .../refund-reason-list/refund-reason-list.tsx |  21 ++
 .../core/js-sdk/src/admin/refund-reasons.ts   | 179 ++++++++++++-
 packages/core/types/src/http/index.ts         |   1 +
 .../types/src/http/payment/admin/entities.ts  |   2 -
 .../types/src/http/payment/admin/payloads.ts  |   5 -
 .../types/src/http/payment/admin/queries.ts   |   2 +-
 .../types/src/http/payment/admin/responses.ts |   4 +-
 .../core/types/src/http/payment/common.ts     |  30 +--
 .../src/http/refund-reason/admin/entities.ts  |   3 +
 .../src/http/refund-reason/admin/index.ts     |   4 +
 .../src/http/refund-reason/admin/payloads.ts  |  21 ++
 .../src/http/refund-reason/admin/queries.ts   |  14 +
 .../src/http/refund-reason/admin/responses.ts |  20 ++
 .../types/src/http/refund-reason/common.ts    |  42 +++
 .../types/src/http/refund-reason/index.ts     |   1 +
 .../payment/src/models/refund-reason.ts       |   2 +-
 39 files changed, 1190 insertions(+), 131 deletions(-)
 create mode 100644 .changeset/quick-rice-deny.md
 create mode 100644 packages/admin/dashboard/src/hooks/table/columns/use-refund-reason-table-columns.tsx
 create mode 100644 packages/admin/dashboard/src/hooks/table/query/use-refund-reason-table-query.tsx
 create mode 100644 packages/admin/dashboard/src/routes/refund-reasons/refund-reason-create/components/refund-reason-create-form/index.ts
 create mode 100644 packages/admin/dashboard/src/routes/refund-reasons/refund-reason-create/components/refund-reason-create-form/refund-reason-create-form.tsx
 create mode 100644 packages/admin/dashboard/src/routes/refund-reasons/refund-reason-create/index.ts
 create mode 100644 packages/admin/dashboard/src/routes/refund-reasons/refund-reason-create/refund-reason-create.tsx
 create mode 100644 packages/admin/dashboard/src/routes/refund-reasons/refund-reason-edit/components/refund-reason-edit-form/index.ts
 create mode 100644 packages/admin/dashboard/src/routes/refund-reasons/refund-reason-edit/components/refund-reason-edit-form/refund-reason-edit-form.tsx
 create mode 100644 packages/admin/dashboard/src/routes/refund-reasons/refund-reason-edit/index.ts
 create mode 100644 packages/admin/dashboard/src/routes/refund-reasons/refund-reason-edit/refund-reason-edit.tsx
 create mode 100644 packages/admin/dashboard/src/routes/refund-reasons/refund-reason-list/components/refund-reason-list-table/index.ts
 create mode 100644 packages/admin/dashboard/src/routes/refund-reasons/refund-reason-list/components/refund-reason-list-table/refund-reason-list-table.tsx
 create mode 100644 packages/admin/dashboard/src/routes/refund-reasons/refund-reason-list/index.ts
 create mode 100644 packages/admin/dashboard/src/routes/refund-reasons/refund-reason-list/loader.ts
 create mode 100644 packages/admin/dashboard/src/routes/refund-reasons/refund-reason-list/refund-reason-list.tsx
 create mode 100644 packages/core/types/src/http/refund-reason/admin/entities.ts
 create mode 100644 packages/core/types/src/http/refund-reason/admin/index.ts
 create mode 100644 packages/core/types/src/http/refund-reason/admin/payloads.ts
 create mode 100644 packages/core/types/src/http/refund-reason/admin/queries.ts
 create mode 100644 packages/core/types/src/http/refund-reason/admin/responses.ts
 create mode 100644 packages/core/types/src/http/refund-reason/common.ts
 create mode 100644 packages/core/types/src/http/refund-reason/index.ts

diff --git a/.changeset/quick-rice-deny.md b/.changeset/quick-rice-deny.md
new file mode 100644
index 0000000000..1abd08b519
--- /dev/null
+++ b/.changeset/quick-rice-deny.md
@@ -0,0 +1,9 @@
+---
+"@medusajs/admin-shared": patch
+"@medusajs/dashboard": patch
+"@medusajs/js-sdk": patch
+"@medusajs/types": patch
+"@medusajs/payment": patch
+---
+
+feat(admin-shared,dashboard,js-sdk,types,payment): refund reasons in dashboard
diff --git a/packages/admin/admin-shared/src/extensions/widgets/constants.ts b/packages/admin/admin-shared/src/extensions/widgets/constants.ts
index 0137c4214f..eab257487e 100644
--- a/packages/admin/admin-shared/src/extensions/widgets/constants.ts
+++ b/packages/admin/admin-shared/src/extensions/widgets/constants.ts
@@ -189,6 +189,11 @@ const RETURN_REASON_INJECTION_ZONES = [
   "return_reason.list.after",
 ] as const
 
+const REFUND_REASON_INJECTION_ZONES = [
+  "refund_reason.list.before",
+  "refund_reason.list.after",
+] as const
+
 const INVENTORY_ITEM_INJECTION_ZONES = [
   "inventory_item.details.before",
   "inventory_item.details.after",
@@ -229,5 +234,6 @@ export const INJECTION_ZONES = [
   ...CAMPAIGN_INJECTION_ZONES,
   ...TAX_INJECTION_ZONES,
   ...RETURN_REASON_INJECTION_ZONES,
+  ...REFUND_REASON_INJECTION_ZONES,
   ...INVENTORY_ITEM_INJECTION_ZONES,
 ] as const
diff --git a/packages/admin/dashboard/src/components/layout/settings-layout/settings-layout.tsx b/packages/admin/dashboard/src/components/layout/settings-layout/settings-layout.tsx
index dfdc4900c5..e3951ea657 100644
--- a/packages/admin/dashboard/src/components/layout/settings-layout/settings-layout.tsx
+++ b/packages/admin/dashboard/src/components/layout/settings-layout/settings-layout.tsx
@@ -43,6 +43,10 @@ const useSettingRoutes = (): INavItem[] => {
         label: t("returnReasons.domain"),
         to: "/settings/return-reasons",
       },
+      {
+        label: t("refundReasons.domain"),
+        to: "/settings/refund-reasons",
+      },
       {
         label: t("salesChannels.domain"),
         to: "/settings/sales-channels",
diff --git a/packages/admin/dashboard/src/dashboard-app/routes/get-route.map.tsx b/packages/admin/dashboard/src/dashboard-app/routes/get-route.map.tsx
index da0c7fb6f1..23c39c6839 100644
--- a/packages/admin/dashboard/src/dashboard-app/routes/get-route.map.tsx
+++ b/packages/admin/dashboard/src/dashboard-app/routes/get-route.map.tsx
@@ -1780,6 +1780,42 @@ export function getRouteMap({
                 },
               ],
             },
+            {
+              path: "refund-reasons",
+              element: <Outlet />,
+              handle: {
+                breadcrumb: () => t("refundReasons.domain"),
+              },
+              children: [
+                {
+                  path: "",
+                  lazy: () =>
+                    import("../../routes/refund-reasons/refund-reason-list"),
+                  children: [
+                    {
+                      path: "create",
+                      lazy: () =>
+                        import(
+                          "../../routes/refund-reasons/refund-reason-create"
+                        ),
+                    },
+
+                    {
+                      path: ":id",
+                      children: [
+                        {
+                          path: "edit",
+                          lazy: () =>
+                            import(
+                              "../../routes/refund-reasons/refund-reason-edit"
+                            ),
+                        },
+                      ],
+                    },
+                  ],
+                },
+              ],
+            },
             ...(settingsRoutes?.[0]?.children || []),
           ],
         },
diff --git a/packages/admin/dashboard/src/hooks/api/refund-reasons.tsx b/packages/admin/dashboard/src/hooks/api/refund-reasons.tsx
index db889056f0..d63c20a4c2 100644
--- a/packages/admin/dashboard/src/hooks/api/refund-reasons.tsx
+++ b/packages/admin/dashboard/src/hooks/api/refund-reasons.tsx
@@ -1,29 +1,124 @@
 import { HttpTypes } from "@medusajs/types"
-import { QueryKey, useQuery, UseQueryOptions } from "@tanstack/react-query"
-import { sdk } from "../../lib/client"
-import { queryKeysFactory } from "../../lib/query-key-factory"
-import { FetchError } from "@medusajs/js-sdk"
+import {
+  useMutation,
+  UseMutationOptions,
+  useQuery,
+  UseQueryOptions,
+} from "@tanstack/react-query"
 
-const REFUND_REASON_QUERY_KEY = "refund-reason" as const
-export const refundReasonQueryKeys = queryKeysFactory(REFUND_REASON_QUERY_KEY)
+import { FetchError } from "@medusajs/js-sdk"
+import { sdk } from "../../lib/client"
+import { queryClient } from "../../lib/query-client"
+import { queryKeysFactory } from "../../lib/query-key-factory"
+
+const REFUND_REASONS_QUERY_KEY = "refund_reasons" as const
+export const refundReasonsQueryKeys = queryKeysFactory(REFUND_REASONS_QUERY_KEY)
 
 export const useRefundReasons = (
-  query?: HttpTypes.RefundReasonFilters,
+  query?: HttpTypes.AdminRefundReasonListParams,
   options?: Omit<
     UseQueryOptions<
-      HttpTypes.RefundReasonsResponse,
+      HttpTypes.AdminRefundReasonListResponse,
       FetchError,
-      HttpTypes.RefundReasonsResponse,
-      QueryKey
+      HttpTypes.AdminRefundReasonListResponse
     >,
-    "queryKey" | "queryFn"
+    "queryFn" | "queryKey"
   >
 ) => {
   const { data, ...rest } = useQuery({
     queryFn: () => sdk.admin.refundReason.list(query),
-    queryKey: [],
+    queryKey: refundReasonsQueryKeys.list(query),
     ...options,
   })
 
   return { ...data, ...rest }
 }
+
+export const useRefundReason = (
+  id: string,
+  query?: HttpTypes.AdminRefundReasonParams,
+  options?: Omit<
+    UseQueryOptions<
+      HttpTypes.AdminRefundReasonResponse,
+      FetchError,
+      HttpTypes.AdminRefundReasonResponse
+    >,
+    "queryFn" | "queryKey"
+  >
+) => {
+  const { data, ...rest } = useQuery({
+    queryFn: () => sdk.admin.refundReason.retrieve(id, query),
+    queryKey: refundReasonsQueryKeys.detail(id),
+    ...options,
+  })
+
+  return { ...data, ...rest }
+}
+
+export const useCreateRefundReason = (
+  query?: HttpTypes.AdminRefundReasonParams,
+  options?: UseMutationOptions<
+    HttpTypes.RefundReasonResponse,
+    FetchError,
+    HttpTypes.AdminCreateRefundReason
+  >
+) => {
+  return useMutation({
+    mutationFn: async (data) => sdk.admin.refundReason.create(data, query),
+    onSuccess: (data, variables, context) => {
+      queryClient.invalidateQueries({
+        queryKey: refundReasonsQueryKeys.lists(),
+      })
+
+      options?.onSuccess?.(data, variables, context)
+    },
+    ...options,
+  })
+}
+
+export const useUpdateRefundReason = (
+  id: string,
+  options?: UseMutationOptions<
+    HttpTypes.AdminRefundReasonResponse,
+    FetchError,
+    HttpTypes.AdminUpdateRefundReason
+  >
+) => {
+  return useMutation({
+    mutationFn: async (data) => sdk.admin.refundReason.update(id, data),
+    onSuccess: (data, variables, context) => {
+      queryClient.invalidateQueries({
+        queryKey: refundReasonsQueryKeys.lists(),
+      })
+      queryClient.invalidateQueries({
+        queryKey: refundReasonsQueryKeys.detail(data.refund_reason.id),
+      })
+
+      options?.onSuccess?.(data, variables, context)
+    },
+    ...options,
+  })
+}
+
+export const useDeleteRefundReasonLazy = (
+  options?: UseMutationOptions<
+    HttpTypes.AdminRefundReasonDeleteResponse,
+    FetchError,
+    string
+  >
+) => {
+  return useMutation({
+    mutationFn: (id: string) => sdk.admin.refundReason.delete(id),
+    onSuccess: (data, variables, context) => {
+      queryClient.invalidateQueries({
+        queryKey: refundReasonsQueryKeys.lists(),
+      })
+      queryClient.invalidateQueries({
+        queryKey: refundReasonsQueryKeys.details(),
+      })
+
+      options?.onSuccess?.(data, variables, context)
+    },
+    ...options,
+  })
+}
diff --git a/packages/admin/dashboard/src/hooks/table/columns/index.ts b/packages/admin/dashboard/src/hooks/table/columns/index.ts
index bbeb3d4d62..0095d324b4 100644
--- a/packages/admin/dashboard/src/hooks/table/columns/index.ts
+++ b/packages/admin/dashboard/src/hooks/table/columns/index.ts
@@ -6,6 +6,7 @@ export * from "./use-order-table-columns"
 export * from "./use-product-table-columns"
 export * from "./use-product-tag-table-columns"
 export * from "./use-product-type-table-columns"
+export * from "./use-refund-reason-table-columns"
 export * from "./use-region-table-columns"
 export * from "./use-return-reason-table-columns"
 export * from "./use-tax-rates-table-columns"
diff --git a/packages/admin/dashboard/src/hooks/table/columns/use-refund-reason-table-columns.tsx b/packages/admin/dashboard/src/hooks/table/columns/use-refund-reason-table-columns.tsx
new file mode 100644
index 0000000000..ba9f27691f
--- /dev/null
+++ b/packages/admin/dashboard/src/hooks/table/columns/use-refund-reason-table-columns.tsx
@@ -0,0 +1,32 @@
+import { HttpTypes } from "@medusajs/types"
+import { useMemo } from "react"
+import { useTranslation } from "react-i18next"
+import { createDataTableColumnHelper } from "@medusajs/ui"
+import { DescriptionCell } from "../../../components/table/table-cells/sales-channel/description-cell"
+
+const columnHelper = createDataTableColumnHelper<HttpTypes.AdminRefundReason>()
+
+export const useRefundReasonTableColumns = () => {
+  const { t } = useTranslation()
+
+  return useMemo(
+    () => [
+      columnHelper.accessor("label", {
+        header: () => t("fields.label"),
+        enableSorting: true,
+        sortLabel: t("fields.label"),
+        sortAscLabel: t("filters.sorting.alphabeticallyAsc"),
+        sortDescLabel: t("filters.sorting.alphabeticallyDesc"),
+      }),
+      columnHelper.accessor("description", {
+        header: () => t("fields.description"),
+        cell: ({ getValue }) => <DescriptionCell description={getValue()} />,
+        enableSorting: true,
+        sortLabel: t("fields.description"),
+        sortAscLabel: t("filters.sorting.alphabeticallyAsc"),
+        sortDescLabel: t("filters.sorting.alphabeticallyDesc"),
+      }),
+    ],
+    [t]
+  )
+}
diff --git a/packages/admin/dashboard/src/hooks/table/query/index.ts b/packages/admin/dashboard/src/hooks/table/query/index.ts
index fb5f55c912..92461c3106 100644
--- a/packages/admin/dashboard/src/hooks/table/query/index.ts
+++ b/packages/admin/dashboard/src/hooks/table/query/index.ts
@@ -6,6 +6,7 @@ export * from "./use-order-table-query"
 export * from "./use-product-table-query"
 export * from "./use-product-tag-table-query"
 export * from "./use-product-type-table-query"
+export * from "./use-refund-reason-table-query"
 export * from "./use-region-table-query"
 export * from "./use-return-reason-table-query"
 export * from "./use-shipping-option-table-query"
diff --git a/packages/admin/dashboard/src/hooks/table/query/use-refund-reason-table-query.tsx b/packages/admin/dashboard/src/hooks/table/query/use-refund-reason-table-query.tsx
new file mode 100644
index 0000000000..578a88b802
--- /dev/null
+++ b/packages/admin/dashboard/src/hooks/table/query/use-refund-reason-table-query.tsx
@@ -0,0 +1,32 @@
+import { HttpTypes } from "@medusajs/types"
+import { useQueryParams } from "../../use-query-params"
+
+type UseRefundReasonTableQueryProps = {
+  prefix?: string
+  pageSize?: number
+}
+
+export const useRefundReasonTableQuery = ({
+  prefix,
+  pageSize = 20,
+}: UseRefundReasonTableQueryProps) => {
+  const queryObject = useQueryParams(
+    ["offset", "q", "order", "created_at", "updated_at"],
+    prefix
+  )
+
+  const { offset, q, order, created_at, updated_at } = queryObject
+  const searchParams: HttpTypes.AdminRefundReasonListParams = {
+    limit: pageSize,
+    offset: offset ? Number(offset) : 0,
+    order,
+    created_at: created_at ? JSON.parse(created_at) : undefined,
+    updated_at: updated_at ? JSON.parse(updated_at) : undefined,
+    q,
+  }
+
+  return {
+    searchParams,
+    raw: queryObject,
+  }
+}
\ No newline at end of file
diff --git a/packages/admin/dashboard/src/i18n/translations/$schema.json b/packages/admin/dashboard/src/i18n/translations/$schema.json
index 8a3b0b2417..41209b6049 100644
--- a/packages/admin/dashboard/src/i18n/translations/$schema.json
+++ b/packages/admin/dashboard/src/i18n/translations/$schema.json
@@ -161,6 +161,9 @@
         "noRecordsMessage": {
           "type": "string"
         },
+        "noRecordsMessageFiltered": {
+          "type": "string"
+        },
         "unsavedChangesTitle": {
           "type": "string"
         },
@@ -229,6 +232,7 @@
         "noSearchResultsFor",
         "noRecordsTitle",
         "noRecordsMessage",
+        "noRecordsMessageFiltered",
         "unsavedChangesTitle",
         "unsavedChangesDescription",
         "includesTaxTooltip",
@@ -10202,6 +10206,115 @@
       ],
       "additionalProperties": false
     },
+    "refundReasons": {
+      "type": "object",
+      "properties": {
+        "domain": {
+          "type": "string"
+        },
+        "subtitle": {
+          "type": "string"
+        },
+        "calloutHint": {
+          "type": "string"
+        },
+        "editReason": {
+          "type": "string"
+        },
+        "create": {
+          "type": "object",
+          "properties": {
+            "header": {
+              "type": "string"
+            },
+            "subtitle": {
+              "type": "string"
+            },
+            "hint": {
+              "type": "string"
+            },
+            "successToast": {
+              "type": "string"
+            }
+          },
+          "required": ["header", "subtitle", "hint", "successToast"],
+          "additionalProperties": false
+        },
+        "edit": {
+          "type": "object",
+          "properties": {
+            "header": {
+              "type": "string"
+            },
+            "subtitle": {
+              "type": "string"
+            },
+            "successToast": {
+              "type": "string"
+            }
+          },
+          "required": ["header", "subtitle", "successToast"],
+          "additionalProperties": false
+        },
+        "delete": {
+          "type": "object",
+          "properties": {
+            "confirmation": {
+              "type": "string"
+            },
+            "successToast": {
+              "type": "string"
+            }
+          },
+          "required": ["confirmation", "successToast"],
+          "additionalProperties": false
+        },
+        "fields": {
+          "type": "object",
+          "properties": {
+            "label": {
+              "type": "object",
+              "properties": {
+                "label": {
+                  "type": "string"
+                },
+                "placeholder": {
+                  "type": "string"
+                }
+              },
+              "required": ["label", "placeholder"],
+              "additionalProperties": false
+            },
+            "description": {
+              "type": "object",
+              "properties": {
+                "label": {
+                  "type": "string"
+                },
+                "placeholder": {
+                  "type": "string"
+                }
+              },
+              "required": ["label", "placeholder"],
+              "additionalProperties": false
+            }
+          },
+          "required": ["label", "description"],
+          "additionalProperties": false
+        }
+      },
+      "required": [
+        "domain",
+        "subtitle",
+        "calloutHint",
+        "editReason",
+        "create",
+        "edit",
+        "delete",
+        "fields"
+      ],
+      "additionalProperties": false
+    },
     "login": {
       "type": "object",
       "properties": {
@@ -11554,70 +11667,6 @@
       ],
       "additionalProperties": false
     },
-    "views": {
-      "type": "object",
-      "properties": {
-        "save": {
-          "type": "string"
-        },
-        "saveAsNew": {
-          "type": "string"
-        },
-        "updateDefaultForEveryone": {
-          "type": "string"
-        },
-        "updateViewName": {
-          "type": "string"
-        },
-        "prompts": {
-          "type": "object",
-          "properties": {
-            "updateDefault": {
-              "type": "object",
-              "properties": {
-                "title": {
-                  "type": "string"
-                },
-                "description": {
-                  "type": "string"
-                },
-                "confirmText": {
-                  "type": "string"
-                },
-                "cancelText": {
-                  "type": "string"
-                }
-              },
-              "required": ["title", "description", "confirmText", "cancelText"],
-              "additionalProperties": false
-            },
-            "updateView": {
-              "type": "object",
-              "properties": {
-                "title": {
-                  "type": "string"
-                },
-                "description": {
-                  "type": "string"
-                },
-                "confirmText": {
-                  "type": "string"
-                },
-                "cancelText": {
-                  "type": "string"
-                }
-              },
-              "required": ["title", "description", "confirmText", "cancelText"],
-              "additionalProperties": false
-            }
-          },
-          "required": ["updateDefault", "updateView"],
-          "additionalProperties": false
-        }
-      },
-      "required": ["save", "saveAsNew", "updateDefaultForEveryone", "updateViewName", "prompts"],
-      "additionalProperties": false
-    },
     "dateTime": {
       "type": "object",
       "properties": {
@@ -11681,6 +11730,76 @@
         "seconds_other"
       ],
       "additionalProperties": false
+    },
+    "views": {
+      "type": "object",
+      "properties": {
+        "save": {
+          "type": "string"
+        },
+        "saveAsNew": {
+          "type": "string"
+        },
+        "updateDefaultForEveryone": {
+          "type": "string"
+        },
+        "updateViewName": {
+          "type": "string"
+        },
+        "prompts": {
+          "type": "object",
+          "properties": {
+            "updateDefault": {
+              "type": "object",
+              "properties": {
+                "title": {
+                  "type": "string"
+                },
+                "description": {
+                  "type": "string"
+                },
+                "confirmText": {
+                  "type": "string"
+                },
+                "cancelText": {
+                  "type": "string"
+                }
+              },
+              "required": ["title", "description", "confirmText", "cancelText"],
+              "additionalProperties": false
+            },
+            "updateView": {
+              "type": "object",
+              "properties": {
+                "title": {
+                  "type": "string"
+                },
+                "description": {
+                  "type": "string"
+                },
+                "confirmText": {
+                  "type": "string"
+                },
+                "cancelText": {
+                  "type": "string"
+                }
+              },
+              "required": ["title", "description", "confirmText", "cancelText"],
+              "additionalProperties": false
+            }
+          },
+          "required": ["updateDefault", "updateView"],
+          "additionalProperties": false
+        }
+      },
+      "required": [
+        "save",
+        "saveAsNew",
+        "updateDefaultForEveryone",
+        "updateViewName",
+        "prompts"
+      ],
+      "additionalProperties": false
     }
   },
   "required": [
@@ -11724,6 +11843,7 @@
     "salesChannels",
     "apiKeyManagement",
     "returnReasons",
+    "refundReasons",
     "login",
     "invite",
     "resetPassword",
@@ -11736,8 +11856,8 @@
     "statuses",
     "labels",
     "fields",
-    "views",
-    "dateTime"
+    "dateTime",
+    "views"
   ],
   "additionalProperties": false
 }
diff --git a/packages/admin/dashboard/src/i18n/translations/en.json b/packages/admin/dashboard/src/i18n/translations/en.json
index 3088c16fc7..30eb795f18 100644
--- a/packages/admin/dashboard/src/i18n/translations/en.json
+++ b/packages/admin/dashboard/src/i18n/translations/en.json
@@ -52,6 +52,7 @@
     "noSearchResultsFor": "No search results for <0>'{{query}}'</0>",
     "noRecordsTitle": "No records",
     "noRecordsMessage": "There are no records to show",
+    "noRecordsMessageFiltered": "There are no records to show matching the filters",
     "unsavedChangesTitle": "Are you sure you want to leave this form?",
     "unsavedChangesDescription": "You have unsaved changes that will be lost if you exit this form.",
     "includesTaxTooltip": "Prices in this column are tax inclusive.",
@@ -2740,6 +2741,37 @@
       }
     }
   },
+  "refundReasons": {
+    "domain": "Refund Reasons",
+    "subtitle": "Manage reasons for issuing refunds.",
+    "calloutHint": "Manage the reasons to categorize refunds.",
+    "editReason": "Edit Refund Reason",
+    "create": {
+      "header": "Add Refund Reason",
+      "subtitle": "Specify the most common reasons for refunds.",
+      "hint": "Create a new refund reason to categorize refunds.",
+      "successToast": "Refund reason {{label}} was successfully created."
+    },
+    "edit": {
+      "header": "Edit Refund Reason",
+      "subtitle": "Edit the value of the refund reason.",
+      "successToast": "Refund reason {{label}} was successfully updated."
+    },
+    "delete": {
+      "confirmation": "You are about to delete the refund reason \"{{label}}\". This action cannot be undone.",
+      "successToast": "Refund reason was successfully deleted."
+    },
+    "fields": {
+      "label": {
+        "label": "Label",
+        "placeholder": "Gesture of goodwill"
+      },
+      "description": {
+        "label": "Description",
+        "placeholder": "Customer had a bad shopping experience"
+      }
+    }
+  },
   "login": {
     "forgotPassword": "Forgot password? - <0>Reset</0>",
     "title": "Welcome to Medusa",
diff --git a/packages/admin/dashboard/src/routes/refund-reasons/refund-reason-create/components/refund-reason-create-form/index.ts b/packages/admin/dashboard/src/routes/refund-reasons/refund-reason-create/components/refund-reason-create-form/index.ts
new file mode 100644
index 0000000000..732708c4de
--- /dev/null
+++ b/packages/admin/dashboard/src/routes/refund-reasons/refund-reason-create/components/refund-reason-create-form/index.ts
@@ -0,0 +1 @@
+export { RefundReasonCreateForm } from "./refund-reason-create-form"
diff --git a/packages/admin/dashboard/src/routes/refund-reasons/refund-reason-create/components/refund-reason-create-form/refund-reason-create-form.tsx b/packages/admin/dashboard/src/routes/refund-reasons/refund-reason-create/components/refund-reason-create-form/refund-reason-create-form.tsx
new file mode 100644
index 0000000000..f1852fefb7
--- /dev/null
+++ b/packages/admin/dashboard/src/routes/refund-reasons/refund-reason-create/components/refund-reason-create-form/refund-reason-create-form.tsx
@@ -0,0 +1,131 @@
+import { zodResolver } from "@hookform/resolvers/zod"
+import { Button, Heading, Input, Text, Textarea, toast } from "@medusajs/ui"
+import { useForm } from "react-hook-form"
+import { useTranslation } from "react-i18next"
+import { z } from "zod"
+import { Form } from "../../../../../components/common/form"
+import {
+  RouteFocusModal,
+  useRouteModal,
+} from "../../../../../components/modals"
+import { KeyboundForm } from "../../../../../components/utilities/keybound-form"
+import { useCreateRefundReason } from "../../../../../hooks/api"
+
+const RefundReasonCreateSchema = z.object({
+  label: z.string().min(1),
+  description: z.string().optional(),
+})
+
+export const RefundReasonCreateForm = () => {
+  const { t } = useTranslation()
+  const { handleSuccess } = useRouteModal()
+
+  const form = useForm<z.infer<typeof RefundReasonCreateSchema>>({
+    defaultValues: {
+      label: "",
+      description: "",
+    },
+    resolver: zodResolver(RefundReasonCreateSchema),
+  })
+
+  const { mutateAsync, isPending } = useCreateRefundReason()
+
+  const handleSubmit = form.handleSubmit(async (data) => {
+    await mutateAsync(data, {
+      onSuccess: ({ refund_reason }) => {
+        toast.success(
+          t("refundReasons.create.successToast", {
+            label: refund_reason.label,
+          })
+        )
+        handleSuccess(`../`)
+      },
+      onError: (error) => {
+        toast.error(error.message)
+      },
+    })
+  })
+
+  return (
+    <RouteFocusModal.Form form={form}>
+      <KeyboundForm
+        className="flex size-full flex-col overflow-hidden"
+        onSubmit={handleSubmit}
+      >
+        <RouteFocusModal.Header />
+        <RouteFocusModal.Body className="flex flex-1 justify-center overflow-auto px-6 py-16">
+          <div className="flex w-full max-w-[720px] flex-col gap-y-8">
+            <div className="flex flex-col gap-y-1">
+              <RouteFocusModal.Title asChild>
+                <Heading>{t("refundReasons.create.header")}</Heading>
+              </RouteFocusModal.Title>
+              <RouteFocusModal.Description asChild>
+                <Text size="small" className="text-ui-fg-subtle">
+                  {t("refundReasons.create.subtitle")}
+                </Text>
+              </RouteFocusModal.Description>
+            </div>
+            <div className="grid gap-4 md:grid-cols-2">
+              <Form.Field
+                control={form.control}
+                name="label"
+                render={({ field }) => {
+                  return (
+                    <Form.Item>
+                      <Form.Label>
+                        {t("refundReasons.fields.label.label")}
+                      </Form.Label>
+                      <Form.Control>
+                        <Input
+                          {...field}
+                          placeholder={t(
+                            "refundReasons.fields.label.placeholder"
+                          )}
+                        />
+                      </Form.Control>
+                      <Form.ErrorMessage />
+                    </Form.Item>
+                  )
+                }}
+              />
+            </div>
+            <Form.Field
+              control={form.control}
+              name="description"
+              render={({ field }) => {
+                return (
+                  <Form.Item>
+                    <Form.Label optional>
+                      {t("refundReasons.fields.description.label")}
+                    </Form.Label>
+                    <Form.Control>
+                      <Textarea
+                        {...field}
+                        placeholder={t(
+                          "refundReasons.fields.description.placeholder"
+                        )}
+                      />
+                    </Form.Control>
+                    <Form.ErrorMessage />
+                  </Form.Item>
+                )
+              }}
+            />
+          </div>
+        </RouteFocusModal.Body>
+        <RouteFocusModal.Footer>
+          <div className="flex items-center justify-end gap-2">
+            <RouteFocusModal.Close asChild>
+              <Button size="small" variant="secondary" type="button">
+                {t("actions.cancel")}
+              </Button>
+            </RouteFocusModal.Close>
+            <Button size="small" type="submit" isLoading={isPending}>
+              {t("actions.save")}
+            </Button>
+          </div>
+        </RouteFocusModal.Footer>
+      </KeyboundForm>
+    </RouteFocusModal.Form>
+  )
+}
diff --git a/packages/admin/dashboard/src/routes/refund-reasons/refund-reason-create/index.ts b/packages/admin/dashboard/src/routes/refund-reasons/refund-reason-create/index.ts
new file mode 100644
index 0000000000..866753ef93
--- /dev/null
+++ b/packages/admin/dashboard/src/routes/refund-reasons/refund-reason-create/index.ts
@@ -0,0 +1 @@
+export { RefundReasonCreate as Component } from "./refund-reason-create"
diff --git a/packages/admin/dashboard/src/routes/refund-reasons/refund-reason-create/refund-reason-create.tsx b/packages/admin/dashboard/src/routes/refund-reasons/refund-reason-create/refund-reason-create.tsx
new file mode 100644
index 0000000000..52970f796c
--- /dev/null
+++ b/packages/admin/dashboard/src/routes/refund-reasons/refund-reason-create/refund-reason-create.tsx
@@ -0,0 +1,10 @@
+import { RouteFocusModal } from "../../../components/modals"
+import { RefundReasonCreateForm } from "./components/refund-reason-create-form"
+
+export const RefundReasonCreate = () => {
+  return (
+    <RouteFocusModal>
+      <RefundReasonCreateForm />
+    </RouteFocusModal>
+  )
+}
\ No newline at end of file
diff --git a/packages/admin/dashboard/src/routes/refund-reasons/refund-reason-edit/components/refund-reason-edit-form/index.ts b/packages/admin/dashboard/src/routes/refund-reasons/refund-reason-edit/components/refund-reason-edit-form/index.ts
new file mode 100644
index 0000000000..f2443caa3b
--- /dev/null
+++ b/packages/admin/dashboard/src/routes/refund-reasons/refund-reason-edit/components/refund-reason-edit-form/index.ts
@@ -0,0 +1 @@
+export { RefundReasonEditForm } from "./refund-reason-edit-form"
diff --git a/packages/admin/dashboard/src/routes/refund-reasons/refund-reason-edit/components/refund-reason-edit-form/refund-reason-edit-form.tsx b/packages/admin/dashboard/src/routes/refund-reasons/refund-reason-edit/components/refund-reason-edit-form/refund-reason-edit-form.tsx
new file mode 100644
index 0000000000..e70ac17f84
--- /dev/null
+++ b/packages/admin/dashboard/src/routes/refund-reasons/refund-reason-edit/components/refund-reason-edit-form/refund-reason-edit-form.tsx
@@ -0,0 +1,119 @@
+import { zodResolver } from "@hookform/resolvers/zod"
+import { HttpTypes } from "@medusajs/types"
+import { Button, Input, Textarea, toast } from "@medusajs/ui"
+import { useForm } from "react-hook-form"
+import { useTranslation } from "react-i18next"
+import { z } from "zod"
+
+import { Form } from "../../../../../components/common/form"
+import { RouteDrawer, useRouteModal } from "../../../../../components/modals"
+import { KeyboundForm } from "../../../../../components/utilities/keybound-form"
+import { useUpdateRefundReason } from "../../../../../hooks/api/refund-reasons"
+
+type RefundReasonEditFormProps = {
+  refundReason: HttpTypes.AdminRefundReason
+}
+
+const RefundReasonEditSchema = z.object({
+  label: z.string().min(1),
+  description: z.string().optional(),
+})
+
+export const RefundReasonEditForm = ({
+  refundReason,
+}: RefundReasonEditFormProps) => {
+  const { t } = useTranslation()
+  const { handleSuccess } = useRouteModal()
+
+  const form = useForm<z.infer<typeof RefundReasonEditSchema>>({
+    defaultValues: {
+      label: refundReason.label,
+      description: refundReason.description ?? undefined,
+    },
+    resolver: zodResolver(RefundReasonEditSchema),
+  })
+
+  const { mutateAsync, isPending } = useUpdateRefundReason(refundReason.id)
+
+  const handleSubmit = form.handleSubmit(async (data) => {
+    await mutateAsync(data, {
+      onSuccess: ({ refund_reason }) => {
+        toast.success(
+          t("refundReasons.edit.successToast", {
+            label: refund_reason.label,
+          })
+        )
+        handleSuccess()
+      },
+      onError: (error) => {
+        toast.error(error.message)
+      },
+    })
+  })
+
+  return (
+    <RouteDrawer.Form form={form}>
+      <KeyboundForm
+        className="flex size-full flex-col overflow-hidden"
+        onSubmit={handleSubmit}
+      >
+        <RouteDrawer.Body className="flex flex-1 flex-col gap-y-4 overflow-auto">
+          <Form.Field
+            control={form.control}
+            name="label"
+            render={({ field }) => {
+              return (
+                <Form.Item>
+                  <Form.Label>
+                    {t("refundReasons.fields.label.label")}
+                  </Form.Label>
+                  <Form.Control>
+                    <Input
+                      {...field}
+                      placeholder={t("refundReasons.fields.label.placeholder")}
+                    />
+                  </Form.Control>
+                  <Form.ErrorMessage />
+                </Form.Item>
+              )
+            }}
+          />
+          <Form.Field
+            control={form.control}
+            name="description"
+            render={({ field }) => {
+              return (
+                <Form.Item>
+                  <Form.Label optional>
+                    {t("refundReasons.fields.description.label")}
+                  </Form.Label>
+                  <Form.Control>
+                    <Textarea
+                      {...field}
+                      placeholder={t(
+                        "refundReasons.fields.description.placeholder"
+                      )}
+                    />
+                  </Form.Control>
+                  <Form.ErrorMessage />
+                </Form.Item>
+              )
+            }}
+          />
+        </RouteDrawer.Body>
+        <RouteDrawer.Footer>
+          <div className="flex items-center justify-end gap-x-2">
+            <RouteDrawer.Close asChild>
+              <Button variant="secondary" size="small" type="button">
+                {t("actions.cancel")}
+              </Button>
+            </RouteDrawer.Close>
+            <Button size="small" type="submit" isLoading={isPending}>
+              {t("actions.save")}
+            </Button>
+          </div>
+        </RouteDrawer.Footer>
+      </KeyboundForm>
+    </RouteDrawer.Form>
+  )
+}
diff --git a/packages/admin/dashboard/src/routes/refund-reasons/refund-reason-edit/index.ts b/packages/admin/dashboard/src/routes/refund-reasons/refund-reason-edit/index.ts
new file mode 100644
index 0000000000..055c5bba7c
--- /dev/null
+++ b/packages/admin/dashboard/src/routes/refund-reasons/refund-reason-edit/index.ts
@@ -0,0 +1 @@
+export { RefundReasonEdit as Component } from "./refund-reason-edit"
diff --git a/packages/admin/dashboard/src/routes/refund-reasons/refund-reason-edit/refund-reason-edit.tsx b/packages/admin/dashboard/src/routes/refund-reasons/refund-reason-edit/refund-reason-edit.tsx
new file mode 100644
index 0000000000..365ab62a37
--- /dev/null
+++ b/packages/admin/dashboard/src/routes/refund-reasons/refund-reason-edit/refund-reason-edit.tsx
@@ -0,0 +1,33 @@
+import { Heading } from "@medusajs/ui"
+import { useTranslation } from "react-i18next"
+import { useParams } from "react-router-dom"
+import { RouteDrawer } from "../../../components/modals"
+import { useRefundReason } from "../../../hooks/api/refund-reasons"
+import { RefundReasonEditForm } from "./components/refund-reason-edit-form"
+
+export const RefundReasonEdit = () => {
+  const { id } = useParams()
+  const { t } = useTranslation()
+
+  const { refund_reason, isPending, isError, error } = useRefundReason(id!)
+
+  const ready = !isPending && !!refund_reason
+
+  if (isError) {
+    throw error
+  }
+
+  return (
+    <RouteDrawer>
+      <RouteDrawer.Header>
+        <RouteDrawer.Title asChild>
+          <Heading>{t("refundReasons.edit.header")}</Heading>
+        </RouteDrawer.Title>
+        <RouteDrawer.Description className="sr-only">
+          {t("refundReasons.edit.subtitle")}
+        </RouteDrawer.Description>
+      </RouteDrawer.Header>
+      {ready && <RefundReasonEditForm refundReason={refund_reason} />}
+    </RouteDrawer>
+  )
+}
\ No newline at end of file
diff --git a/packages/admin/dashboard/src/routes/refund-reasons/refund-reason-list/components/refund-reason-list-table/index.ts b/packages/admin/dashboard/src/routes/refund-reasons/refund-reason-list/components/refund-reason-list-table/index.ts
new file mode 100644
index 0000000000..b2b0b7c834
--- /dev/null
+++ b/packages/admin/dashboard/src/routes/refund-reasons/refund-reason-list/components/refund-reason-list-table/index.ts
@@ -0,0 +1 @@
+export { RefundReasonListTable } from "./refund-reason-list-table"
diff --git a/packages/admin/dashboard/src/routes/refund-reasons/refund-reason-list/components/refund-reason-list-table/refund-reason-list-table.tsx b/packages/admin/dashboard/src/routes/refund-reasons/refund-reason-list/components/refund-reason-list-table/refund-reason-list-table.tsx
new file mode 100644
index 0000000000..3117c8f06c
--- /dev/null
+++ b/packages/admin/dashboard/src/routes/refund-reasons/refund-reason-list/components/refund-reason-list-table/refund-reason-list-table.tsx
@@ -0,0 +1,130 @@
+import { PencilSquare, Trash } from "@medusajs/icons"
+import { HttpTypes } from "@medusajs/types"
+import { Container, createDataTableColumnHelper, toast, usePrompt, } from "@medusajs/ui"
+import { keepPreviousData } from "@tanstack/react-query"
+import { useCallback, useMemo } from "react"
+import { useTranslation } from "react-i18next"
+import { useNavigate } from "react-router-dom"
+import { DataTable } from "../../../../../components/data-table"
+import { useDeleteRefundReasonLazy, useRefundReasons, } from "../../../../../hooks/api"
+import { useRefundReasonTableColumns } from "../../../../../hooks/table/columns"
+import { useRefundReasonTableQuery } from "../../../../../hooks/table/query"
+
+const PAGE_SIZE = 20
+
+export const RefundReasonListTable = () => {
+  const { t } = useTranslation()
+  const { searchParams } = useRefundReasonTableQuery({
+    pageSize: PAGE_SIZE,
+  })
+
+  const { refund_reasons, count, isPending, isError, error } = useRefundReasons(
+    searchParams,
+    {
+      placeholderData: keepPreviousData,
+    }
+  )
+
+  const columns = useColumns()
+
+  if (isError) {
+    throw error
+  }
+
+  return (
+    <Container className="divide-y px-0 py-0">
+      <DataTable
+        data={refund_reasons}
+        columns={columns}
+        rowCount={count}
+        pageSize={PAGE_SIZE}
+        getRowId={(row) => row.id}
+        heading={t("refundReasons.domain")}
+        subHeading={t("refundReasons.subtitle")}
+        emptyState={{
+          empty: {
+            heading: t("general.noRecordsMessage"),
+          },
+          filtered: {
+            heading: t("general.noRecordsMessage"),
+            description: t("general.noRecordsMessageFiltered"),
+          },
+        }}
+        actions={[
+          {
+            label: t("actions.create"),
+            to: "create",
+          },
+        ]}
+        isLoading={isPending}
+        enableSearch={true}
+      />
+    </Container>
+  )
+}
+
+const columnHelper = createDataTableColumnHelper<HttpTypes.AdminRefundReason>()
+
+const useColumns = () => {
+  const { t } = useTranslation()
+  const prompt = usePrompt()
+  const navigate = useNavigate()
+  const base = useRefundReasonTableColumns()
+
+  const { mutateAsync } = useDeleteRefundReasonLazy()
+
+  const handleDelete = useCallback(
+    async (refundReason: HttpTypes.AdminRefundReason) => {
+      const confirm = await prompt({
+        title: t("general.areYouSure"),
+        description: t("refundReasons.delete.confirmation", {
+          label: refundReason.label,
+        }),
+        confirmText: t("actions.delete"),
+        cancelText: t("actions.cancel"),
+      })
+
+      if (!confirm) {
+        return
+      }
+
+      await mutateAsync(refundReason.id, {
+        onSuccess: () => {
+          toast.success(t("refundReasons.delete.successToast"))
+        },
+        onError: (e) => {
+          toast.error(e.message)
+        },
+      })
+    },
+    [t, prompt, mutateAsync]
+  )
+
+  return useMemo(
+    () => [
+      ...base,
+      columnHelper.action({
+        actions: (ctx) => [
+          [
+            {
+              icon: <PencilSquare />,
+              label: t("actions.edit"),
+              onClick: () =>
+                navigate(
+                  `/settings/refund-reasons/${ctx.row.original.id}/edit`
+                ),
+            },
+          ],
+          [
+            {
+              icon: <Trash />,
+              label: t("actions.delete"),
+              onClick: () => handleDelete(ctx.row.original),
+            },
+          ],
+        ],
+      }),
+    ],
+    [base, handleDelete, navigate, t]
+  )
+}
diff --git a/packages/admin/dashboard/src/routes/refund-reasons/refund-reason-list/index.ts b/packages/admin/dashboard/src/routes/refund-reasons/refund-reason-list/index.ts
new file mode 100644
index 0000000000..d77e415f77
--- /dev/null
+++ b/packages/admin/dashboard/src/routes/refund-reasons/refund-reason-list/index.ts
@@ -0,0 +1,2 @@
+export { refundReasonListLoader as loader } from "./loader"
+export { RefundReasonList as Component } from "./refund-reason-list"
diff --git a/packages/admin/dashboard/src/routes/refund-reasons/refund-reason-list/loader.ts b/packages/admin/dashboard/src/routes/refund-reasons/refund-reason-list/loader.ts
new file mode 100644
index 0000000000..05a7c6f41f
--- /dev/null
+++ b/packages/admin/dashboard/src/routes/refund-reasons/refund-reason-list/loader.ts
@@ -0,0 +1,16 @@
+import { refundReasonsQueryKeys } from "../../../hooks/api"
+import { sdk } from "../../../lib/client"
+import { queryClient } from "../../../lib/query-client"
+
+const refundReasonListQuery = () => ({
+  queryKey: refundReasonsQueryKeys.list(),
+  queryFn: async () => sdk.admin.refundReason.list(),
+})
+
+export const refundReasonListLoader = async () => {
+  const query = refundReasonListQuery()
+  return (
+    queryClient.getQueryData(query.queryKey) ??
+    (await queryClient.fetchQuery(query))
+  )
+}
diff --git a/packages/admin/dashboard/src/routes/refund-reasons/refund-reason-list/refund-reason-list.tsx b/packages/admin/dashboard/src/routes/refund-reasons/refund-reason-list/refund-reason-list.tsx
new file mode 100644
index 0000000000..bec203bbef
--- /dev/null
+++ b/packages/admin/dashboard/src/routes/refund-reasons/refund-reason-list/refund-reason-list.tsx
@@ -0,0 +1,21 @@
+import { SingleColumnPage } from "../../../components/layout/pages"
+import { useExtension } from "../../../providers/extension-provider"
+import { RefundReasonListTable } from "./components/refund-reason-list-table"
+
+export const RefundReasonList = () => {
+  const { getWidgets } = useExtension()
+
+  return (
+    <SingleColumnPage
+      showMetadata={false}
+      showJSON={false}
+      hasOutlet
+      widgets={{
+        after: getWidgets("refund_reason.list.after"),
+        before: getWidgets("refund_reason.list.before"),
+      }}
+    >
+      <RefundReasonListTable />
+    </SingleColumnPage>
+  )
+}
diff --git a/packages/core/js-sdk/src/admin/refund-reasons.ts b/packages/core/js-sdk/src/admin/refund-reasons.ts
index 1c6403e270..92b1c63f5f 100644
--- a/packages/core/js-sdk/src/admin/refund-reasons.ts
+++ b/packages/core/js-sdk/src/admin/refund-reasons.ts
@@ -15,28 +15,28 @@ export class RefundReason {
   }
 
   /**
-   * This method retrieves a list of refund reasons. It sends a request to the 
+   * This method retrieves a list of refund reasons. It sends a request to the
    * [List Refund Reasons](https://docs.medusajs.com/api/admin#refund-reasons_getrefundreasons)
    * API route.
-   * 
+   *
    * @param query - Filters and pagination configurations.
    * @param headers - Headers to pass in the request.
    * @returns The paginated list of refund reasons.
-   * 
+   *
    * @example
    * To retrieve the list of refund reasons:
-   * 
+   *
    * ```ts
    * sdk.admin.refundReason.list()
    * .then(({ refund_reasons, count, limit, offset }) => {
    *   console.log(refund_reasons)
    * })
    * ```
-   * 
+   *
    * To configure the pagination, pass the `limit` and `offset` query parameters.
-   * 
+   *
    * For example, to retrieve only 10 items and skip 10 items:
-   * 
+   *
    * ```ts
    * sdk.admin.refundReason.list({
    *   limit: 10,
@@ -46,23 +46,26 @@ export class RefundReason {
    *   console.log(refund_reasons)
    * })
    * ```
-   * 
+   *
    * Using the `fields` query parameter, you can specify the fields and relations to retrieve
    * in each refund reason:
-   * 
+   *
    * ```ts
    * sdk.admin.refundReason.list({
-   *   fields: "id,name"
+   *   fields: "id,label"
    * })
    * .then(({ refund_reasons, count, limit, offset }) => {
    *   console.log(refund_reasons)
    * })
    * ```
-   * 
+   *
    * Learn more about the `fields` property in the [API reference](https://docs.medusajs.com/api/admin#select-fields-and-relations).
-   * 
+   *
    */
-  async list(query?: HttpTypes.RefundReasonFilters, headers?: ClientHeaders) {
+  async list(
+    query?: HttpTypes.AdminRefundReasonListParams,
+    headers?: ClientHeaders
+  ) {
     return await this.client.fetch<HttpTypes.RefundReasonsResponse>(
       `/admin/refund-reasons`,
       {
@@ -71,4 +74,154 @@ export class RefundReason {
       }
     )
   }
+
+  /**
+   * This method retrieves a refund reason by ID. It sends a request to the
+   * [Get Refund Reason](https://docs.medusajs.com/api/admin#refund-reasons_getrefundreasonsid)
+   * API route.
+   *
+   * @param id - The refund reason's ID.
+   * @param query - Configure the fields and relations to retrieve in the refund reason.
+   * @param headers - Headers to pass in the request.
+   * @returns The refund reason's details.
+   *
+   * @example
+   * To retrieve a refund reason by its ID:
+   *
+   * ```ts
+   * sdk.admin.refundReason.retrieve("refr_123")
+   * .then(({ refund_reason }) => {
+   *   console.log(refund_reason)
+   * })
+   * ```
+   *
+   * To specify the fields and relations to retrieve:
+   *
+   * ```ts
+   * sdk.admin.refundReason.retrieve("refr_123", {
+   *   fields: "id,value"
+   * })
+   * .then(({ refund_reason }) => {
+   *   console.log(refund_reason)
+   * })
+   * ```
+   *
+   * Learn more about the `fields` property in the [API reference](https://docs.medusajs.com/api/admin#select-fields-and-relations).
+   */
+  async retrieve(
+    id: string,
+    query?: HttpTypes.AdminRefundReasonParams,
+    headers?: ClientHeaders
+  ) {
+    return await this.client.fetch<HttpTypes.AdminRefundReasonResponse>(
+      `/admin/refund-reasons/${id}`,
+      {
+        query,
+        headers,
+      }
+    )
+  }
+
+  /**
+   * This method creates a refund reason. It sends a request to the
+   * [Create Refund Reason](https://docs.medusajs.com/api/admin#refund-reasons_postrefundreasons)
+   * API route.
+   *
+   * @param body - The details of the refund reason to create.
+   * @param query - Configure the fields and relations to retrieve in the refund reason.
+   * @param headers - Headers to pass in the request.
+   * @returns The refund reason's details.
+   *
+   * @example
+   * sdk.admin.refundReason.create({
+   *   value: "refund",
+   *   label: "Refund",
+   * })
+   * .then(({ refund_reason }) => {
+   *   console.log(refund_reason)
+   * })
+   */
+  async create(
+    body: HttpTypes.AdminCreateRefundReason,
+    query?: HttpTypes.AdminRefundReasonParams,
+    headers?: ClientHeaders
+  ) {
+    return this.client.fetch<HttpTypes.AdminRefundReasonResponse>(
+      `/admin/refund-reasons`,
+      {
+        method: "POST",
+        headers,
+        body,
+        query,
+      }
+    )
+  }
+
+  /**
+   * This method updates a refund reason. It sends a request to the
+   * [Update Refund Reason](https://docs.medusajs.com/api/admin#refund-reasons_postrefundreasonsid)
+   * API route.
+   *
+   * @param id - The refund reason's ID.
+   * @param body - The details of the refund reason to update.
+   * @param query - Configure the fields and relations to retrieve in the refund reason.
+   * @param headers - Headers to pass in the request.
+   * @returns The refund reason's details.
+   *
+   * @example
+   * sdk.admin.refundReason.update("ret_123", {
+   *   value: "refund",
+   *   label: "Refund",
+   * })
+   * .then(({ refund_reason }) => {
+   *   console.log(refund_reason)
+   * })
+   */
+  async update(
+    id: string,
+    body: HttpTypes.AdminUpdateRefundReason,
+    query?: HttpTypes.AdminRefundReasonParams,
+    headers?: ClientHeaders
+  ) {
+    return this.client.fetch<HttpTypes.AdminRefundReasonResponse>(
+      `/admin/refund-reasons/${id}`,
+      {
+        method: "POST",
+        headers,
+        body,
+        query,
+      }
+    )
+  }
+
+  /**
+   * This method deletes a refund reason. It sends a request to the
+   * [Delete Refund Reason](https://docs.medusajs.com/api/admin#refund-reasons_deleterefundreasonsid)
+   * API route.
+   *
+   * @param id - The refund reason's ID.
+   * @param query - Query parameters to pass to the request.
+   * @param headers - Headers to pass in the request.
+   * @returns The deletion's details.
+   *
+   * @example
+   * sdk.admin.refundReason.delete("ret_123")
+   * .then(({ deleted }) => {
+   *   console.log(deleted)
+   * })
+   */
+  async delete(
+    id: string,
+    query?: HttpTypes.AdminRefundReasonParams,
+    headers?: ClientHeaders
+  ) {
+    return await this.client.fetch<HttpTypes.AdminRefundReasonDeleteResponse>(
+      `/admin/refund-reasons/${id}`,
+      {
+        method: "DELETE",
+        headers,
+        query,
+      }
+    )
+  }
 }
diff --git a/packages/core/types/src/http/index.ts b/packages/core/types/src/http/index.ts
index 71bb002ad7..6be5507109 100644
--- a/packages/core/types/src/http/index.ts
+++ b/packages/core/types/src/http/index.ts
@@ -30,6 +30,7 @@ export * from "./product-category"
 export * from "./product-tag"
 export * from "./product-type"
 export * from "./promotion"
+export * from "./refund-reason"
 export * from "./region"
 export * from "./reservation"
 export * from "./return"
diff --git a/packages/core/types/src/http/payment/admin/entities.ts b/packages/core/types/src/http/payment/admin/entities.ts
index 9a4ef7e85a..4b7208b31f 100644
--- a/packages/core/types/src/http/payment/admin/entities.ts
+++ b/packages/core/types/src/http/payment/admin/entities.ts
@@ -4,7 +4,6 @@ import {
   BasePaymentProvider,
   BasePaymentSession,
   BaseRefund,
-  RefundReason,
 } from "../common"
 
 export interface AdminPaymentProvider extends BasePaymentProvider {
@@ -49,4 +48,3 @@ export interface AdminPaymentSession extends BasePaymentSession {
   payment_collection?: AdminPaymentCollection
 }
 export interface AdminRefund extends BaseRefund {}
-export interface AdminRefundReason extends RefundReason {}
diff --git a/packages/core/types/src/http/payment/admin/payloads.ts b/packages/core/types/src/http/payment/admin/payloads.ts
index ffa535448d..2a53d8a735 100644
--- a/packages/core/types/src/http/payment/admin/payloads.ts
+++ b/packages/core/types/src/http/payment/admin/payloads.ts
@@ -22,11 +22,6 @@ export interface AdminRefundPayment {
   note?: string | null
 }
 
-export interface AdminCreateRefundReason {
-  label: string
-  description?: string
-}
-
 export interface AdminCreatePaymentCollection {
   /**
    * The ID of the order this payment collection belongs to.
diff --git a/packages/core/types/src/http/payment/admin/queries.ts b/packages/core/types/src/http/payment/admin/queries.ts
index c11cef6d26..158bd3d12c 100644
--- a/packages/core/types/src/http/payment/admin/queries.ts
+++ b/packages/core/types/src/http/payment/admin/queries.ts
@@ -5,7 +5,7 @@ import {
   BasePaymentFilters,
   BasePaymentSessionFilters,
 } from "../common"
-import { AdminRefundReason } from "./entities"
+import { AdminRefundReason } from "../../refund-reason"
 
 export interface AdminPaymentProviderFilters
   extends FindParams,
diff --git a/packages/core/types/src/http/payment/admin/responses.ts b/packages/core/types/src/http/payment/admin/responses.ts
index 09d2735791..0dab8818ea 100644
--- a/packages/core/types/src/http/payment/admin/responses.ts
+++ b/packages/core/types/src/http/payment/admin/responses.ts
@@ -4,8 +4,8 @@ import {
   AdminPaymentCollection,
   AdminPaymentProvider,
   AdminRefund,
-  AdminRefundReason,
 } from "./entities"
+import { AdminRefundReason } from "../../refund-reason"
 
 export interface AdminPaymentCollectionResponse {
   /**
@@ -60,5 +60,3 @@ export type AdminPaymentProviderListResponse = PaginatedResponse<{
    */
   payment_providers: AdminPaymentProvider[]
 }>
-
-export type AdminRefundReasonDeleteResponse = DeleteResponse<"refund_reason">
diff --git a/packages/core/types/src/http/payment/common.ts b/packages/core/types/src/http/payment/common.ts
index 18dc2c2378..07c7f801f1 100644
--- a/packages/core/types/src/http/payment/common.ts
+++ b/packages/core/types/src/http/payment/common.ts
@@ -1,4 +1,5 @@
 import { BaseFilterable, OperatorMap } from "../../dal"
+import { BaseRefundReason } from "../refund-reason/common"
 
 /**
  * The payment collection's status.
@@ -254,7 +255,7 @@ export interface BaseRefund {
   /**
    * The id of the refund_reason that is associated with the refund
    */
-  refund_reason?: RefundReason | null
+  refund_reason?: BaseRefundReason | null
 
   /**
    * A field to add some additional information about the refund
@@ -337,33 +338,6 @@ 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.
  */
diff --git a/packages/core/types/src/http/refund-reason/admin/entities.ts b/packages/core/types/src/http/refund-reason/admin/entities.ts
new file mode 100644
index 0000000000..c551756d96
--- /dev/null
+++ b/packages/core/types/src/http/refund-reason/admin/entities.ts
@@ -0,0 +1,3 @@
+import { BaseRefundReason } from "../common"
+
+export interface AdminRefundReason extends BaseRefundReason {}
diff --git a/packages/core/types/src/http/refund-reason/admin/index.ts b/packages/core/types/src/http/refund-reason/admin/index.ts
new file mode 100644
index 0000000000..1f82a2ead5
--- /dev/null
+++ b/packages/core/types/src/http/refund-reason/admin/index.ts
@@ -0,0 +1,4 @@
+export * from "./entities"
+export * from "./payloads"
+export * from "./queries"
+export * from "./responses"
diff --git a/packages/core/types/src/http/refund-reason/admin/payloads.ts b/packages/core/types/src/http/refund-reason/admin/payloads.ts
new file mode 100644
index 0000000000..aff7890886
--- /dev/null
+++ b/packages/core/types/src/http/refund-reason/admin/payloads.ts
@@ -0,0 +1,21 @@
+type AdminBaseRefundReasonPayload = {
+  /**
+   * The refund reason's label.
+   * 
+   * @example
+   * "Refund"
+   */
+  label: string
+  /**
+   * The refund reason's description.
+   */
+  description?: string
+  /**
+   * Custom key-value pairs that can be added to the refund reason.
+   */
+  metadata?: Record<string, unknown> | null
+}
+
+export interface AdminCreateRefundReason extends AdminBaseRefundReasonPayload {}
+
+export interface AdminUpdateRefundReason extends AdminBaseRefundReasonPayload {}
diff --git a/packages/core/types/src/http/refund-reason/admin/queries.ts b/packages/core/types/src/http/refund-reason/admin/queries.ts
new file mode 100644
index 0000000000..9a3291dcf7
--- /dev/null
+++ b/packages/core/types/src/http/refund-reason/admin/queries.ts
@@ -0,0 +1,14 @@
+import { BaseFilterable, OperatorMap } from "../../../dal"
+import { SelectParams } from "../../common"
+import { BaseRefundReasonListParams } from "../common"
+
+export interface AdminRefundReasonListParams
+  extends BaseRefundReasonListParams,
+    BaseFilterable<AdminRefundReasonListParams> {
+  /**
+   * Apply filters on the refund reason's deletion date.
+   */
+  deleted_at?: OperatorMap<string>
+}
+
+export interface AdminRefundReasonParams extends SelectParams {}
diff --git a/packages/core/types/src/http/refund-reason/admin/responses.ts b/packages/core/types/src/http/refund-reason/admin/responses.ts
new file mode 100644
index 0000000000..ad00de1382
--- /dev/null
+++ b/packages/core/types/src/http/refund-reason/admin/responses.ts
@@ -0,0 +1,20 @@
+import { DeleteResponse, PaginatedResponse } from "../../common"
+import { AdminRefundReason } from "./entities"
+
+export interface AdminRefundReasonResponse {
+  /**
+   * The refund reason's details.
+   */
+  refund_reason: AdminRefundReason
+}
+
+export interface AdminRefundReasonListResponse
+  extends PaginatedResponse<{
+    /**
+     * The list of refund reasons.
+     */
+    refund_reasons: AdminRefundReason[]
+  }> {}
+
+export interface AdminRefundReasonDeleteResponse
+  extends DeleteResponse<"refund_reason"> {}
diff --git a/packages/core/types/src/http/refund-reason/common.ts b/packages/core/types/src/http/refund-reason/common.ts
new file mode 100644
index 0000000000..f137a9696a
--- /dev/null
+++ b/packages/core/types/src/http/refund-reason/common.ts
@@ -0,0 +1,42 @@
+import { OperatorMap } from "../../dal"
+import { FindParams } from "../common"
+
+export interface BaseRefundReason {
+  /**
+   * The refund reason's ID.
+   */
+  id: string
+  /**
+   * The refund reason's label.
+   *
+   * @example
+   * "Refund"
+   */
+  label: string
+  /**
+   * The refund reason's description.
+   */
+  description?: string | null
+  /**
+   * Custom key-value pairs that can be added to the refund reason.
+   */
+  metadata?: Record<string, any> | null
+  /**
+   * The date that the refund reason was created.
+   */
+  created_at: string
+  /**
+   * The date that the refund reason was updated.
+   */
+  updated_at: string
+}
+
+export interface BaseRefundReasonListParams extends FindParams {
+  q?: string
+  id?: string | string[]
+  label?: string | OperatorMap<string>
+  description?: string | OperatorMap<string>
+  parent_refund_reason_id?: string | OperatorMap<string | string[]>
+  created_at?: OperatorMap<string>
+  updated_at?: OperatorMap<string>
+}
diff --git a/packages/core/types/src/http/refund-reason/index.ts b/packages/core/types/src/http/refund-reason/index.ts
new file mode 100644
index 0000000000..26b8eb9dad
--- /dev/null
+++ b/packages/core/types/src/http/refund-reason/index.ts
@@ -0,0 +1 @@
+export * from "./admin"
diff --git a/packages/modules/payment/src/models/refund-reason.ts b/packages/modules/payment/src/models/refund-reason.ts
index 026630bff2..90c9da40f0 100644
--- a/packages/modules/payment/src/models/refund-reason.ts
+++ b/packages/modules/payment/src/models/refund-reason.ts
@@ -4,7 +4,7 @@ import Refund from "./refund"
 const RefundReason = model.define("RefundReason", {
   id: model.id({ prefix: "refr" }).primaryKey(),
   label: model.text().searchable(),
-  description: model.text().nullable(),
+  description: model.text().searchable().nullable(),
   metadata: model.json().nullable(),
   refunds: model.hasMany(() => Refund, {
     mappedBy: "refund_reason",