Back to Docs

Journals

Post balanced journals with account codes and tax rates, handle GST, keep drafts for review, void and attach files.

A journal is a dated set of debit and credit lines that balance. It is the main way to write to an entity's books.

text
POST /api/public/v1/entities/{entityId}/journals      prosaic.journals.create(entityId, params)

A journal with GST

This records a $100 office expense plus 15% GST, owed to a supplier. With taxMode: 'TAX_EXCLUSIVE', each line's amount is before GST, and Prosaic adds the GST when it posts.

ts
const journal = await prosaic.journals.create(entityId, {
  date: '2026-10-01',
  narration: 'Stationery, supplier invoice 1042',
  taxMode: 'TAX_EXCLUSIVE',
  lines: [
    {
      entityAccountCode: '4030', // Office Expense
      taxRateId: gstOnExpensesId, // NZ_GST_15_EXP
      debit: '100.00',
      description: 'Printer paper and toner',
    },
    {
      entityAccountCode: '8220', // Accounts Payable
      taxRateId: noGstId, // NZ_GST_0_NONE
      credit: '115.00',
    },
  ],
});
bash
curl -X POST https://app.prosaic.works/api/public/v1/entities/YOUR_ENTITY_ID/journals \
  -H "Authorization: Bearer $PROSAIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "date": "2026-10-01",
    "narration": "Stationery, supplier invoice 1042",
    "taxMode": "TAX_EXCLUSIVE",
    "lines": [
      { "entityAccountCode": "4030", "taxRateId": "GST_ON_EXPENSES_RATE_ID", "debit": "100.00", "description": "Printer paper and toner" },
      { "entityAccountCode": "8220", "taxRateId": "NO_GST_RATE_ID", "credit": "115.00" }
    ]
  }'

When it posts, the journal has three lines: $100 to Office Expense, a generated $15 GST line to the entity's GST account, and $115 to Accounts Payable.

Request fields

FieldRequiredNotes
dateYesYYYY-MM-DD, a calendar day in the entity's own timezone.
narrationYes1 to 300 characters. Put your own reference here; see avoiding double-posting.
linesYesThe journal lines. A posted journal needs at least two lines with an amount.
taxModeNoNO_TAX, TAX_EXCLUSIVE or TAX_INCLUSIVE. Leaving it out behaves like NO_TAX.
autoPostNoDefaults to true, which posts the journal. false saves a draft.
fileIdsNoUploaded files to attach. See attachments.

Each line:

FieldNotes
entityAccountCodeThe account's code from the entity's chart of accounts. Required on a line with an amount.
taxRateIdAn id from the entity's taxRates[] (see Tax in NZ and AU). Required on a line with an amount.
debit or creditA decimal string such as "115.00" (numbers are accepted too). Zero or positive. Use one side per line.
descriptionOptional, up to 200 characters.
dimensionOptionIdsOptional tracking categories; see dimensions.

Lines with nothing on either side are dropped. An unknown account code or tax rate ID is rejected with 400.

Amounts

  • Send amounts as decimal strings and do your sums with a decimal library such as Decimal.js, not floating point.
  • Never send a negative amount to flip a line's direction. A negative number is rejected, and in a string the minus sign is stripped, so "-50.00" is read as 50.00 on the side you put it. Move the amount to the other side instead.
  • Strings are cleaned of currency formatting, so "$1,000.00" is read as 1000.00. Prefer plain digits anyway.

Balancing and GST

A posted journal must balance to within one cent. How the check counts GST depends on taxMode:

taxModeLine amounts areAt posting
NO_TAXFinalNothing is added. Debits must equal credits as sent.
TAX_EXCLUSIVEBefore GSTFor each line whose tax rate is above 0%, a GST line is added to the entity's GST account. Debits must equal credits once GST is added.
TAX_INCLUSIVEIncluding GSTGST is split out of each taxed line into a GST line, so the line keeps its net amount. Debits must equal credits as sent.

So with TAX_INCLUSIVE, the example above would send "115.00" on both lines, and post as the same three lines.

Check the balance before you send. An unbalanced journal is refused when it posts, nothing is saved, and today the API reports it as 500 Failed to create journal rather than a 400.

Drafts and posted journals

  • Posted (autoPost left out or true): the journal is in the ledger and the reports straight away. The response's status is posted.
  • Draft (autoPost: false): saved with status draft, without the balance check and without GST lines. Drafts are not in the reports. Someone reviews and posts them in the Prosaic app; the API cannot post a draft.

Drafts are the simplest review step: your product writes drafts, and the customer's accountant posts them.

The response

Journal creation returns the journal itself, not a data envelope:

  • id is this version of the journal.
  • logicalJournalId identifies the journal across versions. Voiding and attaching files take this ID, so store it.
  • date is an instant: the start of the journal's day in the entity's timezone, in UTC. A New Zealand journal dated 2026-10-01 comes back as 2026-09-30T11:00:00.000Z.
  • lines includes any generated GST lines, each with entityAccount and taxRate. Amounts are decimal strings.
  • attachments lists attached files.

Listing journals

ts
for await (const journal of prosaic.journals.list(entityId, {
  dateFrom: '2026-09-30', // the day before: dateFrom is compared with UTC midnight
  dateTo: '2026-10-31',
})) {
  console.log(journal.logicalJournalId, journal.narration, journal.status);
}

GET /entities/{entityId}/journals returns manual journals, newest first, a page at a time (page, pageSize). It does not include journals Prosaic creates itself, such as bank reconciliations. The date filters compare against UTC midnight rather than the entity's day. In New Zealand and Australia that misses journals dated on dateFrom itself, so pass the day before. dateTo already includes its own day.

For every posted line, from every source, use the general ledger.

Voiding a journal

ts
await prosaic.journals.void(entityId, journal.logicalJournalId!);
bash
curl -X PATCH https://app.prosaic.works/api/public/v1/entities/YOUR_ENTITY_ID/journals/YOUR_LOGICAL_JOURNAL_ID/void \
  -H "Authorization: Bearer $PROSAIC_API_KEY"

Only posted journals can be voided. Voiding marks the journal voided and posts a reversal on the same date. The reports then leave both out; the general ledger shows them when you pass includeVoided=true. Journals that belong to an invoice or record a payment cannot be voided this way (409); undo those through the invoice or the bank transaction.

There is no endpoint to edit a posted journal or to delete a draft. To correct a posted journal, void it and post a new one.

Attachments

Attach receipts, invoices and other evidence. First upload the file to the entity, then attach it, either when you create the journal or afterwards.

ts
import { readFile } from 'node:fs/promises';

const bytes = await readFile('receipt-1042.pdf');
const upload = await prosaic.files.upload(
  entityId,
  new File([bytes], 'receipt-1042.pdf', { type: 'application/pdf' }),
);

// When creating the journal:
await prosaic.journals.create(entityId, {
  ...params,
  fileIds: [upload.file.id],
});

// Or on an existing journal:
await prosaic.journals.attachFiles(entityId, logicalJournalId, {
  fileIds: [upload.file.id],
});

Uploads are multipart/form-data with a file field, up to 20 MB. Set the file's type: PDF, JPEG, PNG, GIF, WebP, CSV, plain text, Excel, Word and Outlook MSG are accepted, and anything else is refused with 415. files.list(entityId) lists files already on the entity.

Dimensions

Dimensions are tracking categories, such as Property or Department. dimensions.list(entityId) returns the entity's dimensions and their options. Tag a line with dimensionOptionIds, at most one option per dimension. Options from another entity, or two from the same dimension, are rejected with 400.

Change-sets

POST /entities/{entityId}/change-sets (prosaic.changeSets.create) records proposed writes (journals to post, bank transactions to reconcile) as a pending change-set instead of writing them. Nothing reaches the ledger until the set is approved, and resubmitting identical content returns the existing set.

A change-set's journal lines name accounts by entityAccountId and take amounts as numbers, unlike journals.create. Change-sets were built for AI agents, and today approval happens in Prosaic's own review tooling rather than in your workspace. For a review step that you and your customers' accountants control, use drafts.