# Free Item Exchange Policy - Option 3: Re-evaluate Promotion Eligibility

## Overview

This document explains how the system handles exchanges involving promotional free items (items with 100% discount from "Buy X Get Y" or similar promotions).

## Policy: Option 3 - Re-evaluate Promotion Eligibility

### Key Principles

1. **Free items CAN be returned/exchanged**
   - Previously, free items were blocked from returns
   - Now, they can be included in exchange transactions

2. **Free items have $0 refund value**
   - The customer never paid for free items
   - Returning a free item generates $0 refund

3. **Promotion re-evaluation**
   - When free items are returned, they are removed from the synthetic cart
   - The promotion engine re-evaluates the remaining items + new items
   - If promotions still qualify, a NEW free item may be granted

4. **Fair and transparent**
   - The exchange is treated as a "new transaction"
   - Promotions apply based on the final cart composition
   - Consistent with normal sales flow

## Example Scenario

### Original Invoice #SPR-3
- Item 1: $450 (FREE - 100% discount from "Buy 2 Get 1 Free")
- Item 4: $650 (paid)
- Item 7: $650 (paid)
- **Total paid: $1,482** (including VAT)

### Exchange: Return Free Item (450) + Add New Item (750)

**Step 1: Calculate Return Total**
- Free item (450): **$0 refund** (customer didn't pay for it)
- Items 4 and 7 remain in cart

**Step 2: Build Synthetic Cart**
- Remaining items: [650, 650]
- New items: [750]
- **Synthetic cart: [650, 650, 750]**

**Step 3: Re-evaluate Promotions**
- Check if "Buy 2 Get 1 Free" applies to [650, 650, 750]
- **Result: YES** (3 items qualify for Buy 2 Get 1)
- Cheapest item (650) becomes free

**Step 4: Calculate New Items Total**
- New item: 750
- Promotion discount: -650 (applied to one of the 650 items)
- VAT: 14% of (750 + 650 - 650) = 14% of 750 = $105
- **New Items Total: $855**

**Step 5: Net Difference**
- Return Total: $0
- New Items Total: $855
- **Customer pays: $855**

## Alternative Scenarios

### Scenario A: Return Free Item, No New Items
- Return Total: $0
- New Items Total: $0
- Remaining cart: [650, 650]
- Promotion no longer qualifies (need 3 items for Buy 2 Get 1)
- **Net: $0** (no refund, no charge)

### Scenario B: Return Paid Item, Keep Free Item
- Return Total: $741 (proportional refund for 650 item)
- Free item remains in cart
- Promotion may be invalidated (only 2 items left)
- Free item discount may be removed
- **Net: Depends on promotion re-evaluation**

## Implementation Details

### Code Changes

1. **Removed free item blocking** (`ExchangeApiController.php` lines 90-137)
   - Free items are no longer filtered out from `$returnedItems`
   - They are tracked separately in `$freeItemsBeingReturned`

2. **Separate paid and free returns**
   - `$paidReturnedItems`: Only paid items (for refund calculation)
   - `$freeItemsBeingReturned`: Free items (for logging, $0 refund)
   - `$returnedItems`: All items (for synthetic cart building)

3. **Refund calculation uses paid items only**
   - Loop through `$paidReturnedItems` instead of `$returnedItems`
   - Free items are excluded from refund totals

4. **Synthetic cart excludes returned items**
   - Both paid and free returned items are removed from synthetic cart
   - Promotions are re-evaluated on remaining + new items

### Benefits

- **Customer-friendly**: Allows exchanges of promotional items
- **Fair**: Customer doesn't get refund for items they didn't pay for
- **Consistent**: Promotions apply the same way as in regular sales
- **Transparent**: Clear rules that are easy to explain

### Trade-offs

- **Complexity**: More complex logic than blocking free item returns
- **Customer education**: Customers need to understand $0 refund for free items
- **Edge cases**: Some scenarios may be confusing (e.g., exchanging free item for cheaper item)

## Testing Checklist

- [ ] Return free item only → $0 refund
- [ ] Return free item + add new item → Promotion re-evaluated
- [ ] Return paid item + keep free item → Promotion may be invalidated
- [ ] Return all items (paid + free) → Full refund of paid amount only
- [ ] Partial return of paid items → Proportional refund, free item may lose discount

## Related Files

- `app/Http/Controllers/Api/ExchangeApiController.php` - Main exchange logic
- `app/Services/PromotionEngine.php` - Promotion evaluation
- `app/Services/PromotionalInvoiceService.php` - Promotion application
- `resources/js/pages/user/ExchangeList.tsx` - Frontend exchange UI