Transaction Categories

The transaction categories endpoints allow you to create and retrieve categories for your entities’ chart of accounts. Categories represent the different account classifications used to categorize financial transactions in double-entry bookkeeping.

Category Objects

A category in Open Ledger represents a specific account in your chart of accounts. Based on the actual database schema, each category has the following properties:

1
{
2
  "id": "acc_123abc",
3
  "instanceId": "inst_456def",
4
  "parentAccountId": null,
5
  "name": "Cash",
6
  "type": "ASSET",
7
  "financialType": "CASH",
8
  "isCategory": true,
9
  "code": 1000,
10
  "subTypeCode": 1010,
11
  "tbAccountId": "1234567890",
12
  "templateNodeId": null,
13
  "ledgerId": "ldgr_789xyz",
14
  "entityId": "entity_012jkl",
15
  "createdAt": "2024-01-01T00:00:00Z",
16
  "updatedAt": "2024-01-15T00:00:00Z",
17
  "topLevel": true,
18
  "metadata": {
19
    "description": "Main operating cash account"
20
  }
21
}

Category Types

Open Ledger supports the following category types:

• ASSET: Resources owned by the entity (cash, accounts receivable, inventory)
• LIABILITY: Obligations owed by the entity (accounts payable, loans)
• EQUITY: Owners’ interests in the entity (capital, retained earnings)
• REVENUE: Income earned from business activities (sales, service fees)
• EXPENSE: Costs incurred in business operations (rent, salaries, utilities)

Financial types provide more specific categorization within these broader types, such as:

• CASH, ACCOUNTS_RECEIVABLE, INVENTORY (Asset subtypes)
• ACCOUNTS_PAYABLE, SHORT_TERM_DEBT (Liability subtypes)
• RETAINED_EARNINGS, OWNER_EQUITY (Equity subtypes)
• SALES, SERVICE_REVENUES (Revenue subtypes)
• PAYROLL_EXPENSES, RENT_EXPENSES (Expense subtypes)

Create a Category

Create a new transaction category in the entity’s chart of accounts.

1
POST /v1/categories?entityId={entity_id}
2
Authorization: Bearer {access_token}
3
Content-Type: application/json

Query Parameters

Request Body

1
{
2
  "name": "Marketing Expenses",
3
  "type": "EXPENSE",
4
  "subTypeCode": 5020
5
}

Response

1
{
2
  "category": {
3
    "id": "acc_marketing",
4
    "instanceId": "inst_456def",
5
    "parentAccountId": null,
6
    "name": "Marketing Expenses",
7
    "type": "EXPENSE",
8
    "financialType": null,
9
    "isCategory": true,
10
    "code": null,
11
    "subTypeCode": 5020,
12
    "tbAccountId": null,
13
    "templateNodeId": null,
14
    "ledgerId": "ldgr_789xyz",
15
    "entityId": "entity_123abc",
16
    "createdAt": "2024-01-15T10:30:00Z",
17
    "updatedAt": "2024-01-15T10:30:00Z",
18
    "topLevel": false,
19
    "metadata": null
20
  }
21
}

List Categories

Retrieve a list of transaction categories for an entity.

1
GET /v1/categories?entityId={entity_id}
2
Authorization: Bearer {access_token}

Query Parameters

Response

1
{
2
  "categories": [
3
    {
4
      "id": "acc_cash",
5
      "instanceId": "inst_456def",
6
      "parentAccountId": null,
7
      "name": "Cash", 
8
      "type": "ASSET",
9
      "financialType": "CASH",
10
      "isCategory": true,
11
      "code": 1000,
12
      "subTypeCode": 1010,
13
      "tbAccountId": "1111111111",
14
      "templateNodeId": null,
15
      "ledgerId": "ldgr_789xyz",
16
      "entityId": "entity_123abc",
17
      "createdAt": "2024-01-01T00:00:00Z",
18
      "updatedAt": "2024-01-15T00:00:00Z",
19
      "topLevel": true,
20
      "metadata": null
21
    }
22
    // Additional categories...
23
  ]
24
}

Default Categories

When you create a new entity, Open Ledger automatically creates a set of default categories to get you started:

Asset Categories

• Cash (1001) - Cash and bank accounts
• Accounts Receivable (1002) - Money owed by customers
• Prepaid Expenses (1003) - Expenses paid in advance
• Inventory (1004) - Goods for sale

Liability Categories

• Accounts Payable (2001) - Money owed to vendors
• Credit Cards (2002) - Credit card liabilities
• Loans Payable (2003) - Outstanding loans

Equity Categories

• Owner’s Equity (3001) - Owner investment in the business
• Retained Earnings (3002) - Accumulated profits

Revenue Categories

• Sales Revenue (4001) - Income from product sales
• Service Revenue (4002) - Income from services
• Interest Income (4003) - Income from investments

Expense Categories

• Rent Expense (5001) - Office and facility rent
• Utilities Expense (5002) - Electricity, water, internet
• Salaries Expense (5003) - Employee compensation
• Marketing Expense (5004) - Advertising and promotion
• Office Supplies (5005) - General office materials

Category Integration

Categories in Open Ledger serve multiple purposes:

Transaction Categorization

Categories are used to classify transactions for proper accounting:

• Each transaction must specify a debit category and credit category
• Categories determine which financial statements the transaction appears on
• Proper categorization ensures accurate financial reporting

Chart of Accounts

Categories form your entity’s chart of accounts:

• Hierarchical structure with parent-child relationships
• Numeric codes for easy reference and sorting
• Financial types for detailed classification

TigerBeetle Integration

Categories are backed by TigerBeetle accounts for high-performance processing:

• Each category can have an associated tbAccountId
• Real-time balance calculations
• Audit trail and transaction history

Error Handling

Example error response:

1
{
2
  "error": "Name and type are required"
3
}

Next Steps