# Tax in NZ and AU

> GST tax codes for New Zealand and Australia, GST registration on entities, and reading NZ GST returns.

Source: https://developer.prosaic.works/docs/ledger/tax-nz-au

Every entity holds its own country's GST tax rates, and every journal line with an amount names one of them. The country, and so the set of codes, comes from the entity's workspace. See [one workspace per country](/docs/ledger/embedded-ledger#one-workspace-per-country).

## Tax codes

**New Zealand** (GST at 15%):

| Code            | Name                | Rate |
| --------------- | ------------------- | ---- |
| `NZ_GST_15_INC` | 15% GST on Income   | 15%  |
| `NZ_GST_15_EXP` | 15% GST on Expenses | 15%  |
| `NZ_GST_0_ZERO` | Zero-rated GST      | 0%   |
| `NZ_GST_0_NONE` | No GST              | 0%   |

**Australia** (GST at 10%):

| Code              | Name            | Rate |
| ----------------- | --------------- | ---- |
| `AU_GST_10_INC`   | GST on Income   | 10%  |
| `AU_GST_10_EXP`   | GST on Expenses | 10%  |
| `AU_GST_0_EXPORT` | GST Free        | 0%   |
| `AU_GST_0_INPUT`  | Input Taxed     | 0%   |
| `AU_GST_0_NONE`   | BAS Excluded    | 0%   |

An entity only has its own country's codes. Its tax rates are created with it and listed in `taxRates[]` on the entity, from `entities.list` or the `entities.create` response:

```ts
const {
  data: [entity],
} = await prosaic.entities.list({ entityId });
const rates = new Map(entity.taxRates.map((rate) => [rate.code, rate.id]));

const gstOnExpensesId = rates.get('NZ_GST_15_EXP');
```

Each rate has an `id`, a `code`, a `name` and a `rate`, the percentage as a decimal string.

Different endpoints take different halves of a rate:

- **Journal lines** take the rate's `id`, as `taxRateId`.
- **Accounts** and **bank reconciliations** take the machine `code`, as `taxCode`.

## GST on journals

A journal's `taxMode` decides whether line amounts include GST, and Prosaic writes the GST lines to the entity's GST account when the journal posts:

- `NO_TAX` (or no `taxMode`): amounts are final and no GST lines are added.
- `TAX_EXCLUSIVE`: amounts are before GST, and GST is added on top.
- `TAX_INCLUSIVE`: amounts include GST, and GST is split out.

[Journals](/docs/ledger/journals#balancing-and-gst) has worked examples and the balancing rules.

## GST registration on an entity

Set these on `entities.create`:

| Field                    | Notes                                                                                                                  |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------- |
| `isGstRegistered`        | `true` if the business is registered for GST. Without it, every account defaults to the "No GST" code.                 |
| `gstNumber`              | New Zealand: the 9-digit GST number. Australia: the 11-digit ABN, which is checked against the ABN checksum.           |
| `gstPeriod`              | Months per GST period, as a string: `'1'`, `'2'`, `'3'`, `'6'` or `'12'`. New Zealand files one-, two- or six-monthly. |
| `gstFilingStartDate`     | `YYYY-MM-DD`, the start of the first period Prosaic should prepare.                                                    |
| `areGstReportsAutomated` | `true` to have Prosaic create the entity's GST returns (New Zealand only). Needs all four fields above.                |

The entity response reports these back as `isGstRegistered`, `gstPeriodMonths` and `gstBasis`.

## NZ GST returns

For a New Zealand entity with `areGstReportsAutomated` on, Prosaic creates a GST return for each period from the filing start date. An accountant reviews, finalises and files each return with IRD in the Prosaic app. The API reads returns; it does not finalise or file them.

| Endpoint                                             | SDK                                 |
| ---------------------------------------------------- | ----------------------------------- |
| `GET /gst-returns`                                   | `gstReturns.list` (whole workspace) |
| `GET /entities/{entityId}/gst-returns`               | `gstReturns.listForEntity`          |
| `GET /entities/{entityId}/gst-returns/{gstReturnId}` | `gstReturns.retrieve`               |

```ts
for await (const gstReturn of prosaic.gstReturns.listForEntity(entityId, {
  status: ['draft', 'finalised'],
})) {
  console.log(
    gstReturn.name,
    gstReturn.dateFrom,
    gstReturn.dateTo,
    gstReturn.status,
  );
}

const { data: detail } = await prosaic.gstReturns.retrieve(
  entityId,
  gstReturnId,
);
console.log(
  detail.amountsSource,
  detail.totalGstCollected,
  detail.totalGstCredit,
);
```

- **Statuses:** `draft`, `finalised`, `filed`, `filed_externally`, `accepted`, `rejected`, `awaiting_payment` and `completed`. Filter with `status`, which can repeat or be comma-separated.
- **Box amounts.** `retrieve` returns IRD boxes 5 to 15. For a `draft`, they are calculated live from the posted journals and move as the books change (`amountsSource: 'calculated'`). For every other status, they come from the snapshot taken at finalisation (`'finalised'`).
- **Lists** carry each return's period, due date, `netGstPosition` (Box 15) and a count of unreconciled bank transactions. `netGstPosition` is `null` until the return has been calculated.
- **Dates** (`dateFrom`, `dateTo`, `dueDate`) are New Zealand calendar days.
- Drafts for periods that have not started are hidden unless you pass `includeFutureDrafts: 'true'`.
- GST return amounts are numbers, unlike most amounts in the API.

## Australia today

Australian entities have:

- the AU GST codes above, at 10%;
- the Standard AU Business Template, carrying AU codes;
- AUD as their currency;
- a financial year starting 1 July, with reports cut at midnight Sydney time;
- the ABN as their GST number.

Not yet available: BAS preparation and ATO lodgement, and AU bank feeds. GST returns are not created for Australian entities, so the GST return endpoints return nothing for them. AU bank lines can be imported through the API with `bankAccounts.createWithTransactions` and `bankAccounts.importTransactions` in the meantime.
