Skip to main content

VAT (MTD) end-to-end service guide

Version 8.0 issued 14 May 2025

This guide explains how you can integrate your software with our APIs to submit VAT returns under Making Tax Digital for VAT. It shows how the APIs fit into various end-to-end user journeys. It is intended to help software developers, designers, product owners or business analysts understand how your software needs to interact with HMRC systems.

Overview

VAT (MTD) requires VAT registered businesses with taxable turnover above the VAT registration threshold to:

  • keep records in digital form
  • file their VAT Returns using software (via our VAT (MTD) API)

The frequency of submitting a VAT Return (annually, quarterly or monthly) does not change under MTD.

For more details see VAT Notice 700/22. In particular, section 7 shows the various options for software integration.

Production approvals process for VAT (MTD)

Our key objectives for VAT (MTD) are to:

  • ensure customers have a streamlined end-to-end journey and software that supports everything a business customer needs to do to meet their VAT obligations
  • safeguard customer data and protect HMRC systems against fraud and criminal attack

This section of the guide explains the features your product must include before production credentials are sought, together with features you should consider building into your products.

Minimum functionality standards

The minimum required functionality is as follows:

  • A software product must submit the fraud prevention header data required by law.
  • A VAT (MTD) product must allow the customer to:

The following endpoints are also available. These are optional. However, we do recommend that you include them to support your customers’ needs.

  • Retrieve VAT customer information using the VAT (MTD) API Retrieve VAT customer information endpoint to see the customer’s effective date of registration for VAT and also check whether the customer has entered the VAT Flat Rate Scheme.
  • Retrieve VAT obligations again using the VAT (MTD) API Retrieve VAT obligations endpoint to check if the VAT Return has met the current obligation - or to see the next obligation.
  • Retrieve returns submitted up to four years previously by using the VAT (MTD) View VAT return endpoint.
  • Retrieve VAT liabilities by calling the VAT (MTD) API Retrieve VAT liabilities endpoint.
  • Retrieve VAT payments by calling the VAT (MTD) API Retrieve VAT payments endpoint.
  • Retrieve details of the penalties that have been applied to a VAT account by using the VAT (MTD) Retrieve VAT penalties endpoint.
  • Retrieve the financial details relating to a penalty by using the VAT (MTD) Retrieve financial details endpoint.

Fraud Prevention Headers

You must supply fraud prevention header information for all our APIs, before approval can be granted and production credentials issued.

HMRC must see evidence of fraud prevention headers being sent and be satisfied as to their level of accuracy.

Please use the Test Fraud Prevention Headers API to check headers submitted by your application meet the latest version of the Fraud Prevention Headers specification.

Testing requirements

The following endpoints are required to be tested to cover the VAT reporting:

  1. Use the Create Test User API to create a test user who is an ‘organisation’ to generate test credentials (you will be provided with a test VAT Registration Number (VRN) and User ID and Password details).
  2. Use the VAT (MTD) API Retrieve VAT obligations endpoint to return obligation periods (this will return a canned response in the sandbox environment).
  3. Use the VAT (MTD) API Submit VAT return for period endopint to submit the return for the open obligation period.
  4. We would also need to see testing to any of the other optional endpoints, if these are to be utilised by the software.

Developers need to:

  • consider developing guidelines within the software for relevant users, including a reference to HMRC user interface journeys for customers and agents (you can find examples of the flow for both Agents and Businesses, in the ‘Set up’ section of this guide)
  • use APIs as efficiently as possible to prevent hitting the rate limit
  • build relevant error responses, so that the software can deal with exceptions
  • when authorising software, please make it clear to your users, that the correct VAT (MTD) gateway organisation account credentials, or Agent Services Account credentials, need to be used when logging into the system.
Warning Once all the above steps have been completed, please contact SDSTeam@hmrc.gov.uk within 2 weeks of completing your API testing, to enable us to view the data within our logs. It takes 10 working days to advise of the outcome. When you contact us, we will then ask you to complete 2 questionnaires, before checking your Fraud Prevention Header and VAT (MTD) API testing.

Terms of use

You must comply with our terms of use. You must accept the terms of use before we can issue you with production credentials.

Software choices

HMRC publishes a list of compatible software for VAT (MTD) on GOV.UK. Software providers may request to be added to this list when they have completed the necessary steps in the Production approvals process for VAT (MTD) section.

Your software can be added to this page if you provide a product for retail/commercial use.

Once production access has been granted, we also request that you make a live submission (and provide us with the VAT Registration Number to allow us to check this), before you can be added to the software choices page.

End-to-end user journeys

These journeys show examples of use. Journeys for businesses and agents are broken down into:

Changelog

Version 7.1

12 December 2023

Version 7.0

10 October 2022