Understanding Holiday Schemes

Holiday Schemes in the API

Holiday entitlement is a legal right all UK employees have. The statutory entitlement is 28 days per annum for an employee working a regular 5 day per week pattern. Holiday leave remuneration must be equivalent to the employees' average earnings.

The PayRun.io API offers a flexible set of entities to track, control and remunerate employees for holidays. This covers both statutory entitlement and additional contractual entitlements.

The Entities

The API provides a set of hierarchical objects to control the holiday entitlement calculations.

Employer Holiday Scheme Employee Holiday Scheme Pay Instruction Holiday Reclaim Pay Instruction Holiday YTD Pay Instruction Pay Line Holiday Unit Accrual Unit Depletion

Holiday Scheme

An employer can have any number of holiday schemes. These schemes represent a common amount of entitlement for employees. Multiple schemes can be added to model different entitlement amounts, carry overs and reclaim restrictions.

Holiday Scheme Pay Instructions

Employee holiday scheme membership is controlled using the holiday scheme pay instruction. This pay instruction details when the scheme membership start and ends, it also allows for scheme overrides at the employee level.

Holiday Reclaim Pay Instructions

When an employee wants to use their holiday entitlement, they can reclaim it using the the holiday reclaim pay instruction. The reclaim pay instruction accepts the leave start and end dates along with options to explicitly set the number of holiday units being reclaimed. There is also an option to offset the holiday payment. See offsetting holiday below for more information.

Holiday YTD Pay Instruction

The holiday year to date (YTD) pay instruction allows the payroll administrator to specify the holiday accrual opening balances. This is important when migrating payroll data mid-year. YTD pay instructions can also be used as in period adjustments, allowing standard accrual and depletion to be manipulated.

Pay Line Holiday

Pay lines are generated during pay run calculations. Holiday entitlement unit accrual and depletion values are recorded on the generated Pay Line Holidays.

Holiday Accrual

Holiday schemes define the amount of holiday entitlement an employee can have within a single year. The entitlement to holiday is accrued over the course of the entire year [using several supported strategies] and recorded in the employees' calculated holiday pay lines.

Accrual Year

The holiday scheme entity provides two properties that allow the definition of the holiday scheme accrual year. By setting the year starting month (1 - 12) and year starting day (1 - 31) it is possible to describe any annual period.

Accrual Units

Holiday entitlement can be accrued and reclaimed in two different units; Days and Hours.

  • Days - The holiday pay line units value represents whole and partial days; 1.5 = one and one half days.
  • Hours - The holiday pay line units value represents whole and partial hours; 1.5 = one hour and 30 minutes.

Accrual Units Cannot Be Mixed
Holiday unit types are not interchangeable. Units accrued in days cannot be reclaimed as hours and vice versa.

Accrual Types

The API supports several different types of holiday accrual to support different types of employment.

Days Worked Per Week

The most common accrual mechanism is "Days Worked Per Week". Using this method, an employees accrual is calculated based on the number of days they work in a normal week.
This type of accrual supports employees working a set number of days per week.

Day worked per week accrual is calculated in units of "Day".

Hours Worked Per Week

An alternative [to days worked] is accrual by hours worked per week. This method of accrual is best suited for employees who work a set number of hours per week, but not necessarily on fixed days.

Hours worked per week accrual is calculated in units of "Hour".

Casual or Irregular Hours

For employees who do not have a fixed working pattern, the API provides a method of accrual based on actual hours worked.

Qualifying Pay Codes
To use Casual or Irregular Hours accrual, you must also specify which pay codes qualify for accrual.
The qualifying accrual pay codes are specified on the holiday scheme entity.

Casual or irregular hours accrual is calculated in units of "Hour".

Offsetting Holiday Payments

Another feature [of the API] is the ability to offset holiday leave payments. Using this technique, it is possible to calculate the value of leave payments without affecting the actual take home pay of the employee.

This is especially useful for employees paid a fixed salary.

Holiday Offset Pay Lines
When offsetting is enabled, the value of the holiday pay is negated using a special payment code "HOLOFFSET".

Negative Balance Schemes

The default behavior [of a holiday scheme] is to not allow an employee to reclaim holiday that they have not yet accrued. Setting the scheme to allow negative balances, changes this behavior. A negative balance holiday scheme will allow an employee to reclaim entitlement from their yearly allowance before it has been accrued. The employee is still not allowed to exceed the annual maximum.

Negative Balance On Leaving
One consideration (when allowing a negative balance), is how the company would claw-back overpaid holiday from a leaver who has taken more leave than accrued.

Carry Over Days

Some employment contracts will allow an employee to carry over a certain number of unused days into the next holiday entitlement year.

This behavior is modelled using the "max carry over days" property. This value can be set at both the scheme and instruction level, providing support for global and employee level configurations. Holiday scheme pay instruction settings override holiday scheme settings. Omitting values in the pay instruction causes the scheme level values to be used.

Average Weekly Earnings and Holiday Pay Rates

In the United Kingdom, employees are entitled to 28 days of paid leave (when working a 5 day week) and this total can include bank holidays. The rate at which an employee holiday is paid should be equal to their average weekly earnings over the previous 12 weeks.

By default (and in the absence of an override amount), the PayRun.io API will attempt to calculate the average earnings based on the employees' previous 12 weeks of earnings. There are special conditions for employees who work irregular hours where periods without earnings are ignored.

Employees without 12 Weeks Of History
When an employee without at least 12 weeks of history wishes to reclaim holiday entitlement, there are 2 options:

  1. Specify an override rate - Add an explicit unit rate to be used.
  2. Ignore insufficient history - Allow the system to calculate an average using fewer than 12 weeks.

Reclaim Rate Calculation Exclusions

The reclaim rate calculation is further complicated by the need to identify which elements of pay qualify as regular earnings. The legislation around what constitutes regular pay is complex, but normally boils down to what the employer pays contractually.

Some employment contracts will include a requirement for regular overtime and this means that overtime payments should be considered along with basic payments. However, if overtime is not contractually scheduled, it should be excluded from the average earnings calculation.

To support this requirement, the Holiday Reclaim Pay Instruction includes the optional ability to specify pay codes that should be excluded from average earning calculations.

How to model Probationary Periods

Most employment contracts will only allow new employees' to reclaim leave entitlement up to an accrued amount, within a probationary period. After the employee completes their period of probation, they are then allowed to reclaim leave up to their maximum annual amount.

This behavior needs to be modelled using 2 different holiday schemes. One scheme does not allow negative balance while another does. By moving an employee between schemes, it is possible to enforce the period of probation.

In the following example, employee "Johny Newboy" is not entitled to take more leave than accrued for the first year of his employment. John accrues leave on a "Days worked per week basis".

To model this behavior, there needs to be 2 holiday schemes defined.

  1. Probation Scheme - Allow Negative Balance is "false"
  2. Standard Scheme - Allow Negative Balance is "true"

For his first year, Johny has a pay instruction linked to the Probation Scheme. From the employment anniversary, Johny has a holiday scheme pay instruction linked to the Standard Scheme.

  1. Holiday Scheme Instruction A - Scope: [Employment Start Date] to [1st Anniversary] linked to [Probation Scheme]
  2. Holiday Scheme Instruction B - Scope: [1st Anniversary] onwards, linked to [Standard Scheme]

During his first year, the API will not allow Johny to claim more holiday than has be accrued to date. After his first anniversary, up to the annual maximum can be taken.

How to model Entitlement Increases

Another common practice (in employment contracts) is to increase the amount of entitled days in line with duration of service. Meaning the number of entitled holiday days goes up in line with the length of employment.

Once again, we can accomplish this by using multiple holiday schemes and holiday scheme pay instructions.

In the below demonstration, "Sally Long-stay" is entitled to 1 extra day of leave for every full year of employment, up to 4 additional days. This can be modelled two ways: using company wide schemes or using the override ability of the holiday scheme pay instruction.

Using multiple schemes

  1. Year 1 Scheme - Total entitled days = 28
  2. Year 2 Scheme - Total entitled days = 29
  3. Year 3 Scheme - Total entitled days = 30
  4. Year 4 Scheme - Total entitled days = 31
  5. Long Service Scheme - Total entitled days = 32

Sally has the following holiday scheme pay instructions:

  1. Holiday Scheme Instruction A - Scope: [Employment Start] to [1st anniversary] linked to [Year 1 scheme]
  2. Holiday Scheme Instruction B - Scope: [1st anniversary] to [2nd anniversary] linked to [Year 2 scheme]
  3. Holiday Scheme Instruction C - Scope: [2nd anniversary] to [3rd anniversary] linked to [Year 3 scheme]
  4. Holiday Scheme Instruction D - Scope: [3rd anniversary] to [4th anniversary] linked to [Year 4 scheme]
  5. Holiday Scheme Instruction E - Scope: [4th anniversary] ongoing linked to [Long service scheme]

Using pay instruction overrides

  1. Global Scheme - Total entitled days = 28

Sally has the following holiday scheme pay instructions:

  1. Holiday Scheme Instruction A - Scope: [Employment Start] to [1st anniversary] linked to [Global scheme] - Entitlement override: none
  2. Holiday Scheme Instruction B - Scope: [1st anniversary] to [2nd anniversary] linked to [Global scheme] - Entitlement override: 29
  3. Holiday Scheme Instruction C - Scope: [2nd anniversary] to [3rd anniversary] linked to [Global scheme] - Entitlement override: 30
  4. Holiday Scheme Instruction D - Scope: [3rd anniversary] to [4th anniversary] linked to [Global scheme] - Entitlement override: 31
  5. Holiday Scheme Instruction E - Scope: [4th anniversary] ongoing linked to [Global scheme] - Entitlement override: 32

Ad-hoc accrual and leave in lieu

Sometimes an employee may accrue holiday entitlement outside of the normal accrual scheme. A common trigger for this is when the employee is awarded a day in lieu of additional work.

This ad-hoc behavior can be modelled using the Holiday YTD pay instruction marked as an adjustment.

In the following example, "Jane Overwork" is asked to cover the bank holiday and is awarded an extra day of leave in lieu.

  1. Janes' annual entitlement is 28 days
  2. Jane works on the May bank holiday
  3. Holiday YTD Instruction - Scope [May 1st] to [May 31st], is adjustment = true, Accrued Units = 1, Unit of Measure = Day
  4. Jane now is entitled to 29 days of leave