nz_tax_refund_calculator
Estimate a New Zealand income tax refund, or tax owed, for a year.
Use this for ANY question about a NZ tax refund or an end of year tax bill.
Common use cases: 'am I owed a tax refund', 'I only worked part of the year,
do I get money back', 'I had a second job on an S code, was I overtaxed',
'how much tax should I have paid on 62k'.
A refund is what was deducted minus what was actually owed. PAYE comes out of
each pay as though that pay continued all year, so the two usual causes of a
refund are a part year and a second job on a flat secondary code. Both are
broken out in the result, and both are already inside refund_or_bill rather
than additional to it.
ASK FOR THE PAYE FIGURE if you can. paye_deducted from payslips or an IRD
summary gives a real answer; leaving it out estimates it from the tax code
and months worked, which is much rougher. Also ask whether that figure
includes ACC, because most payslips lump the earner levy in with PAYE and it
is not income tax.
Args:
gross_income: Total gross income for the year, before tax, in NZD.
tax_year: 2026-27, 2025-26, 2024-25 or 2023-24. 2024-25 is approximate
because thresholds moved part way through it.
paye_deducted: Total PAYE deducted for the year. None to estimate it.
acc_included_in_paye: Whether ACC is inside that figure. Usually yes.
tax_code: M, ME, MSL, or a secondary code. Only used when estimating.
months_worked: Months actually worked. Often the whole reason for a refund.
secondary_income: Income from a second job on a secondary code.
secondary_tax_code: SB, S, SH or ST.
donations: Donations to approved donee organisations.
student_loan_deducted: Repayments deducted, or None for no loan.
ietc_eligible: False for a main benefit, Working for Families or NZ Super.
Returns:
refund_or_bill, POSITIVE for a refund owed to the person and NEGATIVE for
tax they owe, with is_refund saying which. Also the correct tax, the
IETC, ACC, and the part year and secondary components of the difference.
The donations credit and student loan square up are returned but are NOT
inside refund_or_bill, because IRD settles those separately.
Salary and wages only. IRD issues an automatic assessment for most people and
that figure is the one that counts.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| tax_code | No | M | |
| tax_year | No | 2026-27 | |
| donations | No | ||
| gross_income | Yes | ||
| ietc_eligible | No | ||
| months_worked | No | ||
| paye_deducted | No | ||
| secondary_income | No | ||
| secondary_tax_code | No | S | |
| acc_included_in_paye | No | ||
| student_loan_deducted | No |