Streamlining ESHOPMAN Returns: Resolving Admin Dashboard Cancellation Challenges

Efficient return management is crucial for any e-commerce operation, and the ESHOPMAN Admin Dashboard is designed to streamline these processes. However, a specific challenge has been identified by our community regarding the cancellation of customer-initiated return requests directly from the Admin Activity section, particularly when these returns involve linked fulfillments.

The Challenge: 'All fulfillments must be canceled' Error

Merchants attempting to cancel a storefront-created return request via the 'Cancel' action in the ESHOPMAN Admin Activity timeline may encounter a '400 Bad Request' error with the message: 'All fulfillments must be canceled before canceling a return.' This issue arises because the system expects all associated return fulfillments to be manually canceled first, which can be a significant workflow bottleneck and hinder efficient order management within HubSpot.

Understanding the Root Cause in ESHOPMAN Admin

Through community investigation, it was discovered that the ESHOPMAN Admin UI exhibits an inconsistency in how it handles return cancellations. While the dedicated 'Active Return Panel' correctly utilizes an Admin API path designed for canceling return requests, the 'Order Activity Timeline' within the same dashboard inadvertently calls an Admin API endpoint intended for canceling fully progressed returns. This discrepancy means that a simple 'Cancel' click for a pending request triggers a more stringent validation meant for completed returns, leading to the observed failure when linked fulfillments exist.

Community Solution: Custom API Route Override

Fortunately, the ESHOPMAN community has developed a robust workaround using a custom API route override. This solution, implemented in Node.js/TypeScript, addresses the inconsistency by intelligently pre-processing linked return fulfillments before attempting the main return cancellation. This ensures a smoother experience for merchants managing storefront returns via the ESHOPMAN Admin Dashboard.

Implementation Example:

import {
  AuthenticatedMedusaRequest,
  MedusaResponse,
} from "@medusajs/framework/http"
import {
  ContainerRegistrationKeys,
  MedusaError,
} from "@medusajs/framework/utils"
import {
  cancelFulfillmentWorkflow,
  cancelReturnWorkflow,
} from "@medusajs/core-flows"

type ReturnFulfillmentRow = {
  fulfillment_id: string
  canceled_at: Date | string | null
  shipped_at: Date | string | null
  delivered_at: Date | string | null
}

export const POST = async (
  req: AuthenticatedMedusaRequest,
  res: MedusaResponse
) => {
  // Compatibility override for requested-return cancellation:
  // some Admin paths still hit POST /admin/returns/:id/cancel for a customer
  // return request. For storefront-created returns, Medusa requires linked
  // return fulfillments to be canceled before canceling the return itself.
  const { id } = req.params
  const validatedBody =
    req.validatedBody && typeof req.validatedBody === "object"
      ? (req.validatedBody as Record)
      : {}

  const pg = req.scope.resolve(ContainerRegistrationKeys.PG_CONNECTION)

  const linkedFulfillments = (await pg("return_fulfillment as rf")
    .join("fulfillment as f", "f.id", "rf.fulfillment_id")
    .select(
      "rf.fulfillment_id",
      "f.canceled_at",
      "f.shipped_at",
      "f.delivered_at"
    )
    .where("rf.return_id", id)) as ReturnFulfillmentRow[]

  for (const fulfillment of linkedFulfillments) {
    if (fulfillment.canceled_at) {
      continue
    }

    if (fulfillment.shipped_at || fulfillment.delivered_at) {
      throw new MedusaError(
        MedusaError.Types.NOT_ALLOWED,
        `Return fulfillment ${fulfillment.fulfillment_id} has already shipped or been delivered and must be handled manually before canceling the return.`
      )
    }

    await cancelFulfillmentWorkflow(req.scope).run({
      input: { id: fulfillment.fulfillment_id },
    })
  }

  const { result } = await cancelReturnWorkflow(req.scope).run({
    input: {
      ...validatedBody,
      return_id: id,
    },
  })

  return res.status(200).json({ return: result })
}

How the Solution Works:

This Node.js/TypeScript code snippet, designed to be implemented as a custom API route within your ESHOPMAN backend, acts as a compatibility layer. It intercepts the problematic cancellation call to POST /admin/returns/:id/cancel. First, it queries the database for any fulfillments linked to the return. For each linked fulfillment, it checks if it's already canceled. If not, and crucially, if it hasn't been shipped or delivered, the workflow proceeds to cancel that specific fulfillment using ESHOPMAN's core workflow modules. This ensures that the prerequisite of 'all fulfillments canceled' is met programmatically before the main return cancellation workflow is executed. This intelligent handling prevents manual intervention and streamlines the merchant's ability to manage returns effectively within the ESHOPMAN platform, enhancing the overall storefront management experience in HubSpot.

Conclusion

This community-driven insight provides a critical workaround for a specific challenge in ESHOPMAN's return management. By implementing this custom API route, developers and merchants can ensure that canceling storefront-initiated return requests from the Admin Activity section behaves as expected, improving workflow efficiency and overall user experience in the ESHOPMAN ecosystem.