Trial Balance API

The Trial Balance Service generates trial balance reports to verify the accounting equation and detect imbalances.

Overview

A trial balance proves that:

1. Total Debits = Total Credits (double-entry integrity)
2. Assets = Liabilities + Equity (accounting equation)

Service Methods

generateTrialBalance(options)

Generate a trial balance report.

Parameters:

Parameter	Type	Default	Description
options.asOfDate	Date	Now	Point-in-time report
options.useCache	boolean	true	Use cached balances (faster)

Returns:

interface TrialBalanceReport {
  asOfDate: Date;
  entries: TrialBalanceEntry[];
  totalDebits: number;
  totalCredits: number;
  difference: number;
  isBalanced: boolean;  // difference < E0.01

  // Grouped by type
  assets: { entries: TrialBalanceEntry[]; total: number };
  liabilities: { entries: TrialBalanceEntry[]; total: number };
  equity: { entries: TrialBalanceEntry[]; total: number };
  revenue: { entries: TrialBalanceEntry[]; total: number };
  expenses: { entries: TrialBalanceEntry[]; total: number };
}

interface TrialBalanceEntry {
  accountCode: string;
  accountName: string;
  accountType: 'ASSET' | 'LIABILITY' | 'EQUITY' | 'REVENUE' | 'EXPENSE';
  debitTotal: number;
  creditTotal: number;
  balance: number;
}

Example:

// Generate current trial balance
const trialBalance = await trialBalanceService.generateTrialBalance();

console.log(`Debits: E${trialBalance.totalDebits.toFixed(2)}`);
console.log(`Credits: E${trialBalance.totalCredits.toFixed(2)}`);
console.log(`Balanced: ${trialBalance.isBalanced}`);

---

verifyTrialBalance(options)

Verify trial balance and create a reconciliation record.

Parameters:

Parameter	Type	Description
options.asOfDate	Date	Point-in-time
options.triggeredBy	string	Actor ID for audit

Returns: Reconciliation record

Example:

const reconciliation = await trialBalanceService.verifyTrialBalance({
  triggeredBy: 'system'
});

if (!reconciliation.isReconciled) {
  console.error('Trial balance does NOT balance!');
}

---

verifyAccountingEquation(asOfDate?)

Verify the accounting equation: Assets = Liabilities + Equity + Net Income

Returns:

{
  assets: number;
  liabilities: number;
  equity: number;
  revenue: number;
  expenses: number;
  netIncome: number;  // Revenue - Expenses
  totalLiabilitiesAndEquity: number;  // L + E + Net Income
  difference: number;
  isBalanced: boolean;
}

Example:

const equation = await trialBalanceService.verifyAccountingEquation();

console.log(`Assets: E${equation.assets.toFixed(2)}`);
console.log(`Liabilities + Equity: E${equation.totalLiabilitiesAndEquity.toFixed(2)}`);
console.log(`Net Income: E${equation.netIncome.toFixed(2)}`);

---

exportToCSV(asOfDate?)

Export trial balance to CSV format.

Returns: CSV string

CSV Format:

Account Code,Account Name,Account Type,Debit,Credit,Balance
1110,User Wallets,ASSET,50000.00,45000.00,5000.00
1120,Vendor Wallets,ASSET,30000.00,28000.00,2000.00
...

TOTAL,,80000.00,80000.00,
DIFFERENCE,,,0.00,
BALANCED,,YES,,

---

getFinancialSummary(asOfDate?)

Get a high-level financial summary.

Returns:

{
  asOfDate: Date;
  totalAssets: number;
  totalLiabilities: number;
  totalEquity: number;
  totalRevenue: number;
  totalExpenses: number;
  netIncome: number;
  cashPosition: number;  // User + Vendor wallets
}

---

compareTrialBalances(startDate, endDate)

Compare trial balances between two dates.

Returns:

{
  startBalance: TrialBalanceReport;
  endBalance: TrialBalanceReport;
  changes: Array<{
    accountCode: string;
    accountName: string;
    startBalance: number;
    endBalance: number;
    change: number;
    changePercent: number;
  }>;
}

Example:

const startOfMonth = new Date('2026-01-01');
const endOfMonth = new Date('2026-01-31');

const comparison = await trialBalanceService.compareTrialBalances(
  startOfMonth,
  endOfMonth
);

// Show top changes
for (const change of comparison.changes.slice(0, 5)) {
  console.log(`${change.accountName}: ${change.changePercent.toFixed(1)}%`);
}

---

Account Type Classification

Account codes follow this convention:

First Digit	Account Type	Normal Balance
1	ASSET	Debit
2	LIABILITY	Credit
3	EQUITY	Credit
4	REVENUE	Credit
5	EXPENSE	Debit

---

Trial Balance vs Cache

Method	Speed	Accuracy	Use Case
useCache: true	Fast	Depends on sync	Quick reports
useCache: false	Slower	Most accurate	Verification

When to use ledger (no cache):

• Monthly/quarterly verification
• After suspected issues
• For regulatory reports

---

Scheduled Verification

Job	Schedule	Purpose
Trial Balance Check	Daily 4:30 AM	Verify debits = credits
Accounting Equation	Weekly Sunday	Verify A = L + E

---

Dashboard Integration

View trial balance reports:

• Current Trial Balance: /admin/accounting/trial-balance
• Historical Comparison: /admin/accounting/trial-balance/compare
• Financial Summary: /admin/accounting/summary

---

Related

• Chart of Accounts - Account structure
• Ledger Service - Core ledger operations
• Balance Verification - Entity reconciliation
• Statements - Account statements