Chart of Accounts API

The Chart of Accounts Service manages the hierarchical structure of ledger accounts.

Overview

The Chart of Accounts (COA) defines:

• Account codes and names
• Account types (Asset, Liability, Equity, Revenue, Expense)
• Normal balances (Debit or Credit)
• Parent-child relationships (hierarchy)

Standard Accounts

Keshless uses a 4-digit account code system:

Assets (1xxx)

Code	Name	Level
1000	Assets	0
1100	Current Assets	1
1110	User Wallets	2
1120	Vendor Wallets	2
1130	Cash in Transit	2
1140	Petty Cash	2

Liabilities (2xxx)

Code	Name	Level
2000	Liabilities	0
2100	Current Liabilities	1
2110	Accounts Payable	2
2120	Pending Withdrawals	2

Equity (3xxx)

Code	Name	Level
3000	Equity	0
3100	Retained Earnings	1
3200	Share Capital	1

Revenue (4xxx)

Code	Name	Level
4000	Revenue	0
4100	Transaction Revenue	1
4110	Transaction Fee Revenue	2
4120	Withdrawal Fee Revenue	2
4130	Commission Income	2

Expenses (5xxx)

Code	Name	Level
5000	Expenses	0
5100	Operating Expenses	1
5110	Processing Costs	2
5120	Refund Expenses	2

---

Service Methods

initialize()

Initialize and seed standard accounts on first run.

Example:

await chartOfAccountsService.initialize();
// ✅ Chart of Accounts initialized successfully

---

createAccount(data)

Create a new account.

Parameters:

Parameter	Type	Required	Description
data.accountCode	string	Yes	4-digit code
data.accountName	string	Yes	Account name
data.accountType	AccountType	Yes	ASSET/LIABILITY/etc.
data.parentCode	string	No	Parent account code
data.description	string	No	Description

Returns: ChartOfAccounts

Example:

const account = await chartOfAccountsService.createAccount({
  accountCode: '4140',
  accountName: 'Premium Subscription Revenue',
  accountType: 'REVENUE',
  parentCode: '4100',
  description: 'Revenue from premium subscriptions'
});

---

getAccount(accountCode)

Get account by code.

Returns: ChartOfAccounts | null

---

getActiveAccount(accountCode)

Get active account by code.

Returns: ChartOfAccounts | null

---

getAccountsByType(accountType)

Get all accounts of a specific type.

Parameters:

Parameter	Type	Description
accountType	string	ASSET/LIABILITY/EQUITY/REVENUE/EXPENSE

Returns: ChartOfAccounts[]

---

getChildAccounts(parentCode)

Get child accounts of a parent.

Returns: ChartOfAccounts[]

---

getAllAccounts(includeInactive?)

Get all accounts.

Parameters:

Parameter	Type	Default	Description
includeInactive	boolean	false	Include deactivated

Returns: ChartOfAccounts[] (sorted by account code)

---

getAccountTree()

Get hierarchical account tree.

Returns:

Array<{
  accountCode: string;
  accountName: string;
  accountType: AccountType;
  normalBalance: NormalBalance;
  level: number;
  isActive: boolean;
  children: Array<...>;  // Recursive
}>

Example:

const tree = await chartOfAccountsService.getAccountTree();
// Returns nested structure for rendering tree view

---

updateAccount(accountCode, updates)

Update an account.

Parameters:

Parameter	Type	Description
updates.accountName	string	New name
updates.description	string	New description
updates.isActive	boolean	Active status

Returns: ChartOfAccounts

---

deactivateAccount(accountCode)

Deactivate an account (soft delete).

Returns: ChartOfAccounts

---

reactivateAccount(accountCode)

Reactivate a deactivated account.

Returns: ChartOfAccounts

---

isAccountActive(accountCode)

Check if account exists and is active.

Returns: boolean

---

getAccountsByCategory(includeInactive?)

Get accounts grouped by category.

Returns:

{
  assets: ChartOfAccounts[];
  liabilities: ChartOfAccounts[];
  equity: ChartOfAccounts[];
  revenue: ChartOfAccounts[];
  expenses: ChartOfAccounts[];
}

---

searchAccounts(searchTerm)

Search accounts by code, name, or description.

Parameters:

Parameter	Type	Description
searchTerm	string	Search query

Returns: ChartOfAccounts[] (max 50 results)

---

getStatistics()

Get COA statistics.

Returns:

{
  totalAccounts: number;
  activeAccounts: number;
  inactiveAccounts: number;
  accountsByType: {
    assets: number;
    liabilities: number;
    equity: number;
    revenue: number;
    expenses: number;
  };
}

---

validateAccountCode(accountCode)

Validate account code format.

Pattern: ^\d{4}(-\w+)?$

Valid: 1110, 1110-user123Invalid: 11, abc1

---

getEntityAccountCode(baseAccountCode, entityId)

Generate entity-specific account code.

Example:

const userAccountCode = chartOfAccountsService.getEntityAccountCode('1110', 'user-123');
// Returns: '1110-user-123'

---

Account Schema

interface ChartOfAccounts {
  id: string;
  accountCode: string;      // Unique 4-digit code
  accountName: string;
  accountType: AccountType;
  normalBalance: NormalBalance;
  parentCode?: string;      // Parent account code
  level: number;            // Hierarchy level (0=top)
  description?: string;
  isActive: boolean;
  isSummary: boolean;       // true for parent accounts
  createdAt: Date;
  updatedAt: Date;
}

---

Account Types

Type	Normal Balance	Increases On
ASSET	Debit	Debit
LIABILITY	Credit	Credit
EQUITY	Credit	Credit
REVENUE	Credit	Credit
EXPENSE	Debit	Debit

---

Hierarchy Levels

Level	Description	Example
0	Top-level category	Assets (1000)
1	Sub-category	Current Assets (1100)
2	Detail account	User Wallets (1110)

---

Dashboard Integration

Manage COA in the admin dashboard:

• Account List: /admin/accounting/chart-of-accounts
• Account Tree: /admin/accounting/chart-of-accounts/tree
• Create Account: /admin/accounting/chart-of-accounts/new

---

Related

• Trial Balance - Balance reports using COA
• Ledger Service - Uses account codes
• Accounting Overview - System overview