---
title: "NZ income tax refund or bill for a year"
method: POST
path: "/v1/tax-refund"
tags: ["Calculators"]
---

# NZ income tax refund or bill for a year

`POST /v1/tax-refund`

## Request

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

Estimate a New Zealand tax refund, and show where it comes from.

A refund is simply what was deducted minus what was actually owed. PAYE
comes out of each pay as though that pay continued all year, so anything
that made the year uneven leaves too much deducted.

The two usual causes are both broken out in the response. `part_year_over_deducted`
is what a short year over-deducts, and is often the entire refund.
`secondary_over_deducted` is what a second job's flat code took beyond what
that income actually cost at your marginal rate. Both are already inside
`refund_or_bill` rather than being additional to it.

Give `paye_deducted` from your payslips or IRD summary for a real answer. If
you leave it out, it is estimated from `tax_code` and `months_worked`, which
needs nothing from IRD and is correspondingly rougher.

Say whether ACC is inside that figure. Most payslips lump the earner levy in
with PAYE, and it is not income tax, so counting it would invent a refund of
up to $2,741 that does not exist.

`refund_or_bill` is POSITIVE for a refund and NEGATIVE for tax owed. The
website shows the same number as a positive figure with a separate label, so
read `is_refund` rather than assuming.

The donations credit and the student loan square-up are returned but are NOT
in `refund_or_bill`, because IRD settles them separately.

2024-25 is approximate and says so: the thresholds moved part way through
that year, so blended rates apply.

Salary and wages only. Not self-employed or rental income, not Working for
Families, and IRD's own automatic assessment is the figure that counts.

## Request body

- TaxRefundRequest
  - `gross_income` number, required: Total gross income for the year, before tax, in NZD.
  - `tax_year` '2026-27' | '2025-26' | '2024-25' | '2023-24': Which year's rules to apply. 2024-25 is a composite year: the thresholds moved on 31 July 2024, so IRD blended rates apply and the result is approximate, which the response flags.
  - `paye_deducted` number, nullable: Total PAYE deducted across the whole year, from your payslips or IRD summary. Omit to estimate it from tax_code and months_worked instead, which is less accurate but needs nothing from IRD.
  - `acc_included_in_paye` boolean: Whether paye_deducted includes the ACC earner levy. Most payslips lump them together. ACC is not income tax, so leaving it in would invent a refund of up to $2,741 that does not exist.
  - `tax_code` 'M' | 'ME' | 'MSL' | 'SB' | 'S' | 'SH' | 'ST': Primary tax code. Only used when paye_deducted is omitted.
  - `months_worked` number: Months actually worked. This is often the whole refund: PAYE is deducted as though each pay continues all year, so a part year over-deducts.
  - `secondary_income` number: Income from a second job taxed on a secondary code.
  - `secondary_tax_code` 'SB' | 'S' | 'SH' | 'ST': The second job's tax code.
  - `donations` number: Donations to approved donee organisations during the year.
  - `student_loan_deducted` number, nullable: Student loan repayments deducted. Omit if there is no loan.
  - `ietc_eligible` boolean: Whether the Independent Earner Tax Credit applies. Set false for anyone on a main benefit, Working for Families or NZ Super.

## Response `200`

The refund or amount owing, and every part it is made of.

- TaxRefundResponse
  - `result` TaxRefundResult, required
    - `tax_year` string, required: The year's rules applied.
    - `tax_year_label` string, required: That year written the way IRD writes it.
    - `approximate` boolean, required: True for 2024-25, where blended rates make the answer approximate.
    - `gross_income` number, required: Gross income you sent.
    - `correct_tax` number, required: Income tax actually owed on that income for the year.
    - `ietc_credit` number, required: Independent Earner Tax Credit applied. Zero if not eligible or outside the band.
    - `net_tax_due` number, required: Tax owed after the IETC. Never below zero.
    - `acc_levy` number, required: ACC earner levy for the year, 1.75% of liable earnings up to the cap. Not income tax.
    - `paye_deducted` number, required: PAYE deducted, as given or as estimated.
    - `paye_credit` number, required: PAYE counting towards the tax bill, after any ACC has been taken out of it.
    - `refund_or_bill` number, required: POSITIVE is a refund owed to you, NEGATIVE is tax you owe. The website shows this as a positive number with a separate label, so compare against is_refund rather than the sign on screen.
    - `is_refund` boolean, required: True when money is owed to you.
    - `donations_claimed` number, required: Donations counted, capped at your income.
    - `donations_credit` number, required: A third of donations claimed. Paid separately by IRD on its own form, so it is NOT included in refund_or_bill.
    - `student_loan_due` number, required: 12% of income over the annual threshold.
    - `student_loan_deducted` number, required: Repayments actually deducted.
    - `student_loan_difference` number, required: Deducted less due. Positive means overpaid. Settled separately from income tax, so also not in refund_or_bill.
    - `secondary_income` number, required: Second job income counted.
    - `secondary_tax_paid` number, required: Flat tax taken on that income by its code.
    - `secondary_tax_true_cost` number, required: What that income actually cost in tax at your true marginal rate.
    - `secondary_over_deducted` number, required: How much the secondary code over-deducted. This is why a second job so often produces a refund, and it is already inside refund_or_bill rather than being extra.
    - `months_worked` number, required: Months worked, after clamping to between 0.5 and 12.
    - `part_year_over_deducted` number, required: How much extra came out because PAYE annualised a part year. Usually the largest single reason for a refund. Already inside refund_or_bill.
  - `disclaimer` string, required: Scope and limits of this estimate.

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