# Ledgers

> Manage the chart of accounts — create, update, merge, and organize ledger accounts.

- **Category:** Guides
- HTML version: https://www.ondayzero.com/docs/guides/ledgers
- All guides: https://www.ondayzero.com/docs/guides/index.md
- Endpoint catalog: https://www.ondayzero.com/docs/reference/index.md

---

# Ledgers (Chart of Accounts)

Ledgers represent accounts in the chart of accounts. Every financial transaction flows through ledger accounts via journal entries.

## Account Types

| Type | Description | Normal Balance |
|------|-------------|----------------|
| `asset` | Cash, bank accounts, receivables, equipment | Debit |
| `liability` | Payables, loans, credit cards | Credit |
| `equity` | Owner's equity, retained earnings | Credit |
| `revenue` | Sales, service income | Credit |
| `expense` | Rent, payroll, utilities, supplies | Debit |

## List Ledgers

```bash
curl "https://api.ondayzero.com/api/v1/ledgers?type=expense&status=active" \
  -H "Authorization: Bearer dz_your_token_here" \
  -H "x-business-id: YOUR_BUSINESS_ID"
```

### Filter Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `name` | string | Partial name match |
| `type` | string | `asset`, `liability`, `equity`, `revenue`, `expense` |
| `status` | string | `active`, `inactive` |
| `id` | string | Comma-separated ledger UUIDs |

Plus the standard [pagination](/docs/guides/pagination) parameters.

## Create a Ledger

There are two creation modes — **templated** (a standard financial account, auto-configured) and **custom** (you specify the accounting properties):

### Templated

```bash
curl -X POST "https://api.ondayzero.com/api/v1/ledgers" \
  -H "Authorization: Bearer dz_your_token_here" \
  -H "x-business-id: YOUR_BUSINESS_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Operating Checking",
    "financial_account_type": "bank_account"
  }'
```

`financial_account_type` is one of `bank_account`, `credit_card`, `payments`, `payroll`, `loan`, `prepaid_card`, `accounts_receivable`, `accounts_payable`.

### Custom

```bash
curl -X POST "https://api.ondayzero.com/api/v1/ledgers" \
  -H "Authorization: Bearer dz_your_token_here" \
  -H "x-business-id: YOUR_BUSINESS_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Prepaid Insurance",
    "type": "asset",
    "sub_type": "current_assets",
    "debit_credit": "debit",
    "sort_code": 1400,
    "report_cash_flow": true,
    "account_number": "1400",
    "description": "Insurance premiums paid in advance",
    "parent_id": "PARENT_LEDGER_UUID"
  }'
```

Custom mode requires `name`, `type`, `sub_type`, `debit_credit`, `sort_code` and `report_cash_flow`. Optional extras: `account_number` (chart-of-accounts code), `parent_id` (nest under a parent account), `cash_flow_section` (`operating`, `investing`, `financing`, `excluded`), `cfs_class`, and `depreciation_tag` (`depreciable` / `amortizable` — lets [fixed assets](/docs/guides/fixed-assets) be capitalized from this account's transactions).

## Update a Ledger

```bash
curl -X PUT "https://api.ondayzero.com/api/v1/ledgers/{ledger_id}" \
  -H "Authorization: Bearer dz_your_token_here" \
  -H "x-business-id: YOUR_BUSINESS_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Prepaid Insurance (Current)",
    "description": "Short-term insurance prepayments"
  }'
```

## Merge Ledgers

Consolidate multiple accounts into one. All journal entry lines, transactions, budgets, reconciliations, and bank rules are reassigned. Source accounts are archived.

```bash
curl -X POST "https://api.ondayzero.com/api/v1/ledgers/merge" \
  -H "Authorization: Bearer dz_your_token_here" \
  -H "x-business-id: YOUR_BUSINESS_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "source_ledger_ids": ["LEDGER_UUID_1", "LEDGER_UUID_2"],
    "target_ledger_id": "TARGET_LEDGER_UUID",
    "new_name": "Consolidated Office Expenses"
  }'
```

Merging system ledgers into another system ledger additionally requires `"confirmation": "MERGE"`. Merges are irreversible.

## Bulk Update and AI Helpers

- `POST /api/v1/ledgers/bulk-update` applies many updates in one call (`{"updates": [{"id": "...", "status": "inactive"}, …]}`).
- `POST /api/v1/ledgers/suggest-cleanup` returns AI suggestions for duplicate or unused accounts; `POST /api/v1/ledgers/suggest-cash-flow` proposes `cash_flow_section` values; `POST /api/v1/ledgers/apply-coa` creates a whole AI-generated chart of accounts at once.

## Delete a Ledger

```bash
curl -X DELETE "https://api.ondayzero.com/api/v1/ledgers/{ledger_id}" \
  -H "Authorization: Bearer dz_your_token_here" \
  -H "x-business-id: YOUR_BUSINESS_ID"
```

> Deletion returns `400` for system accounts (AR, AP, Plaid-managed bank ledgers, …) and `409 Conflict` if the ledger still has journal entries — move or delete those first, merge the ledger into another, or mark it `inactive` instead.

To remove a ledger **and** everything posted to it, preview the blast radius with `GET /api/v1/ledgers/{ledger_id}/cascade-preview`, then `DELETE /api/v1/ledgers/{ledger_id}/cascade`. That starts a background workflow; poll `GET /api/v1/ledgers/deletion-status/{workflow_id}` for progress. This is destructive and cannot be undone.