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

# Ledger Accounts

> View and understand the chart of accounts - the complete list of financial categories used by your organization

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

<Note>
  **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.
</Note>

***

## API Endpoints

### List All Ledger Accounts

**Get all ledger accounts for an organization:**

```http theme={null}
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:**

```json theme={null}
{
  "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:**

```http theme={null}
GET /ledger-accounts/:ledgerAccountId
Headers:
  x-organization-id: {organizationId}
```

**Response:**

```json theme={null}
{
  "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:**

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

**Query parameters:**

See [Viewing Journal Entries](/tontines/general-ledger/viewing-journal-entries#account-activity) 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
```

<Note>
  **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.
</Note>

***

### 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:{id}                    |
| **SAVINGS**                      | LIABILITY | Individual member deposit balances     | organizationUser:{id}                |
| **LOAN\_RECEIVABLE**             | ASSET     | Outstanding loan principal             | loan:{id}                            |
| **INTEREST\_RECEIVABLE**         | ASSET     | Unpaid loan interest                   | loan:{id}                            |
| **PENALTY\_RECEIVABLE**          | ASSET     | Unpaid late fees                       | loan:{id}                            |
| **FIXED\_ASSET**                 | ASSET     | Long-term assets (equipment, property) | fixedAsset:{id} or organization:{id} |
| **BORROWER\_SURPLUS\_LIABILITY** | LIABILITY | Overpayments from borrowers            | loan:{id}                            |
| **RETAINED\_EARNINGS**           | EQUITY    | Accumulated profit                     | organization:{id}                    |
| **RESERVE\_ALLOCATION**          | EQUITY    | Designated reserves                    | reserve:{id}                         |
| **OPENING\_EQUITY**              | EQUITY    | Initial capital                        | organization:{id}                    |
| **OTHER\_EQUITY**                | EQUITY    | Miscellaneous equity                   | organization:{id} or custom          |
| **INTEREST\_INCOME**             | INCOME    | Earned interest on loans               | organization:{id}                    |
| **PENALTY\_INCOME**              | INCOME    | Late payment penalties                 | organization:{id}                    |
| **ENTRY\_FEE\_INCOME**           | INCOME    | Membership fees                        | organization:{id}                    |
| **DISBURSEMENT\_FEE\_INCOME**    | INCOME    | Loan processing fees                   | organization:{id}                    |
| **BAD\_DEBT\_RECOVERY\_INCOME**  | INCOME    | Recovered bad debt                     | organization:{id}                    |
| **OTHER\_INCOME**                | INCOME    | Miscellaneous income                   | organization:{id} or custom          |
| **OPERATING\_EXPENSE**           | EXPENSE   | General operating costs                | organization:{id}                    |
| **BANK\_CHARGE\_EXPENSE**        | EXPENSE   | Bank fees                              | organization:{id}                    |
| **BAD\_DEBT\_EXPENSE**           | EXPENSE   | Loan write-offs                        | organization:{id}                    |

[View complete ledger roles reference →](/tontines/general-ledger/ledger-roles)

***

## 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:**

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

```json theme={null}
{
  "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:**

```http theme={null}
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 →](/tontines/general-ledger/viewing-journal-entries#account-activity)

***

## Account Reconciliation

**Reconciliation** verifies that ledger account balances match external records.

### Cash Account Reconciliation

**Compare to bank statements:**

<Steps>
  <Step title="Get ending balance from bank statement">
    Bank statement shows: 5,100,000 RWF
  </Step>

  <Step title="Get Cash ledger account balance">
    Agatabo shows: 4,950,000 RWF
  </Step>

  <Step title="Identify differences">
    Difference: 150,000 RWF

    Possible 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
  </Step>

  <Step title="Record adjustments">
    Create journal entries for bank fees, interest, or errors
  </Step>

  <Step title="Verify reconciliation">
    Adjusted balance should match bank statement
  </Step>
</Steps>

***

### Member Savings Reconciliation

**Compare to member passbooks or statements:**

<Steps>
  <Step title="Get total Member Savings from trial balance">
    Sum of all SAVINGS accounts: 18,000,000 RWF
  </Step>

  <Step title="Get sum of all member passbook balances">
    Manual calculation or report: 17,900,000 RWF
  </Step>

  <Step title="Identify discrepancy">
    Difference: 100,000 RWF

    Investigate:

    * Recent transactions not yet in passbook
    * Passbook balances not updated
    * Data entry errors
    * Missing transactions
  </Step>

  <Step title="Resolve discrepancies">
    Update passbooks or correct ledger entries
  </Step>
</Steps>

***

### Loan Receivable Reconciliation

**Compare to loan portfolio report:**

<Steps>
  <Step title="Get total Loan Receivable from trial balance">
    Sum of all LOAN\_RECEIVABLE accounts: 15,000,000 RWF
  </Step>

  <Step title="Get sum of all outstanding loans">
    Loan portfolio report: 15,050,000 RWF
  </Step>

  <Step title="Investigate variance">
    Difference: 50,000 RWF

    Check:

    * Recent loan disbursements or payments not yet posted
    * Loan write-offs not recorded
    * Data entry errors
  </Step>

  <Step title="Drill down to individual loans">
    Compare each loan account balance to loan detail
  </Step>
</Steps>

***

## Cannot Modify Account Balances Directly

<Warning>
  **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
</Warning>

**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 →](/tontines/general-ledger/manual-journal-entries)

***

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

```http theme={null}
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**

```http theme={null}
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

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

***

## Related Topics

<CardGroup cols={2}>
  <Card title="Understanding Double-Entry" icon="book-open" href="/tontines/general-ledger/understanding-double-entry">
    Learn how debits and credits affect different account types
  </Card>

  <Card title="Ledger Roles" icon="sitemap" href="/tontines/general-ledger/ledger-roles">
    Complete reference of all account roles and types
  </Card>

  <Card title="Viewing Journal Entries" icon="book" href="/tontines/general-ledger/viewing-journal-entries">
    See how transactions affect account balances
  </Card>

  <Card title="Balance Sheet" icon="file-invoice-dollar" href="/tontines/reports/balance-sheet">
    Classified account report showing financial position
  </Card>

  <Card title="Reconciliation" icon="magnifying-glass-chart" href="/tontines/general-ledger/reconciliation">
    Verify account balances match external records
  </Card>
</CardGroup>