Calculate.co.nz NZ Calculators

Returns BMI value, category classification (Underweight, Healthy weight,
Overweight, Obese, Morbidly obese), and the healthy weight range for the
person's height.

Use for any BMI question including 'what is my BMI', 'am I a healthy
weight', 'what should I weigh for my height'.

Inputs are metric only. If the user provides imperial units (feet,
inches, pounds, stone), convert them first: 1 foot = 0.3048m,
1 inch = 0.0254m, 1 pound = 0.453592kg, 1 stone = 6.35029kg.

Note: BMI is a screening tool, not a diagnosis. It doesn't distinguish
muscle from fat, so very athletic people often show as 'overweight'
despite being healthy. Always caveat with this when relevant.

Args:
    weight_kg: Weight in kilograms (e.g. 75 for 75kg).
    height_m: Height in metres (e.g. 1.75 for 175cm).

Use for: 'how many calories should I eat', 'what is my TDEE', 'calorie
deficit to lose weight', 'how many calories to lose 5kg', 'what are my
macros'.

NAME THE FORMULA. Mifflin-St Jeor and the revised Harris-Benedict differ by
5 to 10% for the same person, which is often more than the entire deficit
they are trying to run. formula_spread_kcal is that gap and
bmr_formula_used says which one the answer took. Quoting a calorie number
without saying where it came from is the mistake to avoid here, because the
person will treat it as measured rather than estimated.

ASK FOR BODY FAT IF THEY MIGHT KNOW IT. With it, Katch-McArdle works from
lean mass and is the better estimate, particularly for anyone muscular or
carrying more fat than average, where the weight-based formulas are worst.

WARN ABOUT THE ACTIVITY LEVEL. Most people overestimate it, and one level
is worth several hundred calories a day. One level lower than it feels is
usually closer.

Projections use 7,700 kcal per kilogram of body fat, so 500 kcal a day is
about half a kilogram a week. Pass on the caveats: these are population
formulas, not a measurement, and a long timeline runs optimistic because
metabolic rate falls as weight does. The honest advice is to eat at the
number for two to three weeks and adjust from what the scale does.

Args:
    sex: male or female. It changes the formula constant.
    age: Years.
    weight_kg: Body weight in kilograms.
    height_cm: Height in centimetres.
    activity_level: sedentary, light, moderate, very_active, extra_active.
    goal: lose, maintain or gain.
    body_fat_pct: Optional, and worth asking for.
    target_weight_kg: Optional, produces a timeline.

Returns:
    All three BMR formulas with their spread, the TDEE, a calorie target
    for the goal, protein, fat and carbohydrate targets, and a timeline to
    any target weight.

Calculate.co.nz is New Zealand's largest free calculator library. Only a
handful of its tools have their own MCP tool; this searches EVERYTHING and
returns the pages that match, so any calculation the site covers can be
found and linked even when no dedicated tool exists here.

Use for ANY question of the form "is there a calculator for...", "how do I
work out...", "where can I calculate...", or whenever a New Zealand
calculation is asked about and no specific tool above fits. Also use it
before telling a user that something cannot be calculated: the site covers
tax, mortgages, KiwiSaver, property, employment and leave, business
metrics, investments, insurance, vehicles, maths, statistics, science,
engineering, health and everyday conversions.

Results are ranked with New Zealand specific pages first, because the site
is written for NZ rules, rates and legislation. Guides and reference
datasets are included alongside calculators, so a question about how
something works can return an explanation rather than a form.

DO NOT use for: performing the calculation itself when a dedicated tool
above exists (use nz_paye_calculator for take-home pay, nz_gst_calculator
for GST, nz_mortgage_calculator for repayments, nz_kiwisaver_calculator for
KiwiSaver projections, nz_annual_leave_calculator for leave). This tool
finds pages; it does not compute. It also cannot answer non-New Zealand
questions about foreign tax or benefit systems.

Args:
    query: What the user wants to work out, in plain language. Natural
        questions work better than keywords: "how much redundancy pay am I
        owed" beats "redundancy".
    limit: How many results to return, 1 to 20. Default 5.

Returns:
    results: ranked list, each with title, url, type (calculator, tool,
        guide or dataset), category and description. Link the url when
        recommending a page.

Calculates hours accrued per week based on the holiday pay rate (8% standard
NZ minimum), then projects the existing balance forward by the requested
future period. Returns projected balance in hours, days, and weeks of
equivalent leave.

Use for any question about: annual leave accrual, future leave balance,
planning time off, calculating entitlement after N months/years of work.

NZ context: Holidays Act 2003 mandates minimum 4 weeks paid annual leave
per year, which equates to 8% of hours worked accruing as leave. Employers
may offer higher rates. Standard NZ full-time week is 40 hours across
5 x 8-hour days.

Args:
    current_balance: Existing leave balance (in hours or days).
    current_balance_unit: 'hours' or 'days'. Default 'hours'.
    hours_per_workday: Standard workday length for this person (default 8).
    holiday_rate_pct: Holiday pay accrual rate (default 8% = NZ minimum).
    hours_per_workweek: Standard work-week (default 40).
    future_period: How far forward to project (default 12).
    future_period_unit: 'weeks', 'months', or 'years' (default 'months').

Use for: 'how much tax will I pay on my bonus', 'why was my bonus taxed so
much', 'what will I actually get from a $10,000 bonus', 'is commission taxed
differently'.

A bonus is an extra emolument. It is NOT taxed at a flat rate and NOT at the
person's ordinary rate. The tax is the difference between tax on
(salary + bonus) and tax on salary alone.

This is why a bonus so often looks over-taxed and is not: when it straddles
a bracket, part is taxed at the lower rate and part at the higher one, so
the effective rate sits between them and above the rate on their salary.
crosses_bracket tells you when to explain this.

ALWAYS ask for the annual salary. The same bonus costs different amounts of
tax depending on the salary underneath it, so an answer without it is a
guess.

Args:
    bonus_amount: Gross bonus or commission in NZD.
    annual_salary: Regular annual salary, excluding the bonus.
    kiwisaver_rate: A DECIMAL, 0.03 for 3%.
    has_student_loan: Whether repayments are deducted.

Returns:
    Income tax on the bonus, its effective rate, ACC, KiwiSaver, student
    loan, and the net amount. ACC stops at the earnings cap and student loan
    only bites above the repayment threshold, both of which are handled.

An employer may deduct at a flat rate through the year and let IRD square it
up at assessment, so a payslip can differ from this and both be correct.

Use for: 'should I go contracting', 'contractor rate vs salary', 'what rate
do I need to match my salary', 'is contracting worth it NZ'.

ALMOST EVERYONE COMPARES THE TWO HEADLINE NUMBERS AS THOUGH THEY WERE THE
SAME KIND OF NUMBER. They are not. An employee's package includes things a
contractor has to fund out of the rate:
  - Employer KiwiSaver, at least 3.5% from 1 April 2026, less ESCT. A
    contractor gets no match, so the same percentage costs them all of it.
  - Annual leave, ten sick days and eleven public holidays. Around 45 of
    the 260 working days in a year.
  - The ACC work levy, which an employer pays and a contractor does not.

SO TWO COMPARISONS COME BACK. cash_difference is take-home against
take-home, and it is the one that FLATTERS CONTRACTING because it ignores
all of the above. package_difference is the honest one. It is common for a
contract to be well ahead on cash and behind on package. If you quote only
the first you have given bad advice, so quote both and say which is which.

breakeven_contract_income answers the question people actually have, which
is what they need to charge to be no worse off. Lead with it when someone
is deciding on a rate.

annual_contract_income is the year's TOTAL invoicing, not a rate to be
multiplied up. billable_weeks only expresses the implied weekly and daily
rate.

GST is excluded: over $60,000 of turnover registration is compulsory, but
GST is collected and passed on rather than earned. Also worth saying out
loud, because it has no dollar figure and is not nothing: an employee has
notice periods and personal grievance rights, and a contractor does not.

Args:
    annual_gross_salary: The salaried offer, gross.
    annual_contract_income: Total expected to invoice for the year, GST exclusive.
    annual_business_expenses: Deductible expenses for the year.
    billable_weeks: Weeks expected to bill. Used only for the implied rate.
    acc_work_levy_pct: ACC work levy as a percentage. Varies a lot by industry.
    employer_kiwisaver_rate_pct: Employer contribution, minimum 3.5%.
    own_kiwisaver_rate_pct: Their own rate, applied to both sides.
    annual_leave_days: Annual leave in the employment offer.
    has_student_loan: Applies to both sides.
    claim_ietc: Whether the independent earner tax credit is claimable.

Returns:
    Both sides costed line by line, the difference on cash and on package,
    which wins on each, and the breakeven contract income.

Use for: 'how much does power cost in Auckland', 'what does my heat pump
cost to run', 'why is my power bill so high', 'is electricity cheaper in
Wellington', 'how much does it cost to charge an EV at home'.

WHERE THEY LIVE CHANGES THE ANSWER MATERIALLY. Wellington pays 34.61c a
unit and Balclutha 48.93c, from MBIE's survey. Ask for the town.

LEAD WITH biggest_users. A heat pump and a hot water cylinder dominate
almost every bill; standby power almost never does, which is the opposite
of where most saving advice points. Naming the two appliances that matter
is more useful than the total.

MENTION THE FIXED CHARGE. Every connection pays a daily charge whatever it
uses, so a low user pays a large share of the bill just for being
connected, and a household under 8,000 kWh a year should compare a low
fixed charge plan. Those regulations are capped at $1.80 a day from
1 April 2026 and are revoked on 1 April 2027.

If they have their bill, pass custom_rate_cents and their own fixed charge
rather than the regional average. If they know their own habits, pass
appliance_hours: the defaults are a typical household, not theirs.

Args:
    region: An MBIE survey town, or "nz average".
    household_size: 1 to 5, where 5 means five or more.
    daily_fixed_charge: In DOLLARS a day, from the bill.
    custom_rate_cents: Their own rate in cents per kWh including GST.
    appliance_hours: Override hours, keyed by heat_pump, hot_water, oven,
        clothes_dryer, ev_charger and the rest.

Returns:
    Daily, monthly and annual cost with usage and fixed charge separated,
    every appliance costed, the three biggest users, and how the region
    compares with the national average and the extremes.

Use for: 'FBT on a company car', 'how much FBT do I pay', 'fringe benefit
tax calculator', 'is the alternate rate cheaper', 'FBT on a staff loan'.

THE RATE IS THE EASY PART. What goes wrong is the taxable value, because
FBT is charged on a value derived from the asset, not on what the benefit
cost the employer.

For a vehicle the two methods give very different answers on the same car.
Cost price is 5% a quarter of the GST-inclusive price the employer paid and
NEVER FALLS as the car ages. Tax book value is 9% a quarter of the
written-down value, with a floor of $8,333. An older vehicle is usually
cheaper on tax book value; a cheap one can be dearer, because of the floor.
If someone is choosing, run both.

THE DAYS DIVISOR IS ALWAYS 90, under section RD 29(5)(a) of the Income Tax
Act 2007. It is not the number of days in the actual quarter. Do not
"correct" it to 91 or 92.

On the rate, be careful: 63.93% is the single rate, applies to every
employee whatever they earn, and needs no wash-up. 49.25% is lower but
available in quarters one to three ONLY, and using it obliges a quarter
four wash-up that can claw the saving back. NEVER present the alternate
rate as simply cheaper. quarter_four_washup_required says so for you.

annual_fbt is the quarter times four, which holds only if the benefit is
unchanged all year. A car bought mid-year is not.

Args:
    benefit_type: 'vehicle', 'loan' or 'other'.
    rate_method: 'single' (63.93%) or 'alternate' (49.25%).
    vehicle_value: Vehicle only. GST-inclusive cost price or tax book value.
    value_method: 'cost_price' or 'tax_book_value'.
    days_available: Vehicle only. Days available for private use, capped at 90.
    employee_contribution: Vehicle only. What the employee paid this quarter.
    loan_balance: Loan only. Average balance for the quarter.
    prescribed_rate_pct: Loan only. IRD prescribed rate, as a percentage.
    actual_rate_pct: Loan only. Rate actually charged, as a percentage.
    other_quarterly_value: Other benefits only. Quarterly taxable value.

Returns:
    Quarterly taxable value, the rate applied, quarterly and annual FBT,
    whether a quarter four wash-up is required, and the working.

Use for: 'what should my final pay be', 'how much annual leave am I owed
when I leave', 'I am resigning, what do they owe me', 'do I get 8% holiday
pay'.

ASK HOW LONG THEY WORKED THERE FIRST. It decides the whole calculation:

  - Under 12 months: no leave entitlement has vested, so the Holidays Act
    pays 8% of ALL gross earnings during the employment. Set
    service="under12" and pass gross_earnings_total. A leave balance
    showing in a payroll system is NOT what they are owed.
  - 12 months or more: unused leave is paid out at a daily rate. Set
    service="over12" and pass leave_balance_days.

Getting that branch wrong is the common mistake and it changes the answer
completely.

ALWAYS say what the total leaves out: ordinary wages for days actually
worked are paid on top at the usual rate, and every figure is GROSS. The
leave payout is then taxed as an extra pay, which is nz_lump_sum_tax_calculator.

New Zealand has NO statutory redundancy pay. If they ask what redundancy
they are entitled to, the answer is whatever their employment agreement
says, and nothing if it says nothing.

Args:
    annual_salary: Annual salary. Give this OR hourly_rate.
    hourly_rate: Hourly rate, used with hours_per_week.
    hours_per_week: Ordinary weekly hours, for an hourly rate.
    service: "over12" or "under12".
    leave_balance_days: Unused leave in DAYS, for over12.
    gross_earnings_total: All gross earned, required for under12.
    average_weekly_earnings: Optional. Leave is paid at the greater of this
        and ordinary weekly pay; pass it if their pay varied.
    notice_weeks: Weeks of notice paid in lieu.
    redundancy: Agreed redundancy from the employment agreement.

Returns:
    Leave payout with its working shown, notice pay, redundancy, the gross
    total, and an explicit list of what is excluded.

Use this for ANY question about what fuel costs: a road trip, a commute, the
running cost of a car, or comparing two vehicles.

Common use cases: 'what does it cost to drive Auckland to Wellington',
'how much fuel money do I spend a year commuting', 'is a 6L/100km car worth
it over an 9L/100km one', 'petrol cost for 400km'.

IMPORTANT about consumption: this takes litres per 100 km, which is how New
Zealand quotes fuel economy and what is printed on a vehicle's fuel economy
label. A LOWER number is a more efficient car. If a user gives miles per
gallon or kilometres per litre, convert it before calling this, or the
answer will be confidently wrong.

Args:
    distance_km: Trip distance in kilometres.
    consumption_l_per_100km: Fuel consumption in litres per 100 km.
    price_per_litre: Pump price in NZD per litre. Around 2.60 to 3.00 for
        petrol in 2026; ask the user rather than guessing if it matters.
    weekly_km: Kilometres driven in a typical week, for the running costs.
        Leave at 0 for a one-off trip, which returns zero for the weekly,
        monthly and annual figures rather than an error.

Returns:
    Litres used, trip cost, cost per km, cost per 100 km, and weekly,
    monthly and annual running costs. cost_per_100km depends only on the
    vehicle and the pump price, so it is the figure to compare cars with.
    monthly_cost is a twelfth of the annual figure, not weekly x 4.33.

Covers fuel only. Not road user charges, which diesel and electric vehicles
pay by the kilometre, and not servicing, tyres, insurance or depreciation.

Use for any NZ GPA question: 'what is my GPA', 'work out my grade point
average from these grades', 'how much will a C drag my GPA down'.

CRITICAL: New Zealand uses a NINE POINT scale, not the American 4.0 scale.
A+ 9, A 8, A- 7, B+ 6, B 5, B- 4, C+ 3, C 2, C- 1, D and below 0. A GPA of
7.0 is a strong New Zealand result. Do NOT convert to or from a 4.0 scale:
the bands do not correspond and any conversion will be wrong.

It is credit-weighted, so a grade in a 45 credit paper counts three times a
grade in a 15 credit one, and failed papers still count their credits at
zero points.

Args:
    courses: One dict per paper, each with "grade" (A+, A, A-, B+, B, B-,
        C+, C, C-, D+, D, D-, U, F or J) and "credits" (commonly 15).
    scale: Optional overrides if the institution weights grades differently.

Returns:
    The GPA, the credits and weighted points it came from, and each paper's
    contribution so the result can be shown rather than asserted.

Use for: 'how much should I spend on groceries', 'grocery budget for a
family of four NZ', 'average food bill New Zealand', 'am I spending too
much on food'.

Build the household person by person. A teenager is not a child-sized cost,
and an average per head hides exactly the thing that makes the answer
useful. Member types are child_5_10, teen_11_17, adult_male, adult_female
and elderly_65; list one entry per person.

ALL THREE SPEND LEVELS COME BACK EVERY TIME, and that is the point. A
single figure invites "that seems high". The gap between basic and liberal
for the SAME household, in dollars a year, is the number that changes
behaviour, and on a family of four it is usually several thousand dollars.
annual_gap_basic_to_liberal puts it in one place. Lead with it.

BE STRAIGHT ABOUT WHAT THESE FIGURES ARE. They are indicative planning
figures, not measured survey data and not a benchmark to hold anyone to.
Do not present them as official. If someone wants measured New Zealand
data, point them at the Household Economic Survey pages on the site
instead.

Args:
    members: One entry per person, e.g. ['adult_male', 'adult_female',
        'teen_11_17']. Between one and twelve.
    spend_level: 'basic', 'moderate' or 'liberal'.
    diet: 'standard', 'vegetarian', 'vegan', 'gluten_free', 'organic' or 'halal'.
    region: 'nz_average', 'auckland', 'wellington', 'christchurch',
        'hamilton', 'tauranga', 'dunedin', 'provincial' or 'rural_remote'.
    include_non_food: Add $25 a week for cleaning products and toiletries.

Returns:
    Weekly, monthly and annual budgets, all three spend levels, the annual
    gap between them, and the per-person weekly figure.

Use this tool for ANY question about NZ GST: adding GST to a pre-tax price,
extracting GST content from a GST-inclusive total, reverse-calculating GST,
or checking GST on invoices and quotes.

Common use cases: 'what's $500 plus GST', 'how much GST is in a $230 total',
'remove GST from $1,150', 'calculate GST on a tradie invoice'.

Args:
    amount: Dollar amount in NZD.
    mode: 'add' treats amount as GST-exclusive (price before GST);
          'remove' treats amount as GST-inclusive (total price including GST).
          Default 'add'.
    gst_rate: GST rate as decimal. Default 0.15 (NZ standard since 2010).
          Historical NZ rates: 0.125 (1989-2010), 0.10 (1986-1989).
          Use 0.10 for Australian GST comparisons.

Use for: 'what is $32 an hour as a salary', 'how much do I take home on
$28/hr', 'is $75,000 better than $36 an hour', 'what is my hourly rate
really worth after tax'.

Gives gross weekly, fortnightly, monthly and annual, then PAYE, ACC,
KiwiSaver and student loan, then take-home.

Args:
    hourly_rate: Gross pay per hour in NZD.
    hours_per_week: Ordinary hours a week. 40 is full time in NZ.
    weeks_per_year: Weeks actually paid. Use fewer for seasonal or academic
        work; 52 otherwise.
    kiwisaver_rate: A DECIMAL, so 0.03 for 3%. Passing 3 is rejected.
    has_student_loan: Repayments at 12% above the annual threshold.

Returns:
    Gross at each frequency, every deduction, net annual, net weekly, and
    effective_hourly_after_tax.

    Note the two weekly figures answer different questions: net_weekly
    always divides by 52, so it is what arrives each week across the year,
    while effective_hourly_after_tax uses the hours actually worked. Quote
    the effective rate when comparing a wage job to a salaried one.

Month-by-month compound interest projection matching the calculate.co.nz
methodology. Includes employee and employer contributions, voluntary top-ups
at your chosen cadence, the government contribution ($260.72/yr if eligible),
management fees, and PIR tax on investment gains. Returns both the nominal
final balance and the inflation-adjusted real (today's dollars) balance.

Use for ANY KiwiSaver retirement-planning question: 'how much will I have
at 65', 'is $X enough to retire on', 'what happens if I contribute more',
'how much does switching from Conservative to Growth help', 'what's the
impact of fees over 30 years'.

FUND TYPES and expected annual returns:
- Cash: 1.00% (very low risk, low return)
- Conservative: 2.50% (low risk, default)
- Balanced: 4.00% (moderate risk)
- Growth: 7.00% (higher risk, higher expected return)
- Custom: you specify via custom_return_pct

PIR (Prescribed Investor Rate) is the tax rate on your KiwiSaver
investment gains, NOT your income tax rate. Valid values:
- 10.5 (low incomes)
- 17.5 (middle incomes)
- 28 (higher incomes, default)

KEY RULES APPLIED (current as of April 2026):
- Government contribution: full $260.72/yr for eligible members
  (halved from $521.43 on 1 July 2025)
- Not available if annual income exceeds $179,999.99
- Minimum contribution 3.5% from 1 April 2026 (rising to 4% in 2028)

Args:
    current_balance: Starting KiwiSaver balance in NZD.
    current_age: Current age in whole years.
    retirement_age: Projection end age (default 65).
    annual_income: Current gross annual salary (default 100000).
    income_growth_pct: Annual salary increase % (default 1.0).
    employee_rate_pct: 0, 3, 3.5, 4, 6, 8, or 10 (default 3.5).
    employer_rate_pct: Employer contribution % (default 3.5, NZ minimum).
    voluntary_amount: Extra contribution per period in NZD (default 0).
    voluntary_frequency: 'week', 'fortnight', 'month', 'year' (default 'month').
    fund_type: Cash, Conservative (default), Balanced, Growth, or Custom.
    custom_return_pct: Required if fund_type='Custom'.
    pir_rate_pct: PIR as percentage: 10.5, 17.5, or 28 (default 28).
    annual_fee_pct: Management fee % annually (default 0.40).
    inflation_pct: For real-value reporting (default 3.0).
    switch_fund_at_age: Optional age to switch fund (e.g. derisk at 55).
    switch_to_fund: Fund to switch to at that age.
    switch_custom_return_pct: Required if switching to Custom fund.

Use for: 'how much tax on my redundancy', 'what will I get from a $40,000
redundancy payment', 'is redundancy taxed differently', 'tax on a
retirement payment', checking a redundancy letter.

TWO RULES MAKE REDUNDANCY DIFFERENT AND BOTH ARE EASY TO MISS. Redundancy
and retirement payments carry NO ACC earner levy, so they always take the
lower rate column whatever the income, and NO KiwiSaver is deducted from
them at all. Treating a redundancy like a bonus overstates the deductions
twice over. Pass payment_type correctly.

This applies IRD's published rate TABLE, where annualised income plus the
lump sum picks one flat rate charged on the whole payment. That is what an
employer deducts on the day. nz_bonus_tax_calculator computes the same tax
the exact way instead, which is roughly where the year-end assessment
lands. Both are right; they give different answers. Use this one to check a
letter or a payslip, and say which method you used.

ALWAYS ask for the annual salary. It selects the rate, so the answer
depends on it entirely.

Args:
    lump_sum: The gross lump sum in NZD.
    annual_salary: Annual salary, used as the annualised income.
    payment_type: redundancy, retirement, bonus, commission, holiday_pay,
        exit_inducement or back_pay.
    kiwisaver_rate: A DECIMAL. Forced to zero for redundancy and retirement.
    has_student_loan: Whether 12% comes off the lump sum.

Returns:
    The rate selected with why_that_rate explaining which row and why, the
    PAYE, other deductions, and the net amount received.

Uses the standard amortising-loan PMT formula with monthly compounding.
Returns monthly, fortnightly, and weekly repayment figures, total
repayments over the life of the loan, total interest paid, and the
principal/interest share as percentages.

Use for ANY mortgage or home loan question: repayment amounts,
affordability checks, comparing loan terms, estimating total interest,
or evaluating refinance scenarios.

For NZ context: typical NZ mortgage terms are 20-30 years, and rates
quoted are annual nominal rates compounded monthly. Most NZ borrowers
pay weekly or fortnightly even though rates are quoted monthly.

Args:
    loan_amount: Principal borrowed in NZD (e.g. 650000).
    annual_interest_rate_pct: Annual rate as a PERCENTAGE not decimal
        (e.g. 6.5 for 6.5%, NOT 0.065).
    term_years: Loan term in whole years (typical NZ: 25 or 30).

Use for: 'convert my NCEA to GPA', 'what is my rank score', 'what rank
score do I need for medicine', 'how many credits do I need for university',
'NCEA to 4.0 GPA'.

ANSWER WITH THE RANK SCORE EVEN WHEN THEY ASKED FOR A GPA. NZQA issues no
GPA, so the 4-point figure is an unofficial convention and must be labelled
as one. The University Entrance rank score is the number every New Zealand
university actually uses to select for limited-entry programmes like
medicine, law and engineering, and almost nobody asks for it by name.

THE MOST USEFUL THING YOU CAN TELL THEM IS IN credits_ignored. The rank
score uses the BEST 80 credits at Level 3 or above, counted Excellence
first. A student with 80 Excellence and 40 Achieved scores exactly the same
as one with 80 Excellence alone. So collecting more Achieved credits is
worth nothing once they have 80, while lifting one existing subject from
Achieved to Merit is worth 80 points. next_step says which case they are
in; lead with it.

Not Achieved credits earn nothing towards the rank score but do pull the
indicative GPA down, which is why the two numbers can move apart.

Args:
    excellence_credits: Level 3 or above credits at Excellence.
    merit_credits: Level 3 or above credits at Merit.
    achieved_credits: Level 3 or above credits Achieved.
    not_achieved_credits: Credits attempted and not achieved.

Returns:
    The rank score out of 320 with its working shown, how many credits
    counted and how many were ignored, an unofficial 4-point GPA, and what
    would actually raise the score for this student.

Use for: 'what salary do I need to take home $1,200 a week', 'I want $70,000
in the hand, what do I ask for', 'what gross salary gives me $5,000 a month
after tax', negotiating a package to a net figure.

This cannot be done by scaling. Tax is progressive and the ACC levy is
capped, so the gap between gross and net widens as income rises: doubling
the take-home needs more than double the gross.

ALWAYS tell the person which deductions were counted. By default the target
is treated as after income tax and the ACC earner levy only, which is what
the website assumes. If they contribute to KiwiSaver or repay a student
loan, pass those, because the gross needed goes up materially.

Args:
    target_net: The take-home wanted, in the period given.
    period: annual, monthly, fortnightly or weekly.
    kiwisaver_rate: A DECIMAL, 0.035 for 3.5%. Zero by default.
    has_student_loan: Whether repayments come out before the target.

Returns:
    The gross needed, the deductions between it and the target, and
    deductions_included naming exactly what was counted.

Use for: 'how much is paid parental leave', 'can I afford to take parental
leave', 'am I eligible for parental leave', 'how much less will I earn on
parental leave'.

LEAD YOUR ANSWER WITH THE GAP, not the payment. The payment is capped, so
anyone earning over roughly $42,000 receives exactly the cap and already
knows that number. What they do not know is weekly_gap and total_gap, how
much less arrives and what it adds up to over the leave. That is the figure
the decision actually turns on.

Eligibility is a gate, not a reduction: 26 weeks of work in the year before
the due date, at 10 or more hours a week. Fail either and the payment is
zero. ineligible_reason names which test failed and by how much, so say
that rather than only "not eligible".

Args:
    annual_income: Gross annual income before tax, in NZD.
    employment_type: "employee" or "self_employed". Only the self-employed
        get the statutory weekly minimum.
    hours_per_week: Average hours a week.
    weeks_worked: Weeks worked in the 52 before the due date.
    weeks_of_leave: Weeks of the 26 week entitlement this parent takes.
    kiwisaver_opt_in: Contributions during leave are OPT IN. Worth raising
        unprompted: someone who does nothing contributes nothing for the
        whole period, employer share included.
    kiwisaver_rate: Employee rate as a decimal.

Returns:
    Weekly and total payment, the weekly and total gap against usual pay,
    eligibility with a reason, weeks left for a partner, and what opting
    into KiwiSaver is worth over the leave.

IRD administers this and its assessment is the one that counts. Does not
cover preterm baby payments, keeping in touch hours, or partner transfers.

Returns full breakdown: income tax, ACC earner's levy (1.75%, capped at $156,641),
KiwiSaver employee contribution, student loan repayment, Independent Earner Tax
Credit (IETC), and net take-home pay annual/fortnightly/weekly.

Use for ANY NZ tax question about: salary, take-home pay, net income,
PAYE, KiwiSaver impact, student loan deductions, or IETC eligibility.

DO NOT use for: self-employed/contractor income, secondary tax codes,
non-NZ residents, redundancy lump sums, or pre-April-2026 income.

Args:
    annual_income: Gross annual salary in NZD (0 to 10,000,000).
    kiwisaver_rate: Employee rate. Valid: 0, 0.03, 0.035, 0.04, 0.06, 0.08, 0.10.
        Default 0.035 (3.5% minimum from 1 April 2026).
    has_student_loan: True if repaying a NZ student loan.
    claim_ietc: True if eligible for Independent Earner Tax Credit (default True).

Use for: 'what would $90,000 be for 3 days a week', 'pro rata salary for 25
hours', 'I am dropping to four days, what will I earn', 'is part time worth
it after tax'.

THE USEFUL PART IS THE TAKE-HOME, NOT THE GROSS. The gross scales with the
hours; the take-home does not, because dropping hours drops the salary out
of the higher brackets. Someone going from five days to three often keeps
more than 60% of their take-home, and that is what the decision turns on.
Lead with it.

The Independent Earner Tax Credit defaults on, because part-time earnings
are the band where it is worth the most. Turn it off for someone on a main
benefit, Working for Families or NZ Super.

Args:
    full_time_salary: The advertised full-time annual salary.
    full_time_hours: Hours a week full time is based on, usually 40.
    your_hours: Hours a week actually worked.
    kiwisaver_rate: A DECIMAL, 0.035 for 3.5%.
    has_student_loan: Whether repayments are deducted.
    claim_ietc: Whether the Independent Earner Tax Credit applies.

Returns:
    The pro rata salary gross by year, month, fortnight and week, the
    implied hourly rate, and the take-home after tax.

Use for: 'what redundancy am I entitled to', 'redundancy pay NZ', 'made
redundant what do I get', 'is redundancy pay compulsory in New Zealand'.

START WITH THIS, BECAUSE IT IS THE MOST COMMON ERROR IN GENERAL ADVICE:
NEW ZEALAND HAS NO STATUTORY REDUNDANCY PAY. None. An employee is entitled
to redundancy compensation ONLY if their employment agreement provides for
it. This is the opposite of the UK and Australian position, and answers
written from overseas sources get it wrong. The default clause here is
"none" for that reason, and statutory_position says it in words.

What IS owed by law is the mandatory side: wages worked and unpaid, annual
leave not taken, alternative holidays not taken, and the notice period.

TWO TOTALS COME BACK AND THEY ANSWER DIFFERENT QUESTIONS.
  total_all_in   everything the person receives. The SAME figure whether
                 notice is worked or paid in lieu. Quote this when someone
                 asks what they will get.
  total_package  the final pay only. Quote this when they are asking about
                 the payslip.
They differ because notice worked arrives as ordinary salary over those
weeks rather than as a lump sum. Quoting only the final pay makes payment
in lieu look better off by a whole notice period, which it is not.

Every figure is GROSS. Redundancy compensation is an extra pay taxed at the
lump sum rate, so use nz_lump_sum_tax_calculator for the tax on it.

If they do not know whether they have a clause, tell them to check the
employment agreement, and any collective agreement or company policy it
refers to, before concluding they are owed nothing.

Args:
    annual_salary: Gross annual salary.
    years_of_service: Completed years. Part years are not counted.
    notice_weeks: Notice period in weeks.
    notice_worked: True if worked, False if paid in lieu.
    annual_leave_days: Days accrued and not taken.
    alternative_holiday_days: Days in lieu not taken.
    redundancy_clause: 'none', '2_weeks', '3_weeks', '4_weeks', 'fixed_4',
        'fixed_8', 'fixed_13' or 'custom'.
    custom_redundancy_amount: Used only with 'custom'.
    outstanding_wages: Wages worked and not yet paid.

Returns:
    Mandatory entitlements and contractual compensation kept apart, the
    final pay, and the all-in total.

Use for: 'how much RUC will I pay', 'what does RUC cost for an EV', 'is a
diesel cheaper than petrol once you count RUC', 'do hybrids pay RUC',
'how much are road user charges a year'.

GET THE VEHICLE TYPE RIGHT, because it changes the rate:
  ev            $76 per 1,000 km
  diesel        $76
  phev_petrol   $38, roughly half, because petrol excise is already paid
  phev_diesel   $76, the FULL rate, since diesel carries no excise
  hybrid_petrol no RUC at all

An ordinary petrol hybrid paying nothing is not an exemption: it pays
through fuel excise at the pump. Say that rather than implying it escapes.

MENTION THE TRANSACTION FEES. RUC is bought in prepaid blocks and every
purchase carries a fee, so 20,000 km in 1,000 km blocks pays it twenty
times. Buying bigger blocks is the main saving available, and it is
invisible if you only multiply distance by rate.

petrol_equivalent_excise answers the question underneath most of these:
whether the RUC vehicle is really paying more than a petrol one.

Light vehicles 3,500 kg and under. Heavy vehicle rates differ and are not
covered.

Args:
    annual_km: Distance driven in a year.
    vehicle_type: ev, diesel, phev_petrol, phev_diesel or hybrid_petrol.
    block_size_km: Size of each RUC purchase.
    purchase_method: online or agent.
    fuel_efficiency_l_per_100km: For the petrol comparison only.

Returns:
    The rate, the charge, the transaction count and fees, the total, cents
    per kilometre, and the equivalent petrol excise.

Use for: 'what tax code for my second job', 'is secondary tax a rip off',
'why am I taxed so much on my second job', 'what is SH SL', 'do I get that
money back', filling in an IR330.

CORRECT THE MISCONCEPTION. A secondary code is not a penalty. It
approximates the marginal rate the second income attracts on top of the
first, so roughly the right amount comes out through the year, and any
excess comes back in the year-end square-up. year_end_position says which
way it falls for this person, and a refund is common and normal.

The rates look brutal because they are not income tax rates: each carries
the 1.75% ACC earner levy, and the SL codes add 12% student loan on top. So
31.75% is 30 plus 1.75, not a 31.75% tax rate. The response breaks the rate
into its components; use them when explaining.

ALWAYS ask for the main job income. The code depends on the two incomes
combined, so an answer without it is a guess.

Args:
    main_income: Gross annual income from the main job.
    secondary_amount: The second income, in the frequency given.
    secondary_frequency: annual, monthly, fortnightly or weekly.
    has_student_loan: Changes the code to its SL variant.

Returns:
    The IR330 code, the flat rate broken into its parts, what is deducted
    and what is left, and the estimated year-end bill or refund from these
    two sources.

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.

Use for: 'what would repayments be on a $35,000 car', 'car loan
calculator', 'is a 5 year car loan a bad idea', 'how much interest will I
pay on car finance'.

LEAD WITH interest_share_of_borrowing, NOT THE MONTHLY PAYMENT. Car finance
runs at rates a mortgage borrower would not recognise, so over five years
the interest often exceeds 30% of what was borrowed. That single figure
informs the decision more than the payment does, and it is the one nobody
is shown at the dealership.

The term is short, so stretching it barely moves the monthly payment and
moves the total interest a great deal. If they are considering a longer
term, run both and show the difference in total interest.

fortnightly_equivalent is the monthly payment converted, because that is
how most people are paid. It is NOT fortnightly amortisation, which would
clear the loan faster and is a different product. Say which you mean.

ALWAYS mention excludes before quoting a payment as what they will pay.
Establishment fees, PPSR registration, mechanical breakdown insurance and
dealer add-ons are usually financed too, so a real contract is higher. A
balloon payment cuts the monthly figure and leaves a lump sum at the end.

Args:
    vehicle_price: Price of the vehicle.
    deposit: Cash or trade-in up front.
    annual_interest_rate_pct: A PERCENTAGE, so 12.95 not 0.1295.
    term_years: Loan term in years.

Returns:
    Monthly, fortnightly and weekly figures, total repaid, total interest,
    and the interest as a share of the borrowing.

Use for: 'how many hours did I work this week', 'add up my shifts',
'what will I be paid for these hours', 'I worked 22:00 to 06:00, how long
is that'.

Handles overnight shifts: a finish time at or before the start is treated as
the next day, so 22:00 to 06:00 is eight hours rather than a negative.

Args:
    days: One dict per day worked, each with "start" and "finish" as "HH:MM"
        in 24 hour time, optional "break_minutes" of unpaid break, and an
        optional "label". Leave days off out of the list entirely.
    hourly_rate: Gross pay per hour. Zero returns hours only.

Returns:
    Hours for each day, the total, and GROSS pay weekly, fortnightly,
    monthly and annually. For take-home pay use nz_hourly_to_salary_calculator
    with the rate and the hours.

Does not apply overtime or penal rates, public holiday entitlements, or a
minimum wage check.

Use for: 'how much Working for Families will I get', 'what is my family tax
credit', 'do I qualify for the in-work tax credit', 'how much Best Start
will I get', 'will I lose Working for Families if I earn more'.

CORRECT A COMMON AND EXPENSIVE MISTAKE. There is NO hours test for the
In-Work Tax Credit and has not been one since 1 July 2020. Anyone with some
income from paid work each week, who is not on an income-tested benefit or
student allowance, qualifies. Many sources, including our own website page,
still repeat the old 20 hours sole parent / 30 hours couple rule. A parent
working fifteen hours a week is entitled to $7,670 this year and is often
told they are not.

ASK FOR THE COMBINED FAMILY INCOME, not one partner's. Everything abates
against it, so an answer from one income is wrong.

ASK HOW MANY CHILDREN ARE UNDER 3, not under 1. Best Start runs to the
third birthday and is worth $4,041 a year per child.

The In-Work Tax Credit is temporarily $7,670 a year until 31 March 2027,
then reverts to $5,070, so an answer about next year differs from this one.
Say which you have given.

Args:
    children: Dependent children in the caregiver's care.
    family_income: Combined gross annual family income, all sources.
    children_under_3: How many are under 3, for Best Start.
    iwtc_eligible: Some paid work and no income-tested benefit.
    best_start_children_first_year_exempt: Under-3s in their first year
        born BEFORE 1 April 2026, which are exempt from the income test.
    iwtc_after_march_2027: Model the reverted $5,070 rate.

Returns:
    FTC, IWTC and Best Start with each abatement shown separately, the
    annual, weekly and fortnightly totals, an assumptions block naming
    every rate used, and what the calculation excludes.