What actually happens when your software files an MTD update

Where most guides stop

Many guides to Making Tax Digital stop at the same point: connect your software to HMRC, and your software does the rest. It is true, and it is useless. You are about to hand a company the ability to file tax on your behalf, and the usual explanation of what that involves is a shrug.

So this is the rest. It comes from what our software does in HMRC's sandbox today and from HMRC's documentation. On 29 October 2026 HMRC gave LetSort production access, which lets it connect to HMRC's live systems. That does not make it HMRC recognised, and we do not claim otherwise. As at 6 November 2026 no filing of any kind has gone through the live service, so the filing steps below have not yet run there. One live connection test reached HMRC, which refused the next step because that account was not signed up for Making Tax Digital. Some of what follows will make you more comfortable. The part about the headers may make you less comfortable, and you should probably know it anyway.

First, the handshake, and the clock you cannot see

When you press “connect to HMRC”, you are sent to HMRC's own site, not ours. You sign in there, you approve the permissions there, and HMRC sends you back with a code. That code is worth ten minutes and can be used once.

Your software trades it for two tokens, and their lifetimes are the thing worth understanding.

The eighteen months is the one to remember. HMRC is explicit: after eighteen months refresh tokens stop working, and you must go through the authorisation process again. HMRC documents no way to extend it. When your provider asks you to reconnect, 18 months after you first authorised it, it is not being lazy. It is being obeyed.

Then your software tells HMRC about your computer

This is the part you may most want to know.

HMRC requires fraud prevention headers on every Making Tax Digital call. Not as a nice-to-have. In HMRC's own words: “You are required by law to submit header data for the VAT (MTD) and Income Tax Self Assessment (MTD) APIs.” If software keeps sending missing or incorrect data after discussions with HMRC, its provider may be fined and blocked from HMRC's APIs.

For a web application like ours, HMRC lists sixteen headers. For eleven it names no circumstance in which a value could be missing. For five it does. Here are the eleven for which HMRC names no exception. Your public IP address and network port are sent too, in two of the other five. Gov-Client-User-IDs carries the identifier you sign in with: for us, your email address and LetSort user ID.

Read that list again as a landlord rather than as an engineer. Gov-Client-Screens is the resolution and colour depth of your monitor. Gov-Client-Window-Size is how big your browser window was. Gov-Client-Timezone is your clock's offset from UTC. Gov-Client-Public-IP-Timestamp is when your IP address was captured. Taken together, those values describe the device that filed your tax. HMRC's stated purpose is to “monitor transactions to help protect your customers' confidential data from criminals and fraudsters”.

That is a defensible thing for a tax authority to want. It is also easy to miss before you click connect. It is in the small print: ours is in our privacy policy.

The two headers we do not send, and why

HMRC is blunt that software must submit data for every header your connection method lists, and that you are required by law to do so. It does not call any of them optional. But for a few, its own guidance names circumstances in which you will not be able to collect a value, and then tells you to follow its missing-data guidance. We omit two, and told HMRC about both. Our replies gave email and password as the reason for the first, and did not mention emailed links.

A third header with a named exception, Gov-Client-Public-Port, was the awkward one. Our API runs on Cloudflare Workers, which did not give us your browser's source port, so for a time we omitted it too. We now collect it from a dedicated service we built for the purpose. If your browser cannot reach that service, the header is left off that call. HMRC's named exception for this header is a private network connection, which does not describe that case. That has its own story: why your MTD software asks for your device details.

This is not a technicality. HMRC requires fraud prevention headers in sandbox calls before it will grant production access, and says they “will be checked by a specialist team”. Getting this wrong does not produce a polite error. It produces a conversation with HMRC.

Now the filing itself: one call that submits, others around it

Here are the main calls a filing can involve, not a complete list, with the API versions that are live in production as at 6 November 2026. Only call three is the submission. HMRC says software should store the business ID rather than fetch it each time. HMRC requires software to let customers view an estimate, but it can do that by signposting them to their HMRC account instead of displaying one. In LetSort, the business ID is fetched after you connect and give your National Insurance number, and then stored, preparing a quarter also reads your business details and obligations from HMRC, and an estimate runs when you ask for one. HMRC's roadmap, re-read on 6 November 2026, shows the Individual Calculations v9.0 changes deployed to the sandbox in September 2026 and lists them under December 2026, “to be confirmed”; v8.0 is still the only production version.

Call three is the only one that submits anything, and it is a single PUT:

HMRC replies 204 No Content. No body, no cheerful message: just a 204 and an X-CorrelationId, a unique ID for tracking the operation. LetSort does not currently store it. The absence of an error is the success, which takes some getting used to, and is why software should check the obligation afterwards. LetSort shows the updated status when you reopen the deadlines page; it does not re-check by itself.

And that check needs patience. HMRC says it “may take up to an hour for the obligation to be marked as fulfilled”. If you file an update close to a deadline (the next is 7 February 2027) and your dashboard still says “open” ten minutes later, nothing is wrong.

Three things about that number it shows you afterwards

Calls four and five exist to produce a tax estimate, and they have some sharp edges.

It is asynchronous. Your software asks HMRC to calculate, gets back 202 Accepted and an ID, and then has to wait: HMRC says software should wait at least five seconds before retrieving the result, to avoid an error. So the little spinner you see is real. It is your software counting to five because HMRC asked it to.

It is an estimate. It is computed from whatever HMRC has received so far: by October, one or two quarters of your property figures, plus some information HMRC already holds, but often not your full year's other income. HMRC calls it “an estimated forecast”. It is not your bill, and treating it as one can leave you unpleasantly surprised when the real bill arrives, with the balancing payment for 2026-27 due on 31 January 2028. If you make payments on account, the ones due on 31 January and 31 July 2027 are usually half of your 2025-26 bill, not anything worked out from this estimate. Reducing them because the estimate looks low means interest if the final bill is higher.

And it is not the filing. Filing your tax return is a separate operation, ending when you confirm the calculation, and it is the point at which you say “this is my tax return” rather than “here are my figures”. As an aside for anyone who has read older documentation: HMRC's spec calls that step the final declaration “(previously known as crystallisation)”, and yet the Obligations API still has an endpoint with the word crystallisation sitting in the path. The term was retired. The word was not.

What happens if you file twice

A repeat of the same figures should simply overwrite the first, and the reason is worth understanding, because it is not the reason you would expect. If you send different figures, read to the end.

HMRC publishes no idempotency mechanism for these APIs. There is no idempotency key, no header, nothing in the reference guide. If you are hoping the platform will politely detect and discard a duplicate submission, it will not, because it has no way of knowing that is what you meant.

What actually protects you is the shape of the data. Quarterly updates are cumulative from the start of the tax year (6 April, or usually 1 April if you chose calendar update periods), the submission is a PUT, and HMRC says each update invalidates the previous submission, so treat the last update sent as the whole picture. Send it twice and the second one should overwrite the first with the same numbers. You are protected by the data model, not by a guarantee. That is a meaningful distinction. HMRC says each update invalidates the previous one. It does not offer that as protection against duplicates.

The same design cuts the other way. Whatever you send last is the picture HMRC holds for the year. If software sends only the latest quarter's figures under year-to-date dates, or leaves something out, HMRC's published errors for this call include date checks but none on amounts falling, and HMRC would then hold less than you have actually earned and spent, until the full year-to-date figures are sent again. HMRC does refuse an update whose end date is earlier than one it already holds. That does not stop out-of-date figures being sent with a current end date.

What production access does and does not mean

HMRC's terms bar providers from claiming or implying their software is ‘HMRC approved’. Production access is permission to connect to HMRC's live systems, for the APIs it names. Its conditions are below. They do not include checking any landlord's figures, and HMRC says it does not recommend any product.

LetSort holds production access. That does not make it HMRC recognised, and we do not claim otherwise. As at 6 November 2026 no filing has gone through LetSort's live service, and the full filing journey has only run in HMRC's test environment. LetSort covers UK property income only and is not on HMRC's software list. HMRC's press release of 12 August 2026 says quarterly updates “need to be sent through HMRC-recognised software”. The regulations say “functional compatible software” (SI 2026/336 reg 3). LetSort is not recognised or listed, so if you need to file now, choose a product from HMRC's finder and check it is available now.

HMRC lists three conditions: that the relevant APIs and endpoints have been tested satisfactorily, that calls include compliant fraud prevention headers, and that a Production Approvals Checklist is completed and aligns with the testing. It separately requires compliance with its terms of use before issuing production credentials. HMRC says the headers in your sandbox calls “will be checked by a specialist team”.

The header data described above is central to it. HMRC separately tells developers to “test with a variety of user IDs, devices, browsers, and screen sizes” to confirm the header spec is implemented correctly. Production access also depends on the product meeting HMRC's minimum functionality standards, including a disclaimer on any tax estimate you are shown.

Recognition is a separate thing. There is no longer a published table of recognised software. GOV.UK's page history for 31 July 2025 says: “The table of software listings has been removed.” In its place is a software finder. You can answer questions for a filtered list, browse all recognised software with filters, or search for a product you already use. HMRC calls listed software ‘recognised’, not approved, and says it does not recommend any product. HMRC's developer hub now says it is no longer accepting production credential access requests for new 2026–27 quarterly update products, because the market window for them has closed. HMRC does not say how this affects requests already in progress. LetSort's request was in progress, and HMRC granted production access on 29 October 2026. Ask a vendor which APIs and versions HMRC has given them production access for. If the answer is vague, that tells you something.

The small print your software lives inside

• HMRC’s standard rate limit is 3 requests per second per application. Exceed it and you get a 429, with the error MESSAGE_THROTTLED_OUT.
• The sandbox has a stateful mode, where you can submit data and read it back. Test users are deleted after three months without use.
• There is a Test Fraud Prevention Headers API to validate your headers, and HMRC warns you not to treat passing it as a guarantee that production will accept them.
• The cumulative endpoint is only available for tax years from 2025-26. The old per-period endpoints still exist, and still serve the years up to 2024-25.

Common questions

Sources

All from HMRC, GOV.UK and legislation.gov.uk. Some API pages show a last-updated date, and the MTD service guide has a dated changelog; most guide pages show no date. So these were re-read on 6 November 2026 and are stated as at that day, no stronger, except where a note gives 8 October 2026.

• HMRC: user-restricted endpoints (the 4-hour and 18-month token lifetimes)
• HMRC: send fraud prevention data (the legal requirement, and the fine-and-block)
• HMRC: fraud prevention, web app via server (the exact header list)
• HMRC: how to integrate (the production access conditions, and the specialist header check)
• HMRC: tax calculations (asynchronous, and the five-second wait; last re-read 8 October 2026)
• HMRC: Property Business (MTD) API v6.0 (the cumulative period summary, currently published as beta)
• HMRC: making updates during the tax year (the “up to an hour” obligation lag)
• HMRC: reference guide (the 3-per-second rate limit; last re-read 8 October 2026)
• HMRC: terms of use (no claiming or implying approval; when ‘HMRC recognised’ may be used)
• HMRC: making updates at tax year end (the final declaration: trigger, retrieve, then submit)
• HMRC: Property Business API error definitions, on GitHub (the refusal of an earlier end date; main branch, which may differ from what is deployed)
• GOV.UK: send quarterly updates (updates are sent using compatible software; updated 16 October 2026)
• HMRC: Business Details (MTD) API (v2.0, the version re-checked)
• HMRC: Obligations (MTD) API (v3.0, the version re-checked)
• HMRC: Obligations API final declaration spec, on GitHub (“previously known as crystallisation”, and the path that still uses the word)
• HMRC: Individual Calculations (MTD) API (v8.0 in production, v9.0 in sandbox only; updated 5 November 2026)
• HMRC press release, 12 August 2026 (quarterly updates “need to be sent through HMRC-recognised software”)
• SI 2026/336, regulation 3 (functional compatible software, defined by what it can do)
• GOV.UK: find software for MTD for Income Tax (the page history: the table of software listings removed on 31 July 2025)
• HMRC: software finder (three routes, and HMRC recommends no specific product)
• HMRC developer hub: MTD for Income Tax end-to-end service guide (production access closed for new 2026–27 quarterly update products)
• HMRC: MTD for Income Tax vendors roadmap (APIs) (Individual Calculations v9.0 in sandbox since September 2026, listed under December 2026, to be confirmed)
• GOV.UK: payments on account (usually half of the previous year’s bill; interest if reduced too far; last re-read 8 October 2026)

Related

• Why your second MTD update looks twice as big as your first
• The landlord's compliance year: every date that actually matters