# Reports

> Trial balance, profit and loss, balance sheet, general ledger, current accounts and depreciation schedule.

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

Reports are read straight from an entity's posted journals, so they are current the moment a journal posts. Drafts are not included, and nor are voided journals or their reversals.

| Report                     | Endpoint                                                 | SDK                            |
| -------------------------- | -------------------------------------------------------- | ------------------------------ |
| Trial balance              | `GET /entities/{entityId}/trial-balance`                 | `reports.trialBalance`         |
| Profit and loss            | `GET /entities/{entityId}/reports/profit-loss`           | `reports.profitLoss`           |
| Balance sheet              | `GET /entities/{entityId}/reports/balance-sheet`         | `reports.balanceSheet`         |
| General ledger, by account | `GET /entities/{entityId}/general-ledger/account`        | `generalLedger.byAccount`      |
| General ledger, entries    | `GET /entities/{entityId}/general-ledger/transaction`    | `generalLedger.byTransaction`  |
| Current accounts           | `GET /entities/{entityId}/reports/current-accounts`      | `reports.currentAccounts`      |
| Depreciation schedule      | `GET /entities/{entityId}/reports/depreciation-schedule` | `reports.depreciationSchedule` |

GST returns are covered in [Tax in NZ and AU](/docs/ledger/tax-nz-au#nz-gst-returns).

## Conventions

- **No envelope.** Reports return the report object itself, with a `metadata` block (the entity, its currency and the report dates), not a `data` wrapper.
- **Decimal strings.** Amounts are strings. Parse them with a decimal library such as Decimal.js rather than adding them as floating-point numbers.
- **Dates** are `YYYY-MM-DD`. A regional format such as `31-10-2026` is rejected with `400`.
- **The entity's own calendar.** Periods such as `this-financial-year` follow the entity's financial year (1 April in New Zealand, 1 July in Australia), and day boundaries fall at midnight in the entity's timezone.
- **Query values are strings.** In the SDK, flags are passed as `'true'` or `'false'` and counts as strings, matching the query string. The exceptions are the general ledger's `includeVoided` (a boolean) and `accountIds` (an array).

## Trial balance

```ts
const tb = await prosaic.reports.trialBalance(entityId, {
  asOfDate: '2026-10-31',
  groupBy: 'reportGroup',
});

console.log(
  tb.totals.isBalanced,
  tb.totals.totalDebits,
  tb.totals.totalCredits,
);
for (const group of tb.accountGroups) {
  for (const account of group.accounts) {
    console.log(account.accountCode, account.accountName, account.netBalance);
  }
}
```

| Parameter                                            | Values                                                                 |
| ---------------------------------------------------- | ---------------------------------------------------------------------- |
| `asOfDate`                                           | Defaults to today.                                                     |
| `reportMode`                                         | `cumulative` (default) or `movement`.                                  |
| `movementStartDate`, `movementEndDate`               | The range for `movement` mode. Defaults to the current financial year. |
| `groupBy`                                            | `type` (default), `reportGroup`, `none`, or `subtype` (deprecated).    |
| `includeZeroBalances`                                | `'false'` (default) or `'true'`.                                       |
| `comparison`                                         | `none` (default) or `periods`.                                         |
| `comparisonType`                                     | `year` (default) or `month`.                                           |
| `comparisonPeriods`                                  | `1` to `12`. Defaults to `1`.                                          |
| `compareToEndOfMonth`, `compareToEndOfFinancialYear` | Snap comparison dates to a month or year end.                          |

In `cumulative` mode, balance sheet accounts show their balance to date and income and expense accounts show the current financial year. `movement` mode shows only the activity in the range, for every account.

Use `groupBy=reportGroup` to group rows by the entity's saved report groups in country order. The group's `type` is its stable key (such as `ass.current`) and `name` is its label (such as Current assets). Rows with no saved group share the `unassigned` group. Every row includes nullable `reportGroup` and `reportCategory` objects with `key` and `name`. A null category is valid for a group-only assignment. Use `groupBy=none` to build your own groups from the rows.

`groupBy=subtype` is deprecated. It still groups rows by their stored `accountSubtype`. To see the groups and categories available for an entity, use `GET /api/public/v1/entities/{entityId}/report-categories`, `reportCategories.list(entityId)` in the SDK, or `list_report_categories` in MCP.

Each account's `netBalance` is **debits minus credits**: positive for a debit balance, negative for a credit balance, whatever the account type. `totals` has `totalDebits`, `totalCredits`, `isBalanced` and `variance`.

## Profit and loss

```ts
const pl = await prosaic.reports.profitLoss(entityId, {
  periodType: 'last-financial-year',
});
```

| Parameter              | Values                                                                                                                          |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `periodType`           | `this-financial-year` (default), `last-financial-year`, `this-quarter`, `last-quarter`, `this-month`, `last-month` or `custom`. |
| `startDate`, `endDate` | The range for `custom`. Leave them out for the other period types.                                                              |
| `comparison`           | `none` (default) or `periods`.                                                                                                  |
| `comparisonType`       | `year` (default), `quarter`, `month` or `custom`. Pair it with the matching `periodType`.                                       |
| `comparisonPeriods`    | `1` to `12`.                                                                                                                    |
| `includeZeroBalances`  | `'false'` (default) or `'true'`.                                                                                                |

The response is split into `tradingIncome`, `costOfSales`, `otherIncome` and `operatingExpenses`, with `totals`.

## Balance sheet

```ts
const bs = await prosaic.reports.balanceSheet(entityId, {
  asOfDate: '2027-03-31',
});
```

Takes `asOfDate` (defaults to today), `includeZeroBalances`, and the same `comparison`, `comparisonType` (`year` or `month`) and `comparisonPeriods` as the trial balance. The response has `sections` and `totals`.

## General ledger

Every posted line, from every source: manual journals, bank reconciliations, invoices and the rest.

```ts
const ledger = await prosaic.generalLedger.byAccount(entityId, {
  periodType: 'custom',
  startDate: '2026-04-01',
  endDate: '2027-03-31',
});
```

- `byAccount` groups entries under each account, with running balances and period totals. Its response has `accounts`.
- `byTransaction` returns a flat list of entries. Its response has `entries`.

| Parameter              | Values                                                                                                                                                                                  |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `periodType`           | `custom` (the default), `this-month`, `last-month`, `this-quarter`, `last-quarter`, `this-financial-year`, `last-financial-year`, `month-to-date`, `quarter-to-date` or `year-to-date`. |
| `startDate`, `endDate` | Both required with `custom`.                                                                                                                                                            |
| `accountIds`           | Entity account IDs: an array in the SDK, which sends them comma-separated.                                                                                                              |
| `includeVoided`        | `true` to include voided journals and their reversals (a boolean in the SDK; `includeVoided=true` in the query string).                                                                 |

Balances here are debits minus credits too.

`GET /entities/{entityId}/ledger` (`ledger.list`) is the older version of this endpoint and is deprecated. Use the general ledger endpoints instead.

## Current accounts

The owners' or shareholders' current accounts: an opening balance, increases (funds introduced and advances), decreases (drawings), and the closing balance for the period. It takes the same `periodType`, `startDate`, `endDate` and comparison parameters as the profit and loss.

```ts
const current = await prosaic.reports.currentAccounts(entityId, {
  periodType: 'this-financial-year',
});
```

## Depreciation schedule

The entity's fixed assets over a period, one row per asset, with `totals`. Both dates are required.

```ts
const schedule = await prosaic.reports.depreciationSchedule(entityId, {
  startDate: '2026-04-01',
  endDate: '2027-03-31',
});
```

Assets themselves are managed with `fixedAssets` and `fixedAssetTypes`; see [Fixed assets](/docs/api/fixed-assets) in the API reference.

## Chart reporting assignments

Discover workspace choices with `GET /api/public/v1/report-categories`, or entity choices with `GET /api/public/v1/entities/{entityId}/report-categories`. The saved reporting group/category pair is authoritative in activated workspaces. Stored `subtype` remains compatibility data, not a promise that reports derive from it. Trial-balance `groupBy=subtype` remains available pending its separate retirement. See [Chart of accounts](/docs/ledger/chart-of-accounts) for required write choices, permissions and conflict recovery.
