# Retirement calculator with pension and spending stages documentation

Inputs, formulas, assumptions and API/MCP examples for the retirement calculator with pension and spending stages. Reproduce a calculation and cite its sources.

Canonical calculator: https://klarfort.com/tools/retirement-calculator/
Content updated: 2026-09-07
Assumptions reviewed: 2026-09-07

## Overview
Model saving before retirement and withdrawals afterward within one monthly timeline. Enter pension income and optional life stages to represent periods with different retirement spending or other income.

Compare the constant-return projection with simulations that vary monthly returns. The model includes your fee, tax and inflation assumptions and reports withdrawal shortfalls as well as ending balances.

## How to use
1. Enter the starting balance, projection length, monthly saving before retirement and the first retirement month.
2. Enter retirement spending, monthly pension and its starting month, with amounts in today's money.
3. Add any non-overlapping life stages using inclusive month ranges, spending and other monthly income.
4. Set return, volatility, fee, tax, inflation and simulation settings, then calculate and review balances and shortfalls.

## Understanding the result
The headline is the constant-return ending balance. Real value expresses it in starting-period purchasing power. The percentile results summarize simulated nominal ending balances.

A simulated path succeeds only when every withdrawal is funded and every month ends with a positive balance. The success percentage describes this model and does not estimate your actual future probability of retirement success.

## Questions
### How are retirement and pension months counted?
Month one is the first projection month. Contributions continue before the entered retirement month; retirement spending begins in that month. Pension income begins in its entered month when the model is in retirement.

### What does a life stage replace?
During retirement, an active stage replaces the base monthly spending and adds its entered income alongside any pension. Stage start and end months are both included, and stages cannot overlap.

### Why can the order of investment returns matter?
Withdrawals reduce the amount left invested after a loss, so later gains may recover less money. The simulations vary monthly returns to illustrate this sequence effect under the entered assumptions.

## Default worked example
Projected value: 0 USD. Retirement projection with staged expenses, entered pension income and simulated sequence risk. Assumptions as of 2026-09-07.

## Formula
Before retirement, contribute monthly. During retirement, withdraw max(inflated expenses − indexed pension − indexed stage income, 0), or invest the surplus. Apply monthly returns, asset fees and tax on positive gains.

- Contributions are made at the beginning of each month. Annual returns are effective rates converted to monthly compound factors. All figures use one entered currency.
- Retirement and pension months are one-based and inclusive. Stage ranges cannot overlap. All retirement expense, pension and stage income amounts are in today's money and grow with the entered inflation rate.
- Success requires no withdrawal shortfall and a positive balance at every month end, including the final month. Zero-volatility simulations match the deterministic path. Return draws are independent lognormal samples; the model does not estimate actual future probabilities.

## Inputs
- currency: Currency; default "USD"
- principal: Starting balance; default 10000
- months: Projection months; default 12
- monthlyContribution: Monthly contribution; default 0
- annualReturn: Annual return (%); default 0
- retirementMonth: First retirement month; default 1
- monthlyExpenses: Monthly retirement spending; default 1000
- pensionStartMonth: First pension month; default 1
- monthlyPension: Monthly pension in today's money; default 0
- annualVolatility: Annual volatility (%); default 0
- annualFee: Annual asset fee (%); default 0
- taxRate: Tax on positive gains (%); default 0
- inflationRate: Annual inflation (%); default 0
- paths: Simulation paths; default 1000
- seed: Leave empty to derive a reproducible seed from your inputs, or enter 16 hexadecimal characters.; default ""
- lifeStages: Optional nonoverlapping inclusive month ranges overriding retirement spending and adding other monthly income. Each amount is expressed in today's money.; default []

## Interfaces
Input schema: https://klarfort.com/tools/retirement-calculator/schema.json
Worked request and response: https://klarfort.com/tools/retirement-calculator/examples.json
Public table: https://klarfort.com/tools/retirement-calculator/table.json
JSON API: POST https://klarfort.com/tools/api/v1/retirement-calculator
MCP endpoint: POST https://klarfort.com/tools/mcp
MCP tool name: retirement-calculator

## JSON request body
```json
{
  "currency": "USD",
  "principal": 10000,
  "months": 12,
  "monthlyContribution": 0,
  "annualReturn": 0,
  "retirementMonth": 1,
  "monthlyExpenses": 1000,
  "pensionStartMonth": 1,
  "monthlyPension": 0,
  "annualVolatility": 0,
  "annualFee": 0,
  "taxRate": 0,
  "inflationRate": 0,
  "paths": 1000,
  "seed": "bcedbf7e441e38da",
  "lifeStages": []
}
```

## Usage and credit
Free for personal, commercial and any other lawful use with credit to KlarFort at https://klarfort.com/. Third-party data terms still apply.

Computed with KlarFort Calculators, https://klarfort.com/

Place a visible credit near the reused material or in the credits for your work or integration. One clear credit per work or integration is sufficient; no separate credit per API request is required. The credit_url field contains the homepage. The citation_url field is an optional calculator reference. Full permission: https://klarfort.com/tools/docs/license/

## Sources
KlarFort calculation methodology: https://klarfort.com/tools/methodology/ (1)