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.
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
const accounts = await prosaic.entityAccounts
.list(entityId)
.autoPagingToArray({ limit: 1000 });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 | A finer grouping used by the reports. |
taxCode | The account's default tax code, such as NZ_GST_15_EXP. |
mappedCode | An optional alternate code, for matching accounts in another system. |
isSystem | true for accounts Prosaic relies on, such as GST, Rounding and Retained Earnings. |
parentId | Set on child accounts. |
source | template, overridden (a template account changed for this entity) or custom. |
Query options:
includeSystem=falseleaves out system accounts (it defaults totrue).includeExcluded=trueadds template accounts that have been hidden from this entity, flaggedisExcluded: 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 a child account under an existing account. |
update(entityId, accountId, params) | Changes name, description, taxCode, mappedCode or code. Parent accounts only take taxCode and mappedCode. |
del(entityId, accountId) | Removes a child account. One that came from the template is recorded as hidden, 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:
await prosaic.entityAccounts.create(entityId, {
parentAccountCode: '4030', // or parentAccountId, or parentMappedCode
code: '4030.1',
name: 'Software subscriptions',
taxCode: 'NZ_GST_15_EXP',
});- The hierarchy has two levels: a parent and its children, no grandchildren.
- Codes contain only digits and dots.
taxCodemust be one of the entity's own tax codes.- You cannot add children under a system account or a bank account's account.
- Only child accounts can be removed, and only while they have no journal entries and no children of their own. Top-level accounts stay.
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() | Prosaic's library of standard accounts, which templates are built from. |
Changes to a template's accounts flow through to the entities created from it, so an embedded platform can manage every customer's chart in one place.
When you create a template, or replace a template's account list, it must include every system account (isSystem: true in globalAccounts.list()). Pass includeSystemAccounts: true to have any you left out added for you.
Two details catch people out:
- Template reads show tax names, writes take tax codes.
charts.listAccountsreturns a tax name such as15% GST on IncomeintaxCode. 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
currentTemplateIdnames the template it was created from, not its chart. Read the chart withentityAccounts.list.
