---
title: "NZ take-home pay after PAYE"
method: POST
path: "/v1/paye"
tags: ["Calculators"]
---

# NZ take-home pay after PAYE

`POST /v1/paye`

## Request

- Base URL: `https://api.calculate.co.nz`
- URL: `https://api.calculate.co.nz/v1/paye`
- Auth: API key in header `X-API-Key`

Calculate NZ take-home pay for the current tax year.

Covers PAYE income tax across the progressive brackets, the ACC earners
levy, KiwiSaver, student loan repayments and the Independent Earner Tax
Credit. Salary and wages only.

Two things worth knowing before you display the result:

- `effective_tax_rate` counts income tax and ACC, not KiwiSaver or student
  loan, so it is not `total_deductions` over gross. KiwiSaver is your money
  and a student loan repays a debt; neither is tax.
- `assumptions` names the tax year and every rate used. Store it alongside
  any saved result, or you will not be able to explain the number after the
  next Budget.

Not covered: secondary tax codes, ESCT variation, non-resident status,
Working for Families, and self-employed income. Those need
`/v1/find-calculator`.

## Request body

- PAYERequest
  - `annual_income` number, required: Gross annual salary in NZD
  - `kiwisaver_rate` number: Employee KiwiSaver contribution rate. Valid values: 0 (opted out), 0.03, 0.035, 0.04, 0.06, 0.08, 0.10. Minimum rose to 3.5% from 1 April 2026 for new enrollees.
  - `has_student_loan` boolean: True if the person is repaying a NZ student loan
  - `claim_ietc` boolean: True if eligible for the Independent Earner Tax Credit. Set False for recipients of main benefits, Working for Families Tax Credits, NZ Super, or non-residents.

## Response `200`

Deductions, take-home pay, and the rates used.

- PAYEResponse
  - `result` PAYEResultBlock, required
    - `gross_annual` number, required: Salary before any deductions, in NZD.
    - `income_tax` number, required: PAYE income tax for the year, across the progressive brackets.
    - `acc_levy` number, required: ACC earners' levy, charged on income up to the annual maximum liable earnings. Separate from income tax.
    - `kiwisaver_employee` number, required: Your KiwiSaver contribution, deducted from gross pay. The employer contribution is not shown here because it does not affect take-home pay.
    - `student_loan` number, required: Student loan repayment on income above the threshold. Zero if not repaying.
    - `ietc_credit` number, required: Independent Earner Tax Credit applied, which reduces tax. Zero when claim_ietc is false or income is outside the eligible band.
    - `total_deductions` number, required: Income tax plus ACC plus KiwiSaver plus student loan, less any IETC.
    - `take_home_annual` number, required: Net pay for the year, gross less total deductions.
    - `take_home_fortnightly` number, required: Annual take-home divided by 26.
    - `take_home_weekly` number, required: Annual take-home divided by 52.
    - `effective_tax_rate` number, required: Income tax plus ACC levy, less any IETC, as a percentage of gross. KiwiSaver and student loan are deliberately excluded because they are not tax: one is your own savings and the other repays a debt. So this is NOT total_deductions divided by gross, and on the example below it is 23.5% where that figure would be 26.5%.
    - `marginal_tax_rate` number, required: Income tax rate on the next dollar earned, as a percentage.
  - `assumptions` Assumptions, required
    - `tax_year` string, required: NZ tax year the rules are taken from, e.g. 2026/27.
    - `kiwisaver_min_rate` number, required: Minimum employee contribution rate, as a decimal.
    - `acc_levy_rate` number, required: ACC earners' levy rate, as a decimal.
    - `student_loan_threshold` number, required: Annual income above which student loan repayments start, in NZD.
    - `student_loan_rate` number, required: Repayment rate on income above the threshold, as a decimal.
  - `disclaimer` string, required: Scope and limits of this calculation.

## 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)