Manual Journal Entries

What are Manual Journal Entries?

Manual journal entries are accounting transactions created directly by users with ledger:write permission, rather than automatically generated through standard operations (deposits, loans, expenses, dividends). They’re used for adjustments, corrections, accruals, and special transactions.

Use sparingly: Most transactions should be recorded through normal Agatabo operations (deposits, loans, expenses, dividends). Manual entries are for exceptional situations requiring direct accounting intervention.

When to Use Manual Entries

Valid use cases: Accounting Adjustments:

Depreciation: Monthly depreciation of fixed assets
Accruals: Recording revenue earned or expenses incurred but not yet paid
Deferrals: Prepaid expenses or unearned revenue
Write-offs: Bad debt write-offs, asset disposals
Reclassifications: Correcting misclassified transactions

Corrections:

Error corrections: Fixing incorrectly posted transactions
Balance adjustments: Reconciling discrepancies

Opening Balances:

Initial setup: Recording starting balances when migrating to Agatabo
Account initialization: Setting up accounts with historical balances

Special Transactions:

One-time events: Transactions without dedicated Agatabo features
Complex allocations: Multi-account distributions

Do NOT use manual entries for:

❌ Member deposits (use Deposits feature)
❌ Loan disbursements or payments (use Loans feature)
❌ Operating expenses (use Expenses feature)
❌ Dividend distributions (use Dividends feature)
❌ Reserve allocations (use Reserves feature)

API Endpoint

Create manual journal entry:

POST /ledger-accounts/manual-journal
Headers:
  x-organization-id: {organizationId}
  x-idempotency-key: {unique-key}
  Content-Type: application/json

Request body:

{
  description?: string;           // Max 2048 chars, explains purpose
  transactionDate?: string;       // ISO date (YYYY-MM-DD), defaults to today in org timezone
  documents?: DocumentItem[];     // Supporting documents
  lines: ManualJournalLineDto[];  // Journal entry lines (debits and credits)
  skipNegativeBalanceCheck?: boolean; // Skip negative balance validation
}

ManualJournalLineDto structure:

{
  ledgerAccountId: string;  // UUID of ledger account
  side: 'DEBIT' | 'CREDIT'; // Line side
  amount: number;           // Amount (max 2 decimal places, minimum 0.01)
}

Response:

{
  "message": "Manual journal entry posted successfully",
  "data": {
    "id": "je-abc123",
    "kind": "MANUAL_JOURNAL",
    "transactionDate": "2026-06-12",
    "status": "POSTED",
    "lines": [
      {
        "id": "line-1",
        "side": "DEBIT",
        "amount": 50000,
        "ledgerAccount": {
          "id": "acc-123",
          "name": "Operating Expense",
          "role": "OPERATING_EXPENSE",
          "type": "EXPENSE"
        }
      },
      {
        "id": "line-2",
        "side": "CREDIT",
        "amount": 50000,
        "ledgerAccount": {
          "id": "acc-456",
          "name": "Cash",
          "role": "CASH",
          "type": "ASSET"
        }
      }
    ]
  }
}

Prerequisites

Requirements:Permissions:

ledger:write permission (typically Accountant or Administrator)

Knowledge:

Understanding of double-entry accounting
Knowledge of debit and credit rules
Familiarity with organization’s chart of accounts

Documentation:

Approval for the adjustment (if required by policy)
Supporting documents (receipts, memos, reconciliation reports)
Clear explanation of purpose

Technical:

Transaction date must be in an open accounting period
Idempotency key for each request (prevents duplicates)

Validation Rules

Required fields:

x-idempotency-key header: Prevents duplicate entries
lines: At least one journal line (typically 2+ for balanced entry)
ledgerAccountId: Valid UUID for each line
side: Must be “DEBIT” or “CREDIT”
amount: Must be ≥ 0.01 with max 2 decimal places

Balance requirement:

Total debits must equal total credits: Enforced automatically
Unbalanced entries are rejected

Amount constraints:

Minimum amount: 0.01 (1 cent in fractional currency)
Decimal places: Maximum 2
No negative amounts: Use opposite side instead (e.g., use CREDIT to decrease an asset, not negative DEBIT)

Account constraints:

Accounts must exist: All ledgerAccountIds must be valid
Accounts must belong to organization: Cannot use accounts from other organizations
Accounts must be active: Inactive accounts cannot be used
Accounts must be accessible: User must have permission to post to these accounts

Date constraints:

Transaction date: Must be in ISO format (YYYY-MM-DD)
Open period only: Cannot post to closed accounting periods
No future dates: Date cannot be after today (unless configured otherwise)

Idempotency:

x-idempotency-key header is mandatory: Request fails without it
Same key returns existing entry: Safe to retry failed requests
Unique per organization: Same key can exist in different organizations

Creating Manual Journal Entry

Using the API

Example 1: Record depreciation expense

POST /ledger-accounts/manual-journal
Headers:
  x-organization-id: org-123
  x-idempotency-key: depreciation-jun-2026
  Content-Type: application/json

Body:
{
  "description": "June 2026 depreciation - computers and furniture",
  "transactionDate": "2026-06-30",
  "lines": [
    {
      "ledgerAccountId": "acc-depreciation-expense",
      "side": "DEBIT",
      "amount": 50000
    },
    {
      "ledgerAccountId": "acc-accumulated-depreciation",
      "side": "CREDIT",
      "amount": 50000
    }
  ]
}

Example 2: Correct posted error Member deposit was incorrectly credited to John instead of Jane.

POST /ledger-accounts/manual-journal
Headers:
  x-organization-id: org-123
  x-idempotency-key: correction-john-to-jane-20260612
  Content-Type: application/json

Body:
{
  "description": "Correction - June 12 deposit was for Jane (orgUser-456), not John (orgUser-123). Original entry: je-xyz789",
  "transactionDate": "2026-06-12",
  "documents": [
    {
      "fileId": "doc-123",
      "fileName": "correction-memo.pdf",
      "documentType": "MEMO"
    }
  ],
  "lines": [
    {
      "ledgerAccountId": "acc-john-savings",
      "side": "DEBIT",
      "amount": 100000
    },
    {
      "ledgerAccountId": "acc-jane-savings",
      "side": "CREDIT",
      "amount": 100000
    }
  ]
}

Example 3: Record accrued interest

POST /ledger-accounts/manual-journal
Headers:
  x-organization-id: org-123
  x-idempotency-key: accrued-interest-jun-2026
  Content-Type: application/json

Body:
{
  "description": "Accrued interest on bank savings account - June 2026",
  "transactionDate": "2026-06-30",
  "lines": [
    {
      "ledgerAccountId": "acc-interest-receivable",
      "side": "DEBIT",
      "amount": 25000
    },
    {
      "ledgerAccountId": "acc-interest-income",
      "side": "CREDIT",
      "amount": 25000
    }
  ]
}

Example 4: Opening balances

POST /ledger-accounts/manual-journal
Headers:
  x-organization-id: org-123
  x-idempotency-key: opening-balances-20260101
  Content-Type: application/json

Body:
{
  "description": "Opening balances as of January 1, 2026",
  "transactionDate": "2026-01-01",
  "lines": [
    {
      "ledgerAccountId": "acc-cash",
      "side": "DEBIT",
      "amount": 5000000
    },
    {
      "ledgerAccountId": "acc-loans-receivable",
      "side": "DEBIT",
      "amount": 10000000
    },
    {
      "ledgerAccountId": "acc-member-savings",
      "side": "CREDIT",
      "amount": 12000000
    },
    {
      "ledgerAccountId": "acc-retained-earnings",
      "side": "CREDIT",
      "amount": 3000000
    }
  ]
}

Journal Entry Structure

Created journal entry:

{
  id: string;                          // Generated journal entry ID
  kind: 'MANUAL_JOURNAL';              // Always MANUAL_JOURNAL
  status: 'POSTED';                    // Always POSTED (no draft state)
  transactionDate: Date;               // Effective date of transaction
  title: 'Manual Entry';               // Always "Manual Entry" (not customizable)
  description: string | null;          // User-provided description
  idempotencyKey: string;              // Idempotency key from header
  createdBy: string;                   // organizationUserId of creator
  createdAt: Date;                     // Timestamp of creation
  organizationId: string;              // Organization ID
  lines: JournalLine[];                // Debit and credit lines
  documents: DocumentItem[] | null;    // Supporting documents
}

Note: Manual journal entries are always POSTED immediately. There is no draft state. Once created, they are permanent and cannot be edited or deleted. To correct, create a reversal entry.

Common Manual Entry Examples

1. Monthly Depreciation

Purpose: Record monthly depreciation expense for fixed assets

Description: June 2026 depreciation - computers and furniture

DEBIT:  Depreciation Expense        50,000 RWF (expense increases)
CREDIT: Accumulated Depreciation    50,000 RWF (contra-asset increases)

Effect: Expense reduces net income, accumulated depreciation reduces fixed asset value.

2. Correct Posted Error

Purpose: Member deposit was recorded to wrong member Original (incorrect) entry:

DEBIT:  Cash                100,000 RWF
CREDIT: John's Savings      100,000 RWF

Correction entry:

Description: Correction - deposit was actually for Jane, not John. Ref: je-original-123

DEBIT:  John's Savings      100,000 RWF (reduces John's balance)
CREDIT: Jane's Savings      100,000 RWF (increases Jane's balance)

Effect: Cash unchanged, John’s balance decreases, Jane’s balance increases.

3. Accrued Interest Income

Purpose: Record interest earned but not yet received

Description: Accrued interest on bank savings account - June 2026

DEBIT:  Interest Receivable   25,000 RWF (asset increases)
CREDIT: Interest Income        25,000 RWF (income increases)

Effect: Recognizes income earned, creates receivable until cash is received.

4. Opening Balances

Purpose: Record initial balances when starting Agatabo

Description: Opening balances as of Jan 1, 2026

DEBIT:  Cash                  5,000,000 RWF
DEBIT:  Loans Receivable     10,000,000 RWF
CREDIT: Member Savings       12,000,000 RWF
CREDIT: Retained Earnings     3,000,000 RWF

Total: 15,000,000 = 15,000,000 ✓ Balanced

Effect: Initializes accounting system with starting balances.

5. Write-off Bad Debt

Purpose: Write off uncollectible loan

Description: Write off loan-123 as uncollectible - member absconded

DEBIT:  Bad Debt Expense       500,000 RWF (expense increases)
CREDIT: Loan Receivable        500,000 RWF (asset decreases)

Effect: Removes uncollectible loan from assets, records expense.

6. Prepaid Expense

Purpose: Record payment for future service (e.g., insurance for 12 months)

Description: Paid 12-month insurance premium

DEBIT:  Prepaid Expenses      600,000 RWF (asset increases)
CREDIT: Cash                  600,000 RWF (asset decreases)

Effect: Exchanges cash for prepaid asset (amortize monthly over 12 months).

7. Reclassify Expense

Purpose: Move expense from one category to another

Description: Reclassify bank charges incorrectly recorded as operating expense

DEBIT:  Bank Charge Expense    30,000 RWF (correct expense category)
CREDIT: Operating Expense      30,000 RWF (incorrect expense category)

Effect: No change to total expenses, improves expense categorization.

Best Practices

Manual journal entry guidelines:Before Creating:

✅ Verify transaction cannot be recorded through standard features
✅ Get approval from supervisor or accountant (if required by policy)
✅ Prepare supporting documentation
✅ Draft entry on paper first, verify balance
✅ Confirm transaction date is in open accounting period
✅ Generate unique idempotency key

Creating the Entry:

✅ Write clear, detailed description (as if explaining to auditor)
✅ Reference original transaction if correcting an error
✅ Attach supporting documents
✅ Double-check account selections
✅ Verify amounts and sides (DEBIT vs CREDIT)
✅ Confirm entry balances before posting

After Posting:

✅ Review posted entry immediately
✅ Save idempotency key for future reference
✅ Document reason in accounting records
✅ Notify relevant stakeholders
✅ Keep copies of all supporting documents
✅ Report all manual entries to management monthly

Documentation:

✅ Description minimum length: 10 characters (recommended: 50-200 characters)
✅ Include “why” not just “what” (e.g., “Correction - deposited to wrong member due to name similarity” not just “Correction”)
✅ Reference original transaction IDs when correcting errors
✅ Use consistent date format (ISO: YYYY-MM-DD)
✅ Attach memos, reconciliation reports, or approval documents

Restrictions and Limitations

Cannot create manual entries for: Closed periods:

❌ Transaction date in closed accounting period
✅ Create in current open period with description referencing prior period

Invalid accounts:

❌ Accounts that don’t exist
❌ Accounts from other organizations
❌ Inactive accounts
✅ Only use active accounts within your organization

System-managed accounts:

⚠️ Some accounts may be restricted (system will reject if not allowed)
⚠️ Verify you have permission to post to target accounts

Unbalanced entries:

❌ Total debits ≠ total credits
✅ Always verify balance before posting

Negative amounts:

❌ Negative amounts not allowed
✅ Use opposite side instead (CREDIT to decrease asset, not negative DEBIT)

Cannot edit or delete:

❌ Once posted, manual entries are permanent
✅ To correct, create reversal entry or new correcting entry

Correcting Manual Entries

Manual journal entries are permanent once posted. To correct:

Method 1: Create Reversal Entry

Create an entry that reverses the original: Original (incorrect):

DEBIT:  Operating Expense  100,000 RWF
CREDIT: Cash               100,000 RWF

Reversal:

Description: Reversal of je-original-123 - incorrect expense category

DEBIT:  Cash               100,000 RWF
CREDIT: Operating Expense  100,000 RWF

Then create correct entry:

Description: Correct entry - should be Bank Charge Expense

DEBIT:  Bank Charge Expense  100,000 RWF
CREDIT: Cash                 100,000 RWF

Method 2: Create Correcting Entry

If only part of entry is wrong, create adjustment: Original (incorrect):

DEBIT:  John's Savings  100,000 RWF
CREDIT: Cash            100,000 RWF

Correction (direct):

Description: Correction - should be Jane's Savings, not John's

DEBIT:  John's Savings   100,000 RWF (decrease)
CREDIT: Jane's Savings   100,000 RWF (increase)

Approval Workflow (Recommended)

While Agatabo doesn’t enforce approval workflows, organizations should establish internal controls:

Entry Amount	Required Approval	Documentation
Under 50,000 RWF	Accountant only	Description + reason
50,000 - 200,000 RWF	Accountant + Treasurer	Description + supporting docs
200,000 - 1,000,000 RWF	Accountant + Treasurer + Finance Committee	Description + docs + approval memo
Over 1,000,000 RWF	Accountant + Management Board	Full documentation + board minutes

Implementation:

Generate idempotency key after approval
Include approval reference in description
Attach approval memo as document

Audit Considerations

Manual entries receive extra scrutiny from auditors: Auditor expectations:

✅ Clear business justification for each entry
✅ Supporting documentation (memos, reconciliations, approvals)
✅ Reasonable frequency (excessive manual entries indicate weak controls)
✅ Proper authorization and approval trail
✅ Accurate and complete descriptions
✅ Balanced entries (no exceptions)

Red flags for auditors:

🚩 Excessive manual entries (suggests weak internal controls)
🚩 Round number entries without documentation
🚩 Manual entries near period-end
🚩 Vague descriptions (“Adjustment”, “Correction” with no detail)
🚩 Manual entries that reverse prior period transactions
🚩 Large manual entries without approval documentation

Best practices for audit-ready manual entries:

✅ Document reason for manual entry (why not standard feature?)
✅ Reference supporting documents (reconciliation reports, memos, invoices)
✅ Maintain approval trail (emails, forms, board minutes)
✅ Export monthly manual entry report for review
✅ Keep copies of all supporting documents for audit

Common Mistakes and Prevention

1. Unbalanced Entry

Mistake: Total debits ≠ total credits Example (wrong):

DEBIT:  Cash             100,000 RWF
CREDIT: Member Savings    50,000 RWF
❌ 100,000 ≠ 50,000 (unbalanced)

Prevention:

Always verify total debits = total credits before posting
System automatically rejects unbalanced entries
Draft entry on paper first with running totals

2. Wrong Account Selection

Mistake: Selecting CASH when meant to select BANK_ACCOUNT Prevention:

Review account selections carefully
Use search to find correct account
Verify account role and type before posting
Double-check member-specific accounts (savings, loans)

3. Wrong Side (Debit vs Credit)

Mistake: Recording DEBIT when should be CREDIT Example (wrong):

To decrease Cash (asset):
❌ DEBIT: Cash -50,000  (not allowed, negative amounts)
✅ CREDIT: Cash 50,000  (correct, credit decreases asset)

Prevention:

Review double-entry rules: Understanding Double-Entry
Remember DEALER mnemonic (Debits: Expenses, Assets, Losses increase; Credits: Equity, Liabilities, Revenue increase)
Think through journal entry logic before posting

4. Unclear Description

Mistake: “Adjustment” or “Correction” with no detail Example (wrong):

❌ Description: "Adjustment"

Example (correct):

✅ Description: "Correction - June 12 deposit for Jane (orgUser-456) was incorrectly credited to John (orgUser-123). Correcting by debiting John and crediting Jane. Original entry: je-xyz789. Approved by Treasurer on 2026-06-13."

Prevention:

Write description as if explaining to auditor
Include what, why, who, when, and reference to original transaction
Minimum 50-200 characters for meaningful explanation

5. Posting to Closed Period

Mistake: Trying to post entry with transaction date in closed period Error message:

"Cannot post transactions dated on or before the last closed period end (2026-05-31).
Use a date after this, or post an adjustment/reversal in the current open period."

Prevention:

Check accounting period status before creating entry
Use current period transaction date for prior period corrections
Reference prior period in description

6. Missing Idempotency Key

Mistake: Not including x-idempotency-key header Error message:

"x-idempotency-key header is required"

Prevention:

Always include x-idempotency-key header
Generate unique key for each entry (e.g., depreciation-jun-2026, correction-)
Save idempotency key for future reference

Idempotency

Manual journal entries require an idempotency key to prevent duplicate entries. How it works:

Supply x-idempotency-key header with unique value
If same key used twice within same organization, second request returns existing entry
Safe to retry failed requests without creating duplicates
Different organizations can use same key (scoped to organization)

Idempotency key format (recommended):

{entry-type}-{identifier}-{date}

Examples:
depreciation-jun-2026
correction-john-to-jane-20260612
opening-balances-20260101
accrual-interest-jun-2026
writeoff-loan-abc123

Example usage:

POST /ledger-accounts/manual-journal
Headers:
  x-organization-id: org-123
  x-idempotency-key: depreciation-jun-2026

# If network fails and request is retried with same key:
# → Returns existing entry created by first request
# → No duplicate entry created

Understanding Double-Entry

Learn debits, credits, and accounting principles

Ledger Accounts

View available accounts and chart of accounts

Ledger Roles

Understand account roles and types

Viewing Journal Entries

Review posted entries and audit trail

Accounting Periods

Understand period closure and constraints

Reversing Entries

Learn how to reverse posted entries

​What are Manual Journal Entries?

​When to Use Manual Entries

​API Endpoint

​Prerequisites

​Validation Rules

​Creating Manual Journal Entry

​Using the API

​Journal Entry Structure

​Common Manual Entry Examples

​1. Monthly Depreciation

​2. Correct Posted Error

​3. Accrued Interest Income

​4. Opening Balances

​5. Write-off Bad Debt

​6. Prepaid Expense

​7. Reclassify Expense

​Best Practices

​Restrictions and Limitations

​Correcting Manual Entries

​Method 1: Create Reversal Entry

​Method 2: Create Correcting Entry

​Approval Workflow (Recommended)

​Audit Considerations

​Common Mistakes and Prevention

​1. Unbalanced Entry

​2. Wrong Account Selection

​3. Wrong Side (Debit vs Credit)

​4. Unclear Description

​5. Posting to Closed Period

​6. Missing Idempotency Key

​Idempotency

​Related Topics

Understanding Double-Entry

Ledger Accounts

Ledger Roles

Viewing Journal Entries

Accounting Periods

Reversing Entries

What are Manual Journal Entries?

When to Use Manual Entries

API Endpoint

Prerequisites

Validation Rules

Creating Manual Journal Entry

Using the API

Journal Entry Structure

Common Manual Entry Examples

1. Monthly Depreciation

2. Correct Posted Error

3. Accrued Interest Income

4. Opening Balances

5. Write-off Bad Debt

6. Prepaid Expense

7. Reclassify Expense

Best Practices

Restrictions and Limitations

Correcting Manual Entries

Method 1: Create Reversal Entry

Method 2: Create Correcting Entry

Approval Workflow (Recommended)

Audit Considerations

Common Mistakes and Prevention

1. Unbalanced Entry

2. Wrong Account Selection

3. Wrong Side (Debit vs Credit)

4. Unclear Description

5. Posting to Closed Period

6. Missing Idempotency Key

Idempotency

Related Topics