payroll.holiday-pay-accrual Unreviewed

def holiday_pay(method: HolidayPayMethod, period_pay: Money, weekly_pay: Sequence[Money], on_date: str) -> HolidayPay

HolidayPayMethod = Literal["rolled-up", "average-week"]

@dataclass(frozen=True)
class HolidayPay:
    amount: Money
    #: average-week: weeks the average was taken over; 0 for rolled-up
    weeks_counted: int

from fune.payroll.holiday_pay_accrual import holiday_pay  # payroll.holiday-pay-accrual@^1

from typing import Optional, Sequence

from .dates_add_days import parse_iso_date  ← from dates.add-days ^1.0.0 · built alongside by fune
from .math_round_div import round_div  ← from math.round-div ^1.0.0 · built alongside by fune
from .money_amount import Money, money  ← from money.amount ^1.0.0 · built alongside by fune
from .payroll_holiday_pay_accrual_data import HOLIDAY_PAY_RULES, HOLIDAY_PAY_RULES_HISTORY, HolidayPayRule  ← this capability’s own data, compiled from data/holiday-pay-rules.json into the same file by fune build
from .payroll_holiday_pay_accrual_types import HolidayPay, HolidayPayMethod


def _rule_for(method: str, on_date: str) -> HolidayPayRule:
    best: Optional[HolidayPayRule] = None
    for rule in HOLIDAY_PAY_RULES:
        if rule.method != method or on_date < rule.valid_from:
            continue
        if rule.valid_to is not None and on_date > rule.valid_to:
            continue
        if best is None or rule.valid_from > best.valid_from:
            best = rule
    if best is None:
        if HOLIDAY_PAY_RULES_HISTORY != "full":
            raise ValueError(
                "no %s holiday pay rule for %s: this build was installed with history=%s. "
                "Reinstall with history=full for older dates." % (method, on_date, HOLIDAY_PAY_RULES_HISTORY)
            )
        raise ValueError("no %s holiday pay rule for %s" % (method, on_date))
    return best


def holiday_pay(method: HolidayPayMethod, period_pay: Money, weekly_pay: Sequence[Money], on_date: str) -> HolidayPay:
    """Holiday pay under the Working Time Regulations 1998, by one of two methods.

    Rolled-up: a 12.07% uplift on pay for work done, paid with it, allowed only
    for irregular-hours and part-year workers in leave years from 1 April 2024.
    Average week: a week's pay as the average over the most recent 52 weeks in
    which the worker was paid, skipping unpaid weeks but never looking back more
    than 104 weeks.
    """
    parse_iso_date(on_date)
    if method == "rolled-up":
        rule = _rule_for(method, on_date)
        if period_pay.minor < 0:
            raise ValueError("periodPay must not be negative")
        return HolidayPay(amount=money(round_div(period_pay.minor * rule.accrual_basis_points, 10000, "half-up"), period_pay.currency), weeks_counted=0)
    if method != "average-week":
        raise ValueError('unknown holiday pay method "%s"' % (method,))

    rule = _rule_for(method, on_date)
    total = 0
    counted = 0
    currency: Optional[str] = None
    window = min(len(weekly_pay), rule.lookback_weeks)
    for i in range(window):
        if counted >= rule.reference_weeks:
            break
        week = weekly_pay[i]
        if currency is None:
            currency = week.currency
        elif week.currency != currency:
            raise ValueError("currency mismatch: %s and %s" % (currency, week.currency))
        if week.minor < 0:
            raise ValueError("weekly pay must not be negative")
        if week.minor == 0:
            continue
        total += week.minor
        counted += 1
    if counted == 0 or currency is None:
        raise ValueError("no week with pay in the last %s weeks" % (rule.lookback_weeks,))
    return HolidayPay(amount=money(round_div(total, counted, "half-up"), currency), weeks_counted=counted)

Install

fune build

With that line in your source, in a Python project (language python in fune.project), fune build resolves it and its 3 dependencies, pins them in fune.lock, downloads only the Python package of each, and builds the code above into your project’s .fune/build, one readable file per capability with a header linking back here. Or pin a range in fune.project and build in one step:

fune add payroll.holiday-pay-accrual

The manifest, vectors and README with only the Python implementation. Install it without the registry with fune add ./payroll.holiday-pay-accrual-1.0.1-python.fune, or fetch it from a terminal with fune pull payroll.holiday-pay-accrual@1.0.1:python.

The whole function, every language, is one file too: payroll.holiday-pay-accrual-1.0.1.fune, 40,071 bytes, sha256 728a430cc5fb2f72f87a2b6d207ae3bb653e159163886445e4e01d65cdfa8f69. It installs into a project of any language.

# fune: before payroll.holiday-pay-accrual

# fune: after payroll.holiday-pay-accrual

# fune: replace dates.add-days in payroll.holiday-pay-accrual
# fune: replace math.round-div in payroll.holiday-pay-accrual
# fune: replace money.amount in payroll.holiday-pay-accrual

# fune: step payroll.holiday-pay-accrual after <n|label>

More from the author

For irregular-hours and part-year workers, in leave years beginning on or after **1 April 2024**, holiday pay may be paid as a **12.07% uplift** on pay for work done, at the same time as that pay (reg 16A). 12.07% is 5.6 weeks of leave over the 46.4 weeks a year left for working. The uplift is rounded to the nearest penny, half up (the regulations do not say; this is the usual payroll rounding, stated so it is testable). `periodPay` should be every kind of pay reg 16 counts for a week's pay (reg 16A(9)): basic pay plus regular overtime, commission and similar. `onDate` is the first day of the worker's leave year; an earlier leave year is refused, because rolled-up holiday pay was not lawful then.

## `average-week`: a week's pay over the reference period

Where a week's pay varies, it is the **average over the most recent 52 weeks in which the worker was paid**, counting back from the week before the leave starts; weeks with no pay are skipped and earlier weeks brought in, but nothing more than **104 weeks** back counts (WTR reg 16(3)(e) and (f), in force from 6 April 2020). A worker employed under 52 weeks is averaged over the weeks they have. The average is rounded to the nearest penny, half up.

`weeklyPay` is one entry per week, **most recent first**, with 0 for a week in which nothing was paid. Leave out entirely any week the worker spent on sick or statutory leave (reg 16(3ZE)(b)), and pass only weeks within the employment. Entries beyond the 104th are ignored. `onDate` is the first day of the leave (the calculation date); it only selects the rule. Deciding which payments are part of a week's pay (reg 16(3ZA)) and, for regular-hours workers, whether a fixed week's pay applies instead, is the caller's.

The 12.07%, 52 and 104 are dated rows in `data/holiday-pay-rules.json`.

Entitlement, rather than pay, is `payroll.holiday-entitlement`.

## Sources

- The Working Time Regulations 1998 (SI 1998/1833) reg 16 (a week's pay, 52-week reference period, 104-week limit) and reg 16A (rolled-up holiday pay at 12.07%): https://www.legislation.gov.uk/uksi/1998/1833/regulation/16, https://www.legislation.gov.uk/uksi/1998/1833/regulation/16A - The Employment Rights (Employment Particulars and Paid Annual Leave) (Amendment) Regulations 2018 (SI 2018/1378), in force 6 April 2020 (12 weeks became 52): https://www.legislation.gov.uk/uksi/2018/1378/made - The Employment Rights (Amendment, Revocation and Transitional Provision) Regulations 2023 (SI 2023/1426) (reg 16A, from leave years beginning 1 April 2024): https://www.legislation.gov.uk/uksi/2023/1426/made - GOV.UK, "Holiday pay and entitlement reforms from 1 January 2024": https://www.gov.uk/government/publications/simplifying-holiday-entitlement-and-holiday-pay-calculations/holiday-pay-and-entitlement-reforms-from-1-january-2024

## Before you rely on this

**Not professional advice.** This capability calculates payroll figures from published rules. It is a software component for developers, not tax or legal advice. Rules change and every rate here has an effective date. Check that the dates cover your case. Verify results against the official sources listed above, and have a payroll specialist review how you use it, before anyone relies on the output. Provided "as is" under its licence, without warranty.

**Unreviewed.** This capability's implementations agree in every language and pass its published test vectors, which were worked out from the official sources cited. But no qualified payroll specialist has yet checked those vectors, or confirmed that the capability covers the cases it claims. Treat it as a draft. Do not use it for real people, money or decisions without your own expert review. Once a qualified reviewer signs off, this notice is replaced with their name, qualification and the date. Each new version needs fresh sign-off.

## Notices

Contains public sector information licensed under the Open Government Licence v3.0 (https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/).

Legislation: Crown copyright and database right.

1.0.1 marks it unreviewed and adds its attribution notices (NOTICE). The code and the tests are unchanged.

Files