---
title: "KiwiSaver balance projected to retirement"
method: POST
path: "/v1/kiwisaver"
tags: ["Calculators"]
---

# KiwiSaver balance projected to retirement

`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`

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.

## Request body

- KiwiSaverRequest
  - `current_balance` number, required: Starting balance in NZD
  - `current_age` integer, required: Age now, in whole years.
  - `retirement_age` integer: Age the projection runs to. 65 is when NZ Super starts.
  - `annual_income` number: Gross annual salary in NZD, before tax.
  - `income_growth_pct` number: Assumed pay rise each year, as a percentage.
  - `employee_rate_pct` number: Your contribution rate. NZ options are 3, 3.5, 4, 6, 8 or 10.
  - `employer_rate_pct` number: Employer contribution rate. The compulsory minimum is 3.5% from 1 April 2026.
  - `voluntary_amount` number: 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_pct` number, nullable: Annual return to assume. Required if fund_type is 'Custom'.
  - `pir_rate_pct` number: Prescribed Investor Rate as a percentage: 10.5, 17.5 or 28.
  - `annual_fee_pct` number: Total annual fund fee, as a percentage of balance.
  - `inflation_pct` number: Assumed inflation, used only for the today's-dollars figure.
  - `switch_fund_at_age` integer, 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_pct` number, nullable: Return after switching. Required if switch_to_fund is 'Custom'.

## Response `200`

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

- KiwiSaverResponse
  - `result` KiwiSaverResult, required
    - `final_balance` number, required: Projected balance at retirement age, in future dollars.
    - `final_balance_real_todays_dollars` number, required: The same balance deflated by inflation_pct. This is the figure to compare against what things cost today.
    - `total_employee_contributions` number, required: Everything you contribute from salary.
    - `total_employer_contributions_net` number, required: Employer contributions after ESCT is deducted.
    - `total_voluntary_contributions` number, required: Everything contributed on top of salary.
    - `total_government_contributions` number, required: Total government contribution over the projection.
    - `total_investment_gains_net` number, required: Investment returns after tax at your PIR.
    - `total_fees_paid` number, required: Total fund fees over the projection.
    - `years_to_retirement` number, required: Years from current_age to retirement_age.
    - `months_projected` integer, required: Number of monthly steps the projection ran.
    - `final_annual_income` number, required: Salary in the final year, after income_growth_pct compounding.
    - `inputs` object, required: The inputs used, echoed back with defaults filled in.
  - `disclaimer` string, required: Scope and limits of this projection.

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