# Journals

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

Source: https://developer.prosaic.works/docs/ledger/journals

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

| Field       | Required | Notes                                                                                                                                  |
| ----------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `date`      | Yes      | `YYYY-MM-DD`, a calendar day in the entity's own timezone.                                                                             |
| `narration` | Yes      | 1 to 300 characters. Put your own reference here; see [avoiding double-posting](/docs/ledger/embedded-ledger#avoiding-double-posting). |
| `lines`     | Yes      | The journal lines. A posted journal needs at least two lines with an amount.                                                           |
| `taxMode`   | No       | `NO_TAX`, `TAX_EXCLUSIVE` or `TAX_INCLUSIVE`. Leaving it out behaves like `NO_TAX`.                                                    |
| `autoPost`  | No       | Defaults to `true`, which posts the journal. `false` saves a draft.                                                                    |
| `fileIds`   | No       | Uploaded files to attach. See [attachments](#attachments).                                                                             |

Each line:

| Field                | Notes                                                                                                                          |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `entityAccountCode`  | The account's `code` from the entity's [chart of accounts](/docs/ledger/chart-of-accounts). Required on a line with an amount. |
| `taxRateId`          | An `id` from the entity's `taxRates[]` (see [Tax in NZ and AU](/docs/ledger/tax-nz-au)). Required on a line with an amount.    |
| `debit` or `credit`  | A decimal string such as `"115.00"` (numbers are accepted too). Zero or positive. Use one side per line.                       |
| `description`        | Optional, up to 200 characters.                                                                                                |
| `dimensionOptionIds` | Optional tracking categories; see [dimensions](#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`:

| `taxMode`       | Line amounts are | At posting                                                                                                                              |
| --------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `NO_TAX`        | Final            | Nothing is added. Debits must equal credits as sent.                                                                                    |
| `TAX_EXCLUSIVE` | Before GST       | For 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_INCLUSIVE` | Including GST    | GST 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](/docs/ledger/reports#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](#drafts-and-posted-journals).
