Work out your take-home pay
Income tax, National Insurance and net pay for any UK salary, 2026-27.
Around 30.3 million people are paid through PAYE Real Time Information in the UK each month, and for every one of them an employer must deduct the right income tax, National Insurance and any student loan on or before payday [1] [2]. Those deductions are not a single sum. They are the output of several separate HMRC routines, each with its own thresholds, rounding rules and edge cases.
This article is written for developers and product teams. It explains what an employee tax calculation API computes, how HMRC's PAYE and National Insurance routines actually work, why tax codes and cumulative bases change the result, and how an engine returns net pay as a set of predictable values a host platform can trust.
An employee tax calculation API is the part of a payroll engine that turns gross pay into net pay. It takes a period's earnings, a tax code, a National Insurance category and the year-to-date figures, and returns income tax, National Insurance, student loan and net pay, each calculated to HMRC's published precision. Because HMRC updates the specification every tax year, the value of the API is that the calling platform never has to hold the tax logic itself [3].
Key takeaways
- An employee tax calculation API returns income tax, National Insurance, student loan deductions and net pay from a period's gross pay and the employee's details [3].
- PAYE income tax is worked out on a cumulative basis by default, using the tax code and free pay tables, so each period accounts for pay and tax already taken in the year [4].
- An emergency or week 1/month 1 code ignores earlier pay and taxes each period in isolation [5].
- Employer National Insurance is charged at 15% on earnings above the £5,000 Secondary Threshold for the 2026-27 tax year, and employees pay 8% between the Primary Threshold and Upper Earnings Limit [6].
- Student loan deductions take 9% of earnings above the plan threshold, rounded down to the nearest pound [7].
What an employee tax calculation API computes
An employee tax calculation API exposes the deduction engine as an operation a calling platform can invoke over HTTP. The host platform sends the inputs (gross pay for the period, the tax code, the National Insurance category letter, the student loan plan and the year-to-date totals) and the engine returns a structured result: income tax, employee and employer National Insurance, any student loan, and the resulting net pay [8].
The calculation is not one figure but a stack of independent routines that run in a defined order. Income tax and National Insurance are worked out separately, using different thresholds and different bases, and student loans sit on top with their own threshold. An engine returns each component as its own field so the host platform can display a full breakdown, drive a payslip and reconcile against the Real Time Information the engine files [2].
Why tax calculation fits the API model
Tax calculation is well suited to an API because it is deterministic. Given the same inputs (gross pay, tax code, National Insurance category and year-to-date figures) the output is fixed by HMRC's specification, so the engine can guarantee the same answer on every call [3]. That determinism is what lets a platform treat the API as the single source of truth for a value like income tax charged at the basic rate of 20% on earnings above the Personal Allowance of £12,570 [9].
The second reason is that the specification changes at least once a year. Tax bands, National Insurance thresholds and student loan plans all move each April, and hard-coding them in the host platform guarantees an annual bug. When the engine holds the specification, the calling platform posts gross pay and receives a current, correct result without a code change [6]. Moonworkers exposes this through its HMRC-recognised payroll API, where the deduction routines are updated to the published specification each tax year.
The inputs the API needs
A correct calculation depends on the host platform supplying the right inputs. The table below sets out the core inputs and why each one changes the result.
| Input | Why it matters | Typical API field |
|---|---|---|
| Gross pay for the period | The base figure all deductions work from | `grossPay` |
| Tax code | Sets the tax-free allowance and the basis of operation | `taxCode` |
| Basis (cumulative or week 1/month 1) | Decides whether earlier pay is taken into account | `taxBasis` |
| National Insurance category | Sets the rate and any relief | `niCategory` |
| Student loan plan | Sets the repayment threshold | `studentLoanPlan` |
| Year-to-date figures | Required for cumulative tax and directors' NI | `yearToDate` |
Sources: HMRC PAYE and National Insurance guidance [4] [6].
PAYE income tax: the cumulative routine
PAYE income tax is the most involved routine because it is cumulative by default. The employer uses the tax code and the free pay tables to give a proportion of the allowances and tax bands for the period, working on a rolling basis up to each payday and taking account of pay and tax already dealt with in the year [4].
Cumulative versus week 1/month 1
On the cumulative basis, taxable pay to date is calculated by subtracting the free pay for the period from the cumulative pay to date, and the tax due to date is worked out against that figure. The tax for the current period is the difference between the tax due to date and the tax already deducted, which is why the cumulative basis self-corrects across the year [3].
The week 1/month 1 basis works differently. It gives a proportion of the allowances and bands for each period but ignores previous pay and tax, so every period is taxed as though it were the first of the year [5]. An engine must model both, because an emergency code often operates on this non-cumulative basis, and applying the wrong basis produces a materially different deduction [10].
Tax codes and their letters
The tax code carries the instruction for the routine, and its letters change the calculation. The table below sets out the common codes an engine must handle.
| Code | Meaning |
|---|---|
| `1257L` | Standard code, full Personal Allowance of £12,570 |
| `BR` | Basic rate on all earnings, no allowance |
| `D0` | Higher rate on all earnings |
| `D1` | Additional rate on all earnings |
| `NT` | No tax deducted |
| `K` prefix | Deductions exceed the allowance, so pay is added to |
Sources: HMRC tax code guidance [11] [9].
Codes also carry a jurisdiction. Scottish codes start with `S` and use the Scottish bands, Welsh codes start with `C`, and an engine has to apply the right band set to the right employee, because Scottish taxpayers pay different rates above the basic band [11]. HMRC also caps any single PAYE deduction at 50% of gross pay, a safety rule the routine must enforce even when a `K` code would otherwise take more [3].
National Insurance: the exact percentage method
National Insurance runs as a separate routine with its own thresholds. Employers can use the published tables or the exact percentage method, and payroll software works National Insurance out using the exact percentage method for precision [6]. HMRC publishes a calculator specifically so software developers can check that their engine computes both the employee and employer figures correctly [8].
Employee and employer rates for 2026-27
The rate depends on the band and the category letter. For a standard category A employee in the 2026-27 tax year, the figures are as follows.
| Payer | Band | Rate |
|---|---|---|
| Employee | Between Primary Threshold (£12,570) and Upper Earnings Limit (£50,270) | 8% |
| Employee | Above the Upper Earnings Limit | 2% |
| Employer | Above the Secondary Threshold (£5,000) | 15% |
Sources: HMRC National Insurance rates and the employer further guide [6] [12].
The employer rate rose to 15% on 6 April 2026, and because the Secondary Threshold is only £5,000, an employer pays National Insurance on the band between £5,000 and £12,570 even though the employee does not [6]. An engine that surfaces the employer figure separately lets a host platform show the true cost of a hire, not just the take-home. The full mechanics are covered in the Moonworkers guide to employer National Insurance.
Directors are calculated annually
Directors are the classic edge case. Their National Insurance is assessed on an annual earnings period rather than on each pay period, so the routine works out contributions on total pay in the year to date and subtracts what has already been paid [13]. An engine may also support the alternative method, where a regular-paid director is assessed period by period and then reconciled to the annual basis at year end [14]. A tax calculation API that does not flag an employee as a director will over or under-deduct, which is why the director status is a required input for anyone running payroll for owner-managed companies through a payroll bureau platform.
Student loans and the order of deductions
Student loan repayment is a third routine that sits on top of tax and National Insurance. The deduction is 9% of earnings above the plan's pay period threshold, rounded down to the nearest whole pound [7]. The thresholds differ by plan, which is why the plan is a required input.
| Plan | Annual threshold 2026-27 | Rate |
|---|---|---|
| Plan 1 | £26,900 | 9% |
| Plan 2 | £29,385 | 9% |
| Plan 4 | £33,795 | 9% |
| Postgraduate Loan | Separate threshold | 6% |
Sources: HMRC student loan deduction tables and repayment guidance [7] [15].
Where an employee has both a student loan and a postgraduate loan, the routine applies each against its own threshold, and the postgraduate loan is deducted first [15]. The Moonworkers guide to student loan deductions sets out the full calculation with worked figures. An engine returns the student loan as its own field so a host platform can show it on the payslip separately from tax and National Insurance.
Authentication and safe integration
An employee tax calculation API is only useful if the integration around it is safe. Two patterns matter most: authentication and correct handling of throughput.
HMRC's own APIs use OAuth 2.0 bearer tokens, and a payroll engine that files to HMRC inherits the same model. An access token lasts 4 hours, after which a single-use refresh token issues a new one, and testing happens in a sandbox before production access is granted [16]. A host platform integrating a tax calculation API should build the token refresh into its client from the start rather than bolting it on later.
Throughput is the second pattern. HMRC applies a standard rate limit and returns an HTTP 429 when an application exceeds it, and the documented approach is to capture the 429, back off for a few seconds with some randomisation, and retry rather than surface an error to the user [17]. A well-built payroll integration treats a 429 as a signal to slow down, not a failure, which keeps a large payrun from stalling when many employees are calculated at once.
Check a calculation against the engine
A quick way to validate a tax calculation API during development is to compare its output against a known figure. The Moonworkers UK salary calculator applies the 2026-27 PAYE and National Insurance rules to any gross salary, which lets a developer confirm the income tax and National Insurance an engine should return before wiring it into a product.
£ per month
e.g. 1257L, S1257L, BR, D0
S = Scotland · C = Wales · W1/M1 = non-cumulative
Enter a salary or hourly rate above
About this calculator
This calculator gives you a close estimate of your UK payroll deductions for 2026-27, using HMRC's exact percentage method. It covers the vast majority of employees on standard tax codes, but it won't match your payslip to the penny in every case. Edge cases it does not cover include in-year tax code changes, K-code carry-forwards, Week 53 adjustments, payrolled benefits in kind, and multi-employment NI deferral. Powered by the same engine as the Moonworkers Payroll API.
Frequently asked questions
Why might the result differ from my payslip?
This calculator uses your current gross pay and tax code to produce an estimate. Your employer may apply adjustments not covered here, such as mid-year tax code changes, K-code carry-forwards, or benefits in kind processed through payroll. For most employees on a standard tax code these differences are negligible.
What tax code should I enter?
Use the tax code shown on your most recent payslip or the PAYE Coding Notice (P2) from HMRC. If you're not sure, 1257L is the standard code for most employees resident in England, Wales, or Northern Ireland. Use S1257L for Scotland or C1257L for Wales if you pay Scottish or Welsh income tax.
Which NI category applies to me?
Most employees use Category A. Use M if you are under 21, H if you are an apprentice under 25, or C if you are over State Pension age. Your employer is responsible for assigning the correct category — if in doubt, check your payslip.
Which student loan plan am I on?
Your plan depends on when and where you studied. Plan 1 covers students who started before September 2012. Plan 2 is for English and Welsh students who started from September 2012 to July 2023. Plan 5 applies to English students who started from August 2023. Plan 4 covers Scottish students. You can check your plan at gov.uk or on your payslip.
What is the YTD cumulative PAYE mode?
HMRC's standard method calculates income tax on your total earnings to date each period, then subtracts tax already paid. If you're mid-year and want to see exactly what tax should be deducted in a specific period, expand the Year-to-date section and enter your running totals from previous periods only.
Conclusion
An employee tax calculation API is a stack of independent HMRC routines behind a single call. Income tax runs cumulatively against a tax code, National Insurance runs on the exact percentage method against separate thresholds, student loans take a flat percentage above a plan threshold, and directors break the period model entirely. The reason to reach for an engine rather than build the maths is that every one of those routines changes at least once a year, and the specification is unforgiving about rounding and order.
The direction of travel is towards more platforms embedding payroll rather than writing tax logic, because the cost of getting a cumulative code or a directors' calculation wrong is a penalty and a correction, not a cosmetic bug. The engines that win are the ones that expose each deduction as a clean, typed field, keep pace with the annual specification, and make the safe integration patterns, token refresh and back-off, the default rather than an afterthought.
Frequently asked questions
What is the difference between a cumulative and a week 1/month 1 tax calculation?
A cumulative calculation takes account of all pay and tax already dealt with in the tax year, so each period self-corrects and the total tax deducted is roughly right by year end [4]. A week 1/month 1 calculation ignores earlier pay and taxes each period as though it were the first of the year, which is common with emergency codes [5]. A tax calculation API must support both, because the basis of operation changes the deduction materially.
How is employee National Insurance calculated in 2026-27?
For a standard category A employee, National Insurance is 8% on earnings between the Primary Threshold of £12,570 and the Upper Earnings Limit of £50,270, and 2% above that [6]. Employers pay 15% on earnings above the £5,000 Secondary Threshold [12]. Payroll software uses the exact percentage method for precision rather than the published tables.
How does an API calculate student loan deductions?
The engine deducts 9% of earnings above the plan's pay period threshold and rounds the result down to the nearest whole pound [7]. The threshold depends on the plan, so the plan is a required input, and where an employee has both a student loan and a postgraduate loan the postgraduate loan is deducted first [15]. Returning the student loan as its own field lets the host platform show it separately on the payslip.
Does an employee tax calculation API need to be HMRC-recognised?
The calculation itself follows HMRC's published specification, but any engine that also files Real Time Information must be HMRC-recognised, because recognition certifies the software meets HMRC's specification for sending Full Payment Submissions and other RTI messages [18]. Recognised products are listed on the GOV.UK register [19]. In practice the same engine that calculates the deductions also reports them, so recognition and calculation accuracy go together.
