Skip to main content
RefundCalculator

Methodology: how the calculators are built

A calculator is only trustworthy if you can audit it. This page is the audit trail — the process each tool passed before it went live.

One engine, pure functions

All 16 tools run on a single pure-TypeScript calculation engine. The maths has no contact with the network, storage or analytics: numbers in, a structured result out. That makes every figure unit-testable and keeps your inputs — by construction, not by promise — on your device.

Versioned rates per tax year

Rates live in a versioned registry keyed by tax year (2021-22 through 2026-27), each entry stamped with its official source URL, verification date and status. Years whose figures are not yet final — currently 2026-27 — carry an unverified status and every result that touches them says so on screen. The registry feeds the sources page and the tax-year changes page automatically.

The release gate

No calculator ships until all six checks pass:

  1. Official sources — every rate traced to GOV.UK, HMRC manuals or legislation.
  2. Boundary tests — unit tests at band edges (Personal Allowance, £50,270, £100,000–£125,140 taper, Scottish thresholds) and at zero.
  3. Worked examples — published examples from official guidance reproduced exactly by the engine.
  4. Manual independent calculation — a human re-derives at least three scenarios per tool without looking at the code.
  5. Qualified tax review — sign-off by a UK-tax-qualified reviewer (ATT/CTA or practising accountant) recorded against the content version.
  6. Limitations written — what the estimate cannot know is listed on the page, not buried in legalese.

Rounding rules

  • Calculations are carried at full precision; displayed money is rounded to the penny (2dp), nearest.
  • Intermediate band values are rounded per band so the on-screen steps always add to the total you see.
  • Percentage relief (e.g. 20% uniform relief) is rounded to the penny after multiplication, never before.

Known limitations

  • Estimates model the common case. Multiple employments, benefits in kind, savings and dividend income, and cross-border situations sit outside most tools.
  • HMRC's own records are the authority — where they differ from an estimate, HMRC wins.
  • Estimates never create a claim; only the official routes we link can.

Calculation version

The current engine version is v1.5.0. The version appears on every calculator page so a support conversation can always pin down exactly which maths produced a number. Changes land with boundary tests and a changelog entry in the repository.

Test coverage

The engine carries unit tests (Vitest) across every calculator family, plus a privacy test that fails the suite if a money value is ever passed to the analytics tracker. Smoke and accessibility tests (Playwright + axe) run in CI. Details are in the handover notes shipped with the code.