Skip to main content

​
Workflows

​
createOrderReturnRequestWorkflow

This documentation provides a reference to the createOrderReturnRequestWorkflow. It belongs to the @mercurjs/requests package. This workflow creates an order return request from a customer. It validates that no return request already exists for the order, verifies that line items and return reasons are valid, creates the request, and links it to both the seller and the order. It exposes a hook for custom extensions. Source code

​
Examples

packages/modules/requests/src/api/store/return-request/route.ts
import {
  AuthenticatedMedusaRequest,
  MedusaResponse,
} from "@medusajs/framework";
import { ContainerRegistrationKeys } from "@medusajs/framework/utils";
import { SELLER_ORDER_LINK } from "@mercurjs/framework";
import { createOrderReturnRequestWorkflow } from "../../../workflows/order-return-request/workflows";
import { StoreCreateReturnRequestType } from "./validators";

export async function POST(
  req: AuthenticatedMedusaRequest<StoreCreateReturnRequestType>,
  res: MedusaResponse
): Promise<void> {
  const query = req.scope.resolve(ContainerRegistrationKeys.QUERY);

  const {
    data: [resource],
  } = await query.graph({
    entity: SELLER_ORDER_LINK,
    fields: ["seller_id"],
    filters: {
      order_id: req.validatedBody.order_id,
    },
  });

  const { result: order_return_request } =
    await createOrderReturnRequestWorkflow.run({
      container: req.scope,
      input: {
        data: { ...req.validatedBody, customer_id: req.auth_context.actor_id },
        seller_id: resource.seller_id,
      },
    });

  res.json({ order_return_request });
}

​
Steps

  • validateOrderReturnRequestStep: Validates that no return request exists, line items are valid, and return reasons exist.
  • createOrderReturnRequestStep: Creates the return request record.
  • createRemoteLinkStep: Creates links between the return request and the seller, and between the return request and the order.

​
Hooks

  • orderReturnRequestCreated: Hook that fires after a return request is created, providing the requestId.

​
Input

​
input
object
required
The return request creation details.

​
Output

​
OrderReturnRequestDTO
OrderReturnRequestDTO
The created order return request.

​
proceedReturnRequestWorkflow

This documentation provides a reference to the proceedReturnRequestWorkflow. It belongs to the @mercurjs/requests package. This workflow processes the actual return after a return request has been approved (status set to “refunded”). It begins the return order process, requests the item returns, and confirms the return. This workflow is nested within the updateOrderReturnRequestWorkflow. Source code

​
Examples

packages/modules/requests/src/workflows/order-return-request/workflows/update-return-request.ts
import { proceedReturnRequestWorkflow } from "./proceed-return-request";

// ... inside updateOrderReturnRequestWorkflow

when(input, (input) => input.status === "refunded").then(() => {
  proceedReturnRequestWorkflow.runAsStep({ input });
});

​
Steps

  • retrieveOrderFromReturnRequestStep: Retrieves the order and return request details.
  • beginReturnOrderWorkflow: Begins the return order process using Medusa’s core workflow.
  • requestItemReturnWorkflow: Requests the specific items to be returned using Medusa’s core workflow.
  • confirmReturnRequestWorkflow: Confirms the return request using Medusa’s core workflow.

​
Input

​
input
VendorUpdateOrderReturnRequestDTO | AdminUpdateOrderReturnRequestDTO
required
The return request update details (must have status “refunded”).

​
Output

​
object
object

​
updateOrderReturnRequestWorkflow

This documentation provides a reference to the updateOrderReturnRequestWorkflow. It belongs to the @mercurjs/requests package. This workflow updates an order return request. When the status is set to “refunded”, it automatically triggers the return processing workflow. After updating, it links any created returns to the seller. It exposes a hook for custom extensions. Source code

​
Examples

packages/modules/requests/src/api/vendor/return-request/[id]/route.ts
import { AuthenticatedMedusaRequest, MedusaResponse } from '@medusajs/framework'
import {
  ContainerRegistrationKeys,
  MedusaError
} from '@medusajs/framework/utils'
import { updateOrderReturnRequestWorkflow } from '../../../../workflows/order-return-request/workflows'
import { VendorUpdateOrderReturnRequestType } from '../validators'

export const POST = async (
  req: AuthenticatedMedusaRequest<VendorUpdateOrderReturnRequestType>,
  res: MedusaResponse
) => {
  const query = req.scope.resolve(ContainerRegistrationKeys.QUERY)

  const {
    data: [request]
  } = await query.graph({
    entity: 'order_return_request',
    fields: req.queryConfig.fields,
    filters: {
      id: req.params.id,
      status: 'pending'
    }
  })

  if (!request) {
    throw new MedusaError(
      MedusaError.Types.INVALID_ARGUMENT,
      'Request is not in pending state!'
    )
  }

  const { result: order_return_request } =
    await updateOrderReturnRequestWorkflow.run({
      input: {
        id: req.params.id,
        ...req.validatedBody,
        vendor_reviewer_id: req.auth_context.actor_id,
        vendor_review_date: new Date()
      },
      container: req.scope
    })

  res.json({ order_return_request })
}

​
Steps

  • updateOrderReturnRequestStep: Updates the return request status and reviewer details.
  • proceedReturnRequestWorkflow: Processes the return (only when status is “refunded”).
  • useQueryGraphStep: Retrieves order and return details for linking.
  • createRemoteLinkStep: Links any created returns to the seller.

​
Hooks

  • orderReturnRequestUpdated: Hook that fires after a return request is updated, providing the requestId.

​
Input

​
input
VendorUpdateOrderReturnRequestDTO | AdminUpdateOrderReturnRequestDTO
required
The return request update details.

​
Output

​
OrderReturnRequestDTO
OrderReturnRequestDTO
The updated order return request.

​
Steps

​
createOrderReturnRequestStep

Creates an order return request record in the database. Source code

​
Input

​
input
CreateOrderReturnRequestDTO
required
The return request creation details.

​
Output

​
OrderReturnRequestDTO
OrderReturnRequestDTO
The created return request.

​
retrieveOrderFromReturnRequestStep

Retrieves the order and complete return request details including line items and seller information. Used to prepare data for return processing. Source code

​
Input

​
request
VendorUpdateOrderReturnRequestDTO | AdminUpdateOrderReturnRequestDTO
required
The return request with the ID to retrieve.

​
Output

​
object
object

​
updateOrderReturnRequestStep

Updates an order return request record. This step includes a compensation function that restores the previous request state if a subsequent step in the workflow fails. Source code

​
Input

​
input
VendorUpdateOrderReturnRequestDTO | AdminUpdateOrderReturnRequestDTO
required
The return request update details.

​
Output

​
OrderReturnRequestDTO
OrderReturnRequestDTO
The updated return request.

​
validateOrderReturnRequestStep

Validates a return request creation by checking:
  1. No return request already exists for the order
  2. All line item IDs belong to the order
  3. All return reason IDs are valid
Source code

​
Input

​
input
CreateOrderReturnRequestDTO
required
The return request data to validate.

​
Output

​
boolean
boolean
Returns true if validation passes. Throws an INVALID_ARGUMENT error if:
  • A return request already exists for the order
  • Any line item ID is invalid
  • Any return reason ID is invalid