---
title: "The right New Zealand tax code, and why"
method: POST
path: "/v1/tax-code"
tags: ["Calculators"]
---

# The right New Zealand tax code, and why

`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`

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.

## Request body

- TaxCodeRequest
  - `annual_income` number, required: Income from THIS job, before tax.
  - `job_type` 'primary' | 'secondary': 'primary' for the main job, 'secondary' for any other.
  - `total_income_all_jobs` number, nullable: Total across every job. A secondary code is chosen on the TOTAL, not on this job alone.
  - `has_student_loan` boolean: Whether a student loan is being repaid.
  - `receives_wff_benefit_or_super` boolean: Working for Families, a main benefit or NZ Super. Any of these removes IETC eligibility.

## Response `200`

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

- TaxCodeResponse
  - `result` TaxCodeResultModel, required
    - `tax_code` string, required: The code to put on the IR330.
    - `job_type` string, required: Which kind of job this is.
    - `description` string, required: Short label for the code.
    - `explanation` string, required: Why this code and not another.
    - `flat_rate` number, nullable: For a secondary code, the flat rate applied to the whole of this job's income.
    - `ietc_eligible` boolean, required: Whether the Independent Earner Tax Credit applies.
    - `warnings` string[], required: Anything that looks wrong in the inputs.
    - `inputs` object, required: The inputs used, with defaults filled in.
  - `disclaimer` string, required: Scope and limits of this guidance.

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/calculate/apis/calculate-co-nz-api.md) · [All operations](https://skmtc.dev/calculate/apis/calculate-co-nz-api/llms.txt) · [OpenAPI document](https://skmtc.dev/calculate/apis/calculate-co-nz-api/revisions/aa59a8e76614?raw)