---
title: "Mortgage repayments and lifetime totals"
method: POST
path: "/v1/mortgage"
tags: ["Calculators"]
---

# Mortgage repayments and lifetime totals

`POST /v1/mortgage`

## Request

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

Calculate NZ mortgage repayments and what the loan costs over its term.

Uses the standard amortisation formula on a rate compounded monthly, which
is how NZ lenders quote.

The fortnightly and weekly figures are the monthly repayment divided by the
average number of fortnights (2.174) and weeks (4.348) in a month, matching
calculate.co.nz. They are the same annual amount paid more often, NOT an
accelerated schedule, so they do not shorten the term. Paying half the
monthly amount every fortnight is the accelerated version, and it is a
different calculation.

`annual_interest_rate_pct` is a percentage, so 5.99 rather than 0.0599.

Assumes one constant rate for the whole term. Real NZ mortgages are usually
fixed in one to five year tranches and re-fixed at whatever the rate is
then, so treat a 30 year total as an illustration of the shape rather than a
forecast.

## Request body

- MortgageRequest
  - `loan_amount` number, required: Principal borrowed in NZD
  - `annual_interest_rate_pct` number, required: Annual nominal rate as a percentage, e.g. 6.5
  - `term_years` integer, required: Loan term in years

## Response `200`

Repayments at three frequencies, plus total interest over the term.

- MortgageResponse
  - `result` MortgageResult, required
    - `loan_amount` number, required: Principal you sent, in NZD.
    - `annual_interest_rate_pct` number, required: Rate you sent, as a percentage.
    - `term_years` integer, required: Term you sent, in years.
    - `monthly_repayment` number, required: Repayment per month, the basis of the calculation.
    - `fortnightly_repayment` number, required: Monthly repayment divided by 2.174, the average fortnights in a month, which is how calculate.co.nz presents it. This is the same annual amount paid more often, NOT an accelerated schedule, so it does not shorten the term or reduce the interest below.
    - `weekly_repayment` number, required: Monthly repayment divided by 4.348, the average weeks in a month. Same caveat as fortnightly: paying weekly at this figure does not pay the loan off faster.
    - `total_repayments` number, required: Everything paid over the full term, on the monthly schedule. The fortnightly and weekly figures are restatements of it, so they do not produce a different total.
    - `total_interest_paid` number, required: Interest portion of the total.
    - `total_principal_paid` number, required: Principal portion, equal to the loan amount.
    - `principal_share_pct` number, required: Principal as a percentage of total repayments.
    - `interest_share_pct` number, required: Interest as a percentage of total repayments.
  - `disclaimer` string, required: Scope and limits of this calculation.

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