Ways to use the calculator

There are 3 ways to use the calculator. Each user can use as much or as little of it as they need.

The service administrator chooses how the service’s own pages and API work. Each organisation using the service has its own settings. They are chosen by the service administrator or by the organisation’s own administrators.

The 3 ways

1. Full question pages

Customers answer one question per page and see their bill. Each organisation has its own web address for them, like /o/example-accountants.

Try Example Accountants’ pages

2. Question pages inside another app

The app starts a journey with what it already knows and sends the customer here. The customer answers the rest, then goes back to the app. The app then collects the tax and what to pay when.

Try the dummy payroll app

3. API calculations

The app sends figures and gets the calculation back. It can send everything. Or it can send one part at a time, such as pay alone for basic Income Tax.

Try the payroll app’s quick check or the API documentation

What can be chosen

Parts of the calculator: 29 parts, such as pay, self-employment, property, savings, dividends, capital gains and student loans. Or a ready-made set: Full Self Assessment, Basic Income Tax, Employees, Self-employed, Landlords, Savers and investors.
Ways to use it: Any of the 3 ways. When a way is off, its pages say the service is not available, and the API refuses calls.
Reading answers automatically: For each way, whether HMRC and DVLA data is read instead of asked.
Each part’s answers: For each part that records can fill, such as pay, State Pension or student loans, one of 3 choices. The customer enters the answers. Or they are read and filled in for the customer to check. Or they are read and the questions are skipped, though they are still shown on ‘Check your answers’. Anything that could not be read is asked.
Answers the app sends: For question pages inside an app: whether customers check what the app sent, or the questions it answered are skipped. The app can also ask for them to be checked.
What else can be worked out: Payment plan amounts (a regular amount to pay towards the next bill) and the tax so far this tax year, each switched on for each of the 3 ways.
Documents customers upload: For pay, property, dividends, savings interest and pension contributions: whether customers can upload a document, such as a P60, to fill in the answers. They check every answer, and the document is not kept.
Telling the app: For question pages inside an app: a web address on the app to tell straight away when a customer finishes. Each notification is signed with the organisation’s own secret.
The result: The bill with all the working, or just the bill and what to pay when.
Apps customers go back to: The web addresses that customers of question pages inside an app may be sent back to.
API keys: An organisation’s administrators create and revoke its keys.

Questions about parts that are not used are not asked. The API refuses their fields. So an app never gets a figure that quietly left something out.

The settings pages number the choices in this order: the parts first, then the ways of use, reading records, each part’s answers, and what else can be worked out.

Every app attaches the same way, with its organisation’s API key. Nothing is special to any one app: HMRC’s Budget Payment Plan service would be one more organisation, like the dummy one on this site.

The example organisations on this site

Example organisations and how each uses the calculator
Organisation	Uses	Ways	Reads data
Example Accountants	Full Self Assessment	Full question pages and the API	All HMRC data on the pages. Pay is used without asking. Customers check the rest. Customers can also upload documents, such as a P60 (sample documents)
Example Payroll App	Basic Income Tax	Question pages inside its app, and the API	Pay the app sends is not asked again. Customers check pay read from HMRC. They always enter their pensions. The app is told straight away when a customer finishes
Example Budget Payment Plan Service	Payment plan amounts	Question pages inside its app, and the API	Its app sends the customer’s HMRC account
Example Tax API	Employees	The API only	HMRC data through the API, with the customer’s permission

To change their settings, sign in to an account with the dummy GOV.UK One Login as Rita Mensah. Then go to ‘Organisations you manage’.

For developers

Organisations call these with their API key. The service’s own API has the same calculations at /api/v1/calculate and /api/v1/modules.

POST /api/v1/saas/calculate: a full calculation under the organisation’s settings
POST /api/v1/saas/modules/{id}/calculate: a calculation from one part’s fields only
POST /api/v1/saas/calculate/with-hmrc-data: answers left out are read from HMRC records
POST /api/v1/saas/journeys: start question pages inside the app, of kind tax_estimate, payment_plan or tax_so_far, then GET /api/v1/saas/results/{id}
POST /api/v1/saas/payment-plan and POST /api/v1/saas/tax-so-far: a payment plan amount, or the tax so far this year, where the settings switch them on
GET /api/v1/saas/notifications: the latest notifications sent to the app, and whether each one reached it
GET /api/v1/saas/settings and GET /api/v1/saas/modules: what the organisation uses, and for each part whether its answers are read

Use cases for each way, each with the end-to-end persona test that walks through it.

Is this page not working properly? (opens in new tab)