> ## 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.

# Reserve Allocations (Top Up)

> Add funds to reserves from retained earnings to build designated savings

## Overview

**Reserve allocation** (also called **Top Up**) transfers money from your organization's retained earnings into a designated reserve. This reduces unallocated retained earnings and increases the reserve balance, earmarking funds for a specific future purpose.

<Note>
  **Accounting treatment**: Allocating to a reserve is a pure equity reclassification. Total organization equity remains unchanged - funds simply move from "undesignated retained earnings" to "designated reserve allocation."
</Note>

## When to Allocate to Reserves

Common scenarios:

* **Monthly routine**: Allocate fixed percentage of profit to emergency reserve
* **After profitable quarter**: Allocate surplus to building fund
* **Portfolio growth**: Increase loan loss reserve as loan portfolio expands
* **Policy compliance**: Meet reserve targets set by bylaws or regulations
* **Goal achievement**: Regular allocations toward specific savings goals
* **Initial funding**: First allocation to newly created reserve
* **Target adjustment**: Increase allocation to reach target faster

## Before You Begin

<Note>
  **Prerequisites:**

  * You have `reserves:write` permission
  * Reserve exists and is marked **Active**
  * Organization has sufficient retained earnings to allocate
  * Accounting period is not closed
  * You have an idempotency key ready (auto-generated by frontend)
</Note>

<Warning>
  **Check retained earnings first**: You cannot allocate more than your current undesignated retained earnings balance.

  **Calculation**:

  ```
  Available for Allocation = Total Retained Earnings - Sum of All Reserve Balances

  Example:
  Total Retained Earnings:     10,000,000 RWF
  Existing Reserve Balances:   -6,000,000 RWF
  -------------------------------------------
  Available to Allocate:        4,000,000 RWF (maximum)
  ```

  If retained earnings are negative or insufficient, allocation will fail.
</Warning>

***

## Step-by-Step Instructions

### Step 1: Navigate to Reserve

<Steps>
  <Step title="Open Reserves section">
    Click **Reserves** in the left sidebar
  </Step>

  <Step title="Find the reserve">
    Locate the reserve you want to allocate to
  </Step>

  <Step title="Click on reserve name">
    Opens reserve details page
  </Step>

  <Step title="Click Top Up or Adjust Balance">
    Opens allocation dialog
  </Step>
</Steps>

***

### Step 2: Enter Allocation Details

| Field           | Description                            | Required | Validation                              |
| --------------- | -------------------------------------- | -------- | --------------------------------------- |
| **Amount**      | How much to allocate to the reserve    | Yes      | Minimum 0.01, matches currency decimals |
| **Action**      | Select "Top Up" (add money to reserve) | Yes      | Must be 'TOP\_UP'                       |
| **Date**        | When this allocation occurred          | Yes      | ISO format, cannot be in closed period  |
| **Description** | Purpose of this allocation             | No       | Optional but recommended                |

***

### Step 3: Choose Amount

Determine how much to allocate based on your strategy:

**Policy-Based Allocation**:

```
Emergency Fund: 15% of monthly net profit
Loan Loss Reserve: 5% of new loan disbursements this month
Equipment Reserve: 100,000 RWF fixed monthly allocation

Example:
Net profit this month: 2,000,000 RWF
Emergency allocation: 2,000,000 × 15% = 300,000 RWF
```

**Target-Based Allocation**:

```
Building Fund target: 25,000,000 RWF
Current balance: 10,000,000 RWF
Gap: 15,000,000 RWF
Months to target: 30 months
Monthly allocation: 15,000,000 / 30 = 500,000 RWF
```

**Available Funds Allocation**:

```
Unallocated retained earnings: 8,000,000 RWF
Allocate 3,000,000 RWF to emergency reserve (37.5% of available)
Remaining unallocated: 5,000,000 RWF (buffer for operations)
```

<Note>
  **Allocation strategies:**

  * **Fixed amount**: 500,000 RWF every month (predictable, easy to budget)
  * **Percentage of profit**: 20% of this month's net income (scales with success)
  * **Target gap**: (Target - Current Balance) / Months Remaining (achieves goal on schedule)
  * **Surplus allocation**: After covering operations, allocate excess to reserves (opportunistic)
</Note>

***

### Step 4: Set Allocation Date

**Date**: When this allocation is effective (usually today)

**Rules**:

* Must be valid ISO date (YYYY-MM-DD)
* Cannot be in closed accounting period
* Can be historical (past dates) if period is still open
* Cannot exceed current date

**Examples**:

* Today: 2026-06-12
* End of last month: 2026-05-31
* First of current month: 2026-06-01

<Note>
  **Typical approach**: Use today's date for current allocations. Use end-of-month dates for monthly allocations recorded at month-end close.
</Note>

***

### Step 5: Add Description (Optional but Recommended)

Document why you're making this allocation for audit trail and transparency:

**Good descriptions:**

* "Monthly allocation - 15% of June 2026 profit (2M RWF net income)"
* "Q2 2026 allocation toward building fund target - 20% of quarterly profit"
* "Increase loan loss reserve to 5% of portfolio (2M RWF additional loans this month)"
* "Year-end allocation per member vote at December 2026 AGM"
* "Initial funding - emergency reserve setup per new policy"
* "Final allocation to reach 3M RWF emergency fund target"

**Poor descriptions:**

* "Allocation"
* "Adding money"
* "Reserve top up"
* (blank)

<Note>
  **Best practice**: Include the source of funds (% of profit, specific decision) and the purpose or target being achieved.
</Note>

***

### Step 6: Submit

<Steps>
  <Step title="Review all fields">
    Confirm amount, date, and action (TOP\_UP) are correct
  </Step>

  <Step title="Verify available retained earnings">
    Ensure allocation won't exceed available undesignated retained earnings
  </Step>

  <Step title="Click Submit or Allocate">
    Funds transferred to reserve via journal entry
  </Step>

  <Step title="Confirm success">
    Reserve balance increases by allocation amount
  </Step>

  <Step title="Verify transaction in history">
    Allocation appears in reserve transaction history
  </Step>
</Steps>

***

## What Happens During Allocation

When you allocate to a reserve, Agatabo automatically:

1. **Validates request**
   * Reserve must be active
   * Reserve must exist and belong to organization
   * Amount must be at least 0.01
   * Date must not be in closed period
   * Sufficient retained earnings available (unless skipNegativeBalanceCheck)

2. **Creates journal entry**
   ```
   Kind: RESERVE_TOP_UP
   Date: Allocation date
   Status: POSTED

   Dr RETAINED_EARNINGS       Amount
      Cr RESERVE_ALLOCATION   Amount
         (scopeKey: reserve:{reserveId})
   ```

3. **Updates balances**
   * Reserve ledger account balance increases by amount (credit to equity account)
   * Retained earnings ledger account balance decreases by amount (debit to equity account)

4. **Records transaction**
   * Transaction appears in reserve transaction history
   * Includes running balance after allocation
   * Linked to journal entry for audit trail

5. **Logs audit trail**
   * Records who made allocation
   * Timestamp of operation
   * Amount and description
   * Full journal entry details

<Note>
  **Total equity unchanged**: Allocation moves money within equity accounts. Your organization's total net worth does not change - funds are simply reclassified from "undesignated retained earnings" to "designated reserve allocation."

  **No cash movement**: Allocating to a reserve does NOT move cash between bank accounts. Cash remains in your bank accounts - this is purely an accounting designation.
</Note>

***

## Common Scenarios

### Monthly Recurring Allocations

Set up systematic reserve building:

<Steps>
  <Step title="Document allocation policy">
    Example: "Allocate 500,000 RWF to Emergency Fund, 200,000 RWF to Equipment Reserve on first business day of each month"
  </Step>

  <Step title="Create calendar reminder">
    Set monthly reminder for reserve allocations (e.g., 1st of each month)
  </Step>

  <Step title="Verify profit first">
    Check P\&L report to confirm retained earnings are positive and sufficient
  </Step>

  <Step title="Execute allocations">
    Top up all reserves per policy
  </Step>

  <Step title="Document in minutes">
    Record monthly allocations in treasurer's report or meeting minutes
  </Step>
</Steps>

**Example monthly routine**:

```
Date: 2026-06-01

Emergency Fund:
  Amount: 500,000 RWF
  Description: "Monthly allocation - June 2026 per policy"

Equipment Reserve:
  Amount: 200,000 RWF
  Description: "Monthly allocation - June 2026 per policy"

Loan Loss Reserve:
  Amount: 100,000 RWF
  Description: "Monthly allocation - June 2026 per policy"

Total allocated: 800,000 RWF
Retained earnings before: 10,000,000 RWF
Retained earnings after: 9,200,000 RWF (undesignated)
```

***

### Profit-Based Allocations

Allocate percentage of profit after closing monthly books:

<Steps>
  <Step title="Run Profit & Loss report">
    Determine net income for the period
  </Step>

  <Step title="Calculate allocations">
    Apply allocation percentages to net income
  </Step>

  <Step title="Top up each reserve">
    Execute allocations for all reserves
  </Step>

  <Step title="Verify retained earnings remain positive">
    Ensure sufficient undesignated retained earnings remain for operations (recommend keeping 20-30% buffer)
  </Step>
</Steps>

**Example**:

```
June 2026 Net Income: 2,000,000 RWF

Allocation policy:
- Emergency Fund: 15% = 300,000 RWF
- Equipment Reserve: 10% = 200,000 RWF
- Loan Loss Reserve: 5% = 100,000 RWF
Total: 30% = 600,000 RWF

Retained earnings:
Before: 12,000,000 RWF
Allocations: -600,000 RWF
After: 11,400,000 RWF (95% remaining for operations)
```

***

### Reaching Reserve Target

Complete a savings goal:

<Steps>
  <Step title="Check current balance">
    View reserve details to see current balance
  </Step>

  <Step title="Calculate final allocation">
    Target - Current Balance = Amount Needed
  </Step>

  <Step title="Verify sufficient retained earnings">
    Ensure available undesignated funds cover the gap
  </Step>

  <Step title="Top up final amount">
    Allocate remaining amount to reach target
  </Step>

  <Step title="Mark reserve inactive (optional)">
    If no more allocations needed, update reserve to inactive status
  </Step>
</Steps>

**Example**:

```
Building Fund:
Target: 25,000,000 RWF
Current balance: 22,000,000 RWF
Gap: 3,000,000 RWF

Available retained earnings: 8,000,000 RWF
Allocation: 3,000,000 RWF (final)

New balance: 25,000,000 RWF (target reached!)
Description: "Final allocation to reach 25M RWF building fund target"

Next step: Mark reserve inactive (no more allocations needed until building purchase)
```

***

### Adjusting for Portfolio Growth

Increase loan loss reserve as loan portfolio expands:

<Steps>
  <Step title="Calculate target reserve">
    E.g., 5% of total outstanding loans
  </Step>

  <Step title="Check current reserve balance">
    View Loan Loss Reserve balance
  </Step>

  <Step title="Calculate shortfall">
    (Portfolio × 5%) - Current Reserve Balance
  </Step>

  <Step title="Allocate shortfall">
    Top up to maintain 5% coverage
  </Step>
</Steps>

**Example**:

```
Outstanding loans increased: 20,000,000 RWF → 25,000,000 RWF

Target (5%): 1,250,000 RWF
Current reserve: 1,000,000 RWF
Shortfall: 250,000 RWF

Allocation:
Amount: 250,000 RWF
Description: "Increase loan loss reserve to 5% of portfolio (25M RWF outstanding loans)"

New balance: 1,250,000 RWF (5% coverage maintained)
```

***

## Validation and Constraints

### Input Validation

**Amount**:

* ✅ Must be at least 0.01
* ✅ Must match organization's currency decimal places
* ❌ Cannot be negative or zero
* ❌ Cannot exceed available retained earnings (unless skipNegativeBalanceCheck)

**Action**:

* ✅ Must be 'TOP\_UP' (for allocations)
* ❌ Cannot be 'RELEASE' (use different operation)

**Date**:

* ✅ Must be valid ISO date (YYYY-MM-DD)
* ✅ Can be historical (past dates in open periods)
* ❌ Cannot be in closed accounting period
* ❌ Cannot exceed current date

**Description**:

* ✅ Optional field
* ✅ Can be empty or null
* ✅ Recommended for audit trail

### Business Logic Validation

**Reserve Status**:

* Reserve must be **active** (isActive = true)
* Inactive reserves reject allocations with error

**Retained Earnings Check**:

* System calculates: Available = Total Retained Earnings - Sum of All Reserves
* Allocation amount must not exceed available amount
* Can be skipped with `skipNegativeBalanceCheck: true` (requires special permission)

**Accounting Period**:

* Date must not fall in closed accounting period
* Validates before creating journal entry

**Idempotency**:

* All allocation operations require idempotency key (header: `x-idempotency-key`)
* Prevents duplicate allocations from retries
* Safe for network failures and page refreshes
* Duplicate requests with same key return existing transaction

***

## Best Practices

<Note>
  **Allocation tips:**

  **Frequency:**

  * Allocate regularly (monthly or quarterly) rather than sporadically
  * Consistent small allocations easier than large lump sums
  * Build allocation into monthly closing process
  * Match allocation timing to profit cycles

  **Amount guidelines:**

  * Don't allocate 100% of retained earnings - keep 20-30% buffer for operations
  * Use percentage-based allocations for scalability (grow with organization)
  * Use fixed amounts for predictable budgeting
  * Consider cash flow needs before large allocations

  **Documentation:**

  * Always add descriptive allocation notes (include % of profit, source, purpose)
  * Document allocation policy in bylaws or financial procedures
  * Report reserve allocations to members at meetings (transparency)
  * Keep allocation schedule consistent with stated policies

  **Target management:**

  * Review reserve targets annually and adjust allocations as needed
  * Rebalance reserves if one grows beyond target while others lag
  * Mark reserves inactive when targets reached
  * Don't over-allocate (diminishes operational flexibility)

  **Safeguards:**

  * Verify retained earnings balance before allocating
  * Don't allocate if it would make undesignated retained earnings negative
  * Get board/committee approval for large allocations (e.g., > 1M RWF)
  * Review reserve strategy quarterly
</Note>

***

## Troubleshooting

### "Insufficient retained earnings"

**Cause**: Allocation would make undesignated retained earnings negative

**Solution**:

<Steps>
  <Step title="Check Balance Sheet">
    View current total retained earnings
  </Step>

  <Step title="Calculate existing reserves">
    Sum all current reserve balances
  </Step>

  <Step title="Determine available amount">
    Available = Total Retained Earnings - Sum of Reserves
  </Step>

  <Step title="Reduce allocation">
    Allocate less than or equal to available amount
  </Step>
</Steps>

**Example**:

```
Balance Sheet shows:
  Total Retained Earnings: 10,000,000 RWF

Existing Reserves:
  Emergency Fund: 2,000,000 RWF
  Building Fund: 3,000,000 RWF
  Loan Loss: 1,000,000 RWF
  Total Reserves: 6,000,000 RWF

Available for new allocations: 4,000,000 RWF

Attempted allocation: 5,000,000 RWF ❌ (exceeds available)
Corrected allocation: 3,500,000 RWF ✅ (leaves 500K buffer)
```

***

### "Reserve is inactive"

**Cause**: Cannot allocate to inactive reserves

**Solutions**:

1. **Reactivate the reserve**:
   * Navigate to reserve details
   * Click Edit or Update
   * Set Active = true
   * Save changes

2. **Create new active reserve**:
   * If old reserve is obsolete
   * Create new reserve with updated purpose
   * Begin allocations to new reserve

***

### "Period closed" or "Cannot create entry in closed period"

**Cause**: Allocation date falls in a closed accounting period

**Solutions**:

1. **Change allocation date** to current open period
2. **Ask administrator** to reopen period (not recommended - breaks period lock)
3. **Wait for next period** and record allocation then

[Learn about period closing →](/tontines/advanced/period-closing)

***

### "Amount validation error"

**Causes and solutions**:

**"Amount must be at least 0.01"**:

* Enter amount >= 0.01 (minimum allocation)

**"Amount decimal places don't match currency"**:

* Check organization's monetary policy (e.g., RWF uses 0 decimals, USD uses 2)
* Enter: 500000 (correct for RWF) not 500000.50 (incorrect for RWF)

**"Amount cannot be negative"**:

* Use positive number for TOP\_UP
* For withdrawals, use RELEASE action instead

***

### "x-idempotency-key header is required"

**Cause**: Frontend didn't send idempotency key with request

**Solution**:

* This is usually a frontend/API client issue
* Ensure the request includes `x-idempotency-key` header
* Use unique key per allocation attempt (e.g., UUID)
* Most frontends auto-generate this

***

## Permissions Required

| Action             | Permission       | Scope |
| ------------------ | ---------------- | ----- |
| View reserves      | `reserves:read`  | ANY   |
| Top up reserve     | `reserves:write` | ANY   |
| View balance sheet | `reports:read`   | ANY   |

<Note>
  **Typical roles**: Administrators and Accountants have `reserves:write`. Regular members typically have `reserves:read` (view only) or no access.
</Note>

***

## Technical Details

### API Endpoint

```
PUT /reserve-allocations/:id/adjust-balance

Headers:
  x-organization-id: <organization_id>
  x-idempotency-key: <unique_key>  (REQUIRED)

Body:
{
  "amount": 500000,
  "action": "TOP_UP",
  "date": "2026-06-12",
  "description": "Monthly allocation - 15% of June profit"
}

Response:
{
  "reserveTransaction": {
    "id": "<transaction_id>",
    "journalEntryId": "<entry_id>",
    "amount": 500000,
    "type": "TOP_UP",
    "date": "2026-06-12",
    "description": "Monthly allocation - 15% of June profit"
  },
  "newBalance": 2500000
}
```

### Journal Entry Pattern

```typescript theme={null}
// RESERVE_TOP_UP Entry
{
  kind: 'RESERVE_TOP_UP',
  transactionDate: '2026-06-12',
  status: 'POSTED',
  lines: [
    {
      role: 'RETAINED_EARNINGS',
      side: 'DEBIT',
      amount: 500000
    },
    {
      role: 'RESERVE_ALLOCATION',
      refId: '<reserve_id>',
      scopeKey: 'reserve:<reserve_id>',
      side: 'CREDIT',
      amount: 500000
    }
  ]
}
```

**Effect on accounts**:

* Retained Earnings (EQUITY): Debited -500,000 (decreases)
* Reserve Allocation (EQUITY): Credited +500,000 (increases)
* Net equity change: 0 (internal transfer)

***

## Related Topics

<CardGroup cols={2}>
  <Card title="Reserves Overview" icon="info" href="/tontines/reserves/overview">
    Understand reserves concept and purpose
  </Card>

  <Card title="Creating Reserves" icon="plus" href="/tontines/reserves/creating-reserves">
    Set up new reserve allocations
  </Card>

  <Card title="Reserve Withdrawals" icon="arrow-down" href="/tontines/reserves/reserve-withdrawals">
    Release funds from reserves
  </Card>

  <Card title="Balance Sheet" icon="scale-balanced" href="/tontines/reports/balance-sheet">
    View retained earnings and reserves
  </Card>

  <Card title="Profit & Loss" icon="chart-line" href="/tontines/reports/profit-and-loss">
    Calculate net income for allocations
  </Card>

  <Card title="Reserve Reporting" icon="chart-bar" href="/tontines/reserves/reserve-reporting">
    View reserve transaction history
  </Card>
</CardGroup>