Calculators

Working for Families entitlement after abatement

A family's Working for Families entitlement for the year.

This is the endpoint the API exists for. A model can work out a percentage; it cannot know that the In-Work Tax Credit is temporarily $7,670 until 31 March 2027, that it reverts to $5,070, or that the pool abates at 27.5 cents in the dollar above $44,900.

Family Tax Credit and In-Work Tax Credit abate TOGETHER against one threshold. Best Start has its own: 21 cents in the dollar above $79,000, and it is paid until a child's third birthday, not the first.

Read differences_from_website before comparing this with the page. Two are deliberate. The website still asks whether the caregiver works 20 hours a week as a sole parent or 30 combined as a couple, and pays nothing otherwise; IRD removed that test on 1 July 2020, so this applies the current one, which is some income from paid work and no income-tested benefit. And the website pays Best Start in full where this abates it.

assumptions returns every rate and threshold used, so a stored answer can be audited later against the rules that applied on the day.

The Minimum Family Tax Credit is not calculated: it tops a low working income up to a guaranteed net figure, which needs the family's tax position rather than its gross income, and IRD works it out separately.

post/v1/working-for-families

Request

  • Base URL: https://api.calculate.co.nz
  • URL: https://api.calculate.co.nz/v1/working-for-families
  • Auth: API key in header X-API-Key

Request body

childreninteger required

Dependent children in the caregiver's care.

family_incomenumber required

Combined gross annual family income from ALL sources: both partners' wages, business income, rental, taxable benefits.

children_under_3integer

How many of those children are under 3, for Best Start. IRD pays it until the third birthday, not the first.

iwtc_eligibleboolean

Whether the In-Work Tax Credit applies. The test is some income from paid work each week and NOT receiving an income-tested benefit or student allowance. There has been NO hours test since 1 July 2020.

best_start_children_first_year_exemptinteger

How many of the under-3s are in their first year AND were born before 1 April 2026. Those are exempt from the Best Start income test for that year.

iwtc_after_march_2027boolean

Model the reverted IWTC of $5,070 instead of the temporary $7,670.

Example request

{
  "best_start_children_first_year_exempt": 0,
  "children": 2,
  "children_under_3": 1,
  "family_income": 85000,
  "iwtc_after_march_2027": false,
  "iwtc_eligible": true
}

Response

FTC, IWTC and Best Start, each abated by its own rule.

disclaimerstring required

Scope and limits of this calculation.

Example response

{
  "disclaimer": "Estimate using IRD rates effective 1 April 2026. Excludes the Minimum Family Tax Credit, shared care and part-year entitlement. Two figures deliberately differ from the website page and are named in differences_from_website. Confirm your actual payments with IRD.",
  "result": {
    "abatement": 11027.5,
    "assumptions": {
      "abatement_rate": 0.275,
      "abatement_threshold": 44900,
      "best_start_abatement_rate": 0.21,
      "best_start_abatement_threshold": 79000,
      "best_start_annual_per_child": 4041,
      "ftc_first_child_annual": 7921,
      "ftc_subsequent_child_annual": 6454,
      "iwtc_annual": 7670,
      "iwtc_is_temporary_rate": true,
      "source": "Inland Revenue, rates effective 1 April 2026"
    },
    "best_start_abatement": 1260,
    "best_start_annual": 2781,
    "best_start_before_abatement": 4041,
    "children": 2,
    "children_under_3": 1,
    "combined_ftc_iwtc_before_abatement": 22045,
    "differences_from_website": [],
    "excludes": [
      "the Minimum Family Tax Credit, which IRD works out separately from the family's tax position rather than its gross income",
      "shared care, which splits entitlement by the share of nights",
      "part-year entitlement and mid-year income changes"
    ],
    "family_income": 85000,
    "ftc_annual": 14375,
    "ftc_iwtc_after_abatement": 11017.5,
    "fully_abated": false,
    "iwtc_annual": 7670,
    "iwtc_eligible": true,
    "tax_year": "2026/27",
    "total_annual": 13798.5,
    "total_fortnightly": 530.71,
    "total_weekly": 265.36
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.