# Pharmacy Direct Purchase Returns

## Overview

A **Direct Purchase Return** processes items bought directly from a supplier (without a purchase order) that need to be sent back — due to damage, wrong items, expired stock, or other reasons. The system tracks the return, updates stock levels, and creates a refund payment to the supplier.

The workflow has three stages, usually performed by different staff:

| Stage | Performed by | Result |
|-------|--------------|--------|
| **1. Create** | Pharmacy staff | A return is created with selected items and quantities |
| **2. Finalize** | Senior staff | The return is reviewed and locked for approval |
| **3. Approve** | Supervisor | Stock is deducted, refund payment is created |

---

## When to Use

Use the Direct Purchase Return feature when:

- **Damaged Items**: Items from a direct purchase arrive damaged
- **Wrong Items**: Supplier delivered incorrect items
- **Expired Items**: Received items are expired or close to expiry
- **Over-Supply**: More items were received than needed
- **Quality Issues**: Items fail quality inspection

---

## How to Use

### Accessing Direct Purchase Returns

1. From the main menu, go to **Pharmacy** → **Returns and Cancellations**
2. Click the **Direct Purchase Returns** tab
3. You will see options:
   - **Create Direct Purchase Return** — Start a new return
   - **Finalize Direct Purchase Return** — Review and finalize saved drafts
   - **Approve Direct Purchase Return** — Approve finalized returns
   - **Completed Returns** — View completed returns

---

### Stage 1 — Creating a Direct Purchase Return

#### Step 1: Search for a Direct Purchase

1. Click **Create Direct Purchase Return**
2. The search page opens with filter options:
   - **From Date** / **To Date** — Select the date range
   - **Purchase No** — Enter a specific purchase number
   - **Invoice Number** — Search by supplier invoice
   - **Supplier** (Distributor) — Filter by supplier name
   - **Item Name** — Search for purchases containing a specific item
3. Click **Search**
4. A table appears listing direct purchase bills with columns: Distributor, Purchase No, Invoice No, Purchase Value

#### Step 2: Select a Purchase and Create the Return

1. Find a direct purchase with items you want to return
2. Click the **Create Return** button on that row
3. A confirmation dialog appears — click **Yes** to confirm
4. You are taken to the **Direct Purchase Return Form** page

> **Note:** If you see an error "There is already a pending return for this purchase", you must complete, approve, or close the existing return first.

#### Step 3: Review and Manage Return Items

The return form shows all items from the original direct purchase in a table:

| Column | Description |
|--------|-------------|
| **Item Name** | Medicine or supply name (with View Item Details button) |
| **Date of Expiry** | When the batch expires |
| **Batch No** | Batch/lot number |
| **Current Stock** | Available stock in the pharmacy |
| **Purchased Quantity** | Original quantity purchased |
| **Free Quantity** | Free-of-charge quantity included |
| **Already Returned Qty** | Previously returned quantity |
| **Remaining Total Qty** | Remaining quantity available to return |
| **Return rate** | Cost per unit (total cost rate) |
| **Returning Total Qty** | Enter the quantity you want to return |
| **Return Value** | Calculated automatically (quantity × rate) |
| **Action** | Remove this item from return button |

#### Step 4: Enter Return Quantities

For each item you want to return:

1. Click in the **Returning Qty** column
2. Enter the quantity you are returning
3. The **Return Value** calculates automatically
4. The **Return Amount** in the right panel updates

**Validation Rules:**
- You cannot return more than the **Remaining Qty**
- You cannot return items already fully returned
- Quantities must be positive numbers

> **Tip:** You don't have to return every item. Leave quantities at 0 for items to keep.

#### Step 5: Removing Items from the Return

You can remove individual items you decide not to return:

1. Click the **Remove this item from return** button () in the **Action** column on the item's row
2. The item is removed from the return form immediately

> **Note:** The Direct Purchase Return form does not have a multi-select "Delete Selected" button with checkboxes like the Disposal Issue Return form. Each item is removed individually using its own Remove button.

#### Step 6: Fill in Return Details

In the right panel:

1. **Return Comments** — Enter a reason (e.g., "QA Testing - Direct Purchase Return")
2. **Payment Method** — Select from the dropdown (Cash, Credit, etc.)
3. **Actual Net Value** — Leave as-is (auto-calculated)

> **Important:** Both Return Comments and Payment Method are required before finalizing.

#### Step 7: Save or Finalize

**Option A: Save**
- Click **Save** to save as draft
- You can return later to continue editing
- Message: **"Return saved successfully"**

**Option B: Finalize**
- Click **Finalize** to submit for approval
- The system validates all required fields
- A print preview is displayed

---

### Stage 2 — Finalizing a Saved Return

1. Click **List of Direct Purchase Returns to Finalize**
   - OR go to Returns and Cancellations → Direct Purchase Returns → **Finalize Direct Purchase Return**
2. Set **From Date** and **To Date**
3. Click **Search**
4. Find your return (shows supplier, return number, value)
5. Click **Finalize**
6. Review the items and quantities
7. Click **Finalize** to submit

---

### Stage 3 — Approving a Return

> **Note:** You need the "Approve Direct Purchase Return" privilege.

1. Click **List of Direct Purchase Returns To Approve**
   - OR go to Returns and Cancellations → Direct Purchase Returns → **Approve Direct Purchase Return**
2. Set date range and click **Search To Approve Requests**
3. Find your return (status: "Pending Approval")
4. Click **Approve**
5. Review one final time
6. Click **Approve** to complete

**What Happens on Approval:**
- Returned items are deducted from stock
- A refund payment to the supplier is created
- The return is marked as "Approved"
- A printable receipt is shown

![Direct Purchase Return print preview](images/direct_purchase_return_print_preview.png)

---

### Viewing Completed Returns

1. Go to Returns and Cancellations → Direct Purchase Returns → **Completed Returns**
2. Set date range and click **Search**
3. Click **Print** on any completed return to view or reprint

---

## Understanding Messages

### Success Messages

| Message | Meaning | Action Required |
|---------|---------|-----------------|
| "Direct Purchase Return Request Saved Successfully" | Draft saved | Continue editing or finalize later |
| "Direct Purchase Return Request Finalized Successfully" | Return submitted for approval | View print preview, print, or wait for approval |
| "Return approved successfully" | Return completed | None — process complete |

### Error Messages

| Message | Meaning | How to Fix |
|---------|---------|-----------|
| "There is already a pending return for this purchase" | A return already exists | Complete or close the existing return |
| "Please enter a reason for return to finalize" | Comment field empty | Enter a reason for the return |
| "Please select payment method" | Payment method not selected | Select from the dropdown |
| "Insufficient stock for [Item] (Batch: [batch])" | Return qty exceeds current stock | Reduce return quantity to current stock or below |
| "Cannot finalize: Stock validation failed" | Stock validation failed | Correct quantities and try again |
| "You are NOT authorized" | Insufficient privileges | Contact administrator |

### Confirmation Dialogs

| Dialog | When It Appears | Action |
|--------|-----------------|--------|
| "Are you sure you want to create a return for this purchase?" | After clicking Create Return | Click Yes to proceed |
| "Are you sure you want to finalize this return?" | After clicking Finalize | Click Yes to submit |

---

## Test Scenarios

These scenarios help verify the return process works correctly:

### Scenario A: Simple Return (Full Quantity)
Return the **full remaining quantity** of at least 2 items. Expected: All items returned, purchase marked as fully returned.

### Scenario B: Partial Return
Return only **some** of the remaining quantity (e.g., 3 out of 15). Expected: Only the entered quantity is returned, remaining qty decreases correctly.

### Scenario C: Empty Return Blocked
Leave ALL quantities at 0 and try to finalize. Expected: Error — "At least one item must have a return quantity."

### Scenario D: Save Draft and Return Later
Enter some quantities, click **Save**, navigate away, then find the return via the Finalize list. Expected: Draft is found, quantities preserved, can continue where you left off.

---

## Best Practices

1. **Verify the Purchase**: Ensure you have the correct direct purchase bill
2. **Document the Reason**: Always fill in return comments with a clear reason
3. **Check Quantities**: Physical count should match entered quantities
4. **Save Frequently**: Save drafts if you need to pause
5. **Print Receipts**: Print return receipts immediately after finalization
6. **Review Before Approving**: Check all items and quantities before approving

---

## Troubleshooting

### Cannot Create Return

**Problem**: "Create Return" button shows error or is disabled

**Solutions**:
- Check the purchase hasn't been fully returned
- Verify no pending return exists for this purchase
- Try a different purchase if this one has issues

### Cannot Finalize

**Problem**: Finalize button shows validation errors

**Solutions**:
- Fill in the Return Comments field
- Select a Payment Method
- Ensure at least one item has a return quantity > 0
- Check quantities don't exceed remaining amounts

### Cannot Approve

**Problem**: Approve button not visible

**Solutions**:
- Verify return has been finalized
- Check you have approval privileges
- Ensure return hasn't already been approved

### Stock Validation Failed at Finalize

**Problem**: "Insufficient stock for [Item]" error when finalizing

**Solutions**:
- Check the current stock shown for the item
- Reduce return quantity to match or be below current stock
- The system checks physical stock, not original purchase quantity

---

## Configuration (Admin)

### Required Privileges

| Task | Required Privilege |
|------|-------------------|
| Create returns | CreateDirectPurchaseReturn |
| Finalize returns | FinalizeDirectPurchaseReturn |
| Approve returns | ApproveDirectPurchaseReturn |
| View completed | ViewDirectPurchaseReturn |

---

## FAQ

**Q: Can I return items from multiple purchases at once?**
A: No, each return is for a single direct purchase only.

**Q: What's the difference between GRN Return and Direct Purchase Return?**
A: GRN Returns are for items received via Goods Received Notes (with purchase orders). Direct Purchase Returns are for items bought directly without a purchase order.

**Q: Can I edit a return after finalizing?**
A: No, but if it hasn't been approved yet, you can close it and create a new one.

**Q: What happens to stock when approved?**
A: Returned items are deducted from pharmacy stock, and a supplier refund payment is created.

---

## Related Features

- **[GRN Returns](Pharmacy-Procurement-GRN-Returns.md)** — Returning items received via GRN
- **[Disposal Issue Returns](Pharmacy/Disposal-Issue-Returns.md)** — Returning disposal/issue items
- **[Pharmacy Procurement — Purchase Orders](Pharmacy-Procurement-Purchase-Orders.md)** — Purchase order management
- **[Pharmacy Navigation Guide](Pharmacy/Pharmacy-Navigation-Guide.md)** — Complete pharmacy module navigation