Calculators

The right New Zealand tax code, and why

Pick the correct tax code for an IR330.

The wrong code is one of the few payroll mistakes that costs money quietly all year, and there are two ways to get it wrong.

A SECONDARY code is chosen on TOTAL income across all jobs, not on what the second job pays. Someone earning $60,000 in a main job and $8,000 in a second one is ST, not SB. Choosing on the smaller figure under-taxes and produces a bill at year end. If total_income_all_jobs is left out, this endpoint falls back to this job's income and returns a warning saying the band is very likely wrong, rather than quietly producing the common mistake.

ME is not simply "M plus a credit". The Independent Earner Tax Credit, worth up to $520 a year, is withdrawn by receiving Working for Families, a main benefit or NZ Super, so someone inside the $24,000 to $70,000 band can still correctly be an M.

Add SL when a student loan is being repaid. On a secondary job the loan repayment is 12% of the gross with no threshold at all, because the repayment threshold belongs to the main job.

post/v1/tax-code

Request

  • Base URL: https://api.calculate.co.nz
  • URL: https://api.calculate.co.nz/v1/tax-code
  • Auth: API key in header X-API-Key

Request body

annual_incomenumber required

Income from THIS job, before tax.

job_type'primary' | 'secondary'

'primary' for the main job, 'secondary' for any other.

total_income_all_jobsnumber nullable

Total across every job. A secondary code is chosen on the TOTAL, not on this job alone.

has_student_loanboolean

Whether a student loan is being repaid.

receives_wff_benefit_or_superboolean

Working for Families, a main benefit or NZ Super. Any of these removes IETC eligibility.

Example request

{
  "annual_income": 8000,
  "has_student_loan": false,
  "job_type": "secondary",
  "receives_wff_benefit_or_super": false,
  "total_income_all_jobs": 68000
}

Response

The code for the IR330, with the reasoning and any warning.

disclaimerstring required

Scope and limits of this guidance.

Example response

{
  "disclaimer": "Guidance on the standard codes for an IR330. Special tax codes, non resident status and multiple secondary jobs are not covered. Inland Revenue's own tool is the authority. Not tax advice.",
  "result": {
    "description": "Secondary job at a 30.0% flat rate",
    "explanation": "SH applies because total income across all jobs of $68,000 falls in that band. The whole of this job's income is taxed at 30.0%, because the lower brackets are already used by the main job.",
    "flat_rate": 0.3,
    "ietc_eligible": false,
    "inputs": {
      "annual_income": 8000,
      "has_student_loan": false,
      "job_type": "secondary",
      "receives_wff_benefit_or_super": false,
      "total_income_all_jobs": 68000
    },
    "job_type": "secondary",
    "tax_code": "SH",
    "warnings": []
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.