The current admin return tracking flow has too many intermediate stages (for example, in transit, received, and restocked), making it confusing for staff to complete a refund.
Staff also cannot easily see who changed a return status and when from a single location.
Requirements
1. Admin 3-Step Return Flow
Staff should complete every return using exactly these three steps:
Approved — accept the customer's return request.
Item returned — confirm the product is back at the store. Pickup and warehouse/received states are combined into this single step.
Refund Completed — issue the Stripe refund to the customer and close the return.
Apply this flow to:
Returns table action icons.
Order Return flow / tracking panel on the order.
The existing database statuses must remain compatible:
pending
approved
in_transit
received
restocked
refunded
rejected
The UI should map legacy/intermediate statuses such as in_transit, received, and restocked into the Item returned step where appropriate.
The customer-facing return request form remains unchanged and should only submit a return request; it must not expose the 3-step staff workflow.
2. Action History for Returns
Add a Comment / Action History icon to each row in the Returns table.
The history should display:
Return creation/requested event.
Status changes.
Performer.
Timestamp.
Human-readable action labels.
Expected action sequence:
Requested → Approved → Item returned → Refund Completed
Use the shared:
ActionHistoryTooltip
transformReturnActionHistory helper
Follow the existing Action History implementation/pattern used by Customers, Coupons, and Products.
Areas to Update
Admin FE
ReturnRequestsPage
OrderReturnTrackingPanel
actionHistoryHelpers
Backend
orderReturn.service
Approve stage
Item returned / tracking stage
Refund stage
Action History append logic
Acceptance Criteria
Admin can approve a pending return as step 1.
Admin can mark the item as returned as step 2.
Admin can complete the refund as step 3.
Completing the final step issues the Stripe refund and results in Refund Completed in the UI.
Existing database statuses remain backward compatible.
Legacy mid-states are represented as Item returned in the new UI flow where applicable.
The same 3-step flow is available from both the Returns table and the Order Return tracking panel.
Returns table rows have an Action History icon.
Action History shows Requested, Approved, Item returned, and Refund Completed events with performer and timestamp.
Customer-facing return request functionality remains unchanged.
Existing Action History patterns/helpers are reused rather than introducing a separate implementation.