Calculators

Annual leave balance projected forward

Project an NZ annual leave balance forward.

Accrues at holiday_rate_pct of hours worked. The Holidays Act 2003 minimum is four weeks a year, which is the 8% default.

The same balance comes back in hours, days and weeks, because which one is meaningful depends on the roster: days assume hours_per_workday and weeks assume hours_per_workweek, so a part-timer week of leave is not the same number of hours as a full-timer one.

This projects an accrual. It does not calculate what leave is worth in dollars, which under the Act depends on ordinary weekly pay versus average weekly earnings and is a genuinely harder question.

post/v1/annual-leave

Request

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

Request body

current_balancenumber required

Existing balance

current_balance_unit'hours' | 'days'

Unit that current_balance is expressed in.

hours_per_workdaynumber

Hours in a normal working day, used to convert days to hours.

holiday_rate_pctnumber

Accrual rate as a percentage of hours worked. The Holidays Act 2003 minimum of four weeks a year is 8%.

hours_per_workweeknumber

Hours worked in a normal week.

future_periodnumber

How far ahead to project, in future_period_unit.

future_period_unit'weeks' | 'months' | 'years'

Unit that future_period is expressed in.

Example request

{
  "current_balance": 40,
  "current_balance_unit": "hours",
  "future_period": 12,
  "future_period_unit": "months",
  "holiday_rate_pct": 8,
  "hours_per_workday": 8,
  "hours_per_workweek": 40
}

Response

Projected balance in hours, days and weeks.

disclaimerstring required

Scope and limits of this calculation.

Example response

{
  "disclaimer": "Estimate only. Actual leave accrual depends on your employment agreement and the Holidays Act 2003. Not legal advice.",
  "result": {
    "hours_accrued_per_week": 3.2,
    "inputs": {
      "current_balance": 40,
      "current_balance_unit": "hours",
      "future_period": 12,
      "future_period_unit": "months",
      "holiday_rate_pct": 8,
      "hours_per_workday": 8,
      "hours_per_workweek": 40
    },
    "projected_balance_days": 25.86,
    "projected_balance_hours": 206.86,
    "projected_balance_weeks": 5.17
  }
}

Changes

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