chore(medusa,core-flows): begin and cancel receive return (#8171)

What:
* `POST /admin/returns/:id/receive` 
* `DELETE /admin/returns/:id/receive`

CLOSES: CC-189

integration-tests/http/__tests__/returns/returns.spec.ts

@@ -201,12 +201,11 @@ medusaIntegrationTestRunner({
           })
         )
 
-        expect(result.data.order_preview).toEqual(
+        expect(result.data.order.order_change).toEqual(
           expect.objectContaining({
             id: expect.any(String),
             return_id: returnId,
             change_type: "return",
-            actions: [],
             description: "Test",
             status: "pending",
             order_id: order.id,
@@ -578,6 +577,63 @@ medusaIntegrationTestRunner({
           `Return id not found: ${returnId}`
         )
       })
+
+      describe("should request a return and receive if", () => {
+        let returnId
+        beforeEach(async () => {
+          let result = await api.post(
+            "/admin/returns",
+            {
+              order_id: order.id,
+              description: "Test",
+            },
+            adminHeaders
+          )
+
+          returnId = result.data.return.id
+          const item = order.items[0]
+          await api.post(
+            `/admin/returns/${returnId}/request-items`,
+            {
+              items: [
+                {
+                  id: item.id,
+                  quantity: 2,
+                  reason_id: returnReason.id,
+                },
+              ],
+            },
+            adminHeaders
+          )
+          await api.post(
+            `/admin/returns/${returnId}/shipping-method`,
+            {
+              shipping_option_id: returnShippingOption.id,
+            },
+            adminHeaders
+          )
+          await api.post(`/admin/returns/${returnId}/request`, {}, adminHeaders)
+        })
+
+        it("should receive the return", async () => {
+          let result = await api.post(
+            `/admin/returns/${returnId}/receive`,
+            {
+              internal_note: "Test internal note",
+            },
+            adminHeaders
+          )
+
+          expect(result.data.order.order_change).toEqual(
+            expect.objectContaining({
+              return_id: returnId,
+              change_type: "return",
+              status: "pending",
+              internal_note: "Test internal note",
+            })
+          )
+        })
+      })
     })
   },
 })

packages/core/core-flows/src/order/workflows/claim/claim-add-new-item.ts

@@ -46,7 +46,7 @@ export const orderClaimAddNewItemWorkflow = createWorkflow(
   ): WorkflowData<OrderDTO> {
     const orderClaim = useRemoteQueryStep({
       entry_point: "order_claim",
-      fields: ["id", "order_id"],
+      fields: ["id", "order_id", "canceled_at"],
       variables: { id: input.claim_id },
       list: false,
       throw_if_key_not_found: true,
@@ -54,7 +54,7 @@ export const orderClaimAddNewItemWorkflow = createWorkflow(
 
     const order: OrderDTO = useRemoteQueryStep({
       entry_point: "orders",
-      fields: ["id", "status", "items.*"],
+      fields: ["id", "status", "canceled_at", "items.*"],
       variables: { id: orderClaim.order_id },
       list: false,
       throw_if_key_not_found: true,

packages/core/core-flows/src/order/workflows/claim/claim-request-item-return.ts

@@ -56,7 +56,7 @@ export const orderClaimRequestItemReturnWorkflow = createWorkflow(
   ): WorkflowData<OrderDTO> {
     const orderClaim = useRemoteQueryStep({
       entry_point: "order_claim",
-      fields: ["id", "order_id", "return_id"],
+      fields: ["id", "order_id", "return_id", "canceled_at"],
       variables: { id: input.claim_id },
       list: false,
       throw_if_key_not_found: true,
@@ -67,7 +67,7 @@ export const orderClaimRequestItemReturnWorkflow = createWorkflow(
     }).then(() => {
       return useRemoteQueryStep({
         entry_point: "return",
-        fields: ["id", "status", "order_id"],
+        fields: ["id", "status", "order_id", "canceled_at"],
         variables: { id: orderClaim.return_id },
         list: false,
         throw_if_key_not_found: true,

packages/core/core-flows/src/order/workflows/exchange/exchange-add-new-item.ts

@@ -46,7 +46,7 @@ export const orderExchangeAddNewItemWorkflow = createWorkflow(
   ): WorkflowData<OrderDTO> {
     const orderExchange = useRemoteQueryStep({
       entry_point: "order_exchange",
-      fields: ["id", "order_id"],
+      fields: ["id", "order_id", "canceled_at"],
       variables: { id: input.exchange_id },
       list: false,
       throw_if_key_not_found: true,
@@ -54,7 +54,7 @@ export const orderExchangeAddNewItemWorkflow = createWorkflow(
 
     const order: OrderDTO = useRemoteQueryStep({
       entry_point: "orders",
-      fields: ["id", "status", "items.*"],
+      fields: ["id", "status", "canceled_at", "items.*"],
       variables: { id: orderExchange.order_id },
       list: false,
       throw_if_key_not_found: true,

packages/core/core-flows/src/order/workflows/exchange/exchange-request-item-return.ts

@@ -57,7 +57,7 @@ export const orderExchangeRequestItemReturnWorkflow = createWorkflow(
   ): WorkflowData<OrderDTO> {
     const orderExchange = useRemoteQueryStep({
       entry_point: "order_exchange",
-      fields: ["id", "order_id", "return_id"],
+      fields: ["id", "order_id", "return_id", "canceled_at"],
       variables: { id: input.exchange_id },
       list: false,
       throw_if_key_not_found: true,
@@ -68,7 +68,7 @@ export const orderExchangeRequestItemReturnWorkflow = createWorkflow(
     }).then(() => {
       return useRemoteQueryStep({
         entry_point: "return",
-        fields: ["id", "status", "order_id"],
+        fields: ["id", "status", "order_id", "canceled_at"],
         variables: { id: orderExchange.return_id },
         list: false,
         throw_if_key_not_found: true,

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

@@ -6,7 +6,6 @@ export * from "./cancel-order-fulfillment"
 export * from "./claim/begin-order-claim"
 export * from "./claim/claim-request-item-return"
 export * from "./complete-orders"
-export * from "./create-complete-return"
 export * from "./create-fulfillment"
 export * from "./create-order-change"
 export * from "./create-order-change-actions"
@@ -21,12 +20,15 @@ export * from "./exchange/exchange-add-new-item"
 export * from "./exchange/exchange-request-item-return"
 export * from "./get-order-detail"
 export * from "./get-orders-list"
+export * from "./return/begin-receive-return"
 export * from "./return/begin-return"
+export * from "./return/cancel-receive-return"
 export * from "./return/cancel-request-return"
 export * from "./return/cancel-return"
 export * from "./return/confirm-return-request"
+export * from "./return/create-complete-return"
 export * from "./return/create-return-shipping-method"
-export * from "./return/receive-return"
+export * from "./return/receive-complete-return"
 export * from "./return/remove-request-item-return"
 export * from "./return/remove-return-shipping-method"
 export * from "./return/request-item-return"

packages/core/core-flows/src/order/workflows/return/begin-receive-return.ts

@@ -0,0 +1,73 @@
+import {
+  OrderChangeDTO,
+  OrderDTO,
+  OrderWorkflow,
+  ReturnDTO,
+} from "@medusajs/types"
+import {
+  WorkflowData,
+  createStep,
+  createWorkflow,
+  transform,
+} from "@medusajs/workflows-sdk"
+import { useRemoteQueryStep } from "../../../common"
+import { createOrderChangeStep } from "../../steps"
+import { throwIfIsCancelled } from "../../utils/order-validation"
+
+const validationStep = createStep(
+  "begin-receive-return-validation",
+  async function (
+    {
+      orderReturn,
+      order,
+    }: {
+      orderReturn: ReturnDTO
+      order: OrderDTO
+    },
+    context
+  ) {
+    throwIfIsCancelled(order, "Order")
+    throwIfIsCancelled(orderReturn, "Return")
+  }
+)
+
+export const beginReceiveReturnWorkflowId = "begin-receive-return"
+export const beginReceiveReturnWorkflow = createWorkflow(
+  beginReceiveReturnWorkflowId,
+  function (
+    input: WorkflowData<OrderWorkflow.BeginReceiveOrderReturnWorkflowInput>
+  ): WorkflowData<OrderChangeDTO> {
+    const orderReturn: ReturnDTO = useRemoteQueryStep({
+      entry_point: "return",
+      fields: ["id", "status", "order_id", "canceled_at"],
+      variables: { id: input.return_id },
+      list: false,
+      throw_if_key_not_found: true,
+    })
+
+    const order: OrderDTO = useRemoteQueryStep({
+      entry_point: "orders",
+      fields: ["id", "version", "status", "canceled_at"],
+      variables: { id: orderReturn.order_id },
+      list: false,
+      throw_if_key_not_found: true,
+    }).config({ name: "order-query" })
+
+    validationStep({ order, orderReturn })
+
+    const orderChangeInput = transform(
+      { orderReturn, order, input },
+      ({ orderReturn, order, input }) => {
+        return {
+          change_type: "return" as const,
+          order_id: order.id,
+          return_id: orderReturn.id,
+          created_by: input.created_by,
+          description: input.description,
+          internal_note: input.internal_note,
+        }
+      }
+    )
+    return createOrderChangeStep(orderChangeInput)
+  }
+)

packages/core/core-flows/src/order/workflows/return/begin-return.ts

@@ -6,8 +6,7 @@ import {
   transform,
 } from "@medusajs/workflows-sdk"
 import { useRemoteQueryStep } from "../../../common"
-import { createOrderChangeStep } from "../../steps/create-order-change"
+import { createOrderChangeStep, createReturnsStep } from "../../steps"
-import { createReturnsStep } from "../../steps/create-returns"
 import { throwIfOrderIsCancelled } from "../../utils/order-validation"
 
 const validationStep = createStep(

packages/core/core-flows/src/order/workflows/return/cancel-receive-return.ts

@@ -0,0 +1,69 @@
+import { OrderChangeDTO, OrderDTO, ReturnDTO } from "@medusajs/types"
+import { OrderChangeStatus } from "@medusajs/utils"
+import {
+  WorkflowData,
+  createStep,
+  createWorkflow,
+} from "@medusajs/workflows-sdk"
+import { useRemoteQueryStep } from "../../../common"
+import { deleteOrderChangesStep } from "../../steps"
+import {
+  throwIfIsCancelled,
+  throwIfOrderChangeIsNotActive,
+} from "../../utils/order-validation"
+
+const validationStep = createStep(
+  "validate-cancel-return-shipping-method",
+  async function ({
+    order,
+    orderChange,
+    orderReturn,
+  }: {
+    order: OrderDTO
+    orderReturn: ReturnDTO
+    orderChange: OrderChangeDTO
+  }) {
+    throwIfIsCancelled(order, "Order")
+    throwIfIsCancelled(orderReturn, "Return")
+    throwIfOrderChangeIsNotActive({ orderChange })
+  }
+)
+
+export const cancelReturnReceiveWorkflowId = "cancel-receive-return"
+export const cancelReturnReceiveWorkflow = createWorkflow(
+  cancelReturnReceiveWorkflowId,
+  function (input: { return_id: string }): WorkflowData<void> {
+    const orderReturn: ReturnDTO = useRemoteQueryStep({
+      entry_point: "return",
+      fields: ["id", "status", "order_id", "canceled_at"],
+      variables: { id: input.return_id },
+      list: false,
+      throw_if_key_not_found: true,
+    })
+
+    const order: OrderDTO = useRemoteQueryStep({
+      entry_point: "orders",
+      fields: ["id", "version", "canceled_at"],
+      variables: { id: orderReturn.order_id },
+      list: false,
+      throw_if_key_not_found: true,
+    }).config({ name: "order-query" })
+
+    const orderChange: OrderChangeDTO = useRemoteQueryStep({
+      entry_point: "order_change",
+      fields: ["id", "status", "version"],
+      variables: {
+        filters: {
+          order_id: orderReturn.order_id,
+          return_id: orderReturn.id,
+          status: [OrderChangeStatus.PENDING, OrderChangeStatus.REQUESTED],
+        },
+      },
+      list: false,
+    }).config({ name: "order-change-query" })
+
+    validationStep({ order, orderReturn, orderChange })
+
+    deleteOrderChangesStep({ ids: [orderChange.id] })
+  }
+)

packages/core/core-flows/src/order/workflows/return/cancel-request-return.ts

@@ -45,7 +45,7 @@ export const cancelReturnRequestWorkflow = createWorkflow(
   function (input: WorkflowInput): WorkflowData<void> {
     const orderReturn: ReturnDTO = useRemoteQueryStep({
       entry_point: "return",
-      fields: ["id", "status", "order_id"],
+      fields: ["id", "status", "order_id", "canceled_at"],
       variables: { id: input.return_id },
       list: false,
       throw_if_key_not_found: true,
@@ -53,7 +53,7 @@ export const cancelReturnRequestWorkflow = createWorkflow(
 
     const order: OrderDTO = useRemoteQueryStep({
       entry_point: "orders",
-      fields: ["id", "version", "items"],
+      fields: ["id", "version", "canceled_at"],
       variables: { id: orderReturn.order_id },
       list: false,
       throw_if_key_not_found: true,

packages/core/core-flows/src/order/workflows/return/cancel-return.ts

@@ -67,6 +67,7 @@ export const cancelReturnWorkflow = createWorkflow(
         entry_point: "return",
         fields: [
           "id",
+          "canceled_at",
           "items.id",
           "items.received_quantity",
           "fulfillments.canceled_at",

packages/core/core-flows/src/order/workflows/return/confirm-return-request.ts

@@ -42,7 +42,7 @@ export const confirmReturnRequestWorkflow = createWorkflow(
   function (input: WorkflowInput): WorkflowData<OrderDTO> {
     const orderReturn: ReturnDTO = useRemoteQueryStep({
       entry_point: "return",
-      fields: ["id", "status", "order_id"],
+      fields: ["id", "status", "order_id", "canceled_at"],
       variables: { id: input.return_id },
       list: false,
       throw_if_key_not_found: true,
@@ -50,7 +50,7 @@ export const confirmReturnRequestWorkflow = createWorkflow(
 
     const order: OrderDTO = useRemoteQueryStep({
       entry_point: "orders",
-      fields: ["id", "version", "items"],
+      fields: ["id", "version", "canceled_at"],
       variables: { id: orderReturn.order_id },
       list: false,
       throw_if_key_not_found: true,

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

@@ -15,15 +15,15 @@ import {
   parallelize,
   transform,
 } from "@medusajs/workflows-sdk"
-import { createRemoteLinkStep, useRemoteQueryStep } from "../../common"
+import { createRemoteLinkStep, useRemoteQueryStep } from "../../../common"
-import { createReturnFulfillmentWorkflow } from "../../fulfillment"
+import { createReturnFulfillmentWorkflow } from "../../../fulfillment"
-import { createCompleteReturnStep } from "../steps/create-complete-return"
+import { createCompleteReturnStep } from "../../steps/create-complete-return"
-import { receiveReturnStep } from "../steps/receive-return"
+import { receiveReturnStep } from "../../steps/receive-return"
 import {
   throwIfItemsDoesNotExistsInOrder,
   throwIfOrderIsCancelled,
-} from "../utils/order-validation"
+} from "../../utils/order-validation"
-import { validateReturnReasons } from "../utils/validate-return-reason"
+import { validateReturnReasons } from "../../utils/validate-return-reason"
 
 function prepareShippingMethodData({
   orderId,

packages/core/core-flows/src/order/workflows/return/create-return-shipping-method.ts

@@ -48,7 +48,7 @@ export const createReturnShippingMethodWorkflow = createWorkflow(
   }): WorkflowData<OrderDTO> {
     const orderReturn: ReturnDTO = useRemoteQueryStep({
       entry_point: "return",
-      fields: ["id", "status", "order_id"],
+      fields: ["id", "status", "order_id", "canceled_at"],
       variables: { id: input.return_id },
       list: false,
       throw_if_key_not_found: true,
@@ -56,7 +56,7 @@ export const createReturnShippingMethodWorkflow = createWorkflow(
 
     const order: OrderDTO = useRemoteQueryStep({
       entry_point: "orders",
-      fields: ["id", "status", "currency_code"],
+      fields: ["id", "status", "currency_code", "canceled_at"],
       variables: { id: orderReturn.order_id },
       list: false,
       throw_if_key_not_found: true,

packages/core/core-flows/src/order/workflows/return/receive-complete-return.ts

@@ -21,7 +21,7 @@ const validationStep = createStep(
       input,
     }: {
       orderReturn
-      input: OrderWorkflow.ReceiveOrderReturnWorkflowInput
+      input: OrderWorkflow.ReceiveCompleteOrderReturnWorkflowInput
     },
     context
   ) {
@@ -30,11 +30,11 @@ const validationStep = createStep(
   }
 )
 
-export const receiveReturnOrderWorkflowId = "receive-return-order"
+export const receiveAndCompleteReturnOrderWorkflowId = "receive-return-order"
-export const receiveReturnOrderWorkflow = createWorkflow(
+export const receiveAndCompleteReturnOrderWorkflow = createWorkflow(
-  receiveReturnOrderWorkflowId,
+  receiveAndCompleteReturnOrderWorkflowId,
   function (
-    input: WorkflowData<OrderWorkflow.ReceiveOrderReturnWorkflowInput>
+    input: WorkflowData<OrderWorkflow.ReceiveCompleteOrderReturnWorkflowInput>
   ): WorkflowData<ReturnDTO> {
     const orderReturn: ReturnDTO = useRemoteQueryStep({
       entry_point: "returns",

packages/core/core-flows/src/order/workflows/return/remove-request-item-return.ts

@@ -62,7 +62,7 @@ export const removeRequestItemReturnWorkflow = createWorkflow(
   ): WorkflowData<OrderDTO> {
     const orderReturn: ReturnDTO = useRemoteQueryStep({
       entry_point: "return",
-      fields: ["id", "status", "order_id"],
+      fields: ["id", "status", "order_id", "canceled_at"],
       variables: { id: input.return_id },
       list: false,
       throw_if_key_not_found: true,
@@ -70,7 +70,7 @@ export const removeRequestItemReturnWorkflow = createWorkflow(
 
     const order: OrderDTO = useRemoteQueryStep({
       entry_point: "orders",
-      fields: ["id", "status", "items.*"],
+      fields: ["id", "status", "canceled_at", "items.*"],
       variables: { id: orderReturn.order_id },
       list: false,
       throw_if_key_not_found: true,

packages/core/core-flows/src/order/workflows/return/remove-return-shipping-method.ts

@@ -60,7 +60,7 @@ export const removeReturnShippingMethodWorkflow = createWorkflow(
   ): WorkflowData {
     const orderReturn: ReturnDTO = useRemoteQueryStep({
       entry_point: "return",
-      fields: ["id", "status", "order_id"],
+      fields: ["id", "status", "order_id", "canceled_at"],
       variables: { id: input.return_id },
       list: false,
       throw_if_key_not_found: true,

packages/core/core-flows/src/order/workflows/return/request-item-return.ts

@@ -57,7 +57,7 @@ export const requestItemReturnWorkflow = createWorkflow(
   ): WorkflowData<OrderDTO> {
     const orderReturn: ReturnDTO = useRemoteQueryStep({
       entry_point: "return",
-      fields: ["id", "status", "order_id"],
+      fields: ["id", "status", "order_id", "canceled_at"],
       variables: { id: input.return_id },
       list: false,
       throw_if_key_not_found: true,
@@ -65,7 +65,7 @@ export const requestItemReturnWorkflow = createWorkflow(
 
     const order: OrderDTO = useRemoteQueryStep({
       entry_point: "orders",
-      fields: ["id", "status", "items.*"],
+      fields: ["id", "status", "canceled_at", "items.*"],
       variables: { id: orderReturn.order_id },
       list: false,
       throw_if_key_not_found: true,

packages/core/core-flows/src/order/workflows/return/update-request-item-return.ts

@@ -77,7 +77,7 @@ export const updateRequestItemReturnWorkflow = createWorkflow(
   ): WorkflowData<OrderDTO> {
     const orderReturn: ReturnDTO = useRemoteQueryStep({
       entry_point: "return",
-      fields: ["id", "status", "order_id"],
+      fields: ["id", "status", "order_id", "canceled_at"],
       variables: { id: input.return_id },
       list: false,
       throw_if_key_not_found: true,
@@ -85,7 +85,7 @@ export const updateRequestItemReturnWorkflow = createWorkflow(
 
     const order: OrderDTO = useRemoteQueryStep({
       entry_point: "orders",
-      fields: ["id", "status", "items.*"],
+      fields: ["id", "status", "canceled_at", "items.*"],
       variables: { id: orderReturn.order_id },
       list: false,
       throw_if_key_not_found: true,

packages/core/core-flows/src/order/workflows/return/update-return-shipping-method.ts

@@ -62,7 +62,7 @@ export const updateReturnShippingMethodWorkflow = createWorkflow(
   ): WorkflowData {
     const orderReturn: ReturnDTO = useRemoteQueryStep({
       entry_point: "return",
-      fields: ["id", "status", "order_id"],
+      fields: ["id", "status", "order_id", "canceled_at"],
       variables: { id: input.return_id },
       list: false,
       throw_if_key_not_found: true,

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

@@ -387,7 +387,7 @@ export interface UpdateOrderItemWithSelectorDTO {
 interface BaseOrderBundledItemActionsDTO {
   id: string
   quantity: BigNumberInput
-  internal_note?: string | null
+  internal_note?: string
   note?: string | null
   metadata?: Record<string, unknown> | null
   [key: string]: any
@@ -399,7 +399,7 @@ interface BaseOrderBundledActionsDTO {
   exchange_id?: string
 
   description?: string
-  internal_note?: string | null
+  internal_note?: string
   reference?: string
   reference_id?: string
   created_by?: string | null
@@ -445,6 +445,7 @@ export interface UpdateReturnDTO {
   metadata?: Record<string, unknown> | null
   items?: {
     quantity: BigNumberInput
+    internal_note?: string | null
     note?: string | null
     reason_id?: string | null
     metadata?: Record<string, unknown> | null

packages/core/types/src/workflow/order/receive-return.ts

@@ -3,15 +3,28 @@ import { BigNumberInput } from "../../totals"
 interface ReceiveReturnItem {
   id: string
   quantity: BigNumberInput
-  internal_note?: string | null
+  internal_note?: string
-  reason_id?: string | null
+  metadata?: Record<string, any> | null
-  note?: string | null
-  metadata?: Record<string, any>
 }
 
-export interface ReceiveOrderReturnWorkflowInput {
+export interface BeginReceiveOrderReturnWorkflowInput {
   return_id: string
-  created_by?: string | null // The id of the authenticated user
+  created_by?: string // The id of the authenticated user
+  description?: string
+  internal_note?: string
+  metadata?: Record<string, any> | null
+}
+
+export interface ReceiveOrderReturnItemsWorkflowInput {
+  return_id: string
   items: ReceiveReturnItem[]
-  internal_note?: string | null
+}
+
+export interface ReceiveCompleteOrderReturnWorkflowInput {
+  return_id: string
+  created_by?: string // The id of the authenticated user
+  items: ReceiveReturnItem[]
+  description?: string
+  internal_note?: string
+  metadata?: Record<string, any> | null
 }

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

@@ -6,14 +6,17 @@ import {
 import { AdminPostCancelReturnReqSchemaType } from "../../validators"
 
 export const POST = async (
-  req: AuthenticatedMedusaRequest,
+  req: AuthenticatedMedusaRequest<AdminPostCancelReturnReqSchemaType>,
   res: MedusaResponse
 ) => {
-  const input = req.validatedBody as AdminPostCancelReturnReqSchemaType
+  const { id } = req.params
 
   const workflow = cancelReturnWorkflow(req.scope)
   const { result } = await workflow.run({
-    input,
+    input: {
+      ...req.validatedBody,
+      return_id: id,
+    },
   })
 
   res.status(200).json({ return: result })

packages/medusa/src/api/admin/returns/[id]/receive/route.ts

@@ -1,4 +1,13 @@
-import { receiveReturnOrderWorkflow } from "@medusajs/core-flows"
+import {
+  beginReceiveReturnWorkflow,
+  cancelReturnReceiveWorkflow,
+} from "@medusajs/core-flows"
+import {
+  ContainerRegistrationKeys,
+  ModuleRegistrationName,
+  promiseAll,
+  remoteQueryObjectFromString,
+} from "@medusajs/utils"
 import {
   AuthenticatedMedusaRequest,
   MedusaResponse,
@@ -9,12 +18,56 @@ export const POST = async (
   req: AuthenticatedMedusaRequest<AdminPostReceiveReturnsReqSchemaType>,
   res: MedusaResponse
 ) => {
-  const input = req.validatedBody as AdminPostReceiveReturnsReqSchemaType
+  const remoteQuery = req.scope.resolve(ContainerRegistrationKeys.REMOTE_QUERY)
+  const orderModuleService = req.scope.resolve(ModuleRegistrationName.ORDER)
 
-  const workflow = receiveReturnOrderWorkflow(req.scope)
+  const { id } = req.params
+
+  const workflow = beginReceiveReturnWorkflow(req.scope)
   const { result } = await workflow.run({
-    input,
+    input: {
+      ...req.validatedBody,
+      return_id: id,
+    },
   })
 
-  res.status(200).json({ return: result })
+  const queryObject = remoteQueryObjectFromString({
+    entryPoint: "return",
+    variables: {
+      id: result.return_id,
+      filters: {
+        ...req.filterableFields,
+      },
+    },
+    fields: req.remoteQueryConfig.fields,
+  })
+
+  const [order, orderReturn] = await promiseAll([
+    orderModuleService.retrieveOrder(result.order_id),
+    remoteQuery(queryObject),
+  ])
+
+  res.json({
+    order,
+    return: orderReturn[0],
+  })
+}
+
+export const DELETE = async (
+  req: AuthenticatedMedusaRequest,
+  res: MedusaResponse
+) => {
+  const { id } = req.params
+
+  await cancelReturnReceiveWorkflow(req.scope).run({
+    input: {
+      return_id: id,
+    },
+  })
+
+  res.status(200).json({
+    id,
+    object: "return",
+    deleted: true,
+  })
 }

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

@@ -5,6 +5,7 @@ import * as QueryConfig from "./query-config"
 import {
   AdminGetOrdersOrderParams,
   AdminGetOrdersParams,
+  AdminPostReceiveReturnsReqSchema,
   AdminPostReturnsConfirmRequestReqSchema,
   AdminPostReturnsReqSchema,
   AdminPostReturnsRequestItemsActionReqSchema,
@@ -125,4 +126,20 @@ export const adminReturnRoutesMiddlewares: MiddlewareRoute[] = [
     matcher: "/admin/returns/:id/request",
     middlewares: [],
   },
+  {
+    method: ["POST"],
+    matcher: "/admin/returns/:id/receive",
+    middlewares: [
+      validateAndTransformBody(AdminPostReceiveReturnsReqSchema),
+      validateAndTransformQuery(
+        AdminGetOrdersOrderParams,
+        QueryConfig.retrieveTransformQueryConfig
+      ),
+    ],
+  },
+  {
+    method: ["DELETE"],
+    matcher: "/admin/returns/:id/receive",
+    middlewares: [],
+  },
 ]

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

@@ -1,6 +1,8 @@
 import { beginReturnOrderWorkflow } from "@medusajs/core-flows"
 import {
   ContainerRegistrationKeys,
+  ModuleRegistrationName,
+  promiseAll,
   remoteQueryObjectFromString,
 } from "@medusajs/utils"
 import {
@@ -42,6 +44,7 @@ export const POST = async (
 ) => {
   const input = req.validatedBody as AdminPostReturnsReqSchemaType
   const remoteQuery = req.scope.resolve(ContainerRegistrationKeys.REMOTE_QUERY)
+  const orderModuleService = req.scope.resolve(ModuleRegistrationName.ORDER)
 
   const workflow = beginReturnOrderWorkflow(req.scope)
   const { result } = await workflow.run({
@@ -59,10 +62,13 @@ export const POST = async (
     fields: req.remoteQueryConfig.fields,
   })
 
-  const [orderReturn] = await remoteQuery(queryObject)
+  const [order, orderReturn] = await promiseAll([
+    orderModuleService.retrieveOrder(result.order_id),
+    remoteQuery(queryObject),
+  ])
 
   res.json({
-    order_preview: result,
+    order,
-    return: orderReturn,
+    return: orderReturn[0],
   })
 }

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

@@ -38,13 +38,6 @@ export const AdminGetOrdersParams = createFindParams({
 
 export type AdminGetOrdersParamsType = z.infer<typeof AdminGetOrdersParams>
 
-const ItemSchema = z.object({
-  id: z.string(),
-  quantity: z.number().min(1),
-  reason_id: z.string().nullish(),
-  note: z.string().optional(),
-})
-
 export const AdminPostReturnsReqSchema = z.object({
   order_id: z.string(),
   location_id: z.string().optional(),
@@ -79,21 +72,33 @@ export type AdminPostOrderExchangesReqSchemaType = z.infer<
 >
 
 export const AdminPostReceiveReturnsReqSchema = z.object({
-  return_id: z.string(),
+  internal_note: z.string().optional(),
-  items: z.array(ItemSchema),
+  description: z.string().optional(),
-  internal_note: z.string().nullish(),
+  metadata: z.record(z.unknown()).nullish(),
 })
 export type AdminPostReceiveReturnsReqSchemaType = z.infer<
   typeof AdminPostReceiveReturnsReqSchema
 >
 
+const ReceiveItemSchema = z.object({
+  id: z.string(),
+  quantity: z.number().min(1),
+  internal_note: z.string().optional(),
+})
+export const AdminPostReceiveReturnItemsReqSchema = z.object({
+  items: z.array(ReceiveItemSchema),
+})
+export type AdminPostReceiveReturnItemsReqSchemaType = z.infer<
+  typeof AdminPostReceiveReturnItemsReqSchema
+>
+
 export const AdminPostCancelReturnReqSchema = z.object({
   return_id: z.string(),
   no_notification: z.boolean().optional(),
   internal_note: z.string().nullish(),
 })
 export type AdminPostCancelReturnReqSchemaType = z.infer<
-  typeof AdminPostReceiveReturnsReqSchema
+  typeof AdminPostCancelReturnReqSchema
 >
 
 export const AdminPostReturnsShippingReqSchema = z.object({

packages/modules/order/src/services/actions/receive-return.ts

@@ -16,7 +16,6 @@ function createReturnItems(data) {
     details: {
       reference_id: item.id,
       quantity: item.quantity,
-      metadata: item.metadata,
     },
   }))
 }

packages/modules/order/src/services/order-module-service.ts

@@ -2478,6 +2478,8 @@ export default class OrderModuleService<
         "requested_at",
         "requested_by",
         "status",
+        "description",
+        "internal_note",
       ],
       relations: [] as string[],
       order: {},