payroll.tax-period

The UK PAYE tax week, tax month and payroll period number that a pay date falls in, weeks 53, 54 and 56 included.

1.0.0 (not the latest) · published 2026-10-03 by charlie · Anterra

Pinned by 16 tests, run in TypeScript, Python and Rust.

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 in its README, and have a payroll specialist review how you use it, before anyone relies on the output. Provided “as is” under its licence, without warranty.

What it does

Every PAYE and National Insurance calculation starts by asking which tax week or tax month a payment falls in. The answer depends only on the date the employee is paid, never on the dates the work was done: a monthly salary paid on 28 April is month 1, and one paid on 3 May is still month 1.

- Tax week 1 is 6 to 12 April, week 2 is 13 to 19 April, and so on. Week 52 ends on 3 or 4 April, so the last one or two days of every tax year (5 April, or 4 and 5 April when the tax year contains 29 February) are **week 53**. - Tax month 1 is 6 April to 5 May, month 2 is 6 May to 5 June, and so on to month 12, 6 March to 5 April. - `period` is what `payroll.income-tax` and the other payroll capabilities take. For monthly pay it is the tax month. For weekly, fortnightly and four-weekly pay it is the tax week of the pay date, because HMRC's cumulative tables for those frequencies are indexed by week: a fortnightly payroll paid in weeks 2, 4, 6 uses the week 2, 4 and 6 figures. A payday in week 53 is the extra payday of the year and HMRC calls it week 53 (weekly), week 54 (fortnightly) or week 56 (four-weekly); those periods are taxed on a non-cumulative basis, which is why they get their own numbers.

For example

tax_period(2026-04-06, monthly) → tax year 2026/27, tax year start 2026-04-06, week 1, month 1, period 1 6 April is week 1 and month 1
tax_period(2026-04-12, weekly) → tax year 2026/27, tax year start 2026-04-06, week 1, month 1, period 1 12 April is still week 1
tax_period(2026-04-13, weekly) → tax year 2026/27, tax year start 2026-04-06, week 2, month 1, period 2 13 April starts week 2

The function

The same function in TypeScript, Python and Rust, pinned by the same tests. Pick your language; the choice follows you around the registry.

def tax_period(pay_date: str, frequency: PayFrequency) -> TaxPeriod

pay_date	date	the date the employee is paid, not the end of the period worked
frequency	PayFrequency	how often this employee is paid
returns	TaxPeriod

The types it declares, generated into your project

PayFrequency = Literal["weekly", "fortnightly", "four-weekly", "monthly"]

@dataclass(frozen=True)
class TaxPeriod:
    """Where a pay date sits in the UK tax year."""

    #: HMRC's label, e.g. 2026/27
    tax_year: str
    #: 6 April of that tax year
    tax_year_start: str
    #: tax week 1-53: week 1 is 6-12 April
    week: int
    #: tax month 1-12: month 1 is 6 April to 5 May
    month: int
    #: the period PAYE and NICs are worked out for: the month when paid monthly, otherwise the tax week, with week 53 reported as 53, 54 or 56 for weekly, fortnightly or four-weekly pay
    period: int

Your code names it in one line, in the file that uses it

from fune.payroll.tax_period import tax_period  # payroll.tax-period@^1

impl/python.py · 33 lines · open · raw

Imports name this capability’s declared dependencies, which fune builds next to it in your project; each one links to its page.

from .dates_add_days import days_between, parse_iso_date  ← from dates.add-days ^1.0.0 · built alongside by fune
from .dates_uk_tax_year import uk_tax_year  ← from dates.uk-tax-year ^1.0.0 · built alongside by fune
from .payroll_tax_period_types import PayFrequency, TaxPeriod


def tax_period(pay_date: str, frequency: PayFrequency) -> TaxPeriod:
    """The tax week, tax month and payroll period a pay date falls in.

    The tax year is 365 or 366 days, which is 52 weeks and one or two days over.
    Those spare days are week 53, and they are the reason ``period`` exists:
    HMRC numbers the extra payday 53, 54 or 56 by frequency and taxes it
    non-cumulatively, so a payroll that just counts weeks gets it wrong.
    """
    if frequency not in ("weekly", "fortnightly", "four-weekly", "monthly"):
        raise ValueError('unknown pay frequency "%s"' % (frequency,))
    year = uk_tax_year(pay_date)
    week = days_between(year.start, pay_date) // 7 + 1

    # Tax months run from the 6th to the 5th, so the calendar month moves on
    # five days before the tax month does.
    date = parse_iso_date(pay_date)
    month = date.month - 3 if date.day >= 6 else date.month - 4
    if month <= 0:
        month += 12

    if frequency == "monthly":
        period = month
    elif week < 53:
        period = week
    else:
        period = {"weekly": 53, "fortnightly": 54, "four-weekly": 56}[frequency]

    return TaxPeriod(tax_year=year.label, tax_year_start=year.start, week=week, month=month, period=period)

Install

fune build

With that line in your source, in a Python project (language python in fune.project), fune build resolves it and its 2 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.tax-period

Download for Python payroll.tax-period-1.0.0-python.fune · 9,295 bytes sha256 95ab2d97efa8e853aa78867bf8e32f079b1ee57ac8d5326c844e46c249ed1a39

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

The whole function, every language, is one file too: payroll.tax-period-1.0.0.fune, 12,936 bytes, sha256 43ed19fe6b4dc194504b76282d6f3d032e7648e498f813adc6d7926c3cc38e4e. It installs into a project of any language.

Customise it in your app

The seams this capability offers. Put a marker directly above a function of your own and fune build wires it into the built code; the package on the registry is not changed, the built file’s header lists it under CUSTOMISED, and fune hooks lists every hook in the project. How hooks work.

before — your function gets the arguments and returns them, changed or not, or throws to refuse the call.

# fune: before payroll.tax-period

after — your function gets the result and the arguments, and returns the final result.

# fune: after payroll.tax-period

replace — inside this capability’s code only, calls to a dependency go to your function, with the same signature. Other capabilities that use it are unaffected; write in * to replace it everywhere.

# fune: replace dates.add-days in payroll.tax-period
# fune: replace dates.uk-tax-year in payroll.tax-period

step — your function runs at a numbered point inside the function’s body, receives the in-scope values it names as parameters, and may return replacements. List the points with fune show payroll.tax-period --steps.

# fune: step payroll.tax-period after <n|label>

Tests

A version published now needs at least 8 tests for every function, and one that expects the error for each function that throws; the registry refuses it otherwise. fune verify --all runs each case in TypeScript, Python and Rust, and a project runs them again with fune verify. This page lists the cases; it does not run them. The exact JSON is vectors.json.

Case	Arguments		Expected
6 April is week 1 and month 1	2026-04-06, monthly	→	tax year 2026/27, tax year start 2026-04-06, week 1, month 1, period 1
12 April is still week 1	2026-04-12, weekly	→	tax year 2026/27, tax year start 2026-04-06, week 1, month 1, period 1
13 April starts week 2	2026-04-13, weekly	→	tax year 2026/27, tax year start 2026-04-06, week 2, month 1, period 2
5 May is the last day of month 1	2026-05-05, monthly	→	tax year 2026/27, tax year start 2026-04-06, week 5, month 1, period 1
6 May is month 2	2026-05-06, monthly	→	tax year 2026/27, tax year start 2026-04-06, week 5, month 2, period 2
a fortnightly payday is placed by its tax week	2026-09-23, fortnightly	→	tax year 2026/27, tax year start 2026-04-06, week 25, month 6, period 25
5 January is still tax month 9	2026-01-05, monthly	→	tax year 2025/26, tax year start 2025-04-06, week 40, month 9, period 9
4 April is week 52	2027-04-04, weekly	→	tax year 2026/27, tax year start 2026-04-06, week 52, month 12, period 52
5 April is week 53 for a weekly payroll	2027-04-05, weekly	→	tax year 2026/27, tax year start 2026-04-06, week 53, month 12, period 53
5 April is week 54 for a fortnightly payroll	2027-04-05, fortnightly	→	tax year 2026/27, tax year start 2026-04-06, week 53, month 12, period 54

Show the other 6 tests

Case	Arguments		Expected
5 April is week 56 for a four-weekly payroll	2027-04-05, four-weekly	→	tax year 2026/27, tax year start 2026-04-06, week 53, month 12, period 56
5 April is just month 12 for a monthly payroll	2027-04-05, monthly	→	tax year 2026/27, tax year start 2026-04-06, week 53, month 12, period 12
a tax year containing 29 February has two week-53 days: 4 April is one	2024-04-04, weekly	→	tax year 2023/24, tax year start 2023-04-06, week 53, month 12, period 53
29 February itself	2024-02-29, four-weekly	→	tax year 2023/24, tax year start 2023-04-06, week 48, month 11, period 48
an impossible date is an error	2026-02-30, monthly	→	error: is not a real calendar date
an unknown frequency is an error	2026-04-06, daily	→	error: unknown pay frequency

More from the author

This capability does not check that a payroll really is fortnightly or four-weekly (that the paydays are 14 or 28 days apart); it places one date.

Sources: HMRC, "Employer further guide to PAYE and NICs" (CWG2), sections on tax weeks and months and on week 53 payments, https://www.gov.uk/government/publications/cwg2-further-guide-to-paye-and-national-insurance-contributions; HMRC, "Specification for PAYE tax table routines" v24.0, paragraph 14 (payments in weeks 53, 54 or 56), https://www.gov.uk/government/publications/payroll-technical-specifications-income-tax.

Files

Path	Bytes
README.md	1,822
impl/python.py	1,409
impl/rust.rs	1,985
impl/typescript.ts	1,480
vectors.json	2,938