Order Returns

The Orders module provides a complete return lifecycle with auto-generated return numbers, approval workflows, and integrated refund processing.

Return Lifecycle

requested → approved → received → refunded
         → rejected

Return Model

Field	Type	Description
id	UUID	Primary key
order_id	UUID	Parent order
return_number	string	Auto-generated (RET-YYYYMMDD-XXXX)
status	string	requested, approved, rejected, received, refunded
reason_category	string	Reason category (defective, wrong_item, etc.)
reason_detail	string	Detailed reason
customer_notes	text	Customer's notes
admin_notes	text	Admin notes
items	jsonb	Items being returned [{order_item_id, quantity}]
refund_amount	decimal	Amount to refund
refund_method	string	How to refund (original_payment, store_credit, bank_transfer)
approved_by	int	Admin who approved
approved_at	datetime	Approval timestamp
received_at	datetime	When items were received back
refunded_at	datetime	When refund was processed

API Flow

1. Request Return

POST /api/v1/orders/{order}/returns

{
  "reason_category": "defective",
  "reason_detail": "Screen has dead pixels",
  "customer_notes": "Noticed on first use",
  "items": [
    { "order_item_id": "uuid", "quantity": 1 }
  ]
}

2. Approve or Reject

PATCH /api/v1/returns/{return}/approve

{
  "admin_notes": "Approved — scheduling pickup",
  "refund_amount": 999.00,
  "refund_method": "original_payment"
}

PATCH /api/v1/returns/{return}/reject

{
  "admin_notes": "Item shows signs of physical damage"
}

3. Mark as Received

PATCH /api/v1/returns/{return}/received

4. Process Refund

POST /api/v1/returns/{return}/refund

This creates an OrderRefund record and updates the order's payment status.

Events

Event	When
order.return_requested	Customer submits return request
order.return_approved	Admin approves return
order.refund_processed	Refund processed for return

Listing Returns

GET /api/v1/orders/{order}/returns

Returns all return requests for an order, ordered by creation date.