Reserve Allocations (Top Up)

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.

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

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

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)

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.

Step-by-Step Instructions

Step 1: Navigate to Reserve

Open Reserves section

Click Reserves in the left sidebar

Find the reserve

Locate the reserve you want to allocate to

Click on reserve name

Opens reserve details page

Click Top Up or Adjust Balance

Opens allocation dialog

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)

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)

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

Typical approach: Use today’s date for current allocations. Use end-of-month dates for monthly allocations recorded at month-end close.

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)

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

Step 6: Submit

Review all fields

Confirm amount, date, and action (TOP_UP) are correct

Verify available retained earnings

Ensure allocation won’t exceed available undesignated retained earnings

Click Submit or Allocate

Funds transferred to reserve via journal entry

Confirm success

Reserve balance increases by allocation amount

Verify transaction in history

Allocation appears in reserve transaction history

What Happens During Allocation

When you allocate to a reserve, Agatabo automatically:

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)

Creates journal entry

Kind: RESERVE_TOP_UP
Date: Allocation date
Status: POSTED

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

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)
Records transaction
- Transaction appears in reserve transaction history
- Includes running balance after allocation
- Linked to journal entry for audit trail
Logs audit trail
- Records who made allocation
- Timestamp of operation
- Amount and description
- Full journal entry details

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.

Common Scenarios

Monthly Recurring Allocations

Set up systematic reserve building:

Document allocation policy

Example: “Allocate 500,000 RWF to Emergency Fund, 200,000 RWF to Equipment Reserve on first business day of each month”

Create calendar reminder

Set monthly reminder for reserve allocations (e.g., 1st of each month)

Verify profit first

Check P&L report to confirm retained earnings are positive and sufficient

Execute allocations

Top up all reserves per policy

Document in minutes

Record monthly allocations in treasurer’s report or meeting minutes

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:

Run Profit & Loss report

Determine net income for the period

Calculate allocations

Apply allocation percentages to net income

Top up each reserve

Execute allocations for all reserves

Verify retained earnings remain positive

Ensure sufficient undesignated retained earnings remain for operations (recommend keeping 20-30% buffer)

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:

Check current balance

View reserve details to see current balance

Calculate final allocation

Target - Current Balance = Amount Needed

Verify sufficient retained earnings

Ensure available undesignated funds cover the gap

Top up final amount

Allocate remaining amount to reach target

Mark reserve inactive (optional)

If no more allocations needed, update reserve to inactive status

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:

Calculate target reserve

E.g., 5% of total outstanding loans

Check current reserve balance

View Loan Loss Reserve balance

Calculate shortfall

(Portfolio × 5%) - Current Reserve Balance

Allocate shortfall

Top up to maintain 5% coverage

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

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

Troubleshooting

”Insufficient retained earnings”

Cause: Allocation would make undesignated retained earnings negative Solution:

Check Balance Sheet

View current total retained earnings

Calculate existing reserves

Sum all current reserve balances

Determine available amount

Available = Total Retained Earnings - Sum of Reserves

Reduce allocation

Allocate less than or equal to available amount

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:

Reactivate the reserve:
- Navigate to reserve details
- Click Edit or Update
- Set Active = true
- Save changes
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:

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

Learn about 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

Typical roles: Administrators and Accountants have reserves:write. Regular members typically have reserves:read (view only) or no access.

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

// 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)

Reserves Overview

Understand reserves concept and purpose

Creating Reserves

Set up new reserve allocations

Reserve Withdrawals

Release funds from reserves

Balance Sheet

View retained earnings and reserves

Profit & Loss

Calculate net income for allocations

Reserve Reporting

View reserve transaction history

​Overview

​When to Allocate to Reserves

​Before You Begin

​Step-by-Step Instructions

​Step 1: Navigate to Reserve

​Step 2: Enter Allocation Details

​Step 3: Choose Amount

​Step 4: Set Allocation Date

​Step 5: Add Description (Optional but Recommended)

​Step 6: Submit

​What Happens During Allocation

​Common Scenarios

​Monthly Recurring Allocations

​Profit-Based Allocations

​Reaching Reserve Target

​Adjusting for Portfolio Growth

​Validation and Constraints

​Input Validation

​Business Logic Validation

​Best Practices

​Troubleshooting

​”Insufficient retained earnings”

​“Reserve is inactive”

​”Period closed” or “Cannot create entry in closed period”

​“Amount validation error”

​”x-idempotency-key header is required”

​Permissions Required

​Technical Details

​API Endpoint

​Journal Entry Pattern

​Related Topics

Reserves Overview

Creating Reserves

Reserve Withdrawals

Balance Sheet

Profit & Loss

Reserve Reporting

Overview

When to Allocate to Reserves

Before You Begin

Step-by-Step Instructions

Step 1: Navigate to Reserve

Step 2: Enter Allocation Details

Step 3: Choose Amount

Step 4: Set Allocation Date

Step 5: Add Description (Optional but Recommended)

Step 6: Submit

What Happens During Allocation

Common Scenarios

Monthly Recurring Allocations

Profit-Based Allocations

Reaching Reserve Target

Adjusting for Portfolio Growth

Validation and Constraints

Input Validation

Business Logic Validation

Best Practices

Troubleshooting

”Insufficient retained earnings”

“Reserve is inactive”

”Period closed” or “Cannot create entry in closed period”

“Amount validation error”

”x-idempotency-key header is required”

Permissions Required

Technical Details

API Endpoint

Journal Entry Pattern

Related Topics