Annual Statutory Update
This runbook rolls ir's South African statutory rate data forward to a new tax year. Most rates are data-driven, so a normal year means editing JSON files and a few registration lists in the app, with no changes to calculation logic. Do not assume a change is data-only until the release notes, schema and calculation impacts have been assessed.
Who this is for. These steps change files in the ir app's source code and are carried out by whoever maintains the app (the person who commits and deploys ir), not from the Desk. Site administrators then migrate and verify.
The SA tax year runs 1 March to the last day of February. The year of assessment is the calendar year in which the tax year ends: the 2026-2027 tax year (1 March 2026 to 28 February 2027) has year of assessment 2027, and its files are suffixed _2027.
When to run
After National Treasury's annual Budget (usually late February), once SARS publishes the new PAYE tables, rebates, thresholds and the updated Budget Tax Guide. Some figures are gazetted separately and on different dates (see the watch list below); confirm each one before relying on it.
Step 1: Add the statutory rate pack
The rate pack is the single source of truth for every date-effective calculation: PAYE, UIF, SDL, ETI amounts, medical credits, travel, subsistence, retirement, COIDA and lump-sum tax.
- Copy the most recent pack in
ir/ir_setup/data/, for examplestatutory_rates_2027.json→statutory_rates_2028.json. - Update the metadata:
tax_year,year_of_assessment,effective_from,effective_toandsource_reference, and keepis_active: 1. - Update the values that changed (see the watch list). Leave structurally stable values as they are.
- Recompute the PAYE
base_tax(cumulative tax) for each bracket:base_tax = previous bracket's base_tax + (previous bracket's width × previous bracket's rate).amount_overequals the bracket's lower bound.
The loader (ir.utils.statutory_rates) picks up every statutory_rates_*.json file in ir_setup/data/ automatically and uses the pack whose effective_from / effective_to window contains the payroll date. This file needs no registration.
Step 2: Add the supporting files, and register them
In the same ir/ir_setup/data/ folder, add the new year's files (copy the previous year's and adjust):
| File | Used for |
|---|---|
tax_slabs_<YYYY>.json |
The year's Income Tax Slab (the Desk-reviewable tax table). |
tax_rebates_<YYYY>.json |
Rebates and medical tax credits for the Tax Rebates and Medical Tax Credit settings. |
payroll_period_<YYYY>.json |
The Payroll Period dates. |
holiday_list_<YYYY>.json |
South African public holidays for the calendar years the tax year spans. Check for once-off public holidays declared for that year, such as election days. |
Unlike the rate pack, these four files are not picked up automatically. ir/ir_setup/install.py reads them from four fixed lists: PAYROLL_PERIOD_FILES, INCOME_TAX_SLAB_FILES, TAX_REBATE_FILES and PUBLIC_HOLIDAY_FILES. Add the new file name to each list, otherwise the new year's file is silently skipped and no Payroll Period, Income Tax Slab, rebates or holiday list are created for it.
ETI slabs and travel rates
- Travel Allowance Rate records are company-scoped and are seeded from the rate pack (
ir.ir_setup.install.seed_statutory_rate_packs). No separate file is needed. - ETI Slab records are not derived from the rate pack. Add the new year's first 12 months and second 12 months slabs to the
_ETI_SLABSlist inir/ir_setup/install.py. On migrate,ensure_eti_slabscreates any slab whose title doesn't exist yet and never changes existing ones. Keep the established title format, for exampleETI 2026-2027 (2026-03-01 to 2027-02-28) First 12 Months. - The rate pack's own
etiblock still drives the ETI amount calculation, so the new year's ETI figures must be entered in both places.
Treat the rate pack and these source files as the source-controlled truth. Desk records are for reviewing, not a separate place to invent rates.
Step 3: Rehearse, migrate, restart, verify
Never edit a production site first. Commit the pack and source references, run the tests, restore a representative backup to a staging site, and migrate there:
bench --site <site> migrate
The rate packs are held in an in-process cache (functools.lru_cache), not in Frappe's Redis cache, so bench clear-cache does not clear them. Migration clears the cache only in the process that runs the migration (through ir's after_migrate hook). Every other running web or background worker keeps the old rates until it restarts, so restart the bench after every migration that changes a rate pack:
bench restart
When testing interactively without a full migrate, clear the cache yourself in bench console:
from ir.utils.statutory_rates import clear_rate_pack_cache, get_rate_pack
clear_rate_pack_cache()
get_rate_pack("<a date in the new tax year>")["tax_year"]
Run the statutory compliance tests:
bench --site <site> run-tests --app ir --module ir.tests.test_statutory_compliance
Add or update date-based tests that check headline values, bracket boundaries, mid-year effective-date changes, the UIF cap, ETI bands, the COIDA cap, official interest rate periods and JSON validity. A test meant to prove a fixed historic year must never depend on today's date.
Then run the payroll, VAT and COIDA end-to-end scenarios on staging and obtain practitioner sign-off.
Step 4: After deploying
On each site's migration, ir's after_migrate hook (ensure_all_company_tax_configuration) creates the new year's company-scoped Payroll Period, Income Tax Slab and Tax Rebates rows. It only fills in what is missing and never overwrites existing records. ZA Local Setup's Load Tax Slabs, Load Tax Rebates and Load Medical Tax Credits options do the same on demand, for example for a company added between migrations. See ZA Local Setup & Fiscal Year.
Then update each employee's Salary Structure Assignment from 1 March to link the new year's Income Tax Slab, so PAYE uses the new brackets from the first payroll of the new tax year. This is a manual, per-employee step; nothing automates it.
Watch list: figures that change and must be confirmed each year
These are gazetted on different dates by different authorities. Never assume they carried forward.
- PAYE brackets, rebates and thresholds: SARS Budget Tax Guide. (Brackets were not adjusted for 2024-2025 or 2025-2026.)
- Medical scheme tax credits: SARS.
- ETI band amounts and thresholds, and their effective month: gazetted through the Taxation Laws Amendment Act. The amounts increased from 1 April 2025. Remember that both the rate pack and the
_ETI_SLABSlist need updating (Step 2). - UIF monthly remuneration cap: Department of Employment and Labour (R17,712 since June 2021, but verify).
- Prescribed reimbursive travel rate per km: SARS notice.
- Subsistence allowance daily amounts (incidentals only, and meals and incidentals): SARS notice.
- COIDA annual earnings cap: Department of Employment and Labour notice, on its own assessment-year cycle.
- Retirement lump-sum and severance tax tables: change infrequently (last reset 1 March 2023); confirm the exemption and brackets.
- Official interest rates and housing valuation values used for fringe benefits: date-effective; confirm each period.
Deployment control
Back up production before the controlled deployment, migrate, and restart immediately afterwards (Step 3). A successful migration proves only that the deployment ran; it doesn't prove that the copied statutory values or their interpretation are legally correct. Keep the official sources, review evidence and sign-off with the release record.
Primary references
- SARS Guide for Employers in respect of Employees' Tax (2027)
- SARS Budget 2026 frequently asked questions
- South African Government notices, for separately gazetted COIDA and labour figures
Archive the exact publication, PDF or version used for sign-off; a link to a landing page is not enough audit evidence.
Note on the 2024-2025 and 2025-2026 packs
statutory_rates_2025.json (2024-2025) and statutory_rates_2026.json (2025-2026) were added after the fact so that prior-year recalculations work. Their PAYE brackets, rebates, thresholds and medical credits come from the app's vetted prior-year data. The figures listed in each file's verification_notes.verify_before_use block were carried forward and should be checked against the original SARS and Department of Employment and Labour gazettes before being relied on for historical recalculations.