Back to Docs

Chart of accounts

Templates, an entity's own accounts, system accounts, and adding or changing 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.

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

LevelWhat it isRead with
TemplateA workspace-level blueprint that entities are created from.charts.list, charts.listAccounts
EntityThe 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:

FieldNotes
idThe entity account's ID.
codeWhat journal lines send as entityAccountCode, for example 4030.
nameFor example Office Expense.
typeAsset, Liability, Equity, Revenue or Expense.
subtypeA finer grouping used by the reports.
taxCodeThe account's default tax code, such as NZ_GST_15_EXP.
mappedCodeAn optional alternate code, for matching accounts in another system.
isSystemtrue for accounts Prosaic relies on, such as GST, Rounding and Retained Earnings.
parentIdSet on child accounts.
sourcetemplate, 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:

MethodWhat 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:

ts
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.
  • taxCode must 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.

MethodWhat 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, deleteAccountChanges 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.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.