# payroll.income-tax
Status: needs review by a qualified payroll professional before it is published.
PAYE income tax for one payment. Give it the employee's tax code, the pay
frequency and tax period (from `payroll.tax-period`), this period's taxable pay,
the taxable pay and tax so far this tax year, and the pay date; it returns the
tax to deduct (or refund) and the running totals.
## Which method
This follows HMRC's **"Specification for PAYE tax table routines"** (version
24.0, February 2026), the computerised form of the printed tax tables that
payroll software is expected to implement. It is not a "divide the annual
bands by 12" approximation, and the difference shows up in pence:
- **Free pay** for a code is worked out per week or month from
`number x £10 + £9`, rounded *up* to the penny, with codes over 500 split into
blocks of 500 (£96.16 a week, £416.67 a month each) plus a remainder, exactly
as paragraph 4.3.1 says. 1257L is £241.92 a week and £1,048.26 a month.
- **Taxable pay** is rounded *down* to the whole pound.
- The **band thresholds to date** are `annual band x n / 52` (or `/ 12`) held
to four decimal places without rounding; the test of which band applies uses
that figure rounded *up* to the pound, the tax formula uses it exactly.
- Every tax formula is worked to four decimal places and the result is
rounded *down* to the penny.
All of that is done in integer ten-thousandths of a pound, so the three
languages agree to the penny. HMRC notes (paragraph 16) that the printed
tables can differ from this specification by 1p, exceptionally 2p; this
capability matches the specification, not the printed tables.
## What it handles
- Cumulative codes: tax due to date on pay to date, less tax already deducted.
A negative result is a refund.
- Week 1 / month 1 codes (`W1`, `M1`, `X`): each payment on its own, with the
week 1 figures (week 2 for fortnightly, week 4 for four-weekly pay). The
year-to-date arguments are only added to for the running totals.
- Weeks 53, 54 and 56 are always non-cumulative (paragraph 14).
- Suffix codes, K codes, 0T, BR, D codes (`D0` 40%, `D1` 45%; Scotland `SD0`
21% to `SD3` 48%, `SD2` 47% in 2023-24) and NT. NT on a cumulative basis
refunds all tax deducted so far this year.
- Scottish (S), Welsh (C) and rest-of-UK bands for 2023-24 to 2026-27. Welsh
rates are held as their own rows even though they currently equal the
rest-of-UK rates, because the Senedd can set them separately.
- **The overriding limit** (the "K-code 50% rule"): tax deducted from a payment
may not exceed 50% of that payment. Under a cumulative code the tax held
back is recovered in later periods automatically, because the next
calculation compares tax due to date with tax actually deducted
(`taxNotDeducted` reports what was held back). The limit never restricts a
refund, and on negative pay it is zero (paragraph 4.5.4).
## What it does not do
- Payrolled benefits in kind: the limit is applied to the whole of `pay`; if
you payroll benefits, the limit should be applied to cash pay only.
- Mid-year changes of region: supply the code in force for this payment; the
pay and tax to date carry over, as the specification says.
- It trusts `previousTaxToDate` to be tax actually deducted, as HMRC's
routine requires.
- The newest band rows have no end date. They stay in force until a new
version adds the next tax year, so a 2027-28 pay date is answered with
2026-27 bands until then.
## Sources
- HMRC, "Specification for PAYE tax table routines", version 24.0 (February
2026), paragraphs 3-16 and Appendices A-C (band widths, rates, Maxrate 50%):
https://www.gov.uk/government/publications/payroll-technical-specifications-income-tax
- HMRC, "Rates and thresholds for employers" for each year (rest-of-UK,
Scottish and Welsh bands and the 1257L emergency code):
https://www.gov.uk/guidance/rates-and-thresholds-for-employers-2023-to-2024,
https://www.gov.uk/guidance/rates-and-thresholds-for-employers-2024-to-2025,
https://www.gov.uk/guidance/rates-and-thresholds-for-employers-2025-to-2026,
https://www.gov.uk/guidance/rates-and-thresholds-for-employers-2026-to-2027
- The Income Tax (Pay As You Earn) Regulations 2003 (SI 2003/2682), regulation
23 (cumulative basis, overriding limit):
https://www.legislation.gov.uk/uksi/2003/2682/regulation/23
1.0.1 fixes Python accepting a trailing newline or non-ASCII digits in payDate; adds tests.
## 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 professional (CIPP) 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 professional (CIPP) 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.2 marks it unreviewed and adds its attribution notices (NOTICE). The code and the tests are unchanged.