Viewing Journal Entries

Overview

Journal entries are the fundamental accounting records in Agatabo. Every financial transaction (member deposits, loan disbursements, expenses, dividends, reserve allocations) creates a journal entry showing exactly how accounts were debited and credited.

Automatic creation: Most journal entries are created automatically when you perform business operations. You record transactions, and Agatabo handles the accounting.

Accessing Journal Entries

Navigate to General Ledger

Click General Ledger in sidebar

Select Journal Entries

View searchable list of all journal entries

Apply filters

Filter by date, kind, status, or search for specific entries

Click entry to view details

See full transaction details, all debit/credit lines, and metadata

Journal Entry Information

Each entry displays:

Field	Description
ID	Unique identifier for the journal entry
Transaction Date	When the transaction occurred (not when entry was created)
Kind	Type of transaction (SAVINGS_DEPOSIT, LOAN_DISBURSEMENT, DIVIDEND_DISTRIBUTION, etc.)
Title	Short label describing the transaction
Description	Detailed explanation of what happened
Status	POSTED (permanent, affects balances) or DRAFT (temporary, can be edited)
Lines	Debit and credit details (must balance)
Created By	User who recorded the transaction
Created At	Timestamp when entry was created
Idempotency Key	Unique key preventing duplicate entries
References	Links to source entities (loan ID, member ID, reserve ID, dividend pool ID, etc.)
Parent Entry	Parent journal entry (for multi-step transactions)
Reversed Entry	Link to reversal entry (if reversed)
Documents	Attached supporting documents

Journal Entry Kinds

Agatabo uses these transaction types:

Savings & Deposits

SAVINGS_DEPOSIT: Member deposits funds to savings account
ENTRY_FEE: Membership fee payment

Loans

LOAN_DISBURSEMENT: Loan principal disbursed to member
LOAN_PAYMENT: Member makes loan payment (principal + interest)
LOAN_PENALTY: Late payment penalty applied
LOAN_DEFAULT: Loan written off as bad debt
INTEREST_PAID_IN_ADVANCE: Upfront interest payment

Expenses

EXPENSE_PAYMENT: Operating expense payment
BANK_CHARGE: Bank fees and charges

Reserves

RESERVE_TOP_UP: Allocate funds from retained earnings to reserve
RESERVE_RELEASE: Release funds from reserve back to retained earnings
RESERVE_EXPENSE: Expense paid directly from reserve funds (creates parent RESERVE_RELEASE + child RESERVE_EXPENSE)

Dividends

DIVIDEND_DISTRIBUTION: Distribute retained earnings to member savings accounts

Fixed Assets

ASSET_CASH_PURCHASE: Purchase asset with cash
ASSET_COLLATERAL: Acquire asset as loan collateral
ASSET_GIFT: Receive donated asset
ASSET_DISPOSAL: Sell or dispose of asset
CASH_OPENING: Record opening cash balance

Administrative

REVERSAL: Reverse a previous journal entry
PERIOD_CLOSE: Close accounting period and transfer net income to retained earnings

View complete ledger overview →

Understanding Journal Lines

Each journal entry consists of 2 or more lines that must balance (total debits = total credits).

Example 1: Member Deposit

Journal Entry ID: je-abc123
Transaction Date: June 10, 2026
Kind: SAVINGS_DEPOSIT
Title: Savings Deposit
Description: Alice monthly savings deposit
Status: POSTED
Created By: treasurer@org.com

Lines:
  1. DEBIT:  Cash (organization:org123)              100,000 RWF
  2. CREDIT: Savings (organizationUser:alice)        100,000 RWF

Total Debits: 100,000 RWF
Total Credits: 100,000 RWF
✓ Balanced

Example 2: Dividend Distribution

Journal Entry ID: je-def456
Transaction Date: June 12, 2026
Kind: DIVIDEND_DISTRIBUTION
Title: Dividend Distribution
Description: Q2 2026 Dividend
Status: POSTED
Created By: accountant@org.com
Dividend Pool ID: pool-xyz789

Lines:
  1. DEBIT:  Retained Earnings (organization:org123)    5,000,000 RWF
  2. CREDIT: Savings (organizationUser:alice)             100,000 RWF
  3. CREDIT: Savings (organizationUser:bob)               100,000 RWF
  4. CREDIT: Savings (organizationUser:carol)             100,000 RWF
  ... (50 members total)

Total Debits: 5,000,000 RWF
Total Credits: 5,000,000 RWF
✓ Balanced

Example 3: Reserve Allocation

Journal Entry ID: je-ghi789
Transaction Date: June 12, 2026
Kind: RESERVE_TOP_UP
Title: Reserve Top Up
Description: Emergency fund monthly allocation
Status: POSTED
Created By: treasurer@org.com
Reserve ID: reserve-emergency-123

Lines:
  1. DEBIT:  Reserve Allocation (reserve:emergency)   1,000,000 RWF
  2. CREDIT: Retained Earnings (organization:org123)  1,000,000 RWF

Total Debits: 1,000,000 RWF
Total Credits: 1,000,000 RWF
✓ Balanced

Filtering Journal Entries

Filter by Date Range

Parameters:

from: Start date (ISO format: YYYY-MM-DD)
to: End date (ISO format: YYYY-MM-DD)

Examples:

This month: from=2026-06-01&to=2026-06-30
This quarter: from=2026-04-01&to=2026-06-30
This year: from=2026-01-01&to=2026-12-31
Last 30 days: from=2026-05-13&to=2026-06-12

Filter by Kind

Parameter: kind (journal_entry_kind enum) Common filters:

Show only deposits: kind=SAVINGS_DEPOSIT
Show only loans: kind=LOAN_DISBURSEMENT
Show only expenses: kind=EXPENSE_PAYMENT
Show only dividends: kind=DIVIDEND_DISTRIBUTION
Show only reserves: kind=RESERVE_TOP_UP

Get all available kinds:

GET /ledger-accounts/journal-entry-kinds

Filter by Status

Parameter: status (DRAFT or POSTED) DRAFT:

Entry created but not yet finalized
Does not affect account balances
Can be edited or deleted
Not included in financial reports
Used for preparing entries before posting

POSTED:

Entry finalized and locked
Affects account balances immediately
Cannot be edited or deleted (permanent)
Included in all financial reports
Creates audit trail

Examples:

Show only posted: status=POSTED
Show only drafts: status=DRAFT

Filter by Entity Reference

Member filter:

organizationUserId=alice-123

Shows all entries affecting this member (deposits, withdrawals, dividends, loans) Loan filter:

loanId=loan-456

Shows all entries for this loan (disbursement, payments, penalties) Reserve filter:

reserveAllocationId=reserve-789

Shows all entries for this reserve (top-ups, releases, expenses) Dividend pool filter:

dividendPoolId=pool-012

Shows all entries for this dividend pool (distributions) Bank account filter:

bankAccountId=bank-345

Shows all entries affecting this bank account

Filter by Creator

Parameter: createdBy=organizationUserId Shows all entries created by a specific user (useful for audit). Example:

createdBy=treasurer-user-123

Filter by Parent/Reversal

Parent entry:

parentJournalEntryId=je-parent-123

Shows child entries of a specific parent (e.g., reserve-funded expenses) Reversed entry:

reversedEntryId=je-reversed-456

Shows the reversal entry for a specific entry

Search by Text

Parameter: searchTerm=text Searches in:

Entry description
Entry title
Account names
Member names
Related entity details

Examples:

searchTerm=alice (finds all entries mentioning Alice)
searchTerm=emergency (finds emergency fund transactions)
searchTerm=rent (finds rent expense entries)

Pagination

Parameters:

page: Page number (default: 1)
limit: Items per page (default: 20, max varies by endpoint)

Example:

page=1&limit=50

Response includes pagination metadata:

{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 50,
    "totalCount": 532,
    "totalPages": 11,
    "hasNextPage": true,
    "hasPreviousPage": false
  }
}

Viewing Entry Details

Click on any journal entry to see: Full transaction information:

All debit and credit lines with account details
Scope keys showing which specific entity each line affects
Running balance (before/after) for each affected account
Transaction amount and balance verification

Metadata:

Created by (user who created the entry)
Created at timestamp
Transaction date (when it occurred)
Idempotency key (prevents duplicates)

References:

Source entity links (loan ID, member ID, reserve ID, dividend pool ID)
Parent journal entry (for multi-step transactions)
Reversed entry (if entry was reversed)

Supporting documents:

Attached receipts, invoices, or documentation
Document type and description

Audit trail:

Who created the entry
When it was created
What triggered its creation
Related transactions

Common Use Cases

Finding a Specific Transaction

By transaction date and amount:

Filter by date range

Set from/to dates around transaction date

Sort by transaction date

Most recent first

Scan for amount

Look for matching transaction amount

Click to view details

Verify it’s the correct transaction

Reviewing All Transactions for a Member

View member’s financial history:

Filter by member

Set organizationUserId parameter

Sort by transaction date

Chronological order

Review all entries

See deposits, withdrawals, loans, dividends

Verify balances

Check that savings balance matches entries

Investigating an Accounting Error

Find and diagnose discrepancies:

Run trial balance

Identify which account is unbalanced

Get account details

View account’s current balance

View account activity

List all entries affecting the account

Find problematic entry

Look for unbalanced or incorrect entries

Contact accountant

Report issue for correction (may require reversal)

Auditing Dividend Distributions

Verify dividend distribution accuracy:

Filter by dividend pool

Set dividendPoolId parameter

View distribution entry

See DIVIDEND_DISTRIBUTION journal entry

Check all credit lines

Verify each member received correct amount

Verify total

Confirm total credits equal total debit to retained earnings

Tracking Reserve Activity

Monitor reserve allocations and releases:

Filter by reserve

Set reserveAllocationId parameter

Filter by kind

Show RESERVE_TOP_UP, RESERVE_RELEASE, and RESERVE_EXPENSE

Review chronologically

See all top-ups and releases over time

Verify current balance

Ensure balance matches expected based on entries

Reversing Journal Entries

Reversals are permanent: Reversing a journal entry creates a new REVERSAL entry that exactly offsets the original. Both entries remain in the ledger permanently for audit trail. Most transactions should not be reversed manually - use proper business operations to correct errors.

When to Reverse

Appropriate uses:

Correcting accounting errors (wrong account, wrong amount)
Voiding duplicate entries
Correcting period mismatches (transaction in wrong accounting period)

Inappropriate uses:

Normal business corrections (use proper operations instead)
Member requested refunds (use withdrawal transaction)
Loan payment errors (use loan adjustment features)

How Reversals Work

Original entry:

DEBIT: Cash +100,000
CREDIT: Savings (Alice) +100,000

Reversal entry (automatically created):

Kind: REVERSAL
Description: Reversal of je-abc123: [reason]

DEBIT: Savings (Alice) -100,000
CREDIT: Cash -100,000

Net effect:

Original entry remains in ledger (for audit)
Reversal entry offsets it (nullifies impact)
Both entries permanently recorded
Account balances return to pre-transaction state

API Endpoint

POST /ledger-accounts/journal/:journalEntryId/reverse

Headers:
  x-organization-id: <org_id>
  x-idempotency-key: <unique_key>

Body:
{
  "reversalDate": "2026-06-15",
  "description": "Reason for reversal",
  "skipNegativeBalanceCheck": false
}

Permission required: ledger:write - Only accountants and administrators can reverse entries.

Reconciliation

Journal entries should match external records: Cash reconciliation:

Compare journal entries (kind=CASH_*) with bank statements
Ensure all deposits, withdrawals, and fees are recorded
Investigate discrepancies immediately

Member savings reconciliation:

Compare entries affecting SAVINGS accounts with member expectations
Verify deposits and withdrawals match member records
Check dividend distributions are correct

Loan reconciliation:

Ensure loan disbursements match loan schedules
Verify payments applied correctly (principal vs. interest)
Check penalties and fees are accurate

Exporting Journal Entries

Use cases:

External audit (provide transaction log to auditors)
Analysis (download to Excel for pivot tables)
Compliance (transaction log for regulators)
Backup (archive accounting records)

How to export:

Apply desired filters

Date range, kind, status, etc.

Click Export

Choose export format

Select format

Excel (.xlsx), CSV (.csv), or PDF

Download file

Save exported journal entries

Export includes:

All visible journal entries matching filters
All debit and credit lines for each entry
Account details, amounts, dates, descriptions
Formatted for readability in chosen format

Best Practices

Working with journal entries:Regular Review:

Review journal entries monthly for accuracy
Spot-check automatic entries to verify correctness
Monitor for unusual or unexpected entries
Report suspicious entries to management immediately

Filtering:

Use specific filters to narrow results (date + kind + entity)
Start broad, then narrow down when searching
Save common filter combinations for frequent use

Manual Entries:

NEVER create manual journal entries without accountant approval
Understand double-entry basics before attempting manual entries
Always document reason for manual entries clearly
Verify entry balances before posting

Audit Trail:

Keep exported journal entry reports for 7+ years
Cross-reference with source documents during audits
Maintain documentation for all manual entries
Track all reversals with clear explanations

Error Prevention:

Trust automatic entries (they’re tested and correct)
Don’t reverse entries unless absolutely necessary
Use proper business operations to correct most errors
Consult accountant before manual interventions

Technical Details

API Endpoints

Search journal entries:

GET /ledger-accounts/journal-search

Query parameters:
  searchTerm?: string
  from?: YYYY-MM-DD
  to?: YYYY-MM-DD
  kind?: journal_entry_kind
  status?: DRAFT | POSTED
  page?: number (default 1)
  limit?: number (default 20)
  organizationUserId?: string
  loanId?: string
  bankAccountId?: string
  dividendPoolId?: string
  reserveAllocationId?: string
  createdBy?: string
  parentJournalEntryId?: string
  reversedEntryId?: string
  roleDefinitionId?: string
  installmentId?: string

Response:
{
  "message": "Journal entries retrieved successfully",
  "data": [
    {
      "id": "je-123",
      "kind": "SAVINGS_DEPOSIT",
      "transactionDate": "2026-06-10",
      "status": "POSTED",
      "title": "Savings Deposit",
      "description": "Alice monthly deposit",
      "lines": [
        {
          "id": "line-1",
          "side": "DEBIT",
          "amount": "100000",
          "ledgerAccount": {
            "id": "acc-cash",
            "role": "CASH",
            "type": "ASSET",
            "name": "Cash"
          }
        },
        {
          "id": "line-2",
          "side": "CREDIT",
          "amount": "100000",
          "ledgerAccount": {
            "id": "acc-alice-savings",
            "role": "SAVINGS",
            "type": "LIABILITY",
            "name": "Alice Savings",
            "refId": "alice-123"
          }
        }
      ]
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "totalCount": 532,
    "totalPages": 27,
    "hasNextPage": true,
    "hasPreviousPage": false
  }
}

Get specific journal entry:

GET /ledger-accounts/journal/:journalEntryId

Response:
{
  "message": "Journal entry retrieved successfully",
  "data": {
    "id": "je-123",
    "kind": "SAVINGS_DEPOSIT",
    "transactionDate": "2026-06-10",
    "status": "POSTED",
    "title": "Savings Deposit",
    "description": "Alice monthly deposit",
    "idempotencyKey": "unique-key-123",
    "createdBy": "treasurer-123",
    "createdAt": "2026-06-10T14:30:00Z",
    "documents": [],
    "lines": [...]
  }
}

Get journal entry kinds:

GET /ledger-accounts/journal-entry-kinds

Response:
{
  "message": "Journal entry kinds retrieved successfully",
  "data": [
    {
      "value": "SAVINGS_DEPOSIT",
      "label": "Savings Deposit",
      "isFilterable": true
    },
    {
      "value": "LOAN_DISBURSEMENT",
      "label": "Loan Disbursement",
      "isFilterable": true
    },
    ...
  ]
}

Get account activity:

GET /ledger-accounts/:ledgerAccountId/activity

(Same query parameters and response structure as journal-search)

Get role transactions:

GET /ledger-accounts/role-transactions/:roleDefinitionId

(Same query parameters and response structure as journal-search)

Permissions Required

Action	Permission	Scope
View journal entries	`ledger:read`	ANY or specific entity
Search all entries	`ledger:read`	ANY
View specific entry	`ledger:read`	Entry’s organization
View account activity	`ledger:read`	Account’s organization
Reverse entry	`ledger:write`	ANY

Typical roles:

Administrators and Accountants: ledger:read and ledger:write (ANY scope) - can view and modify all entries
Treasurers: ledger:read (ANY scope) - can view all entries but not modify
Regular members: ledger:read (own organizationUserId scope) - can only view their own transactions

Need Help?

Double-Entry Accounting

Learn accounting basics

Ledger Roles

Understand account roles

General Ledger Overview

Complete accounting system overview

Manual Journal Entries

Create manual accounting entries

Reconciliation

Reconcile accounts and detect errors

​Overview

​Accessing Journal Entries

​Journal Entry Information

​Journal Entry Kinds

​Savings & Deposits

​Loans

​Expenses

​Reserves

​Dividends

​Fixed Assets

​Administrative

​Understanding Journal Lines

​Example 1: Member Deposit

​Example 2: Dividend Distribution

​Example 3: Reserve Allocation

​Filtering Journal Entries

​Filter by Date Range

​Filter by Kind

​Filter by Status

​Filter by Entity Reference

​Filter by Creator

​Filter by Parent/Reversal

​Search by Text

​Pagination

​Viewing Entry Details

​Common Use Cases

​Finding a Specific Transaction

​Reviewing All Transactions for a Member

​Investigating an Accounting Error

​Auditing Dividend Distributions

​Tracking Reserve Activity

​Reversing Journal Entries

​When to Reverse

​How Reversals Work

​API Endpoint

​Reconciliation

​Exporting Journal Entries

​Best Practices

​Technical Details

​API Endpoints

​Permissions Required

​Need Help?

Double-Entry Accounting

Ledger Roles

General Ledger Overview

Manual Journal Entries

Reconciliation

Overview

Accessing Journal Entries

Journal Entry Information

Journal Entry Kinds

Savings & Deposits

Loans

Expenses

Reserves

Dividends

Fixed Assets

Administrative

Understanding Journal Lines

Example 1: Member Deposit

Example 2: Dividend Distribution

Example 3: Reserve Allocation

Filtering Journal Entries

Filter by Date Range

Filter by Kind

Filter by Status

Filter by Entity Reference

Filter by Creator

Filter by Parent/Reversal

Search by Text

Pagination

Viewing Entry Details

Common Use Cases

Finding a Specific Transaction

Reviewing All Transactions for a Member

Investigating an Accounting Error

Auditing Dividend Distributions

Tracking Reserve Activity

Reversing Journal Entries

When to Reverse

How Reversals Work

API Endpoint

Reconciliation

Exporting Journal Entries

Best Practices

Technical Details

API Endpoints

Permissions Required

Need Help?