> ## 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.
# Manual Journal Entries
> Create accounting adjustments, corrections, and special transactions using 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:**
```http theme={null}
POST /ledger-accounts/manual-journal
Headers:
x-organization-id: {organizationId}
x-idempotency-key: {unique-key}
Content-Type: application/json
```
**Request body:**
```typescript theme={null}
{
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:**
```typescript theme={null}
{
ledgerAccountId: string; // UUID of ledger account
side: 'DEBIT' | 'CREDIT'; // Line side
amount: number; // Amount (max 2 decimal places, minimum 0.01)
}
```
**Response:**
```json theme={null}
{
"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**
```http theme={null}
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.
```http theme={null}
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**
```http theme={null}
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**
```http theme={null}
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:**
```typescript theme={null}
{
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](/tontines/general-ledger/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-{timestamp})
* 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:**
```http theme={null}
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
```
***
## Related Topics
Learn debits, credits, and accounting principles
View available accounts and chart of accounts
Understand account roles and types
Review posted entries and audit trail
Understand period closure and constraints
Learn how to reverse posted entries