---
title: "NZ paid parental leave payment and shortfall"
method: POST
path: "/v1/parental-leave"
tags: ["Calculators"]
---

# NZ paid parental leave payment and shortfall

`POST /v1/parental-leave`

## Request

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

New Zealand paid parental leave: what arrives, and what is missing.

LEAD WITH THE GAP. The payment is capped, so anyone earning above roughly
$42,000 receives exactly the cap and the useful figure is `weekly_gap`: how
much less than usual arrives each week, and `total_gap` across the leave.
Quoting only the payment answers the wrong question for most people.

Eligibility is a gate, not a reduction. It needs 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, and `ineligible_reason` names which test failed and by how
much rather than returning a bare zero.

A self-employed person is paid at least the statutory weekly minimum even
when their income works out lower. An employee gets no such floor.

KiwiSaver contributions during leave are OPT IN. Someone who does nothing
contributes nothing for the whole period, employer share included, so
`kiwisaver_total_over_leave` is what opting in is worth.

The 26 week entitlement is shareable, and `weeks_available_for_partner` is
what is left for the other parent.

## Request body

- ParentalLeaveRequest
  - `annual_income` number, required: Gross annual income before tax, in NZD.
  - `employment_type` 'employee' | 'self_employed': Only a self-employed person gets the statutory weekly minimum.
  - `hours_per_week` number: Average hours a week. Under 10 fails eligibility.
  - `weeks_worked` integer: Weeks worked in the 52 before the due date. Under 26 fails eligibility.
  - `weeks_of_leave` integer: Weeks of the 26 week entitlement taken. The balance goes to a partner.
  - `kiwisaver_opt_in` boolean: Contributions during leave are OPT IN. Doing nothing contributes nothing.
  - `kiwisaver_rate` number: Employee rate as a decimal.

## Response `200`

Weekly and total payment, and the gap against usual pay.

- ParentalLeaveResponse
  - `result` ParentalLeaveResult, required
    - `eligible` boolean, required: Whether both statutory tests are met.
    - `ineligible_reason` string, required: Which test failed, and by how much. Empty when eligible.
    - `annual_income` number, required: Income you sent.
    - `ordinary_weekly_pay` number, required: Usual weekly pay, income divided by 52.
    - `weekly_payment` number, required: Weekly parental leave payment. Zero if not eligible.
    - `fortnightly_payment` number, required: Twice the weekly payment.
    - `capped_at_maximum` boolean, required: True when usual pay exceeds the statutory cap.
    - `self_employed_minimum_applied` boolean, required: True when the self-employed floor lifted the payment.
    - `weeks_of_leave` integer, required: Weeks taken.
    - `weeks_available_for_partner` integer, required: The rest of the 26 week entitlement.
    - `total_payment` number, required: Payment across the whole leave.
    - `weekly_gap` number, required: Usual weekly pay less the payment. For anyone over about $42,000 this is the number that matters, not the payment itself.
    - `total_gap` number, required: The shortfall across the whole leave period.
    - `kiwisaver_opted_in` boolean, required: Whether contributions continue.
    - `kiwisaver_employee_weekly` number, required: Your weekly contribution, if opted in.
    - `kiwisaver_employer_weekly` number, required: Employer weekly contribution, if opted in.
    - `kiwisaver_total_over_leave` number, required: Both contributions across the leave.
  - `disclaimer` string, required: Scope and limits of this estimate.

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