# Chart of accounts

> Templates, an entity's own accounts, system accounts, and adding or changing accounts.

Source: https://developer.prosaic.works/docs/ledger/chart-of-accounts

Every entity has its own chart of accounts. It is copied from a **template** when the entity is created, and journal lines name its accounts by **code**.

In the new chart architecture, each account has its own code and an explicit reporting placement. The placement consists of a report group and, where applicable, a report category.

There are two levels, and their IDs are not interchangeable:

| Level    | What it is                                                  | Read with                            |
| -------- | ----------------------------------------------------------- | ------------------------------------ |
| Template | A workspace-level blueprint that entities are created from. | `charts.list`, `charts.listAccounts` |
| Entity   | The accounts one entity actually posts to.                  | `entityAccounts.list`                |

Post journals against the entity's accounts. Template account IDs are never valid on a journal.

## An entity's accounts

```ts
const accounts = await prosaic.entityAccounts
  .list(entityId)
  .autoPagingToArray({ limit: 1000 });
```

```bash
curl https://app.prosaic.works/api/public/v1/entities/YOUR_ENTITY_ID/charts \
  -H "Authorization: Bearer $PROSAIC_API_KEY"
```

Each account has:

| Field        | Notes                                                                               |
| ------------ | ----------------------------------------------------------------------------------- |
| `id`         | The entity account's ID.                                                            |
| `code`       | What journal lines send as `entityAccountCode`, for example `4030`.                 |
| `name`       | For example `Office Expense`.                                                       |
| `type`       | `Asset`, `Liability`, `Equity`, `Revenue` or `Expense`.                             |
| `subtype`    | Stored legacy compatibility data; use the saved reporting pair for classification.  |
| `taxCode`    | The account's default tax code, such as `NZ_GST_15_EXP`.                            |
| `mappedCode` | Optional alternate code for a workflow that uses different codes.                   |
| `isSystem`   | `true` for accounts Prosaic relies on, such as GST, Rounding and Retained Earnings. |
| `parentId`   | A legacy hierarchy reference. Use the saved reporting pair for placement.           |
| `source`     | `template`, `overridden` (a template account changed for this entity) or `custom`.  |

Query options:

- `includeSystem=false` leaves out system accounts (it defaults to `true`).
- `includeExcluded=true` adds template accounts that have been hidden from this entity, flagged `isExcluded: true`.

In the SDK these are strings: `{ includeSystem: 'false' }`.

An account's `taxCode` is a default, not a rule: each journal line names its own tax rate. If an entity is created without `isGstRegistered: true`, every account defaults to its country's "No GST" code.

Bank accounts linked to an entity get their own account in the chart. You can find it at `bankAccounts[].entityAccount` on the entity in `GET /entities`.

## Changing an entity's chart

All of these are on `entityAccounts`, under `/entities/{entityId}/charts`:

| Method                                 | What it does                                                                                                              |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `create(entityId, params)`             | Adds an account with reporting choices when inputs are enabled; uses a parent otherwise.                                  |
| `update(entityId, accountId, params)`  | Updates eligible account metadata or reporting. Parent account fields have additional restrictions in earlier workspaces. |
| `del(entityId, accountId)`             | Deletes an eligible custom account or excludes a template-linked account so `restore` can bring it back.                  |
| `restore(entityId, templateAccountId)` | Brings back a hidden template account.                                                                                    |
| `reset(entityId, accountId)`           | Returns a changed template account to the template's values.                                                              |

Adding an account:

```ts
await prosaic.entityAccounts.create(entityId, {
  reporting: { groupKey: 'exp.operating', categoryKey: null },
  code: '4050',
  name: 'Software subscriptions',
  taxCode: 'NZ_GST_15_EXP',
});
```

Call `reportCategories.list(entityId)` first. In enabled workspaces, choose an active assignable group and an eligible category or explicit null. Account type derives from the group. Bank and other verified functions can require a category. Do not send a parent with the pair. Nonactivated workspaces retain the legacy parent-based write shape and reject explicit assignment writes.

Codes contain only digits and dots. Use the firm's own account code for posting, and keep the account ID when renaming it. A report group places the account in a report section. A category adds detail within that section. Each account has one saved pair even when discovery lists the same category under several groups. Compare the selected group's ID with the category's `allowedGroupIds` and send the keys in the write.

If the firm recodes an account, reread the chart and refresh any rules, imports or integrations that reference the old code. Use the entity editor or pass `code` to the SDK’s `entityAccounts.update` to change an eligible account code. The MCP `update_chart_account` tool currently exposes other account fields.

## Discovery and conflict handling

Before an entity exists, call `reportCategories.listForWorkspace()` (`GET /api/public/v1/report-categories`). It uses the authorised workspace, returns `workspaceId`, `country`, `groups`, `categories` and `reportingInputsEnabled`, and accepts no country override. Entity discovery uses all active connected workspaces. The capability is observational; writes recheck policy and permissions.

```ts
const { data: taxonomy } = await prosaic.reportCategories.listForWorkspace();
const group = taxonomy.groups.find((g) => g.key === 'exp.operating');
if (!group?.isAssignable) throw new Error('Assignable group unavailable');
```

A metadata-only patch preserves classification:

```ts
await prosaic.entityAccounts.update(entityId, accountId, {
  description: 'Monthly subscriptions',
});
```

Read current assignments before editing. Include the saved pair in `expected`; explicit null means it was unassigned. A valid group-only edit has `categoryKey: null`:

```ts
await prosaic.entityAccounts.update(entityId, accountId, {
  reporting: {
    groupKey: 'exp.operating',
    categoryKey: null,
    expected: {
      groupKey: current.reportGroup.key,
      categoryKey: current.reportCategory?.key ?? null,
    },
  },
});
```

Missing, mixed or invalid choices return `400 VALIDATION_ERROR`. `409 CHART_INPUT_CONTRACT_MISMATCH` requires rediscovery. Other stale-state conflicts require rereading and reviewing current data before another save. Policy evaluation failure returns `503 CHART_INPUT_POLICY_UNAVAILABLE`. Never retry a mutation automatically with a different shape. Read-only subtype compatibility and trial-balance `groupBy=subtype` remain available; their retirement is separate.

## Templates

Templates live in the workspace. A new workspace starts with five: a standard chart for its country (`Standard NZ Business Template` or `Standard AU Business Template`) and the Company, Trust, Sole Trader and Partnership charts. The standard chart carries the workspace's own GST codes.

| Method                                                   | What it does                                                                 |
| -------------------------------------------------------- | ---------------------------------------------------------------------------- |
| `charts.list()`                                          | The workspace's templates, with an account count for each.                   |
| `charts.listAccounts(chartId)`                           | A template's accounts. `includeHidden: true` adds global accounts not in it. |
| `charts.create(params)`                                  | Creates a template from a list of accounts.                                  |
| `charts.update(chartId, params)`                         | Renames it, or replaces its whole account list.                              |
| `charts.createAccount`, `updateAccount`, `deleteAccount` | Changes one account in a template.                                           |
| `charts.del(chartId)`                                    | Deletes a template no entity uses.                                           |
| `globalAccounts.list()`                                  | Standard accounts for the earlier chart contract.                            |

Template metadata propagation respects entity overrides. Reporting changes require human review and propagation approval. API and OAuth credentials cannot confirm template review, approve propagation or bypass role locks.

In enabled workspaces, included template rows carry `groupKey`, explicit `categoryKey` (nullable), and required system-role mappings. A full replacement includes stable existing row `id` values and row `expectedUpdatedAt` values, plus the template `expectedUpdatedAt`. Keep IDs when codes change. API-created or changed pairs remain unreviewed. A person must confirm them in the chart editor before application. First-use role locks remain permanent. Nonactivated workspaces keep the legacy global-library/system-account flow.

Before replacing the account list, read every page with `charts.listAccounts(chartId)` and check that each response has the same `templateUpdatedAt`. Send that version as the template's `expectedUpdatedAt`. If the version changes between pages, discard the partial list and start again.

Two details catch people out:

- **Template reads show tax names, writes take tax codes.** `charts.listAccounts` returns a tax _name_ such as `15% GST on Income` in `taxCode`. When you write a template, send the machine code (`NZ_GST_15_INC`) instead. Entity accounts return the machine code.
- **Template IDs are not entity IDs.** An entity's `currentTemplateId` names the template it was created from, not its chart. Read the chart with `entityAccounts.list`.
