Creating Reserves

Overview

Creating a reserve establishes a designated fund within your organization’s equity for a specific future purpose. Reserves help you organize and track savings toward goals while keeping funds separate from general retained earnings.

What happens: Creating a reserve sets up the tracking structure (metadata + ledger account) but does NOT allocate any funds yet. New reserves start with a balance of zero and must be topped up separately.

Before You Begin

Prerequisites:

You have reserves:write permission
You have identified a specific purpose for the reserve
You have determined target reserve amount (optional but recommended)
You’ve decided on a unique, descriptive name

Note: You do NOT need existing retained earnings to create a reserve - only to allocate funds to it later. Creating the reserve is just setting up the structure.

Step-by-Step Instructions

Step 1: Navigate to Reserves

Open Reserves section

Click Reserves in the left sidebar

Click Add Reserve or New Reserve

Opens the reserve creation dialog

Step 2: Enter Reserve Details

Field	Description	Required	Default
Name	Short, descriptive name for the reserve	Yes	-
Description	Purpose, target amount, and usage guidelines	No	Empty
Active	Whether reserve can receive allocations	No	true (Active)

Step 3: Choose Reserve Name

Use clear, specific names that indicate purpose: Good names:

“Emergency Fund”
“Building Purchase Reserve”
“Computer Equipment Replacement”
“Loan Loss Reserve”
“Member Dividend Reserve 2026”
“Statutory Reserve”
“Expansion Fund”

Poor names:

“Reserve 1”
“Miscellaneous”
“Money”
“Savings”

Naming rules:

Must be non-empty string
Must be unique within your organization (cannot duplicate existing reserve name)
Can be updated later if needed
Used in ledger account name: ” Reserve Allocation”

Naming tip: Include the year if the reserve is time-specific (e.g., “Expansion Fund 2026”). For ongoing reserves, use general names (e.g., “Emergency Reserve”).

Step 4: Add Description (Optional but Recommended)

Provide details about the reserve’s purpose, target amount, and usage rules: Example descriptions: Emergency Reserve:

Purpose: Cover unexpected operational expenses and cash flow gaps
Target: 3,000,000 RWF (3 months operating expenses)
Allocation: 200,000 RWF monthly until target reached
Usage: Requires treasurer + chairperson approval for releases
Review: Quarterly balance review
Established: June 2026

Building Fund:

Purpose: Save toward purchasing office space in Kimihurura
Target: 25,000,000 RWF
Timeline: Accumulate over 5 years (2026-2031)
Allocation: 20% of monthly net profit + any large donations
Expected purchase: 2031

Loan Loss Reserve:

Purpose: Cover bad debt from loan defaults
Target: 5% of total outstanding loans (currently 1,500,000 RWF)
Allocation: 50,000 RWF monthly + 5% of new loan disbursements
Usage: Offset loan write-offs and bad debt expenses
Review: Adjust quarterly based on portfolio size and delinquency rates

Equipment Reserve:

Purpose: Replace aging computers and office equipment
Target: 2,000,000 RWF
Equipment list:
  - 5 laptops @ 800,000 RWF each
  - 2 printers @ 300,000 RWF each
Timeline: Purchase in Q4 2027
Allocation: 80,000 RWF monthly for 25 months

Step 5: Set Active Status

Active (recommended for new reserves):

Reserve can receive top-ups
Appears in allocation dialogs and dropdown lists
Default setting for all new reserves

Inactive:

Reserve cannot receive new allocations or releases
Use when reserve is fully funded and no longer growing
Use when reserve purpose is complete but keeping for historical tracking
Can be toggled back to active later if needed

When to mark inactive:

After reserve reaches target and no more allocations needed
When reserve purpose is obsolete but you want to keep the record
For year-specific reserves after the year ends (e.g., “Dividend Reserve 2025” after 2025)

Step 6: Submit

Review all fields

Verify name is unique, descriptive, and clear
Check description includes target amount and purpose

Click Save or Create Reserve

Reserve is created with zero balance

Confirm creation

Reserve appears in reserves list

Allocate initial funds (next step)

After creation, navigate to reserve and use “Top Up” to add funds

What Happens During Creation

When you create a reserve, Agatabo automatically:

Creates ReserveAllocationMeta record
- Stores reserve metadata (id, name, description, isActive)
- Links to your organization
- Generates unique UUID identifier
Creates linked ledger account
- Role: RESERVE_ALLOCATION (equity account type)
- Scope key: reserve:{reserveId} (unique identifier)
- Account name: “{Reserve Name} Reserve Allocation”
- Initial balance: 0 (zero)
Adds to reserves list
- Appears in reserve listing pages
- Available in allocation dropdowns (if active)
- Queryable via /reserve-allocations endpoint
Logs in audit trail
- Records who created the reserve
- Timestamp of creation
- Initial configuration

Important: New reserves start at zero balance. After creating a reserve, you must separately allocate funds to it using the “Top Up” or “Adjust Balance” action. Creating the reserve just establishes the tracking structure - no accounting entries are created until you allocate funds.

Learn how to allocate funds →

Common Scenarios

Setting Up Standard Reserve Set

Many tontines benefit from these core reserves:

Create Emergency Reserve

Name: “Emergency Fund”
Description: “Cover unexpected operational expenses. Target: 3,000,000 RWF (3 months operating expenses). Allocate 200,000 RWF monthly.”
Active: Yes

Create Loan Loss Reserve

Name: “Loan Loss Reserve”
Description: “Cover bad debt from loan defaults. Target: 5-10% of outstanding loans. Review quarterly.”
Active: Yes

Create Equipment Reserve

Name: “Equipment Replacement”
Description: “Replace aging computers and furniture. Target: Based on equipment lifecycle. Allocate 100,000 RWF monthly.”
Active: Yes

Establish allocation policy

Document in bylaws: “Allocate 15% of monthly profit to Emergency, 5% to Loan Loss, 10% to Equipment”

Begin monthly allocations

After all reserves created, start regular monthly top-ups

Creating Project-Specific Reserve

For one-time goals with specific timelines:

Create reserve with project name

Name: “Office Building Fund 2026-2030”
Description: “Save toward purchasing 200sqm office space in Kimihurura. Target: 30,000,000 RWF. Purchase planned: December 2030. Allocate 25% of monthly profit.”

Set clear timeline

Include start and end dates in description

Calculate monthly allocation

Target / Number of months = Monthly allocation
30,000,000 RWF / 60 months = 500,000 RWF/month

Begin aggressive allocations

Larger monthly allocations to reach goal by deadline

Mark inactive after use

Once funds released and building purchased, mark inactive (or delete if balance is zero)

Creating Year-Specific Reserve

For annual recurring purposes:

Create with year in name

Name: “Member Dividend Reserve 2026”
Description: “Designated funds for 2026 annual dividend distribution. Target: 5,000,000 RWF. Distribution: December 2026 AGM.”

Allocate throughout year

Monthly allocations from retained earnings

Release for dividend payment

When ready to distribute, release funds and record dividend expense

Mark inactive after year-end

After distribution complete, mark inactive

Create next year's reserve

In January 2027, create “Member Dividend Reserve 2027”

Replacing or Restructuring Reserve

If you need to rename or restructure: Option 1: Update Existing Reserve (recommended)

Navigate to reserve details

Find the reserve you want to update

Click Edit or Update

Modify name, description, or active status

Save changes

Reserve updated, balance and history preserved

Option 2: Delete and Recreate (only if no history)

Check reserve balance

Must be exactly zero to delete

Check transaction history

Must have no posted journal entries (no top-ups or releases ever recorded)

Delete old reserve

Only possible if both conditions met

Create new reserve

With updated name and purpose

Option 3: Transfer and Replace (if reserve has balance)

Release all funds from old reserve

Withdraw entire balance back to retained earnings

Mark old reserve inactive

Preserves historical records (cannot delete if has transaction history)

Create new reserve

With updated name and structure

Allocate funds to new reserve

Transfer funds from retained earnings to new reserve

Validation and Constraints

Name Validation

Rules:

✅ Must be non-empty string
✅ Must be unique within organization (case-sensitive)
❌ Cannot be blank or whitespace only
❌ Cannot duplicate existing reserve name

If name already exists:

Error: “A reserve with this name already exists”
Choose different name
Or update existing reserve instead of creating new one
Consider adding year or version (e.g., “Emergency Fund v2”)

Description

Rules:

✅ Optional field
✅ Can be null or empty string
✅ No length limit (but keep reasonable for readability)

Active Status

Rules:

✅ Optional field
✅ Boolean: true (active) or false (inactive)
✅ Defaults to true if not specified

Initial Balance

Fixed value:

All new reserves start with balance = 0
Cannot set initial balance during creation
Must use “Top Up” operation after creation to allocate funds

Best Practices

Reserve setup tips:Naming:

Use consistent naming conventions (e.g., all end with “Reserve” or “Fund”)
Include year for time-specific reserves (“Expansion Fund 2026”)
Use descriptive names that clearly indicate purpose
Keep names concise but meaningful (under 50 characters)

Quantity:

Limit to 3-7 reserves (too many become difficult to manage)
Don’t create a reserve unless you intend to actually allocate to it
Consolidate similar-purpose reserves rather than creating many small ones

Documentation:

Always add detailed description with target amount
Include allocation policy (% of profit, fixed monthly amount)
Document usage/approval requirements
Specify review frequency (monthly, quarterly, annually)

Targets:

Set specific, measurable targets in descriptions
Emergency fund: 3-6 months operating expenses
Loan loss: 5-10% of outstanding loans
Equipment: Based on replacement cost and lifecycle
Building/expansion: Based on project estimates

Governance:

Get member approval for reserve policies (good governance)
Document reserve strategy in bylaws or financial guidelines
Review reserve structure annually - consolidate or eliminate unused reserves
Report reserve balances and targets to members at meetings

Management:

Create all planned reserves upfront (don’t add ad-hoc)
Begin allocations immediately after creation
Mark inactive rather than deleting (preserves history)
Review descriptions annually and update targets as needed

Troubleshooting

”A reserve with this name already exists”

Cause: Reserve names must be unique within your organization Solutions:

Choose a different name
Add year or version to differentiate (e.g., “Emergency Fund 2026”)
Check if you meant to update the existing reserve instead
View reserves list to see all existing names

Cannot allocate funds after creating reserve

Cause: New reserves start with zero balance - creation and allocation are separate operations Solution:

Navigate to reserve details

Click on the newly created reserve in the list

Click Top Up or Adjust Balance

Opens the balance adjustment dialog

Select Top Up action

Choose “TOP_UP” (not “RELEASE”)

Enter amount

Amount to allocate from retained earnings (must have sufficient retained earnings)

Confirm

Funds transferred from retained earnings to reserve

Learn about reserve allocations →

Possible causes:

Reserve is inactive
- Solution: Edit reserve and set Active = true
Missing permissions
- Solution: Ensure you have reserves:read permission
Page not refreshed
- Solution: Refresh the page to reload reserve list
Frontend filter
- Solution: Check if dropdown filters out certain reserves

Cannot delete newly created reserve

Cause: Even new reserves with zero balance cannot be deleted if they have ANY transaction history Explanation:

Creating the reserve creates the ledger account
But ledger account creation is NOT a transaction
Reserve is only deletable if it has NEVER had any top-ups or releases
If you did even one top-up then released it all, cannot delete (has history)

Solution:

Mark the reserve as inactive instead of deleting
Or use a different name if you must recreate

Permissions Required

Action	Permission	Scope
View reserves	`reserves:read`	ANY
Create reserve	`reserves:write`	ANY
Update reserve	`reserves:write`	ANY
Delete reserve	`reserves:write`	ANY (only if zero balance + no history)

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

Technical Details

API Endpoint

POST /reserve-allocations

Headers:
  x-organization-id: <organization_id>

Body:
{
  "name": "Emergency Fund",
  "description": "Cover unexpected expenses. Target: 3M RWF.",
  "isActive": true
}

Response:
{
  "id": "<reserve_id>",
  "organizationId": "<organization_id>",
  "name": "Emergency Fund",
  "description": "Cover unexpected expenses. Target: 3M RWF.",
  "isActive": true,
  "balance": 0,
  "createdAt": "2026-06-12T10:30:00Z",
  "updatedAt": "2026-06-12T10:30:00Z"
}

Database Structure

ReserveAllocationMeta:

{
  id: string (UUID)
  organizationId: string
  ledgerAccountId: string (unique, auto-created)
  name: string (unique per organization)
  description: string | null
  isActive: boolean (default: true)
  createdAt: DateTime
  updatedAt: DateTime
}

Linked Ledger Account:

{
  id: string (UUID)
  organizationId: string
  roleDefinitionId: string (RESERVE_ALLOCATION role)
  scopeKey: "reserve:{reserveAllocationId}"
  name: "{Reserve Name} Reserve Allocation"
  balance: Decimal (starts at 0)
  accountType: "EQUITY"
}

Scope Key Format

reserve:{reserveAllocationId}

Example:
reserve:550e8400-e29b-41d4-a716-446655440000

This scope key uniquely identifies the ledger account for this specific reserve allocation.

Reserves Overview

Understand reserves concept and how they work

Reserve Allocations

Add funds to reserves (Top Up)

Reserve Withdrawals

Release funds from reserves

Reserve Reporting

View balances and transaction history

Managing Reserves

Edit or delete reserves

Reserve-Funded Expenses

Spend directly from reserves

​Overview

​Before You Begin

​Step-by-Step Instructions

​Step 1: Navigate to Reserves

​Step 2: Enter Reserve Details

​Step 3: Choose Reserve Name

​Step 4: Add Description (Optional but Recommended)

​Step 5: Set Active Status

​Step 6: Submit

​What Happens During Creation

​Common Scenarios

​Setting Up Standard Reserve Set

​Creating Project-Specific Reserve

​Creating Year-Specific Reserve

​Replacing or Restructuring Reserve

​Validation and Constraints

​Name Validation

​Description

​Active Status

​Initial Balance

​Best Practices

​Troubleshooting

​”A reserve with this name already exists”

​Cannot allocate funds after creating reserve

​Reserve doesn’t appear in allocation dropdown

​Cannot delete newly created reserve

​Permissions Required

​Technical Details

​API Endpoint

​Database Structure

​Scope Key Format

​Related Topics

Reserves Overview

Reserve Allocations

Reserve Withdrawals

Reserve Reporting

Managing Reserves

Reserve-Funded Expenses

Overview

Before You Begin

Step-by-Step Instructions

Step 1: Navigate to Reserves

Step 2: Enter Reserve Details

Step 3: Choose Reserve Name

Step 4: Add Description (Optional but Recommended)

Step 5: Set Active Status

Step 6: Submit

What Happens During Creation

Common Scenarios

Setting Up Standard Reserve Set

Creating Project-Specific Reserve

Creating Year-Specific Reserve

Replacing or Restructuring Reserve

Validation and Constraints

Name Validation

Description

Active Status

Initial Balance

Best Practices

Troubleshooting

”A reserve with this name already exists”

Cannot allocate funds after creating reserve

Reserve doesn’t appear in allocation dropdown

Cannot delete newly created reserve

Permissions Required

Technical Details

API Endpoint

Database Structure

Scope Key Format

Related Topics