Calculators

NZ income tax refund or bill for a year

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.

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

Request body

gross_incomenumber 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_deductednumber 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_payeboolean

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_workednumber

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_incomenumber

Income from a second job taxed on a secondary code.

secondary_tax_code'SB' | 'S' | 'SH' | 'ST'

The second job's tax code.

donationsnumber

Donations to approved donee organisations during the year.

student_loan_deductednumber nullable

Student loan repayments deducted. Omit if there is no loan.

ietc_eligibleboolean

Whether the Independent Earner Tax Credit applies. Set false for anyone on a main benefit, Working for Families or NZ Super.

Example request

{
  "acc_included_in_paye": true,
  "gross_income": 62000,
  "months_worked": 8,
  "paye_deducted": 12800,
  "tax_year": "2026-27"
}

Response

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

disclaimerstring required

Scope and limits of this estimate.

Example response

{
  "disclaimer": "Estimate only. IRD issues an automatic income tax assessment for most people and its figure is the one that counts. Salary and wages only: this does not cover self-employed or rental income, Working for Families, or losses carried forward. Not tax advice.",
  "result": {
    "acc_levy": 1085,
    "approximate": false,
    "correct_tax": 10820.5,
    "donations_claimed": 0,
    "donations_credit": 0,
    "gross_income": 62000,
    "ietc_credit": 520,
    "is_refund": true,
    "months_worked": 8,
    "net_tax_due": 10300.5,
    "part_year_over_deducted": 2891.17,
    "paye_credit": 11715,
    "paye_deducted": 12800,
    "refund_or_bill": 1414.5,
    "secondary_income": 0,
    "secondary_over_deducted": 0,
    "secondary_tax_paid": 0,
    "secondary_tax_true_cost": 0,
    "student_loan_deducted": 0,
    "student_loan_difference": 0,
    "student_loan_due": 0,
    "tax_year": "2026-27",
    "tax_year_label": "2026/27"
  }
}

Changes

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