Calculators

KiwiSaver balance projected to retirement

Project a KiwiSaver balance from now until retirement age.

Steps forward month by month, applying employee and employer contributions, the government contribution, investment returns taxed at your PIR, and fund fees. Contributions grow with income_growth_pct.

The result breaks the final balance into where it came from: your contributions, your employer contributions after ESCT, voluntary top-ups, the government contribution, investment gains, and fees paid. That breakdown is the point of the endpoint; a single final number tells you nothing about which lever to pull.

Read final_balance_real_todays_dollars before final_balance. Over thirty years inflation does more to the headline figure than most contribution decisions do, and the real figure is the one comparable to what things cost now.

Set fund_type or give custom_return_pct. To model de-risking near retirement, set switch_fund_at_age and switch_to_fund.

A projection on constant assumptions, not a forecast. Real returns vary, the rules change, and contribution histories have gaps.

post/v1/kiwisaver

Request

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

Request body

current_balancenumber required

Starting balance in NZD

current_ageinteger required

Age now, in whole years.

retirement_ageinteger

Age the projection runs to. 65 is when NZ Super starts.

annual_incomenumber

Gross annual salary in NZD, before tax.

income_growth_pctnumber

Assumed pay rise each year, as a percentage.

employee_rate_pctnumber

Your contribution rate. NZ options are 3, 3.5, 4, 6, 8 or 10.

employer_rate_pctnumber

Employer contribution rate. The compulsory minimum is 3.5% from 1 April 2026.

voluntary_amountnumber

Extra contribution on top of salary deductions, in NZD.

voluntary_frequency'week' | 'fortnight' | 'month' | 'year'

How often the voluntary amount is paid.

fund_type'Cash' | 'Conservative' | 'Balanced' | 'Growth' | 'Custom'

Fund risk profile, which sets the assumed return unless Custom.

custom_return_pctnumber nullable

Annual return to assume. Required if fund_type is 'Custom'.

pir_rate_pctnumber

Prescribed Investor Rate as a percentage: 10.5, 17.5 or 28.

annual_fee_pctnumber

Total annual fund fee, as a percentage of balance.

inflation_pctnumber

Assumed inflation, used only for the today's-dollars figure.

switch_fund_at_ageinteger nullable

Age to switch funds, for a de-risking plan. Omit for no switch.

switch_to_fund'Cash' | 'Conservative' | 'Balanced' | 'Growth' | 'Custom' nullable

Fund to switch into at switch_fund_at_age.

switch_custom_return_pctnumber nullable

Return after switching. Required if switch_to_fund is 'Custom'.

Example request

{
  "annual_income": 90000,
  "current_age": 35,
  "current_balance": 25000,
  "retirement_age": 65
}

Response

Projected balance, and where every dollar of it came from.

disclaimerstring required

Scope and limits of this projection.

Example response

{
  "disclaimer": "Projection only. Actual outcomes depend on market returns, fee changes, rule changes, and contribution history. Investment returns are assumed constant; real-world returns vary. Not financial advice.",
  "result": {
    "final_annual_income": 121306.38,
    "final_balance": 279905.19,
    "final_balance_real_todays_dollars": 115317.23,
    "inputs": {
      "annual_fee_pct": 0.4,
      "annual_income": 90000,
      "current_age": 35,
      "current_balance": 25000,
      "employee_rate_pct": 3.5,
      "employer_rate_pct": 3.5,
      "fund_type": "Conservative",
      "income_growth_pct": 1,
      "inflation_pct": 3,
      "pir_rate_pct": 28,
      "retirement_age": 65,
      "voluntary_amount": 0,
      "voluntary_frequency": "month"
    },
    "months_projected": 360,
    "total_employee_contributions": 109572.48,
    "total_employer_contributions_net": 78891.96,
    "total_fees_paid": 16622.3,
    "total_government_contributions": 7821.6,
    "total_investment_gains_net": 75241.42,
    "total_voluntary_contributions": 0,
    "years_to_retirement": 30
  }
}

Changes

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