feat(core-flows,order,medusa): exchange endpoints (#8396)

packages/medusa/src/api/admin/claims/[id]/outbound/items/[action_id]/route.ts

@@ -1,5 +1,5 @@
 import {
-  removeItemClaimActionWorkflow,
+  removeAddItemClaimActionWorkflow,
   updateClaimAddItemWorkflow,
 } from "@medusajs/core-flows"
 import {
@@ -55,7 +55,7 @@ export const DELETE = async (
 
   const { id, action_id } = req.params
 
-  const { result: orderPreview } = await removeItemClaimActionWorkflow(
+  const { result: orderPreview } = await removeAddItemClaimActionWorkflow(
     req.scope
   ).run({
     input: {

packages/medusa/src/api/admin/claims/query-config.ts

@@ -4,7 +4,6 @@ export const defaultAdminClaimFields = [
   "order_id",
   "return_id",
   "display_id",
-  "location_id",
   "order_version",
   "refund_amount",
   "created_at",

packages/medusa/src/api/admin/claims/validators.ts

@@ -143,6 +143,17 @@ export type AdminPostClaimsRequestReturnItemsReqSchemaType = z.infer<
   typeof AdminPostClaimsRequestReturnItemsReqSchema
 >
 
+export const AdminPostClaimsRequestItemsReturnActionReqSchema = z.object({
+  quantity: z.number().optional(),
+  internal_note: z.string().nullish().optional(),
+  reason_id: z.string().nullish().optional(),
+  metadata: z.record(z.unknown()).nullish().optional(),
+})
+
+export type AdminPostClaimsRequestItemsReturnActionReqSchemaType = z.infer<
+  typeof AdminPostClaimsRequestItemsReturnActionReqSchema
+>
+
 export const AdminPostClaimItemsReqSchema = z.object({
   items: z.array(
     z.object({

packages/medusa/src/api/admin/exchanges/[id]/cancel/route.ts

@@ -0,0 +1,23 @@
+import { cancelOrderExchangeWorkflow } from "@medusajs/core-flows"
+import {
+  AuthenticatedMedusaRequest,
+  MedusaResponse,
+} from "../../../../../types/routing"
+import { AdminPostCancelExchangeReqSchemaType } from "../../validators"
+
+export const POST = async (
+  req: AuthenticatedMedusaRequest<AdminPostCancelExchangeReqSchemaType>,
+  res: MedusaResponse
+) => {
+  const { id } = req.params
+
+  const workflow = cancelOrderExchangeWorkflow(req.scope)
+  const { result } = await workflow.run({
+    input: {
+      ...req.validatedBody,
+      exchange_id: id,
+    },
+  })
+
+  res.status(200).json({ exchange: result })
+}

packages/medusa/src/api/admin/exchanges/[id]/inbound/items/[action_id]/route.ts

@@ -0,0 +1,96 @@
+import {
+  removeItemReturnActionWorkflow,
+  updateRequestItemReturnWorkflow,
+} from "@medusajs/core-flows"
+import {
+  ContainerRegistrationKeys,
+  remoteQueryObjectFromString,
+} from "@medusajs/utils"
+import {
+  AuthenticatedMedusaRequest,
+  MedusaResponse,
+} from "../../../../../../../types/routing"
+import { defaultAdminDetailsReturnFields } from "../../../../../returns/query-config"
+import { AdminPostExchangesRequestItemsReturnActionReqSchemaType } from "../../../../validators"
+
+export const POST = async (
+  req: AuthenticatedMedusaRequest<AdminPostExchangesRequestItemsReturnActionReqSchemaType>,
+  res: MedusaResponse
+) => {
+  const { id, action_id } = req.params
+
+  const remoteQuery = req.scope.resolve(ContainerRegistrationKeys.REMOTE_QUERY)
+
+  const [exchange] = await remoteQuery(
+    remoteQueryObjectFromString({
+      entryPoint: "order_exchange",
+      variables: {
+        id,
+      },
+      fields: ["return_id"],
+    }),
+    undefined,
+    {
+      throwIfKeyNotFound: true,
+    }
+  )
+
+  const { result } = await updateRequestItemReturnWorkflow(req.scope).run({
+    input: {
+      data: { ...req.validatedBody },
+      return_id: exchange.return_id,
+      exchange_id: exchange.id,
+      action_id,
+    },
+  })
+
+  const queryObject = remoteQueryObjectFromString({
+    entryPoint: "return",
+    variables: {
+      id: exchange.return_id,
+    },
+    fields: defaultAdminDetailsReturnFields,
+  })
+
+  const [orderReturn] = await remoteQuery(queryObject)
+
+  res.json({
+    order_preview: result,
+    return: orderReturn,
+  })
+}
+
+export const DELETE = async (
+  req: AuthenticatedMedusaRequest,
+  res: MedusaResponse
+) => {
+  const remoteQuery = req.scope.resolve(ContainerRegistrationKeys.REMOTE_QUERY)
+
+  const { id, action_id } = req.params
+
+  const { result: orderPreview } = await removeItemReturnActionWorkflow(
+    req.scope
+  ).run({
+    input: {
+      return_id: id,
+      action_id,
+    },
+  })
+
+  const queryObject = remoteQueryObjectFromString({
+    entryPoint: "return",
+    variables: {
+      id,
+      filters: {
+        ...req.filterableFields,
+      },
+    },
+    fields: req.remoteQueryConfig.fields,
+  })
+  const [orderReturn] = await remoteQuery(queryObject)
+
+  res.json({
+    order_preview: orderPreview,
+    return: orderReturn,
+  })
+}

packages/medusa/src/api/admin/exchanges/[id]/inbound/items/route.ts

@@ -0,0 +1,60 @@
+import { orderExchangeRequestItemReturnWorkflow } from "@medusajs/core-flows"
+import {
+  ContainerRegistrationKeys,
+  remoteQueryObjectFromString,
+} from "@medusajs/utils"
+
+import {
+  AuthenticatedMedusaRequest,
+  MedusaResponse,
+} from "../../../../../../types/routing"
+import { defaultAdminDetailsReturnFields } from "../../../../returns/query-config"
+import { AdminPostExchangesReturnRequestItemsReqSchemaType } from "../../../validators"
+
+export const POST = async (
+  req: AuthenticatedMedusaRequest<AdminPostExchangesReturnRequestItemsReqSchemaType>,
+  res: MedusaResponse
+) => {
+  const { id } = req.params
+
+  const remoteQuery = req.scope.resolve(ContainerRegistrationKeys.REMOTE_QUERY)
+
+  const [exchange] = await remoteQuery(
+    remoteQueryObjectFromString({
+      entryPoint: "order_exchange",
+      variables: {
+        id,
+      },
+      fields: ["return_id"],
+    }),
+    undefined,
+    {
+      throwIfKeyNotFound: true,
+    }
+  )
+
+  const { result } = await orderExchangeRequestItemReturnWorkflow(
+    req.scope
+  ).run({
+    input: {
+      ...req.validatedBody,
+      return_id: exchange.return_id,
+      exchange_id: id,
+    },
+  })
+
+  const queryObject = remoteQueryObjectFromString({
+    entryPoint: "return",
+    variables: {
+      id: exchange.return_id,
+    },
+    fields: defaultAdminDetailsReturnFields,
+  })
+
+  const [orderReturn] = await remoteQuery(queryObject)
+
+  res.json({
+    order_preview: result,
+    return: orderReturn,
+  })
+}

packages/medusa/src/api/admin/exchanges/[id]/inbound/shipping-method/[action_id]/route.ts

@@ -0,0 +1,110 @@
+import {
+  removeReturnShippingMethodWorkflow,
+  updateReturnShippingMethodWorkflow,
+} from "@medusajs/core-flows"
+import {
+  ContainerRegistrationKeys,
+  remoteQueryObjectFromString,
+} from "@medusajs/utils"
+import {
+  AuthenticatedMedusaRequest,
+  MedusaResponse,
+} from "../../../../../../../types/routing"
+import { defaultAdminDetailsReturnFields } from "../../../../../returns/query-config"
+import { AdminPostExchangesShippingActionReqSchemaType } from "../../../../validators"
+
+export const POST = async (
+  req: AuthenticatedMedusaRequest<AdminPostExchangesShippingActionReqSchemaType>,
+  res: MedusaResponse
+) => {
+  const { id, action_id } = req.params
+
+  const remoteQuery = req.scope.resolve(ContainerRegistrationKeys.REMOTE_QUERY)
+
+  const [exchange] = await remoteQuery(
+    remoteQueryObjectFromString({
+      entryPoint: "order_exchange",
+      variables: {
+        id,
+      },
+      fields: ["return_id"],
+    }),
+    undefined,
+    {
+      throwIfKeyNotFound: true,
+    }
+  )
+
+  const { result } = await updateReturnShippingMethodWorkflow(req.scope).run({
+    input: {
+      data: { ...req.validatedBody },
+      return_id: exchange.return_id,
+      action_id,
+    },
+  })
+
+  const queryObject = remoteQueryObjectFromString({
+    entryPoint: "order_exchange",
+    variables: {
+      id,
+      filters: {
+        ...req.filterableFields,
+      },
+    },
+    fields: req.remoteQueryConfig.fields,
+  })
+
+  const [orderExchange] = await remoteQuery(queryObject)
+
+  res.json({
+    order_preview: result,
+    exchange: orderExchange,
+  })
+}
+
+export const DELETE = async (
+  req: AuthenticatedMedusaRequest,
+  res: MedusaResponse
+) => {
+  const remoteQuery = req.scope.resolve(ContainerRegistrationKeys.REMOTE_QUERY)
+
+  const { id, action_id } = req.params
+
+  const [exchange] = await remoteQuery(
+    remoteQueryObjectFromString({
+      entryPoint: "order_exchange",
+      variables: {
+        id,
+      },
+      fields: ["return_id"],
+    }),
+    undefined,
+    {
+      throwIfKeyNotFound: true,
+    }
+  )
+
+  const { result: orderPreview } = await removeReturnShippingMethodWorkflow(
+    req.scope
+  ).run({
+    input: {
+      return_id: exchange.return_id,
+      action_id,
+    },
+  })
+
+  const queryObject = remoteQueryObjectFromString({
+    entryPoint: "return",
+    variables: {
+      id: exchange.return_id,
+    },
+    fields: defaultAdminDetailsReturnFields,
+  })
+
+  const [orderReturn] = await remoteQuery(queryObject)
+
+  res.json({
+    order_preview: orderPreview,
+    return: orderReturn,
+  })
+}

packages/medusa/src/api/admin/exchanges/[id]/inbound/shipping-method/route.ts

@@ -0,0 +1,58 @@
+import { createExchangeShippingMethodWorkflow } from "@medusajs/core-flows"
+import {
+  ContainerRegistrationKeys,
+  remoteQueryObjectFromString,
+} from "@medusajs/utils"
+
+import {
+  AuthenticatedMedusaRequest,
+  MedusaResponse,
+} from "../../../../../../types/routing"
+import { defaultAdminDetailsReturnFields } from "../../../../returns/query-config"
+import { AdminPostReturnsShippingReqSchemaType } from "../../../../returns/validators"
+
+export const POST = async (
+  req: AuthenticatedMedusaRequest<AdminPostReturnsShippingReqSchemaType>,
+  res: MedusaResponse
+) => {
+  const { id } = req.params
+
+  const remoteQuery = req.scope.resolve(ContainerRegistrationKeys.REMOTE_QUERY)
+
+  const [exchange] = await remoteQuery(
+    remoteQueryObjectFromString({
+      entryPoint: "order_exchange",
+      variables: {
+        id,
+      },
+      fields: ["return_id"],
+    }),
+    undefined,
+    {
+      throwIfKeyNotFound: true,
+    }
+  )
+
+  const { result } = await createExchangeShippingMethodWorkflow(req.scope).run({
+    input: {
+      ...req.validatedBody,
+      return_id: exchange.return_id,
+      exchange_id: id,
+    },
+  })
+
+  const queryObject = remoteQueryObjectFromString({
+    entryPoint: "return",
+    variables: {
+      id: exchange.return_id,
+    },
+    fields: defaultAdminDetailsReturnFields,
+  })
+
+  const [orderReturn] = await remoteQuery(queryObject)
+
+  res.json({
+    order_preview: result,
+    return: orderReturn,
+  })
+}

packages/medusa/src/api/admin/exchanges/[id]/outbound/items/[action_id]/route.ts

@@ -0,0 +1,83 @@
+import {
+  removeItemExchangeActionWorkflow,
+  updateExchangeAddItemWorkflow,
+} from "@medusajs/core-flows"
+import {
+  ContainerRegistrationKeys,
+  remoteQueryObjectFromString,
+} from "@medusajs/utils"
+import {
+  AuthenticatedMedusaRequest,
+  MedusaResponse,
+} from "../../../../../../../types/routing"
+import { AdminPostExhangesItemsActionReqSchemaType } from "../../../../validators"
+
+export const POST = async (
+  req: AuthenticatedMedusaRequest<AdminPostExhangesItemsActionReqSchemaType>,
+  res: MedusaResponse
+) => {
+  const { id, action_id } = req.params
+
+  const remoteQuery = req.scope.resolve(ContainerRegistrationKeys.REMOTE_QUERY)
+
+  const { result } = await updateExchangeAddItemWorkflow(req.scope).run({
+    input: {
+      data: { ...req.validatedBody },
+      exchange_id: id,
+      action_id,
+    },
+  })
+
+  const queryObject = remoteQueryObjectFromString({
+    entryPoint: "order_exchange",
+    variables: {
+      id,
+      filters: {
+        ...req.filterableFields,
+      },
+    },
+    fields: req.remoteQueryConfig.fields,
+  })
+
+  const [orderExchange] = await remoteQuery(queryObject)
+
+  res.json({
+    order_preview: result,
+    exchange: orderExchange,
+  })
+}
+
+export const DELETE = async (
+  req: AuthenticatedMedusaRequest,
+  res: MedusaResponse
+) => {
+  const remoteQuery = req.scope.resolve(ContainerRegistrationKeys.REMOTE_QUERY)
+
+  const { id, action_id } = req.params
+
+  const { result: orderPreview } = await removeItemExchangeActionWorkflow(
+    req.scope
+  ).run({
+    input: {
+      exchange_id: id,
+      action_id,
+    },
+  })
+
+  const queryObject = remoteQueryObjectFromString({
+    entryPoint: "order_exchange",
+    variables: {
+      id,
+      filters: {
+        ...req.filterableFields,
+      },
+    },
+    fields: req.remoteQueryConfig.fields,
+  })
+  const [orderExchange] = await remoteQuery(queryObject)
+
+  res.json({
+    order_preview: orderPreview,
+    exchange: orderExchange,
+  })
+}

packages/medusa/src/api/admin/exchanges/[id]/outbound/items/route.ts

@@ -0,0 +1,42 @@
+import { orderExchangeAddNewItemWorkflow } from "@medusajs/core-flows"
+import {
+  ContainerRegistrationKeys,
+  remoteQueryObjectFromString,
+} from "@medusajs/utils"
+
+import {
+  AuthenticatedMedusaRequest,
+  MedusaResponse,
+} from "../../../../../../types/routing"
+import { AdminPostExchangesAddItemsReqSchemaType } from "../../../validators"
+
+export const POST = async (
+  req: AuthenticatedMedusaRequest<AdminPostExchangesAddItemsReqSchemaType>,
+  res: MedusaResponse
+) => {
+  const { id } = req.params
+
+  const remoteQuery = req.scope.resolve(ContainerRegistrationKeys.REMOTE_QUERY)
+
+  const { result } = await orderExchangeAddNewItemWorkflow(req.scope).run({
+    input: { ...req.validatedBody, exchange_id: id },
+  })
+
+  const queryObject = remoteQueryObjectFromString({
+    entryPoint: "order_exchange",
+    variables: {
+      id,
+      filters: {
+        ...req.filterableFields,
+      },
+    },
+    fields: req.remoteQueryConfig.fields,
+  })
+
+  const [orderExchange] = await remoteQuery(queryObject)
+
+  res.json({
+    order_preview: result,
+    exchange: orderExchange,
+  })
+}

packages/medusa/src/api/admin/exchanges/[id]/outbound/shipping-method/[action_id]/route.ts

@@ -0,0 +1,83 @@
+import {
+  removeExchangeShippingMethodWorkflow,
+  updateExchangeShippingMethodWorkflow,
+} from "@medusajs/core-flows"
+import {
+  ContainerRegistrationKeys,
+  remoteQueryObjectFromString,
+} from "@medusajs/utils"
+import {
+  AuthenticatedMedusaRequest,
+  MedusaResponse,
+} from "../../../../../../../types/routing"
+import { AdminPostExchangesShippingActionReqSchemaType } from "../../../../validators"
+
+export const POST = async (
+  req: AuthenticatedMedusaRequest<AdminPostExchangesShippingActionReqSchemaType>,
+  res: MedusaResponse
+) => {
+  const { id, action_id } = req.params
+
+  const remoteQuery = req.scope.resolve(ContainerRegistrationKeys.REMOTE_QUERY)
+
+  const { result } = await updateExchangeShippingMethodWorkflow(req.scope).run({
+    input: {
+      data: { ...req.validatedBody },
+      exchange_id: id,
+      action_id,
+    },
+  })
+
+  const queryObject = remoteQueryObjectFromString({
+    entryPoint: "order_exchange",
+    variables: {
+      id,
+      filters: {
+        ...req.filterableFields,
+      },
+    },
+    fields: req.remoteQueryConfig.fields,
+  })
+
+  const [orderExchange] = await remoteQuery(queryObject)
+
+  res.json({
+    order_preview: result,
+    exchange: orderExchange,
+  })
+}
+
+export const DELETE = async (
+  req: AuthenticatedMedusaRequest,
+  res: MedusaResponse
+) => {
+  const remoteQuery = req.scope.resolve(ContainerRegistrationKeys.REMOTE_QUERY)
+
+  const { id, action_id } = req.params
+
+  const { result: orderPreview } = await removeExchangeShippingMethodWorkflow(
+    req.scope
+  ).run({
+    input: {
+      exchange_id: id,
+      action_id,
+    },
+  })
+
+  const queryObject = remoteQueryObjectFromString({
+    entryPoint: "order_exchange",
+    variables: {
+      id,
+      filters: {
+        ...req.filterableFields,
+      },
+    },
+    fields: req.remoteQueryConfig.fields,
+  })
+  const [orderExchange] = await remoteQuery(queryObject)
+
+  res.json({
+    order_preview: orderPreview,
+    exchange: orderExchange,
+  })
+}

packages/medusa/src/api/admin/exchanges/[id]/outbound/shipping-method/route.ts

@@ -0,0 +1,41 @@
+import { createExchangeShippingMethodWorkflow } from "@medusajs/core-flows"
+import {
+  ContainerRegistrationKeys,
+  remoteQueryObjectFromString,
+} from "@medusajs/utils"
+import {
+  AuthenticatedMedusaRequest,
+  MedusaResponse,
+} from "../../../../../../types/routing"
+import { AdminPostExchangesShippingReqSchemaType } from "../../../validators"
+
+export const POST = async (
+  req: AuthenticatedMedusaRequest<AdminPostExchangesShippingReqSchemaType>,
+  res: MedusaResponse
+) => {
+  const { id } = req.params
+
+  const remoteQuery = req.scope.resolve(ContainerRegistrationKeys.REMOTE_QUERY)
+
+  const { result } = await createExchangeShippingMethodWorkflow(req.scope).run({
+    input: { ...req.validatedBody, exchange_id: id },
+  })
+
+  const queryObject = remoteQueryObjectFromString({
+    entryPoint: "order_exchange",
+    variables: {
+      id,
+      filters: {
+        ...req.filterableFields,
+      },
+    },
+    fields: req.remoteQueryConfig.fields,
+  })
+
+  const [orderExchange] = await remoteQuery(queryObject)
+
+  res.json({
+    order_preview: result,
+    exchange: orderExchange,
+  })
+}

packages/medusa/src/api/admin/exchanges/[id]/request/route.ts

@@ -0,0 +1,80 @@
+import {
+  cancelBeginOrderExchangeWorkflow,
+  confirmExchangeRequestWorkflow,
+} from "@medusajs/core-flows"
+import {
+  ContainerRegistrationKeys,
+  remoteQueryObjectFromString,
+} from "@medusajs/utils"
+import {
+  AuthenticatedMedusaRequest,
+  MedusaResponse,
+} from "../../../../../types/routing"
+import { defaultAdminDetailsReturnFields } from "../../../returns/query-config"
+
+export const POST = async (
+  req: AuthenticatedMedusaRequest,
+  res: MedusaResponse
+) => {
+  const { id } = req.params
+
+  const remoteQuery = req.scope.resolve(ContainerRegistrationKeys.REMOTE_QUERY)
+
+  const { result } = await confirmExchangeRequestWorkflow(req.scope).run({
+    input: { exchange_id: id },
+  })
+
+  const queryObject = remoteQueryObjectFromString({
+    entryPoint: "order_exchange",
+    variables: {
+      id,
+      filters: {
+        ...req.filterableFields,
+      },
+    },
+    fields: req.remoteQueryConfig.fields,
+  })
+
+  const [orderExchange] = await remoteQuery(queryObject, undefined, {
+    throwIfKeyNotFound: true,
+  })
+
+  let orderReturn
+  if (orderExchange.return_id) {
+    const [orderReturnData] = await remoteQuery(
+      remoteQueryObjectFromString({
+        entryPoint: "return",
+        variables: {
+          id: orderExchange.return_id,
+        },
+        fields: defaultAdminDetailsReturnFields,
+      })
+    )
+    orderReturn = orderReturnData
+  }
+
+  res.json({
+    order_preview: result,
+    exchange: orderExchange,
+    return: orderReturn,
+  })
+}
+
+export const DELETE = async (
+  req: AuthenticatedMedusaRequest,
+  res: MedusaResponse
+) => {
+  const { id } = req.params
+
+  await cancelBeginOrderExchangeWorkflow(req.scope).run({
+    input: {
+      exchange_id: id,
+    },
+  })
+
+  res.status(200).json({
+    id,
+    object: "exchange",
+    deleted: true,
+  })
+}

packages/medusa/src/api/admin/exchanges/middlewares.ts

@@ -0,0 +1,212 @@
+import { MiddlewareRoute } from "@medusajs/framework"
+import { validateAndTransformBody } from "../../utils/validate-body"
+import { validateAndTransformQuery } from "../../utils/validate-query"
+import * as QueryConfig from "./query-config"
+import {
+  AdminGetOrdersOrderParams,
+  AdminGetOrdersParams,
+  AdminPostCancelExchangeReqSchema,
+  AdminPostExchangesAddItemsReqSchema,
+  AdminPostExchangesRequestItemsReturnActionReqSchema,
+  AdminPostExchangesReturnRequestItemsReqSchema,
+  AdminPostExchangesShippingActionReqSchema,
+  AdminPostExchangesShippingReqSchema,
+  AdminPostExhangesItemsActionReqSchema,
+  AdminPostOrderExchangesReqSchema,
+} from "./validators"
+
+export const adminExchangeRoutesMiddlewares: MiddlewareRoute[] = [
+  {
+    method: ["GET"],
+    matcher: "/admin/exchanges",
+    middlewares: [
+      validateAndTransformQuery(
+        AdminGetOrdersParams,
+        QueryConfig.listTransformQueryConfig
+      ),
+    ],
+  },
+  {
+    method: ["GET"],
+    matcher: "/admin/exchanges/:id",
+    middlewares: [
+      validateAndTransformQuery(
+        AdminGetOrdersOrderParams,
+        QueryConfig.retrieveTransformQueryConfig
+      ),
+    ],
+  },
+  {
+    method: ["POST"],
+    matcher: "/admin/exchanges",
+    middlewares: [
+      validateAndTransformBody(AdminPostOrderExchangesReqSchema),
+      validateAndTransformQuery(
+        AdminGetOrdersOrderParams,
+        QueryConfig.retrieveTransformQueryConfig
+      ),
+    ],
+  },
+  {
+    method: ["POST"],
+    matcher: "/admin/exchanges/:id/inbound/items",
+    middlewares: [
+      validateAndTransformBody(AdminPostExchangesReturnRequestItemsReqSchema),
+      validateAndTransformQuery(
+        AdminGetOrdersOrderParams,
+        QueryConfig.retrieveTransformQueryConfig
+      ),
+    ],
+  },
+  {
+    method: ["POST"],
+    matcher: "/admin/exchanges/:id/inbound/items/:action_id",
+    middlewares: [
+      validateAndTransformBody(
+        AdminPostExchangesRequestItemsReturnActionReqSchema
+      ),
+      validateAndTransformQuery(
+        AdminGetOrdersOrderParams,
+        QueryConfig.retrieveTransformQueryConfig
+      ),
+    ],
+  },
+  {
+    method: ["DELETE"],
+    matcher: "/admin/exchanges/:id/inbound/items/:action_id",
+    middlewares: [
+      validateAndTransformQuery(
+        AdminGetOrdersOrderParams,
+        QueryConfig.retrieveTransformQueryConfig
+      ),
+    ],
+  },
+  {
+    method: ["POST"],
+    matcher: "/admin/exchanges/:id/inbound/shipping-method",
+    middlewares: [
+      validateAndTransformBody(AdminPostExchangesShippingReqSchema),
+      validateAndTransformQuery(
+        AdminGetOrdersOrderParams,
+        QueryConfig.retrieveTransformQueryConfig
+      ),
+    ],
+  },
+  {
+    method: ["POST"],
+    matcher: "/admin/exchanges/:id/inbound/shipping-method/:action_id",
+    middlewares: [
+      validateAndTransformBody(AdminPostExchangesShippingActionReqSchema),
+      validateAndTransformQuery(
+        AdminGetOrdersOrderParams,
+        QueryConfig.retrieveTransformQueryConfig
+      ),
+    ],
+  },
+  {
+    method: ["DELETE"],
+    matcher: "/admin/exchanges/:id/inbound/shipping-method/:action_id",
+    middlewares: [
+      validateAndTransformQuery(
+        AdminGetOrdersOrderParams,
+        QueryConfig.retrieveTransformQueryConfig
+      ),
+    ],
+  },
+
+  {
+    method: ["POST"],
+    matcher: "/admin/exchanges/:id/outbound/items",
+    middlewares: [
+      validateAndTransformBody(AdminPostExchangesAddItemsReqSchema),
+      validateAndTransformQuery(
+        AdminGetOrdersOrderParams,
+        QueryConfig.retrieveTransformQueryConfig
+      ),
+    ],
+  },
+  {
+    method: ["POST"],
+    matcher: "/admin/exchanges/:id/outbound/items/:action_id",
+    middlewares: [
+      validateAndTransformBody(AdminPostExhangesItemsActionReqSchema),
+      validateAndTransformQuery(
+        AdminGetOrdersOrderParams,
+        QueryConfig.retrieveTransformQueryConfig
+      ),
+    ],
+  },
+  {
+    method: ["DELETE"],
+    matcher: "/admin/exchanges/:id/outbound/items/:action_id",
+    middlewares: [
+      validateAndTransformQuery(
+        AdminGetOrdersOrderParams,
+        QueryConfig.retrieveTransformQueryConfig
+      ),
+    ],
+  },
+  {
+    method: ["POST"],
+    matcher: "/admin/exchanges/:id/outbound/shipping-method",
+    middlewares: [
+      validateAndTransformBody(AdminPostExchangesShippingReqSchema),
+      validateAndTransformQuery(
+        AdminGetOrdersOrderParams,
+        QueryConfig.retrieveTransformQueryConfig
+      ),
+    ],
+  },
+  {
+    method: ["POST"],
+    matcher: "/admin/exchanges/:id/outbound/shipping-method/:action_id",
+    middlewares: [
+      validateAndTransformBody(AdminPostExchangesShippingActionReqSchema),
+      validateAndTransformQuery(
+        AdminGetOrdersOrderParams,
+        QueryConfig.retrieveTransformQueryConfig
+      ),
+    ],
+  },
+  {
+    method: ["DELETE"],
+    matcher: "/admin/exchanges/:id/outbound/shipping-method/:action_id",
+    middlewares: [
+      validateAndTransformQuery(
+        AdminGetOrdersOrderParams,
+        QueryConfig.retrieveTransformQueryConfig
+      ),
+    ],
+  },
+  {
+    method: ["POST"],
+    matcher: "/admin/exchanges/:id/request",
+    middlewares: [
+      validateAndTransformQuery(
+        AdminGetOrdersOrderParams,
+        QueryConfig.retrieveTransformQueryConfig
+      ),
+    ],
+  },
+  {
+    method: ["DELETE"],
+    matcher: "/admin/exchanges/:id/request",
+    middlewares: [],
+  },
+  {
+    method: ["DELETE"],
+    matcher: "/admin/exchanges/:id",
+    middlewares: [],
+  },
+  {
+    method: ["POST"],
+    matcher: "/admin/exchanges/:id/cancel",
+    middlewares: [
+      validateAndTransformBody(AdminPostCancelExchangeReqSchema),
+      validateAndTransformQuery(
+        AdminGetOrdersOrderParams,
+        QueryConfig.retrieveTransformQueryConfig
+      ),
+    ],
+  },
+]

packages/medusa/src/api/admin/exchanges/query-config.ts

@@ -0,0 +1,27 @@
+export const defaultAdminExchangeFields = [
+  "id",
+  "type",
+  "order_id",
+  "return_id",
+  "display_id",
+  "order_version",
+  "created_at",
+  "updated_at",
+  "canceled_at",
+]
+
+export const defaultAdminDetailsExchangeFields = [
+  ...defaultAdminExchangeFields,
+  "additional_items.*",
+]
+
+export const retrieveTransformQueryConfig = {
+  defaultFields: defaultAdminDetailsExchangeFields,
+  isList: false,
+}
+
+export const listTransformQueryConfig = {
+  defaults: defaultAdminExchangeFields,
+  defaultLimit: 20,
+  isList: true,
+}

packages/medusa/src/api/admin/exchanges/route.ts

@@ -0,0 +1,74 @@
+import { beginExchangeOrderWorkflow } from "@medusajs/core-flows"
+import {
+  ContainerRegistrationKeys,
+  ModuleRegistrationName,
+  promiseAll,
+  remoteQueryObjectFromString,
+} from "@medusajs/utils"
+import {
+  AuthenticatedMedusaRequest,
+  MedusaResponse,
+} from "../../../types/routing"
+import { AdminPostOrderExchangesReqSchemaType } from "./validators"
+
+export const GET = async (
+  req: AuthenticatedMedusaRequest,
+  res: MedusaResponse
+) => {
+  const remoteQuery = req.scope.resolve(ContainerRegistrationKeys.REMOTE_QUERY)
+
+  const queryObject = remoteQueryObjectFromString({
+    entryPoint: "order_exchanges",
+    variables: {
+      filters: {
+        ...req.filterableFields,
+      },
+      ...req.remoteQueryConfig.pagination,
+    },
+    fields: req.remoteQueryConfig.fields,
+  })
+
+  const { rows: exchanges, metadata } = await remoteQuery(queryObject)
+
+  res.json({
+    exchanges,
+    count: metadata.count,
+    offset: metadata.skip,
+    limit: metadata.take,
+  })
+}
+
+export const POST = async (
+  req: AuthenticatedMedusaRequest<AdminPostOrderExchangesReqSchemaType>,
+  res: MedusaResponse
+) => {
+  const input = req.validatedBody as AdminPostOrderExchangesReqSchemaType
+  const remoteQuery = req.scope.resolve(ContainerRegistrationKeys.REMOTE_QUERY)
+  const orderModuleService = req.scope.resolve(ModuleRegistrationName.ORDER)
+
+  const workflow = beginExchangeOrderWorkflow(req.scope)
+  const { result } = await workflow.run({
+    input,
+  })
+
+  const queryObject = remoteQueryObjectFromString({
+    entryPoint: "order_exchange",
+    variables: {
+      id: result.exchange_id,
+      filters: {
+        ...req.filterableFields,
+      },
+    },
+    fields: req.remoteQueryConfig.fields,
+  })
+
+  const [order, orderExchange] = await promiseAll([
+    orderModuleService.retrieveOrder(result.order_id),
+    remoteQuery(queryObject),
+  ])
+
+  res.json({
+    order,
+    exchange: orderExchange[0],
+  })
+}

packages/medusa/src/api/admin/exchanges/validators.ts

@@ -0,0 +1,170 @@
+import { z } from "zod"
+import {
+  createFindParams,
+  createOperatorMap,
+  createSelectParams,
+} from "../../utils/validators"
+
+export const AdminGetOrdersOrderParams = createSelectParams().merge(
+  z.object({
+    id: z.union([z.string(), z.array(z.string())]).optional(),
+    status: z.union([z.string(), z.array(z.string())]).optional(),
+    created_at: createOperatorMap().optional(),
+    updated_at: createOperatorMap().optional(),
+    deleted_at: createOperatorMap().optional(),
+  })
+)
+
+export type AdminGetOrdersOrderParamsType = z.infer<
+  typeof AdminGetOrdersOrderParams
+>
+
+/**
+ * Parameters used to filter and configure the pagination of the retrieved order.
+ */
+export const AdminGetOrdersParams = createFindParams({
+  limit: 15,
+  offset: 0,
+}).merge(
+  z.object({
+    id: z.union([z.string(), z.array(z.string())]).optional(),
+    order_id: z.union([z.string(), z.array(z.string())]).optional(),
+    status: z.union([z.string(), z.array(z.string())]).optional(),
+    created_at: createOperatorMap().optional(),
+    updated_at: createOperatorMap().optional(),
+    deleted_at: createOperatorMap().optional(),
+  })
+)
+
+export type AdminGetOrdersParamsType = z.infer<typeof AdminGetOrdersParams>
+
+export const AdminPostOrderExchangesReqSchema = z.object({
+  order_id: z.string(),
+  description: z.string().optional(),
+  internal_note: z.string().optional(),
+  metadata: z.record(z.unknown()).nullish(),
+})
+export type AdminPostOrderExchangesReqSchemaType = z.infer<
+  typeof AdminPostOrderExchangesReqSchema
+>
+
+export const AdminPostReceiveExchangesReqSchema = z.object({
+  internal_note: z.string().optional(),
+  description: z.string().optional(),
+  metadata: z.record(z.unknown()).nullish(),
+})
+export type AdminPostReceiveExchangesReqSchemaType = z.infer<
+  typeof AdminPostReceiveExchangesReqSchema
+>
+
+const ReceiveItemSchema = z.object({
+  id: z.string(),
+  quantity: z.number().min(1),
+  internal_note: z.string().optional(),
+})
+export const AdminPostReceiveExchangeItemsReqSchema = z.object({
+  items: z.array(ReceiveItemSchema),
+})
+export type AdminPostReceiveExchangeItemsReqSchemaType = z.infer<
+  typeof AdminPostReceiveExchangeItemsReqSchema
+>
+
+export const AdminPostCancelExchangeReqSchema = z.object({
+  no_notification: z.boolean().optional(),
+})
+export type AdminPostCancelExchangeReqSchemaType = z.infer<
+  typeof AdminPostCancelExchangeReqSchema
+>
+
+export const AdminPostExchangesRequestItemsReturnActionReqSchema = z.object({
+  quantity: z.number().optional(),
+  internal_note: z.string().nullish().optional(),
+  reason_id: z.string().nullish().optional(),
+  metadata: z.record(z.unknown()).nullish().optional(),
+})
+
+export type AdminPostExchangesRequestItemsReturnActionReqSchemaType = z.infer<
+  typeof AdminPostExchangesRequestItemsReturnActionReqSchema
+>
+
+export const AdminPostExchangesShippingReqSchema = z.object({
+  shipping_option_id: z.string(),
+  custom_price: z.number().optional(),
+  description: z.string().optional(),
+  internal_note: z.string().optional(),
+  metadata: z.record(z.unknown()).optional(),
+})
+
+export type AdminPostExchangesShippingReqSchemaType = z.infer<
+  typeof AdminPostExchangesShippingReqSchema
+>
+
+export const AdminPostExchangesShippingActionReqSchema = z.object({
+  custom_price: z.number().optional(),
+  internal_note: z.string().nullish().optional(),
+  metadata: z.record(z.unknown()).nullish().optional(),
+})
+
+export type AdminPostExchangesShippingActionReqSchemaType = z.infer<
+  typeof AdminPostExchangesShippingActionReqSchema
+>
+
+export const AdminPostExchangesAddItemsReqSchema = z.object({
+  items: z.array(
+    z.object({
+      variant_id: z.string(),
+      quantity: z.number(),
+      unit_price: z.number().optional(),
+      internal_note: z.string().optional(),
+      allow_backorder: z.boolean().optional(),
+      metadata: z.record(z.unknown()).optional(),
+    })
+  ),
+})
+
+export type AdminPostExchangesAddItemsReqSchemaType = z.infer<
+  typeof AdminPostExchangesAddItemsReqSchema
+>
+
+export const AdminPostExchangesReturnRequestItemsReqSchema = z.object({
+  items: z.array(
+    z.object({
+      id: z.string(),
+      quantity: z.number(),
+      description: z.string().optional(),
+      internal_note: z.string().optional(),
+      reason_id: z.string().optional(),
+      metadata: z.record(z.unknown()).optional(),
+    })
+  ),
+})
+
+export type AdminPostExchangesReturnRequestItemsReqSchemaType = z.infer<
+  typeof AdminPostExchangesReturnRequestItemsReqSchema
+>
+
+export const AdminPostExchangesDismissItemsActionReqSchema = z.object({
+  quantity: z.number().optional(),
+  internal_note: z.string().nullish().optional(),
+})
+
+export type AdminPostExchangesDismissItemsActionReqSchemaType = z.infer<
+  typeof AdminPostExchangesDismissItemsActionReqSchema
+>
+
+export const AdminPostExchangesConfirmRequestReqSchema = z.object({
+  no_notification: z.boolean().optional(),
+})
+
+export type AdminPostExchangesConfirmRequestReqSchemaType = z.infer<
+  typeof AdminPostExchangesConfirmRequestReqSchema
+>
+
+export const AdminPostExhangesItemsActionReqSchema = z.object({
+  quantity: z.number().optional(),
+  internal_note: z.string().nullish().optional(),
+})
+
+export type AdminPostExhangesItemsActionReqSchemaType = z.infer<
+  typeof AdminPostExhangesItemsActionReqSchema
+>

packages/medusa/src/api/middlewares.ts

@@ -7,6 +7,7 @@ import { adminCurrencyRoutesMiddlewares } from "./admin/currencies/middlewares"
 import { adminCustomerGroupRoutesMiddlewares } from "./admin/customer-groups/middlewares"
 import { adminCustomerRoutesMiddlewares } from "./admin/customers/middlewares"
 import { adminDraftOrderRoutesMiddlewares } from "./admin/draft-orders/middlewares"
+import { adminExchangeRoutesMiddlewares } from "./admin/exchanges/middlewares"
 import { adminFulfillmentProvidersRoutesMiddlewares } from "./admin/fulfillment-providers/middlewares"
 import { adminFulfillmentSetsRoutesMiddlewares } from "./admin/fulfillment-sets/middlewares"
 import { adminFulfillmentsRoutesMiddlewares } from "./admin/fulfillments/middlewares"
@@ -106,4 +107,5 @@ export default defineMiddlewares([
   ...storeReturnReasonRoutesMiddlewares,
   ...adminReturnReasonRoutesMiddlewares,
   ...adminClaimRoutesMiddlewares,
+  ...adminExchangeRoutesMiddlewares,
 ])