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

What: * `POST /admin/returns/:id/receive` * `DELETE /admin/returns/:id/receive` CLOSES: CC-189
2024-07-18 09:55:04 -03:00
parent 8ffcec3fc4
commit 1a472733ae
29 changed files with 371 additions and 72 deletions
--- a/integration-tests/http/tests/returns/returns.spec.ts
+++ b/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",
+            })
+          )
+        })
+      })
    })
  },
 })
--- a/packages/core/core-flows/src/order/workflows/claim/claim-add-new-item.ts
+++ b/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,
--- a/packages/core/core-flows/src/order/workflows/claim/claim-request-item-return.ts
+++ b/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,
--- a/packages/core/core-flows/src/order/workflows/exchange/exchange-add-new-item.ts
+++ b/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,
--- a/packages/core/core-flows/src/order/workflows/exchange/exchange-request-item-return.ts
+++ b/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,
--- a/packages/core/core-flows/src/order/workflows/index.ts
+++ b/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"
--- a/packages/core/core-flows/src/order/workflows/return/begin-receive-return.ts
+++ b/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)
+  }
+)
--- a/packages/core/core-flows/src/order/workflows/return/begin-return.ts
+++ b/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 { createReturnsStep } from "../../steps/create-returns"
+import { createOrderChangeStep, createReturnsStep } from "../../steps"
 import { throwIfOrderIsCancelled } from "../../utils/order-validation"

 const validationStep = createStep(
--- a/packages/core/core-flows/src/order/workflows/return/cancel-receive-return.ts
+++ b/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] })
+  }
+)
--- a/packages/core/core-flows/src/order/workflows/return/cancel-request-return.ts
+++ b/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,
--- a/packages/core/core-flows/src/order/workflows/return/cancel-return.ts
+++ b/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",
--- a/packages/core/core-flows/src/order/workflows/return/confirm-return-request.ts
+++ b/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,
--- a/packages/core/core-flows/src/order/workflows/return/create-complete-return.ts
+++ b/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 { createReturnFulfillmentWorkflow } from "../../fulfillment"
-import { createCompleteReturnStep } from "../steps/create-complete-return"
-import { receiveReturnStep } from "../steps/receive-return"
+import { createRemoteLinkStep, useRemoteQueryStep } from "../../../common"
+import { createReturnFulfillmentWorkflow } from "../../../fulfillment"
+import { createCompleteReturnStep } from "../../steps/create-complete-return"
+import { receiveReturnStep } from "../../steps/receive-return"
 import {
  throwIfItemsDoesNotExistsInOrder,
  throwIfOrderIsCancelled,
-} from "../utils/order-validation"
-import { validateReturnReasons } from "../utils/validate-return-reason"
+} from "../../utils/order-validation"
+import { validateReturnReasons } from "../../utils/validate-return-reason"

 function prepareShippingMethodData({
  orderId,
--- a/packages/core/core-flows/src/order/workflows/return/create-return-shipping-method.ts
+++ b/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,
--- a/packages/core/core-flows/src/order/workflows/return/receive-complete-return.ts
+++ b/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 receiveReturnOrderWorkflow = createWorkflow(
-  receiveReturnOrderWorkflowId,
+export const receiveAndCompleteReturnOrderWorkflowId = "receive-return-order"
+export const receiveAndCompleteReturnOrderWorkflow = createWorkflow(
+  receiveAndCompleteReturnOrderWorkflowId,
  function (
-    input: WorkflowData<OrderWorkflow.ReceiveOrderReturnWorkflowInput>
+    input: WorkflowData<OrderWorkflow.ReceiveCompleteOrderReturnWorkflowInput>
  ): WorkflowData<ReturnDTO> {
    const orderReturn: ReturnDTO = useRemoteQueryStep({
      entry_point: "returns",
--- a/packages/core/core-flows/src/order/workflows/return/remove-request-item-return.ts
+++ b/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,
--- a/packages/core/core-flows/src/order/workflows/return/remove-return-shipping-method.ts
+++ b/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,
--- a/packages/core/core-flows/src/order/workflows/return/request-item-return.ts
+++ b/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,
--- a/packages/core/core-flows/src/order/workflows/return/update-request-item-return.ts
+++ b/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,
--- a/packages/core/core-flows/src/order/workflows/return/update-return-shipping-method.ts
+++ b/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,
--- a/packages/core/types/src/order/mutations.ts
+++ b/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
--- a/packages/core/types/src/workflow/order/receive-return.ts
+++ b/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
-  reason_id?: string | null
-  note?: string | null
-  metadata?: Record<string, any>
+  internal_note?: string
+  metadata?: Record<string, any> | null
 }

-export interface ReceiveOrderReturnWorkflowInput {
+export interface BeginReceiveOrderReturnWorkflowInput {
  return_id: string
-  created_by?: string | null // The id of the authenticated user
-  items: ReceiveReturnItem[]
-  internal_note?: string | null
+  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[]
+}
+
+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
 }
--- a/packages/medusa/src/api/admin/returns/[id]/cancel/route.ts
+++ b/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 })
--- a/packages/medusa/src/api/admin/returns/[id]/receive/route.ts
+++ b/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,
+  })
 }
--- a/packages/medusa/src/api/admin/returns/middlewares.ts
+++ b/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: [],
+  },
 ]
--- a/packages/medusa/src/api/admin/returns/route.ts
+++ b/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,
-    return: orderReturn,
+    order,
+    return: orderReturn[0],
  })
 }
--- a/packages/medusa/src/api/admin/returns/validators.ts
+++ b/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(),
-  items: z.array(ItemSchema),
-  internal_note: z.string().nullish(),
+  internal_note: z.string().optional(),
+  description: z.string().optional(),
+  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({
--- a/packages/modules/order/src/services/actions/receive-return.ts
+++ b/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,
    },
  }))
 }
--- a/packages/modules/order/src/services/order-module-service.ts
+++ b/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: {},