---
title: "Weekly main benefit, abatement and Accommodation Supplement"
method: POST
path: "/v1/benefit-entitlement"
tags: ["Calculators"]
---

# Weekly main benefit, abatement and Accommodation Supplement

`POST /v1/benefit-entitlement`

## Request

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

Estimate a weekly main benefit and what goes with it.

Four things decide the answer and only the first is widely known:

  - The base rate, which depends on the benefit and the living situation.
  - Abatement. The first $160 a week of other income is free. Above that a
    sole parent loses 30c in the dollar to $250 and 70c after, and everyone
    else loses 70c from the start. This is the part people get wrong: they
    assume a dollar earned is a dollar lost, and for the first $160 it is
    not lost at all.
  - The Accommodation Supplement, which is 70% of housing costs ABOVE an
    entry threshold, not 70% of the rent. The threshold is 25% of the base
    rate for renters and boarders and 30% for owners, and only 62% of a
    board payment counts as a housing cost at all.
  - The Winter Energy Payment, 1 May to 1 October, which is only paid while
    some main benefit is still payable after abatement.

The rates are read from the published register rather than typed, and
`rate_source` returns which figure was used, when it was last verified
against the Work and Income tables, and when it next changes. Benefit rates
move every 1 April, so a cached answer given in May is wrong.

This is an estimate of the published rates, not an assessment. Entitlement
also depends on residency, relationship status, assets and obligations that
no calculator sees, so it will not match a Work and Income decision.

## Request body

- BenefitEntitlementRequest
  - `benefit_type` 'jobseeker' | 'sole_parent' | 'supported_living': Which main benefit is being received.
  - `situation` 'single_25' | 'single_20_24' | 'single_18_19_away' | 'single_18_19_home' | 'couple_no_children' | 'couple_children' | 'sole_parent': Living situation, which selects the weekly rate.
  - `weekly_income` number: Other gross weekly income before tax. The first $160 a week is free of abatement.
  - `accommodation_cost` number: Weekly rent, board or ownership cost.
  - `housing_type` 'rent' | 'board' | 'mortgage': Only 62% of a board payment counts as an accommodation cost.
  - `area` integer: Accommodation Supplement area, 1 to 4. Area 1 is the highest cost.
  - `children` integer: Number of dependent children.
  - `winter` boolean: Whether the Winter Energy Payment period applies, 1 May to 1 October.

## Response `200`

The weekly entitlement built up step by step, with the rate's provenance.

- BenefitEntitlementResponse
  - `result` BenefitEntitlementResult, required
    - `base_rate` number, required: Weekly rate before any abatement.
    - `abatement` number, required: Reduction for other income.
    - `benefit_after_abatement` number, required: Main benefit actually payable.
    - `accommodation_supplement` number, required: Accommodation Supplement payable.
    - `accommodation_supplement_max` number, required: The cap for this area and family type.
    - `accommodation_cost_counted` number, required: Housing cost counted. For board this is 62% of what is paid.
    - `entry_threshold` number, required: Costs below this earn no supplement. 25% of the base rate, or 30% for ownership.
    - `winter_energy_payment` number, required: Winter Energy Payment, if in the period.
    - `total_weekly` number, required: Everything payable each week.
    - `rate_source` object, required: Which register figure the base rate came from, when it was verified, and when it next changes.
    - `inputs` object, required: The inputs used, with defaults filled in.
  - `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)