Back to Docs

Tax in NZ and AU

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

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.

Tax codes

New Zealand (GST at 15%):

CodeNameRate
NZ_GST_15_INC15% GST on Income15%
NZ_GST_15_EXP15% GST on Expenses15%
NZ_GST_0_ZEROZero-rated GST0%
NZ_GST_0_NONENo GST0%

Australia (GST at 10%):

CodeNameRate
AU_GST_10_INCGST on Income10%
AU_GST_10_EXPGST on Expenses10%
AU_GST_0_EXPORTGST Free0%
AU_GST_0_INPUTInput Taxed0%
AU_GST_0_NONEBAS Excluded0%

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 has worked examples and the balancing rules.

GST registration on an entity

Set these on entities.create:

FieldNotes
isGstRegisteredtrue if the business is registered for GST. Without it, every account defaults to the "No GST" code.
gstNumberNew Zealand: the 9-digit GST number. Australia: the 11-digit ABN, which is checked against the ABN checksum.
gstPeriodMonths per GST period, as a string: '1', '2', '3', '6' or '12'. New Zealand files one-, two- or six-monthly.
gstFilingStartDateYYYY-MM-DD, the start of the first period Prosaic should prepare.
areGstReportsAutomatedtrue 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.

EndpointSDK
GET /gst-returnsgstReturns.list (whole workspace)
GET /entities/{entityId}/gst-returnsgstReturns.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.