Getting Started

Core Concepts

Understanding the accounting fundamentals of Open Ledger.

Open Ledger is built on established accounting principles while providing modern APIs and components. Understanding these core concepts will help you effectively implement and customize the platform.

Double-Entry entitykeeping

At the foundation of Open Ledger is the double-entry entitykeeping system, where every transaction affects at least two accounts:

Transaction: Client paid $500 for services
DEBIT: Cash/Bank Account       $500 (Asset ↑)
CREDIT: Service Revenue        $500 (Revenue ↑)

Account Types and Behaviors

Open Ledger follows standard accounting rules for how different account types behave:

Account TypeIncreases WithDecreases WithNormal Balance
AssetDEBITCREDITDEBIT
LiabilityCREDITDEBITCREDIT
EquityCREDITDEBITCREDIT
RevenueCREDITDEBITCREDIT
ExpenseDEBITCREDITDEBIT

Handling Negative Amounts

When processing transactions, negative amounts are treated as reversals:

  • Negative DEBIT: Effectively treated as a CREDIT
  • Negative CREDIT: Effectively treated as a DEBIT

This handles scenarios like refunds, returns, and expense reimbursements correctly.

Chart of Accounts

The Chart of Accounts is a comprehensive listing of all accounts used by an organization to record financial transactions in its general ledger. Each account typically has:

  • A unique numeric identifier or code
  • A descriptive name
  • Classification that determines which financial statement it appears on (e.g., Balance Sheet or Income Statement)

Open Ledger maintains this accounting structure while offering extended capabilities:

ASSETS (100-199)
101 - Operating Cash Account
102 - Savings Account
110 - Accounts Receivable
120 - Inventory
150 - Property
151 - Equipment
152 - Furniture
LIABILITIES (200-299)
201 - Accounts Payable
210 - Short-term Loans
250 - Long-term Debt
EQUITY (300-399)
301 - Common Stock
310 - Retained Earnings
REVENUE (400-499)
401 - Product Sales
410 - Service Revenue
EXPENSES (500-599)
501 - Cost of Goods Sold
510 - Salaries Expense
520 - Rent Expense

Account Model

In Open Ledger, accounts are modeled with these key attributes:

AttributeDescription
IDUnique identifier
NameHuman-readable name
TypeAsset, Liability, Equity, Revenue, or Expense
SubTypeMore specific classification (e.g., Cash, Accounts Receivable)
Parent AccountOptional - for organizations that want hierarchical organization
CodeNumeric accounting code for reference
Is CategoryFlag for category vs. transactional accounts

Transactions and Journal Entries

Every financial event is recorded as a transaction in Open Ledger:

Transaction Model

Transaction Interface Schema
1interface Transaction {
2  id: string;
3  instance_id: string;
4  timestamp: Date;
5  amount: Decimal;
6  currency: string;
7  description?: string;
8  debit_account_id: string;
9  credit_account_id: string;
10  status:
11    | "PENDING"
12    | "CLEARED"
13    | "RECONCILED"
14    | "POSTED"
15    | "REVERSED"
16    | "EXPIRED";
17  tb_transfer_id?: string;
18  metadata?: Record<string, any>;
19  created_at: Date;
20  updated_at: Date;
21  entity_id?: string;
22  created_by?: number;
23  updated_by?: number;
24}

Transaction Lifecycle

  1. Creation: Transactions begin as PENDING when first recorded
  2. Clearing: Move to CLEARED when confirmed by financial institutions
  3. Reconciliation: Marked as RECONCILED when matched to bank records
  4. Posting: Finalized as POSTED when approved for financial statements
  5. Reversal: Can be REVERSED if needed to correct errors
  6. Expiration: Marked EXPIRED if pending transactions aren’t confirmed

Financial Reports

Open Ledger automatically generates standard financial reports:

Income Statement

Revenue and expenses summary showing net profit/loss over time.

Balance Sheet

Assets = Liabilities + Equity at a specific point in time.

Cash Flow Statement

Cash movement across operating, investing, and financing activities.

Data Model Integration

Open Ledger’s data model maps to traditional accounting concepts while maintaining modern API practices:

Multi-tenant Structure:

  • Organizations & Workspaces: Multi-tenant structure for enterprise use
  • Instances: Independent accounting environments
  • entities: Individual accounting entities (companies, departments)
  • Ledger Accounts: Chart of accounts entries
  • Transactions: Financial events with double-entry enforcement
  • Categories: Classification system for transactions
Organization
└── Workspaces (Development, Staging, Production)
    └── Instances (Financial Systems)
        └── entities (Companies, Departments, etc.)

API Integration Points:

  • Transaction Creation: Record financial events
  • Account Management: Create/modify chart of accounts
  • Categorization: Classify transactions for reporting
  • Report Generation: Create financial statements
  • Data Synchronization: Connect with external financial sources

By understanding these core concepts, you’ll be better equipped to implement and customize Open Ledger for your specific requirements.