Ledger Accounts

What are Ledger Accounts?

Ledger accounts are the individual categories where financial transactions are recorded in the double-entry accounting system. Together, all ledger accounts form the chart of accounts - the complete list of financial categories used by your organization.

Key concept: Every journal entry affects at least two ledger accounts (one debit, one credit). Ledger accounts track the cumulative effect of all transactions over time, providing a running balance for each financial category.

API Endpoints

List All Ledger Accounts

Get all ledger accounts for an organization:

GET /ledger-accounts?includeInactive={boolean}
Headers:
  x-organization-id: {organizationId}

Query parameters:

Parameter	Type	Required	Description
`includeInactive`	boolean	No	Include inactive accounts in results. Defaults to false (active only).

Response:

{
  "message": "Ledger accounts fetched successfully",
  "data": [
    {
      "id": "acc-123",
      "name": "Cash - Main Account",
      "balance": "5000000",
      "isActive": true,
      "scopeKey": "organization:org-123",
      "roleDefinitionId": "role-def-456",
      "roleDefinition": {
        "id": "role-def-456",
        "role": "CASH",
        "type": "ASSET",
        "name": "Cash",
        "isSystem": true,
        "isActive": true
      }
    },
    {
      "id": "acc-789",
      "name": "Member Savings - Alice",
      "balance": "500000",
      "isActive": true,
      "scopeKey": "organizationUser:user-abc",
      "roleDefinitionId": "role-def-789",
      "roleDefinition": {
        "id": "role-def-789",
        "role": "SAVINGS",
        "type": "LIABILITY",
        "name": "Member Savings",
        "isSystem": true,
        "isActive": true
      }
    }
  ]
}

Accounts sorted by: Name (ascending, alphabetical)

Get Single Ledger Account

Get details for a specific ledger account:

GET /ledger-accounts/:ledgerAccountId
Headers:
  x-organization-id: {organizationId}

Response:

{
  "message": "Ledger account retrieved successfully",
  "data": {
    "id": "acc-123",
    "organizationId": "org-123",
    "roleDefinitionId": "role-def-456",
    "scopeKey": "organization:org-123",
    "name": "Cash - Main Account",
    "description": null,
    "balance": "5000000",
    "isActive": true,
    "createdAt": "2026-01-01T00:00:00.000Z",
    "updatedAt": "2026-06-12T10:30:00.000Z"
  }
}

Get Account Activity

Get journal entry lines affecting a specific account:

GET /ledger-accounts/:ledgerAccountId/activity?page={page}&limit={limit}&from={date}&to={date}
Headers:
  x-organization-id: {organizationId}

Query parameters: See Viewing Journal Entries for complete filter documentation.

Account Structure

Each ledger account has the following properties:

Field	Type	Description
id	UUID	Unique account identifier
name	string	Account display name (e.g., “Cash - Main Account”, “Member Savings - Alice”)
balance	Decimal	Current balance (positive or negative)
isActive	boolean	Whether account is active (inactive accounts excluded from most reports)
scopeKey	string	Entity scope (organization, organizationUser, loan, reserve, fixedAsset)
roleDefinition	object	Account role defining behavior and type
roleDefinition.role	string	System role code (CASH, SAVINGS, LOAN_RECEIVABLE, etc.)
roleDefinition.type	enum	Account type (ASSET, LIABILITY, EQUITY, INCOME, EXPENSE)
roleDefinition.isSystem	boolean	Whether role is system-managed (true) or custom (false)

Account Types

1. Assets (ASSET)

Resources owned by the organization: Account roles:

CASH: Cash on hand or in bank accounts
LOAN_RECEIVABLE: Principal amount of outstanding loans
INTEREST_RECEIVABLE: Accrued interest not yet paid
PENALTY_RECEIVABLE: Accrued penalties not yet paid
FIXED_ASSET: Property, equipment, furniture, buildings

Normal balance: DEBIT (positive balance = debit side) Increases with: Debit entries Decreases with: Credit entries Example accounts:

Cash - Main Account (organization:org-123): 5,000,000 RWF
Loan - Bob's Business Loan (loan:loan-456): 2,000,000 RWF
Office Furniture (fixedAsset:asset-789): 500,000 RWF

2. Liabilities (LIABILITY)

What the organization owes to others: Account roles:

SAVINGS: Member savings balances (one account per member)
BORROWER_SURPLUS_LIABILITY: Overpayments from borrowers

Normal balance: CREDIT (positive balance = credit side) Increases with: Credit entries Decreases with: Debit entries Example accounts:

Member Savings - Alice (organizationUser:user-abc): 500,000 RWF
Member Savings - Bob (organizationUser:user-def): 800,000 RWF
Borrower Surplus (loan:loan-123): 10,000 RWF

Important: Member savings are liabilities (not equity) because the organization owes these funds to members on demand. Members can withdraw their savings at any time, making it an obligation.

3. Equity (EQUITY)

Organization’s net worth (capital): Account roles:

RETAINED_EARNINGS: Accumulated profits from operations
RESERVE_ALLOCATION: Designated reserves (emergency fund, loan loss reserve, etc.)
OPENING_EQUITY: Initial capital when starting organization
OTHER_EQUITY: Miscellaneous equity accounts

Normal balance: CREDIT (positive balance = credit side) Increases with: Credit entries (profits, capital contributions) Decreases with: Debit entries (losses, dividend distributions, reserve allocations) Example accounts:

Retained Earnings (organization:org-123): 4,500,000 RWF
Emergency Fund Reserve (reserve:reserve-abc): 1,000,000 RWF
Loan Loss Reserve (reserve:reserve-def): 500,000 RWF

4. Income (INCOME)

Revenue earned by the organization: Account roles:

INTEREST_INCOME: Interest earned on loans
PENALTY_INCOME: Late payment penalties
ENTRY_FEE_INCOME: Membership fees
DISBURSEMENT_FEE_INCOME: Loan processing fees
BAD_DEBT_RECOVERY_INCOME: Recovered previously written-off debts
OTHER_INCOME: Miscellaneous income

Normal balance: CREDIT (positive balance = credit side) Increases with: Credit entries (earning revenue) Decreases with: Debit entries (reversals, corrections) Example accounts:

Interest Income (organization:org-123): 2,500,000 RWF
Entry Fee Income (organization:org-123): 100,000 RWF
Penalty Income (organization:org-123): 50,000 RWF

Period-end behavior:

Income accounts reset to zero at period close
Balances transferred to Retained Earnings

5. Expenses (EXPENSE)

Costs incurred by the organization: Account roles:

OPERATING_EXPENSE: General operating costs (rent, utilities, supplies, salaries)
BANK_CHARGE_EXPENSE: Bank fees and charges
BAD_DEBT_EXPENSE: Loan write-offs

Normal balance: DEBIT (positive balance = debit side) Increases with: Debit entries (incurring expenses) Decreases with: Credit entries (reversals, corrections) Example accounts:

Operating Expense (organization:org-123): 2,000,000 RWF
Bank Charge Expense (organization:org-123): 150,000 RWF
Bad Debt Expense (organization:org-123): 300,000 RWF

Period-end behavior:

Expense accounts reset to zero at period close
Balances transferred to Retained Earnings (reducing equity)

Account Roles

System-defined roles determine account behavior and how transactions are processed. Complete list of account roles:

Role	Type	Purpose	Scope Pattern
CASH	ASSET	Bank account balances and cash on hand	organization:
SAVINGS	LIABILITY	Individual member deposit balances	organizationUser:
LOAN_RECEIVABLE	ASSET	Outstanding loan principal	loan:
INTEREST_RECEIVABLE	ASSET	Unpaid loan interest	loan:
PENALTY_RECEIVABLE	ASSET	Unpaid late fees	loan:
FIXED_ASSET	ASSET	Long-term assets (equipment, property)	fixedAsset: or organization:
BORROWER_SURPLUS_LIABILITY	LIABILITY	Overpayments from borrowers	loan:
RETAINED_EARNINGS	EQUITY	Accumulated profit	organization:
RESERVE_ALLOCATION	EQUITY	Designated reserves	reserve:
OPENING_EQUITY	EQUITY	Initial capital	organization:
OTHER_EQUITY	EQUITY	Miscellaneous equity	organization: or custom
INTEREST_INCOME	INCOME	Earned interest on loans	organization:
PENALTY_INCOME	INCOME	Late payment penalties	organization:
ENTRY_FEE_INCOME	INCOME	Membership fees	organization:
DISBURSEMENT_FEE_INCOME	INCOME	Loan processing fees	organization:
BAD_DEBT_RECOVERY_INCOME	INCOME	Recovered bad debt	organization:
OTHER_INCOME	INCOME	Miscellaneous income	organization: or custom
OPERATING_EXPENSE	EXPENSE	General operating costs	organization:
BANK_CHARGE_EXPENSE	EXPENSE	Bank fees	organization:
BAD_DEBT_EXPENSE	EXPENSE	Loan write-offs	organization:

View complete ledger roles reference →

Scope Keys

Scope keys link ledger accounts to specific entities, enabling per-entity accounting. Format:

{entity_type}:{entity_id}

Examples:

Scope Key	Account Type	Example
`organization:org-123`	Organization-wide accounts	Cash, Retained Earnings, Income, Expenses
`organizationUser:user-abc`	Member-specific accounts	Alice’s SAVINGS account
`loan:loan-456`	Loan-specific accounts	Bob’s loan LOAN_RECEIVABLE, INTEREST_RECEIVABLE
`reserve:reserve-789`	Reserve-specific accounts	Emergency Fund RESERVE_ALLOCATION
`fixedAsset:asset-012`	Asset-specific accounts	Office furniture FIXED_ASSET

Why scope keys matter:

✅ Each member has their own SAVINGS account (tracked separately)
✅ Each loan has its own LOAN_RECEIVABLE account
✅ Each reserve has its own RESERVE_ALLOCATION account
✅ Enables per-member, per-loan, per-reserve accounting
✅ Allows querying all accounts for a specific entity

Example: Member-specific accounts:

{
  "name": "Member Savings - Alice",
  "scopeKey": "organizationUser:user-abc",
  "roleDefinition": {
    "role": "SAVINGS",
    "type": "LIABILITY"
  },
  "balance": "500000"
}

{
  "name": "Member Savings - Bob",
  "scopeKey": "organizationUser:user-def",
  "roleDefinition": {
    "role": "SAVINGS",
    "type": "LIABILITY"
  },
  "balance": "800000"
}

Account Balance

For each account, the balance represents:

Cumulative effect of all posted journal entries affecting that account
Running total since account creation
Current value as of the latest transaction

Balance calculation:

Balance = Sum of DEBIT lines - Sum of CREDIT lines (for the account)

For ASSET and EXPENSE accounts:
  Positive balance = Debit balance (normal)
  Negative balance = Credit balance (abnormal)

For LIABILITY, EQUITY, and INCOME accounts:
  Positive balance = Credit balance (normal)
  Negative balance = Debit balance (abnormal)

Example - Cash Account (ASSET):

Account: Cash - Main Account
Type: ASSET (normal debit balance)

Opening Balance (Jan 1):     5,000,000 RWF
+ Member deposits (debits):  +2,000,000 RWF
- Loans disbursed (credits): -1,500,000 RWF
- Expenses paid (credits):     -300,000 RWF
= Closing Balance (Jan 31):   5,200,000 RWF (debit)

Example - Member Savings Account (LIABILITY):

Account: Member Savings - Alice
Type: LIABILITY (normal credit balance)

Opening Balance (Jan 1):     500,000 RWF
+ Deposits (credits):       +100,000 RWF
+ Dividends (credits):       +50,000 RWF
- Withdrawals (debits):      -80,000 RWF
= Closing Balance (Jan 31):  570,000 RWF (credit)

Viewing Account Activity

To see all transactions affecting an account:

GET /ledger-accounts/:ledgerAccountId/activity
Headers:
  x-organization-id: {organizationId}
Query params:
  ?page=1&limit=20&from=2026-01-01&to=2026-06-30

Response includes:

All journal entry lines affecting the account
Transaction date, description, amount, debit/credit side
Running balance after each transaction
References to related entities (member, loan, reserve)

Example activity:

Date	Description	Debit	Credit	Balance
Jan 1	Opening Balance	5,000,000	-	5,000,000
Jan 5	Member deposit	100,000	-	5,100,000
Jan 10	Loan disbursement	-	500,000	4,600,000
Jan 15	Loan repayment	550,000	-	5,150,000
Jan 20	Operating expense	-	200,000	4,950,000
Jan 31	Closing Balance			4,950,000

View complete account activity documentation →

Account Reconciliation

Reconciliation verifies that ledger account balances match external records.

Cash Account Reconciliation

Compare to bank statements:

Get ending balance from bank statement

Bank statement shows: 5,100,000 RWF

Get Cash ledger account balance

Agatabo shows: 4,950,000 RWF

Identify differences

Difference: 150,000 RWFPossible causes:

Outstanding checks (issued but not yet cleared)
Deposits in transit (deposited but not yet cleared)
Bank fees not yet recorded in Agatabo
Interest earned not yet recorded

Record adjustments

Create journal entries for bank fees, interest, or errors

Verify reconciliation

Adjusted balance should match bank statement

Member Savings Reconciliation

Compare to member passbooks or statements:

Get total Member Savings from trial balance

Sum of all SAVINGS accounts: 18,000,000 RWF

Get sum of all member passbook balances

Manual calculation or report: 17,900,000 RWF

Identify discrepancy

Difference: 100,000 RWFInvestigate:

Recent transactions not yet in passbook
Passbook balances not updated
Data entry errors
Missing transactions

Resolve discrepancies

Update passbooks or correct ledger entries

Loan Receivable Reconciliation

Compare to loan portfolio report:

Get total Loan Receivable from trial balance

Sum of all LOAN_RECEIVABLE accounts: 15,000,000 RWF

Get sum of all outstanding loans

Loan portfolio report: 15,050,000 RWF

Investigate variance

Difference: 50,000 RWFCheck:

Recent loan disbursements or payments not yet posted
Loan write-offs not recorded
Data entry errors

Drill down to individual loans

Compare each loan account balance to loan detail

Cannot Modify Account Balances Directly

Ledger account balances cannot be edited directly. They change only through journal entries.This ensures:

✅ Complete audit trail (every change recorded)
✅ Double-entry integrity (all entries balanced)
✅ Compliance with accounting standards
✅ Protection against unauthorized changes

To adjust an account balance: Option 1: Use standard features

Member deposit → Records to SAVINGS and CASH accounts
Loan disbursement → Records to LOAN_RECEIVABLE and CASH accounts
Expense payment → Records to OPERATING_EXPENSE and CASH accounts
Dividend distribution → Records to RETAINED_EARNINGS and SAVINGS accounts

Option 2: Create manual journal entry

Requires ledger:write permission
Must be balanced (debits = credits)
Requires approval (recommended)
See manual journal entries guide →

Inactive Accounts

Accounts can be marked inactive when they are no longer in use. When to inactivate:

Account has zero balance
No activity expected in foreseeable future
Member has left organization (zero savings balance)
Loan fully repaid (zero receivable balance)
Reserve fully released (zero allocation balance)

Effects of inactive status:

❌ Excluded from default reports (unless includeInactive=true)
❌ Cannot be used in new journal entries
✅ Still appears in historical reports for date ranges when it was active
✅ Balance preserved (can verify historical balances)
✅ Can be reactivated if needed

API: Include inactive accounts

GET /ledger-accounts?includeInactive=true
Headers:
  x-organization-id: org-123

Creating Custom Ledger Accounts

You can create custom ledger accounts for organization-specific needs. Prerequisites:

ledger:write permission
Custom role definition (non-system role)

API: Create custom ledger account

POST /ledger-accounts
Headers:
  x-organization-id: {organizationId}
Body:
{
  "roleDefinitionId": "role-def-custom-123",
  "name": "SMS Service Charges"
}

Restrictions:

❌ Cannot create accounts with system role definitions
❌ Cannot create duplicate accounts with same name
✅ Can create multiple accounts with same role (different names)

Example use cases:

SMS charges expense category
Donation income category
Specific project expense tracking
Specialized reserve categories

Best Practices

Ledger account management best practices:Daily:

✅ Review key account balances (Cash, Member Savings totals)
✅ Verify no abnormal balances (negative cash, negative savings)
✅ Monitor large balance changes

Monthly:

✅ Reconcile all Cash accounts to bank statements
✅ Verify Member Savings total matches sum of individual balances
✅ Reconcile Loan Receivable to loan portfolio report
✅ Review trial balance (all account balances)
✅ Investigate unusual balances or variances

Quarterly:

✅ Export and archive chart of accounts
✅ Review inactive accounts (reactivate or keep inactive)
✅ Compare account balances to prior quarters

Best Practices:

✅ Use consistent account naming conventions
✅ Don’t create unnecessary custom accounts (use system accounts when possible)
✅ Inactivate zero-balance accounts that won’t be used again
✅ Document reason for custom accounts
✅ Review account list regularly for cleanup
✅ Report discrepancies to accountant immediately
✅ Never edit balances directly (always use journal entries)

Understanding Double-Entry

Learn how debits and credits affect different account types

Ledger Roles

Complete reference of all account roles and types

Viewing Journal Entries

See how transactions affect account balances

Balance Sheet

Classified account report showing financial position

Reconciliation

Verify account balances match external records

​What are Ledger Accounts?

​API Endpoints

​List All Ledger Accounts

​Get Single Ledger Account

​Get Account Activity

​Account Structure

​Account Types

​1. Assets (ASSET)

​2. Liabilities (LIABILITY)

​3. Equity (EQUITY)

​4. Income (INCOME)

​5. Expenses (EXPENSE)

​Account Roles

​Scope Keys

​Account Balance

​Viewing Account Activity

​Account Reconciliation

​Cash Account Reconciliation

​Member Savings Reconciliation

​Loan Receivable Reconciliation

​Cannot Modify Account Balances Directly

​Inactive Accounts

​Creating Custom Ledger Accounts

​Best Practices

​Related Topics

Understanding Double-Entry

Ledger Roles

Viewing Journal Entries

Balance Sheet

Reconciliation

What are Ledger Accounts?

API Endpoints

List All Ledger Accounts

Get Single Ledger Account

Get Account Activity

Account Structure

Account Types

1. Assets (ASSET)

2. Liabilities (LIABILITY)

3. Equity (EQUITY)

4. Income (INCOME)

5. Expenses (EXPENSE)

Account Roles

Scope Keys

Account Balance

Viewing Account Activity

Account Reconciliation

Cash Account Reconciliation

Member Savings Reconciliation

Loan Receivable Reconciliation

Cannot Modify Account Balances Directly

Inactive Accounts

Creating Custom Ledger Accounts

Best Practices

Related Topics