Entitld (0.1.0)

5.6 weeks a year, capped at 28 days.

Employed the whole leave year and you get that figure flat. Joined part way through and you accrue a twelfth of it each month, counted from the monthly anniversary of the start date rather than from the 1st, rounded up to the next half day. Once all twelve are earned the rounding stops and the exact figure applies.

For a starter that figure is reg 15A: the most they may take in their first year. Reg 13(5) separately sets their entitlement as the share of the leave year remaining when they start, which can be lower. Someone starting on the last day of a 28-day leave year gets 2.5 here and 0.0767 by the calendar. Government guidance and the gov.uk calculator use the twelfths, some HR systems use the calendar. The question is unresolved, and until it is settled this returns the reg 15A figure, which calculation_basis.regulation names.

A leaving date inside the leave year is a different rule again. Reg 14 settles the final entitlement by the calendar days actually worked, and we return it unrounded: 6.9808 days, not 7. Anywhere we hand you an exact decimal, calculation_basis.rounding_guidance says so. Round those up, never to nearest. A four-day-a-week worker is owed 22.4 days and nearest pays them 22.

Leave carried forward from an earlier year is not included. The regulations let a worker bring leave forward when sickness or statutory leave stopped them taking it, or when the employer did not give them the chance (reg 13(14), (15) and (17), 13A(7A)), and a relevant agreement can carry the extra 1.6 weeks (13A(7)). We are not sent that history, so add any carried-forward leave to this figure yourself.

The 12.07% method, for leave years starting on or after 1 April 2024. Tell us the hours they worked and we give you the hours they accrued.

Rounded to whole hours once, right at the end. Under 30 minutes goes down, 30 or more goes up. Nothing in between is rounded, which is the whole point: rounding twice gives a different answer.

This is accrual, not their balance. Reg 15B(2) makes what they are entitled to at any point the hours accrued, plus leave carried forward from an earlier year, less leave already taken. We do not model carry-forward, so add it and subtract leave taken yourself. Hours accrued while off sick or on statutory leave come from /v1/accrual/during-absence, not from here.

Reg 15B(4) caps accrual at 28 days a year. It is expressed in days and we take hours only, so the cap is not applied.

For part-timers who book leave in hours rather than days, where a short working day makes a figure in days misleading.

We work out their annual days, then multiply by the length of their working day. Someone on 25 hours over five days gets 28 x 5 = 140 hours. We need days_per_week for that, and to know whether the 28-day cap bites.

This is not the 12.07% method. That one is for people with no settled working week, and using it on a fixed part-timer pays them short.

Full leave years only for now. A mid-year starter or leaver needs an hours-denominated rounding rule we have no source for yet, so send those to /v1/entitlement/fixed instead.

Leave carried forward from an earlier year is not included. The regulations let a worker bring leave forward when sickness or statutory leave stopped them taking it, or when the employer did not give them the chance (reg 13(14), (15) and (17), 13A(7A)), and a relevant agreement can carry the extra 1.6 weeks (13A(7)). We are not sent that history, so add any carried-forward leave to this figure yourself.

How much they have accrued so far this leave year, less whatever they have already taken.

Irregular workers accrue against hours worked, so we answer in hours. Fixed workers accrue a share of their annual entitlement, so we answer in days. Read the unit field before the number. A negative balance means they have taken leave they have not earned yet, which we report rather than hide.

A fixed worker still employed accrues twelfths, rounded up to the next half day only inside their first year, where reg 15A applies, and exact after it. Once a leaving date inside the leave year is known, reg 14 takes over and the balance becomes the exact proportion of the year they worked.

We only call those twelfths reg 15A if employment_start shows the worker is inside their first year, because that is as far as reg 15A(1) reaches. Otherwise, and that includes every request without an employment_start, we call it a monthly accrual convention: same arithmetic, no statute behind it. Send employment_start and you get the statutory answer where one exists.

Round an exact entitlement decimal up, never to nearest; round a balance down. calculation_basis.rounding_guidance flags the entitlement cases.

Leave carried forward from an earlier year is not included, for either worker type: reg 13(14), (15) and (17) and 13A(7) and (7A) for fixed workers, reg 15D for irregular-hours and part-year workers. Add it to accrued yourself.

Someone on irregular hours carries on accruing holiday while they are off sick or on statutory leave. /v1/entitlement/irregular-hours cannot help you there, because it accrues on hours worked and someone who is absent works none. This is the endpoint for that gap.

We average their weekly hours over the period ending the day the absence starts, then accrue 12.07% of that average for every week they are away. Reg 15C, inserted by SI 2023/1426.

The average divides by the weeks in the period LESS the annual leave they took in it, which you send as annual_leave_weeks_taken. That follows government guidance (DBT, 2024): 52 weeks less a full 5.6 weeks is 46.4, so their own holiday does not pull the average down. Send 0 and it divides by every week, which is a literal reading of reg 15C(4) and gives a lower figure.

The rule for dropping weeks is not the holiday pay rule, and getting the two the wrong way round is a real mistake. A week where they worked no hours STAYS IN. Reg 15C(4) counts every week that is not absence, "including weeks during which the worker did not work any hours", and dropping those would inflate the average. What comes out is any week touched by sickness or statutory leave, for any amount of time at all, and the window then reaches further back to replace it. Never past 104 weeks.

Set employee_status_confirmed true for statutory leave. Acas gives statutory leave only to people with employee status, we cannot see whether yours has it, so you tell us and we record that you said so. Sickness does not need it.

What a week of their leave is worth, averaged over the last 52 weeks they were actually paid.

We look back from reference_date and never further than 104 weeks. Weeks they were not paid for come out, and so does any week touched by sickness or statutory leave, marked with week_type. Each one we drop, the window reaches back another week to replace it.

If there are fewer than 52 paid weeks in the whole 104, you get the average of however many we found and short_reference_period set. We will not stretch past 104 weeks and we will not pad the gap with an invented figure.

One rate, and the law sets two. For the 4 weeks of leave under reg 13 and for irregular-hours leave (reg 15B), a week of pay includes commission, status payments and regular overtime (reg 16(3ZA)). For the additional 1.6 weeks (reg 13A) it does not, and reg 16(3)(da) splits the same way. Send full pay and this figure is the reg 13 and 15B rate. It can be higher than the reg 13A rate for a worker who earns any of those payments.

Rolled-up holiday pay. An employer who pays an irregular-hours or part-year worker a 12.07% uplift on each payslip (reg 16A) has already discharged this liability for that leave (16A(8)). Do not pay this average on top.

Weeks. Reg 16(3B) makes a week end on a Saturday, or on another day where the worker is paid weekly by a week ending that day. Send week_start on that boundary: we do not check it, and weeks cut differently give a different average.

Everything is whole pence, in and out.

What you owe a salaried leaver for holiday they never took.

Salary over 52 gives the weekly rate, then over days_per_week gives the day rate, then times the days owed. We round once, at the end.

This one is for fixed salaries only. If their pay varies, use /v1/pay/holiday-pay: averaging what they actually earned is the right method there and this is not.

days_untaken takes decimals deliberately. It is built to swallow a reg 14 figure straight from the entitlement endpoints, 6.9808 and all, because rounding it to 7 first costs you money that is not owed.

For salaried leavers under reg 14. An irregular-hours or part-year worker leaving is paid under reg 15E instead: their untaken reg 15B(2) balance, at the reg 16 rate from /v1/pay/holiday-pay. Nothing is due for leave already paid as rolled-up holiday pay (15E(5)). A relevant agreement setting the sum displaces either route (14(3)(a), 15E(3)(a)).

Gives you the latest ruleset effective on or before the date you ask for, which is how the calculation endpoints resolve it too.