Goal

Add the minimum structured after-sales workflow required to handle customer return and refund requests without relying on ad hoc support tickets.

---

Scope

Included:

• Customer creates a return request against an order
• Request can include one or more order items
• Admin can review, approve, reject, refund, and close the request
• Evidence URLs can be attached
• Resolution preference can be captured

Excluded from MVP:

• Shipping label generation
• Warehouse receiving scan
• Automatic Stripe refund execution from the return record
• Customer-facing self-service page UI
• Return portal emails

Current implementation status:

• Data model is implemented
• Customer return request API is implemented
• Admin review API is implemented
• Admin Returns workspace is implemented
• Customer-facing account-page return UI is still pending

---

Data model

return_requests

Top-level case record.

Key fields:

• order_id
• user_id
• email
• status
• reason
• customer_note
• resolution_preference
• resolution
• refund_amount
• evidence_json
• admin_notes
• requested_at
• approved_at
• completed_at

return_request_items

Line-item detail for partial returns.

Key fields:

• return_request_id
• order_item_id
• product_id
• quantity
• reason
• item_condition
• evidence_json

---

Status model

Customer / admin lifecycle:

• new
• reviewing
• approved
• received
• refunded
• rejected
• closed

Resolution values:

• refund
• replacement
• store_credit
• reject

---

API surface

Customer

GET /api/user/returns

Returns the current user’s return requests with linked items.

POST /api/user/returns

Creates a new return request.

Validation:

• user must own the order, or match historical guest email
• at least one order item must be selected
• requested quantity must not exceed ordered quantity

Admin

GET /api/admin/returns

Returns all return requests with lightweight order and customer context.

PATCH /api/admin/returns

Updates:

• status
• resolution
• refundAmount
• adminNotes

---

Admin UI

New admin workspace:

• Returns

Capabilities:

• filter by status
• inspect request details
• view requested items
• update status and resolution
• store internal notes

Current status:

• Backend workspace exists in admin
• Core review / resolution actions are in place
• This is currently an operations-first MVP rather than a polished customer portal

---

Future extension path

Phase 2 can layer on:

• auto-trigger refund from approved returns
• exchange / replacement workflow
• label upload and logistics coordination
• customer return history in account page
• delivery-triggered “request a return” entry point