> ## Documentation Index
> Fetch the complete documentation index at: https://help.agatabo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Modifying Loans

> Increase principal, extend period, or adjust interest rate for active loans

## Overview

Loan modification in Agatabo allows you to adjust the loan's overall terms - increasing the principal amount, extending the period, or changing the interest rate. The system regenerates the repayment schedule from the modification date forward while keeping past installments unchanged.

<Note>
  **Important**: This is a **term-level modification system**, not an installment-level system. You cannot modify individual installment amounts or due dates. Instead, you modify the loan's global terms, and the system recalculates the entire schedule.
</Note>

## What Can Be Modified

### Principal Amount (Top-up)

**Increase** the loan principal amount:

* Add funds to an existing loan
* Member receives additional cash disbursement
* New schedule calculated from modification date forward
* **Restriction**: Cannot reduce principal (increase only)

**Example**: 500,000 RWF loan → modify to 700,000 RWF

* Additional 200,000 RWF disbursed to member
* Schedule recalculated for remaining period with new principal

### Loan Period (Extension)

**Extend** the loan duration:

* Add more months to the repayment period
* Reduces monthly payment burden
* Increases total interest paid
* **Restriction**: Cannot shorten period (extend only)

**Example**: 12-month loan → extend to 18 months

* 6 additional months added
* Monthly payments recalculated with new period

### Interest Rate

**Change** the interest rate:

* Adjust up or down
* New rate applies from modification date forward
* **Optional**: Can keep the same rate

**Example**: 5% monthly → modify to 3% monthly

* New installments calculated with 3% rate

## What Cannot Be Modified

<Warning>
  **Restrictions on modifications**:

  * **Cannot reduce** principal amount (increase only)
  * **Cannot shorten** loan period (extend only)
  * **Cannot modify** interest calculation type (SIMPLE, REDUCING\_BALANCE, COMPOUND)
  * **Cannot modify** installment type (EQUAL\_PRINCIPAL vs EQUAL\_TOTAL)
  * **Cannot modify** payment allocation order
  * **Cannot modify** individual installment amounts or due dates
  * **Cannot modify** COMPLETED or DEFAULTED loans (active only)
  * **Cannot modify** if later payments or penalties exist (must reverse those first)
</Warning>

## When to Modify Loans

Modify loans when:

* **Top-up request**: Member needs additional funds
* **Financial hardship**: Member needs lower payments (extend period)
* **Interest rate adjustment**: Market conditions or policy changes
* **Loan restructuring**: Prevent default with better terms

**Prerequisites**:

* Loan must be ACTIVE
* Both parties agree to new terms
* Committee approval (per your organization's policy)

## The 3-Step Modification Process

### Step 1: Enter New Terms

<Steps>
  <Step title="Navigate to loan details">
    Loans → Select the loan → Open details
  </Step>

  <Step title="Click 'Modify Loan' button">
    Located in the Loan Overview card (if you have permission)
  </Step>

  <Step title="Enter new terms">
    Fill in the modification form:

    * **New Principal**: Must be ≥ current principal
    * **New Period**: Must be ≥ current period (in months)
    * **New Interest Rate**: Optional, enter new percentage
    * **Modification Date**: When the change takes effect
    * **Bank Account**: Required if increasing principal (for disbursement)
  </Step>

  <Step title="Click 'Next'">
    Proceeds to preview step
  </Step>
</Steps>

### Step 2: Preview Changes

The preview shows the financial impact of the modification:

**Comparison display**:

* Old vs New principal amounts
* Old vs New loan periods
* Old vs New interest rates
* **Cash Disbursed**: Additional amount to be disbursed (if principal increased)
* **Interest Adjustment**: Change in total interest

**Schedule preview**:

* Installments before modification date (unchanged)
* Installments after modification date (new calculations)

<Steps>
  <Step title="Review the impact">
    Verify the changes are correct
  </Step>

  <Step title="Check disbursement amount">
    If increasing principal, confirm cash amount
  </Step>

  <Step title="Click 'Next'">
    Proceeds to confirmation
  </Step>
</Steps>

### Step 3: Confirm and Submit

<Steps>
  <Step title="Add reason (optional)">
    Document why the modification is being made
  </Step>

  <Step title="Acknowledge terms">
    Confirm you understand the changes
  </Step>

  <Step title="Click 'Confirm Modification'">
    Submits the modification
  </Step>
</Steps>

## What Happens When You Modify

1. **Validation checks**:
   * Confirms loan is ACTIVE
   * Verifies new principal ≥ current principal
   * Verifies new period ≥ current period
   * Checks no later payments/penalties exist

2. **Journal entries created**:
   * **Dr BANK\_ACCOUNT**: Cash disbursed (if principal increased)
   * **Cr LOAN\_RECEIVABLE**: Principal increase
   * Additional entries for interest (if interest paid in advance)

3. **LoanModificationMeta record created**:
   * Stores old vs new terms
   * Links to journal entry
   * Records modification date, reason, and creator

4. **Loan schedule regenerated**:
   * Installments **before** modification date: **unchanged**
   * Installments **after** modification date: **recalculated** with new terms

5. **Cash disbursed** (if principal increased):
   * Additional funds released to member
   * From selected bank account

6. **Modification history updated**:
   * Appears in loan details
   * Shows in modification history table

## Understanding Schedule Regeneration

The modification creates a "before and after" schedule:

**Example**: Loan started June 1, 2026 (12 months, 500,000 RWF)
Modified on September 1, 2026 (extend to 18 months, increase to 700,000 RWF)

**Installments 1-3** (June, July, August):

* **Unchanged** - calculated with original terms
* Already paid or in progress

**Installments 4-18** (September onward):

* **Recalculated** - uses new principal (700,000 RWF) and new period (18 months)
* New monthly amounts based on remaining principal and remaining months

<Note>
  **Important**: The system doesn't "restart" the loan. It calculates what the remaining balance is at the modification date and spreads it over the new remaining period with the new terms.
</Note>

## Modification History

All modifications are tracked and displayed in the loan details:

**History shows**:

* Modification date
* Old → New principal
* Old → New period
* Old → New interest rate
* Cash disbursed
* Reason (if provided)
* Who made the modification
* When it was created

**Actions available**:

* View full details
* Undo the latest modification (if no later events exist)

## Undoing a Modification

You can reverse the **most recent modification** if needed:

<Steps>
  <Step title="Go to loan details">
    Find the loan with the modification
  </Step>

  <Step title="View Modification History">
    In the Loan Overview card
  </Step>

  <Step title="Click 'Undo' (trash icon)">
    Only available for the latest modification
  </Step>

  <Step title="Confirm">
    Reverses the modification
  </Step>
</Steps>

**What happens**:

* Reverses all journal entries
* Deletes the modification record
* Schedule reverts to previous state
* Cash disbursement is reversed (if applicable)

<Warning>
  **Cannot undo if**:

  * Any loan payments were made after the modification date
  * Any penalties were applied after the modification date
  * You must reverse those events first, then undo the modification
</Warning>

## Common Modification Scenarios

### Top-up (Additional Funds)

Member needs more money:

```
Original: 500,000 RWF, 12 months, 5% monthly
Modified: 800,000 RWF, 12 months, 5% monthly (same period and rate)

Result:
- Additional 300,000 RWF disbursed
- Remaining installments recalculated with higher principal
- Monthly payments increase
```

### Period Extension (Lower Payments)

Member needs lower monthly payments:

```
Original: 500,000 RWF, 12 months, 5% monthly
Modified: 500,000 RWF, 18 months, 5% monthly (same principal and rate)

Result:
- No additional cash disbursed
- Remaining installments spread over more months
- Monthly payments decrease
- Total interest increases
```

### Top-up with Extension

Combination modification:

```
Original: 500,000 RWF, 12 months, 5% monthly
Modified: 700,000 RWF, 18 months, 4% monthly

Result:
- Additional 200,000 RWF disbursed
- Extended period for more flexibility
- Reduced rate to help member
```

### Interest Rate Adjustment

Policy change:

```
Original: 500,000 RWF, 12 months, 5% monthly
Modified: 500,000 RWF, 12 months, 3% monthly (rate reduction)

Result:
- No cash disbursement
- Future installments use new 3% rate
- Total interest decreases
```

## Best Practices

<Note>
  **Modification tips:**

  * Get written request from member
  * Obtain committee approval per policy
  * Document reason clearly
  * Preview changes before confirming
  * Keep modification history for audit
  * Use top-ups strategically (don't over-lend)
  * Consider member's repayment capacity
  * Communicate new schedule to member
  * Print/send updated schedule to member
</Note>

## Important Restrictions

### Modification Date Constraints

The modification date must be:

* ✅ After the loan start date
* ✅ On or before today (not in future)
* ✅ On or before the last installment due date
* ✅ At a date with no existing modification (one per date)

### Interest Refund Prevention

The system blocks modifications that would require refunding interest to the borrower:

* For **IN\_ADVANCE** loans: Cannot reduce principal or period in ways requiring refund
* For **WITH\_INSTALLMENTS** loans: Cannot reduce interest below outstanding receivable

### Event Ordering

Cannot modify if:

* ❌ Payments were made after the modification date (reverse payments first)
* ❌ Penalties were applied after the modification date (reverse penalties first)
* ❌ Any other loan events exist after the modification date

## Permissions Required

| Action            | Permission     | Scope |
| ----------------- | -------------- | ----- |
| View loan details | `loans:read`   | ANY   |
| Modify loan       | `loans:modify` | ANY   |
| Undo modification | `loans:modify` | ANY   |

## Related Operations

<CardGroup cols={2}>
  <Card title="Creating Loans" icon="plus" href="/tontines/loans/creating-loans">
    Understand initial loan setup
  </Card>

  <Card title="Viewing Loan Details" icon="file-lines" href="/tontines/loans/viewing-loan-details">
    Check modification history
  </Card>

  <Card title="Recording Payments" icon="money-bill-transfer" href="/tontines/loans/recording-loan-payments">
    Handle payments on modified loans
  </Card>

  <Card title="Loan Analytics" icon="chart-line" href="/tontines/loans/loan-analytics">
    Monitor modified loan performance
  </Card>
</CardGroup>