> ## 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 Withdrawals (Release)

> Release funds from reserves back to retained earnings for designated purposes

## Overview

**Reserve withdrawal** (also called **Release**) transfers money from a designated reserve back to retained earnings. This increases unallocated retained earnings and decreases the reserve balance, making earmarked funds available for general organizational use.

<Note>
  **Two ways to use reserve funds:**

  1. **Pure Release**: Withdraw funds from reserve back to retained earnings, then spend separately (two separate operations)
  2. **Reserve-Funded Expense**: Spend directly from reserve when recording expense (automatic release + expense in one operation)

  This page covers **pure release** only. For reserve-funded expenses, see the expenses documentation.
</Note>

## When to Release from Reserves

Common scenarios:

* **Using funds for intended purpose**: Release from Building Fund before purchasing building
* **Emergency expenditure**: Release from Emergency Reserve before covering unexpected costs
* **Reserve reduction**: Decrease reserve that exceeds target
* **Reserve elimination**: Empty reserve that is no longer needed
* **Policy adjustment**: Rebalance reserves per updated allocation strategy
* **Freeing designated funds**: Make earmarked funds available for general use

<Warning>
  **Important considerations:**

  * Only release reserves when using funds for the stated purpose or when rebalancing
  * Don't release reserves just to access cash - that defeats the purpose of having designated savings
  * Consider using **reserve-funded expenses** instead of release + separate expense (maintains better audit trail)
  * Get appropriate approval before releasing significant amounts
</Warning>

## Before You Begin

<Note>
  **Prerequisites:**

  * You have `reserves:write` permission
  * Reserve has sufficient balance to release
  * You have a valid reason for releasing funds
  * Accounting period is not closed
  * You have an idempotency key ready (auto-generated by frontend)
</Note>

***

## 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 release from
  </Step>

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

  <Step title="Click Release or Adjust Balance">
    Opens withdrawal dialog
  </Step>
</Steps>

***

### Step 2: Enter Release Details

| Field           | Description                                  | Required | Validation                                  |
| --------------- | -------------------------------------------- | -------- | ------------------------------------------- |
| **Amount**      | How much to release from the reserve         | Yes      | Minimum 0.01, cannot exceed reserve balance |
| **Action**      | Select "Release" (remove money from reserve) | Yes      | Must be 'RELEASE'                           |
| **Date**        | When this release occurred                   | Yes      | ISO format, cannot be in closed period      |
| **Description** | Purpose of this release                      | No       | Optional but strongly recommended           |

***

### Step 3: Choose Amount

Determine how much to release based on your needs:

**Full Expenditure Release**:

```
Upcoming expense: 3,000,000 RWF for equipment
Equipment Reserve balance: 5,000,000 RWF
Release: 3,000,000 RWF (exact amount needed)
Remaining: 2,000,000 RWF in reserve
```

**Partial Release**:

```
Emergency repair cost: 500,000 RWF
Emergency Reserve balance: 3,000,000 RWF
Release: 500,000 RWF (just enough for emergency)
Remaining: 2,500,000 RWF in reserve (maintain buffer)
```

**Complete Closure**:

```
Reserve purpose completed (building purchased)
Building Fund balance: 1,500,000 RWF (leftover)
Release: 1,500,000 RWF (entire balance)
Remaining: 0 RWF (reserve can be marked inactive)
```

**Excess Reduction**:

```
Target: 3,000,000 RWF
Current balance: 5,000,000 RWF (over-allocated)
Release: 2,000,000 RWF (bring back to target)
Remaining: 3,000,000 RWF (at target)
```

<Warning>
  **Cannot exceed balance**: You can only release up to the current reserve balance. If reserve has 1,000,000 RWF, you cannot release 2,000,000 RWF.
</Warning>

***

### Step 4: Set Release Date

**Date**: When this release is effective (usually today or when funds will be used)

**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
* Future planned expense: 2026-06-30 (end of month)
* Historical correction: 2026-06-01 (if period still open)

***

### Step 5: Add Description (Strongly Recommended)

**Critical**: Document WHY funds are being released for audit trail and transparency:

**Good descriptions:**

* "Released for office building purchase - Contract #2026-456, 25M RWF property acquisition"
* "Emergency repair of water damage to office - Invoice #2026-234, contractor ABC Ltd"
* "Reducing reserve below target per Q2 2026 member meeting decision - excess allocation"
* "Closing obsolete reserve after project completion - Building Fund no longer needed"
* "Releasing for equipment purchase - 5 laptops @ 800K each = 4M RWF"
* "Rebalancing reserves per updated allocation policy - transferring to Emergency Fund"

**Poor descriptions:**

* "Withdrawal"
* "Need money"
* "Release"
* (blank)

<Note>
  **Audit requirement**: Reserve releases should always have detailed descriptions explaining the purpose. This demonstrates to members and auditors that reserves were used appropriately for their intended purposes.

  **Best practice**: Include reference numbers (invoice #, contract #, meeting minutes date) that link the release to supporting documentation.
</Note>

***

### Step 6: Submit

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

  <Step title="Verify reserve balance">
    Ensure release won't exceed available reserve balance
  </Step>

  <Step title="Click Submit or Release">
    Funds transferred from reserve to retained earnings via journal entry
  </Step>

  <Step title="Confirm success">
    Reserve balance decreases, retained earnings increases
  </Step>

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

  <Step title="Record corresponding transaction (if applicable)">
    If funds were released to pay for something, record that expense or purchase separately
  </Step>
</Steps>

***

## What Happens During Release

When you release from 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
   * Amount cannot exceed reserve balance
   * Date must not be in closed period

2. **Creates journal entry**
   ```
   Kind: RESERVE_RELEASE
   Date: Release date
   Status: POSTED

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

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

4. **Records transaction**
   * Transaction appears in reserve transaction history with type "RELEASE"
   * Includes running balance after release
   * Linked to journal entry for audit trail

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

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

  **No cash movement**: Releasing from a reserve does NOT move cash between bank accounts or create cash. Cash remains in your bank accounts - this is purely an accounting designation that makes previously earmarked funds available for general use.
</Note>

***

## Reserve Release vs. Reserve-Funded Expense

There are **two ways** to use reserve funds:

### Option 1: Pure Release (This Page)

**Process**:

1. Release funds from reserve to retained earnings (RESERVE\_RELEASE journal entry)
2. Separately record expense or purchase (EXPENSE\_PAYMENT journal entry)

**When to use**:

* Large purchases requiring multiple steps (release funds, get quotes, then purchase)
* When you need funds available before knowing exact expense amount
* Rebalancing or closing reserves without immediate expense
* Transferring between reserves (release from one, top up another)

**Example**:

```
Step 1: Release from Building Fund
Amount: 25,000,000 RWF
Description: "Released for office building purchase per contract #456"

Journal Entry:
Dr RESERVE_ALLOCATION (Building Fund)  25,000,000
   Cr RETAINED_EARNINGS                25,000,000

Step 2: Record Asset Purchase (separately)
Amount: 25,000,000 RWF
Description: "Office building purchase - 123 Main St"

Journal Entry:
Dr FIXED_ASSET                         25,000,000
   Cr CASH (Bank Account)              25,000,000
```

***

### Option 2: Reserve-Funded Expense (Recommended for Most Expenses)

**Process**:

1. Record expense and specify reserve allocation ID
2. System automatically creates two linked journal entries:
   * Entry 1: RESERVE\_RELEASE (parent)
   * Entry 2: RESERVE\_EXPENSE (child, linked to parent)

**When to use**:

* Regular expenses paid from reserves
* Emergency expenditures from Emergency Reserve
* Any expense where you know exact amount at time of payment

**Benefits**:

* Automatic linkage between release and expense
* Better audit trail (entries are linked)
* Simpler process (one operation instead of two)
* Clear reserve usage tracking

**Example**:

```
Record expense with reserveAllocationId = Emergency Reserve

System creates two entries:

Entry 1 (RESERVE_RELEASE - parent):
Dr RESERVE_ALLOCATION (Emergency)     500,000
   Cr RETAINED_EARNINGS               500,000

Entry 2 (RESERVE_EXPENSE - child):
Dr OPERATING_EXPENSE (Repairs)        500,000
   Cr CASH (Bank Account)             500,000
Parent: Entry 1
```

[Learn about reserve-funded expenses →](/tontines/expenses/recording-expenses)

***

## Common Scenarios

### Scenario 1: Using Reserve for Large Purchase

**Situation**: Building Fund has 25M RWF, ready to purchase office space

<Steps>
  <Step title="Verify purpose alignment">
    Ensure purchase matches reserve purpose (Building Fund → building purchase ✅)
  </Step>

  <Step title="Release funds from reserve">
    Amount: 25,000,000 RWF<br />
    Description: "Released for office building purchase - Contract #2026-456"
  </Step>

  <Step title="Record asset purchase separately">
    Navigate to Fixed Assets → Add Asset → Cash Purchase<br />
    Amount: 25,000,000 RWF<br />
    Description: "Office building at 123 Main St - Released from Building Fund"
  </Step>

  <Step title="Mark reserve inactive">
    If building purchase complete and reserve no longer needed, set Active = false
  </Step>
</Steps>

**Result**:

```
Building Fund balance: 25M → 0 RWF
Retained earnings: +25M RWF (released funds)
Fixed assets: +25M RWF (new building)
Cash: -25M RWF (payment to seller)
Net equity: Unchanged (release offset by expense/asset)
```

***

### Scenario 2: Emergency Expenditure

**Situation**: Unexpected office repairs needed, Emergency Reserve has 3M RWF

<Steps>
  <Step title="Verify emergency nature">
    Unexpected, urgent expense that cannot wait for regular budget
  </Step>

  <Step title="Get approval (if required)">
    Some organizations require committee approval for emergency reserve usage
  </Step>

  <Step title="Option A: Use reserve-funded expense">
    Record expense and select Emergency Reserve as funding source<br />
    (Recommended - automatic linkage)
  </Step>

  <Step title="Option B: Release then expense">
    1. Release exact amount needed (e.g., 500,000 RWF)<br />
    2. Record expense separately with same reference
  </Step>

  <Step title="Report to members">
    Notify members at next meeting that emergency reserve was used
  </Step>

  <Step title="Plan replenishment">
    Schedule allocations to restore emergency reserve to target level
  </Step>
</Steps>

**Using reserve-funded expense (recommended)**:

```
Record expense:
Amount: 500,000 RWF
Reserve: Emergency Reserve
Description: "Emergency repair - water damage to office, Invoice #2026-234"

System creates:
Entry 1: Release from reserve
Entry 2: Expense payment (linked to Entry 1)

Result:
Emergency Reserve: 3M → 2.5M RWF
Cash: -500K RWF (repair payment)
```

***

### Scenario 3: Closing or Reducing Excess Reserve

**Situation**: Equipment Reserve has 5M RWF but target is only 3M RWF (over-allocated)

<Steps>
  <Step title="Confirm reduction decision">
    Get member or committee approval if required by policy
  </Step>

  <Step title="Calculate excess">
    Current: 5,000,000 RWF<br />
    Target: 3,000,000 RWF<br />
    Excess: 2,000,000 RWF
  </Step>

  <Step title="Release excess amount">
    Amount: 2,000,000 RWF<br />
    Description: "Reducing Equipment Reserve to 3M RWF target per Q2 2026 review - excess allocation"
  </Step>

  <Step title="Keep reserve active">
    Continue future allocations to maintain 3M RWF target
  </Step>
</Steps>

**Complete closure** (if reserve no longer needed):

<Steps>
  <Step title="Release full balance">
    Amount: 5,000,000 RWF (entire balance)<br />
    Description: "Closing Equipment Reserve - equipment purchase complete, reserve no longer needed per June 2026 member meeting"
  </Step>

  <Step title="Mark reserve inactive">
    Edit reserve and set Active = false
  </Step>

  <Step title="Optional: Delete reserve">
    If reserve has zero balance and you want to remove it entirely (can only delete if no transaction history after this release)
  </Step>
</Steps>

***

### Scenario 4: Rebalancing Between Reserves

**Situation**: Transfer funds from over-funded Building Fund to under-funded Emergency Reserve

<Steps>
  <Step title="Release from source reserve">
    Reserve: Building Fund<br />
    Amount: 1,000,000 RWF<br />
    Description: "Rebalancing reserves - transferring to Emergency Fund per policy update"
  </Step>

  <Step title="Top up target reserve">
    Reserve: Emergency Fund<br />
    Amount: 1,000,000 RWF<br />
    Description: "Rebalancing reserves - transferred from Building Fund per policy update"
  </Step>
</Steps>

**Result**:

```
Building Fund: -1M RWF
Emergency Fund: +1M RWF
Retained earnings: Unchanged (net zero from release + top up)
Total reserves: Unchanged (same total, different distribution)
```

***

## Validation and Constraints

### Input Validation

**Amount**:

* ✅ Must be at least 0.01
* ✅ Must match organization's currency decimal places
* ✅ Cannot exceed reserve balance
* ❌ Cannot be negative or zero

**Action**:

* ✅ Must be 'RELEASE' (for withdrawals)
* ❌ Cannot be 'TOP\_UP' (use allocation 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
* ✅ Strongly recommended for audit trail

### Business Logic Validation

**Reserve Status**:

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

**Reserve Balance Check**:

* Release amount must not exceed current reserve balance
* System validates before creating journal entry
* Error if insufficient: "Insufficient reserve balance"

**Accounting Period**:

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

**Idempotency**:

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

***

## Best Practices

<Note>
  **Release tips:**

  **Purpose and Approval:**

  * Only release for stated reserve purpose or with valid rebalancing reason
  * Get approval before releasing from significant reserves (set thresholds in policy)
  * Always provide detailed descriptions explaining release rationale
  * Include reference numbers linking to supporting documentation

  **Audit Trail:**

  * Link reserve release to corresponding expense/purchase in descriptions
  * Use same reference numbers for release and related transactions
  * Report reserve releases to members at meetings (transparency)
  * Keep supporting documents (invoices, contracts, approval minutes)

  **Reserve Management:**

  * Replenish reserves after usage if reserve purpose is ongoing
  * Don't release "just because" - maintain reserve discipline
  * Review reserve balances quarterly - release excess if consistently over target
  * Plan releases in advance for large expenditures

  **Alternatives:**

  * Consider using **reserve-funded expenses** instead of pure release (better audit trail)
  * For expenses, specify reserve when recording expense rather than releasing first
  * Pure release best for: large purchases, rebalancing, reserve closures
</Note>

***

## Troubleshooting

### "Insufficient reserve balance"

**Cause**: Release amount exceeds current reserve balance

**Solution**:

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

  <Step title="Reduce release amount">
    Release only up to available balance
  </Step>

  <Step title="Alternative sources">
    If you need more funds:<br />

    * Use general retained earnings (outside reserves)<br />
    * Release from multiple reserves<br />
    * Wait to accumulate more in reserve
  </Step>
</Steps>

**Example**:

```
Reserve balance: 1,000,000 RWF
Attempted release: 2,000,000 RWF ❌

Solutions:
- Release 1,000,000 RWF ✅ (maximum available)
- Release 800,000 RWF from this reserve + 1,200,000 from retained earnings ✅
```

***

### "Reserve is inactive"

**Cause**: Cannot release from inactive reserves

**Solutions**:

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

2. **Check if deactivated intentionally**:
   * If reserve was deactivated after completion, may need to reopen
   * Contact administrator if unsure why reserve is inactive

***

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

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

**Solutions**:

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

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

***

### "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 release attempt (e.g., UUID)
* Most frontends auto-generate this

***

## Approval Workflows (Recommended)

**Suggested authorization levels** (adapt to your organization):

| Reserve Release Amount  | Required Approval        | Documentation                                            |
| ----------------------- | ------------------------ | -------------------------------------------------------- |
| Under 100,000 RWF       | Treasurer alone          | Receipt/invoice required                                 |
| 100,000 - 500,000 RWF   | Treasurer + Chairperson  | Written justification + supporting docs                  |
| 500,000 - 2,000,000 RWF | Executive committee vote | Meeting minutes + approval vote + supporting docs        |
| Over 2,000,000 RWF      | Full member meeting vote | Special meeting minutes + member vote + contracts/quotes |

<Note>
  **Governance tip**: Document reserve release approval requirements in your organization's bylaws or financial policies. This prevents unauthorized depletion of designated savings and ensures appropriate oversight for large expenditures.

  **Emergency provisions**: Define emergency thresholds where approval can be obtained retroactively (e.g., emergency repairs under 200K RWF can be approved by Treasurer, reported at next meeting).
</Note>

***

## Permissions Required

| Action               | Permission       | Scope |
| -------------------- | ---------------- | ----- |
| View reserves        | `reserves:read`  | ANY   |
| Release from 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": "RELEASE",
  "date": "2026-06-12",
  "description": "Released for emergency office repairs - Invoice #2026-234"
}

Response:
{
  "reserveTransaction": {
    "id": "<transaction_id>",
    "journalEntryId": "<entry_id>",
    "amount": 500000,
    "type": "RELEASE",
    "date": "2026-06-12",
    "description": "Released for emergency office repairs - Invoice #2026-234"
  },
  "newBalance": 2500000
}
```

### Journal Entry Pattern

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

**Effect on accounts**:

* Reserve Allocation (EQUITY): Debited -500,000 (decreases)
* Retained Earnings (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="Reserve Allocations" icon="arrow-up" href="/tontines/reserves/reserve-allocations">
    Add funds to reserves (Top Up)
  </Card>

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

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

  <Card title="Reserve-Funded Expenses" icon="receipt" href="/tontines/expenses/recording-expenses">
    Spend directly from reserves (recommended)
  </Card>

  <Card title="Fixed Assets" icon="building" href="/tontines/fixed-assets/overview">
    Record large purchases (buildings, equipment)
  </Card>
</CardGroup>