GOV.UK
This version is in beta - expect some breaking changes.
VAT (MTD) API
| Available in Sandbox | Yes |
|---|---|
| Sandbox base URL | https://test-api.service.hmrc.gov.uk |
| Available in Production | Yes |
| Production base URL | https://api.service.hmrc.gov.uk |
Overview
Making Tax Digital introduces digital record-keeping for VAT-registered businesses. Those that are above the VAT threshold will be mandated to use this service from April 2019. Those that are below the threshold can use this service voluntarily. HMRC customers (and their agents) will use digital record-keeping software to interact directly with our systems via the MTD APIs.
The MTD VAT API allows software to supply business financial data to HMRC, so that clients can fulfil their obligations.
For more background on the VAT API, see the MTDfB VAT Guide for Vendors.
How it works
- The client (or their agent) enters their VAT account information into the software.
- The software updates HMRC via the API.
- The API submits this information to an HMRC systems database, where the client’s liability is stored to establish whether the client has met their obligations.
Fraud prevention
It will become compulsory to supply header information for this API from April 2019 to prevent fraud. We recommend that you include this now.
Changelog
You can find the changelog in the vat-api GitHub wiki.
Support
- Raise non-technical or platform-related issues with the Software Development Support Team (SDST).
- Raise technical issues on the vat-api GitHub page.
Testing
You can use the sandbox environment to test this API. You can use the Create Test User API or it's frontend service to create test users.
It may not be possible to test all scenarios in the sandbox. You can test some scenarios by passing the Gov-Test-Scenario header. Documentation for each endpoint includes a Test data section, which explains the scenarios that you can simulate using the Gov-Test-Scenario header.
If you have a specific testing need that is not supported in the sandbox, contact our support team.
Some APIs may be marked [test only]. This means that they are not available for use in production and may change.
Versioning
When an API changes in a way that is backwards-incompatible, we increase the version number of the API. See our reference guide for more on versioning.
Errors
We use standard HTTP status codes to show whether an API request succeeded or not. They are usually in the range:
- 200 to 299 if it succeeded, including code 202 if it was accepted by an API that needs to wait for further action
- 400 to 499 if it failed because of a client error by your application
- 500 to 599 if it failed because of an error on our server
Errors specific to each API are shown in the Endpoints section, under Response. See our reference guide for more on errors.
Endpoints
/organisations/vat/{vrn}/obligations
Retrieve VAT obligations. This endpoint is one of the mandatory endpoints to use to achieve the minimum level of compliance. The other endpoint required to achieve the minimum level of compliance is Submit VAT return for period.
Authorisation
This endpoint is
user-restricted
- it requires an Authorization header containing an OAuth 2.0 Bearer Token with the read:vat scope.
Path parameters
| Name | Description |
|---|---|
|
vrn
string
required
|
VAT registration number.
For example: |
Query parameters
| Name | Description |
|---|---|
|
from
string
optional
|
Date from which to return obligations. Mandatory unless the status is O.
For example: |
|
to
string
optional
|
Date to which to return obligations. Mandatory unless the status is O.
For example: |
|
status
string
optional
|
Obligation status to return: O=Open, F= Fulfilled. Omit status to retrieve all obligations.
For example: |
Request headers
| Name | Description |
|---|---|
|
Accept
required
|
Specifies the response format and the version of the API to be used. For example: application/vnd.hmrc.1.0+json
|
|
Gov-Test-Scenario
optional
|
Only in sandbox environment. See Test Data table for all header values. For example: -
|
|
Authorization
required
|
An
OAuth 2.0 Bearer Token
with the read:vat scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb
|
See also fraud prevention for other request headers which will become mandatory.
Response headers
| Name | Description |
|---|---|
|
X-CorrelationId
required
|
Unique id for operation tracking For example: c75f40a6-a3df-4429-a697-471eeec46435
|
See also fraud prevention for other request headers which will become mandatory.
Response
HTTP status: 200 (OK)
{
"obligations": [
{
"start": "2017-01-01",
"end": "2017-03-31",
"due": "2017-05-07",
"status": "F",
"periodKey": "18A1",
"received": "2017-05-06"
},
{
"start": "2017-04-01",
"end": "2017-06-30",
"due": "2017-08-07",
"status": "O",
"periodKey": "18A2"
}
]
}
{
"obligations": [
{
"start": "2017-01-01",
"end": "2017-01-31",
"due": "2017-03-07",
"status": "F",
"periodKey": "18AD",
"received": "2017-03-06"
},
{
"start": "2017-02-01",
"end": "2017-02-28",
"due": "2017-04-07",
"status": "O",
"periodKey": "18AE"
}
]
}
| Name | Description |
|---|---|
|
obligations
array
required
|
Obligation |
|
start
string
required
|
The start date of this obligation period Date in the format
For example: |
|
end
string
required
|
The end date of this obligation period Date in the format
For example: |
|
due
string
required
|
The due date for this obligation period, in the format YYYY-MM-DD. For example: 2017-01-25. The due date for monthly/quarterly obligations is one month and seven days from the end date. The due date for Payment On Account customers is the last working day of the month after the end date. For example if the end date is 2018-02-28, the due date is 2018-03-29 (because the 31 March is a Saturday and the 30 March is Good Friday). |
|
status
string
required
|
Which obligation statuses to return (O = Open, F = Fulfilled)
For example: |
|
received
string
optional
|
The obligation received date, is returned when status is (F = Fulfilled) Date in the format
For example: |
|
periodKey
string
required
|
The ID code for the period that this obligation belongs to. The format is a string of four alphanumeric characters. Occasionally the format includes the # symbol.
For example: |
Error scenarios
| Scenario | HTTP status | Code |
|---|---|---|
|
Invalid VRN |
400 (Bad Request) |
VRN_INVALID |
|
Invalid date from |
400 (Bad Request) |
INVALID_DATE_FROM |
|
Invalid date to |
400 (Bad Request) |
INVALID_DATE_TO |
|
Invalid date range, must be 366 days or less |
400 (Bad Request) |
INVALID_DATE_RANGE |
|
Invalid status |
400 (Bad Request) |
INVALID_STATUS |
|
The remote endpoint has indicated that no associated data is found |
404 (Not Found) |
NOT_FOUND |
|
The client and/or agent is not authorised. This is normally because: the client is not subscribed to MTD, the agent is not subscribed to Agent Services, or the client has not authorised the agent to act on their behalf. |
403 (Forbidden) |
CLIENT_OR_AGENT_NOT_AUTHORISED |
For error scenarios that are common across all APIs, and for error formats, see our reference guide.
Test data
Scenario simulations using Gov-Test-Scenario headers are only available in sandbox environment.
| Header Value (Gov-Test-Scenario) | Scenario |
|---|---|
Default (No header value) |
Simulates the scenario where the client has quarterly obligations and one is fulfilled |
QUARTERLY_NONE_MET |
Simulates the scenario where the client has quarterly obligations and none are fulfilled |
QUARTERLY_ONE_MET |
Simulates the scenario where the client has quarterly obligations and one is fulfilled |
QUARTERLY_TWO_MET |
Simulates the scenario where the client has quarterly obligations and two are fulfilled |
QUARTERLY_THREE_MET |
Simulates the scenario where the client has quarterly obligations and three are fulfilled |
QUARTERLY_FOUR_MET |
Simulates the scenario where the client has quarterly obligations and four are fulfilled |
MONTHLY_NONE_MET |
Simulates the scenario where the client has monthly obligations and none are fulfilled |
MONTHLY_ONE_MET |
Simulates the scenario where the client has monthly obligations and one month is fulfilled |
MONTHLY_TWO_MET |
Simulates the scenario where the client has monthly obligations and two months are fulfilled |
MONTHLY_THREE_MET |
Simulates the scenario where the client has monthly obligations and three months are fulfilled |
MONTHLY_OBS_##_OPEN |
Simulates the scenario where the client has monthly obligations for 2018 and the ## month is open. All previous obligations for same year will show as fulfilled. Accepts 01 to 12. Example: MONTHLY_OBS_03_OPEN |
MONTHLY_OBS_12_FULFILLED |
Simulates the scenario where the client has monthly obligations for 2018 and all obligations are fulfilled. |
QUARTERLY_OBS_##_OPEN |
Simulates the scenario where the client has quarterly obligations for 2018 and the ## quarter is open. All previous obligations for same year will show as fulfilled. Accepts 01 to 04. Example: QUARTERLY_OBS_02_OPEN |
QUARTERLY_OBS_04_FULFILLED |
Simulates the scenario where the client has quarterly obligations for 2018 and all obligations are fulfilled. |
MULTIPLE_OPEN_MONTHLY |
Simulates the scenario where the client has monthly obligations for 2018 and two are open. |
MULTIPLE_OPEN_QUARTERLY |
Simulates the scenario where the client has quarterly obligations for 2018 and two are open. |
OBS_SPANS_MULTIPLE_YEARS |
Simulates the scenario where the client has an obligation that spans both calendar years 2018 and 2019. |
NOT_FOUND |
Simulates the scenario where no data is found |
/organisations/vat/{vrn}/returns
Submit VAT return for period. This endpoint is one of the mandatory endpoints to use to achieve the minimum level of compliance. The other endpoint required to achieve the minimum level of compliance is Retrieve VAT obligations.
Authorisation
This endpoint is
user-restricted
- it requires an Authorization header containing an OAuth 2.0 Bearer Token with the write:vat scope.
Path parameters
| Name | Description |
|---|---|
|
vrn
string
required
|
VAT registration number.
For example: |
Request headers
| Name | Description |
|---|---|
|
Accept
required
|
Specifies the response format and the version of the API to be used. For example: application/vnd.hmrc.1.0+json
|
|
Content-Type
required
|
Specifies the format of the request body, which must be JSON. For example: application/json
|
|
Gov-Test-Scenario
optional
|
Only in sandbox environment. See Test Data table for all header values. For example: -
|
|
Authorization
required
|
An
OAuth 2.0 Bearer Token
with the write:vat scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb
|
See also fraud prevention for other request headers which will become mandatory.
Request
{
"periodKey": "A001",
"vatDueSales": 105.50,
"vatDueAcquisitions": -100.45,
"totalVatDue": 5.05,
"vatReclaimedCurrPeriod": 105.15,
"netVatDue": 100.10,
"totalValueSalesExVAT": 300,
"totalValuePurchasesExVAT": 300,
"totalValueGoodsSuppliedExVAT": 3000,
"totalAcquisitionsExVAT": 3000,
"finalised": true
}
{
"periodKey": "#001",
"vatDueSales": 100.00,
"vatDueAcquisitions": 100.00,
"totalVatDue": 200.00,
"vatReclaimedCurrPeriod": 100.00,
"netVatDue": 100.00,
"totalValueSalesExVAT": 500,
"totalValuePurchasesExVAT": 500,
"totalValueGoodsSuppliedExVAT": 500,
"totalAcquisitionsExVAT": 500,
"finalised": true
}
| Name | Description |
|---|---|
|
periodKey
string
required
|
The ID code for the period that this obligation belongs to. The format is a string of four alphanumeric characters. Occasionally the format includes the # symbol.
For example: |
|
vatDueSales
number
required
|
VAT due on sales and other outputs. This corresponds to box 1 on the VAT Return form. The value must be between -9999999999999.99 and 9999999999999.99. |
|
vatDueAcquisitions
number
required
|
VAT due on acquisitions from other EC Member States. This corresponds to box 2 on the VAT Return form. The value must be between -9999999999999.99 and 9999999999999.99. |
|
totalVatDue
number
required
|
Total VAT due (the sum of vatDueSales and vatDueAcquisitions). This corresponds to box 3 on the VAT Return form. The value must be between -9999999999999.99 and 9999999999999.99. |
|
vatReclaimedCurrPeriod
number
required
|
VAT reclaimed on purchases and other inputs (including acquisitions from the EC). This corresponds to box 4 on the VAT Return form. The value must be between -9999999999999.99 and 9999999999999.99. |
|
netVatDue
number
required
|
The difference between totalVatDue and vatReclaimedCurrPeriod. This corresponds to box 5 on the VAT Return form. The value must be between 0.00 and 99999999999.99 |
|
totalValueSalesExVAT
number
required
|
Total value of sales and all other outputs excluding any VAT. This corresponds to box 6 on the VAT Return form. The value must be in pounds (no pence) between -9999999999999 and 9999999999999. |
|
totalValuePurchasesExVAT
number
required
|
Total value of purchases and all other inputs excluding any VAT (including exempt purchases). This corresponds to box 7 on the VAT Return form. The value must be in pounds (no pence) between -9999999999999 and 9999999999999. |
|
totalValueGoodsSuppliedExVAT
number
required
|
Total value of all supplies of goods and related costs, excluding any VAT, to other EC member states. This corresponds to box 8 on the VAT Return form. The value must be in pounds (no pence) between -9999999999999 and 9999999999999. |
|
totalAcquisitionsExVAT
number
required
|
Total value of acquisitions of goods and related costs excluding any VAT, from other EC member states. This corresponds to box 9 on the VAT Return form. The value must be in pounds (no pence) between -9999999999999 and 9999999999999. |
|
finalised
boolean
required
|
Declaration that the user has finalised their VAT return.
For example: |
Response headers
| Name | Description |
|---|---|
|
X-CorrelationId
required
|
Unique id for operation tracking For example: c75f40a6-a3df-4429-a697-471eeec46435
|
|
Receipt-ID
required
|
Unique reference number returned for a submission For example: 2dd537bc-4244-4ebf-bac9-96321be13cdc
|
|
Receipt-Timestamp
required
|
The timestamp from the signature, in ISO8601 format For example: 2018-02-14T09:32:15Z
|
|
Receipt-Signature
required
|
This header is not currently used For example: DO NOT USE
|
See also fraud prevention for other request headers which will become mandatory.
Response
HTTP status: 201 (Created)
{
"processingDate": "2018-01-16T08:20:27.895+0000",
"paymentIndicator": "BANK",
"formBundleNumber": "256660290587",
"chargeRefNumber": "aCxFaNx0FZsCvyWF"
}
| Name | Description |
|---|---|
|
processingDate
string
required
|
The time that the message was processed in the system. |
|
formBundleNumber
string
required
|
Unique number that represents the form bundle. The system stores VAT Return data in forms, which are held in a unique form bundle.
Must conform to the regular expression |
|
paymentIndicator
string
optional
|
Is DD if the netVatDue value is a debit and HMRC holds a Direct Debit Instruction for the client. Is BANK if the netVatDue value is a credit and HMRC holds the client’s bank data. Otherwise not present. Limited to the following possible values: DD
BANK
|
|
chargeRefNumber
string
optional
|
The charge reference number is returned, only if the netVatDue value is a debit. Between 1 and 16 characters. |
Error scenarios
| Scenario | HTTP status | Code |
|---|---|---|
|
Invalid VRN |
400 (Bad Request) |
VRN_INVALID |
|
Invalid period key |
400 (Bad Request) |
PERIOD_KEY_INVALID |
|
Invalid request |
400 (Bad Request) |
INVALID_REQUEST |
|
totalVatDue should be equal to the sum of vatDueSales and vatDueAcquisitions |
400 (Bad Request) |
VAT_TOTAL_VALUE |
|
netVatDue should be the difference between the largest and the smallest values among totalVatDue and vatReclaimedCurrPeriod |
400 (Bad Request) |
VAT_NET_VALUE |
|
Please provide a numeric field |
400 (Bad Request) |
INVALID_NUMERIC_VALUE |
|
The monetary amount is invalid |
400 (Bad Request) |
INVALID_MONETARY_AMOUNT |
|
User has not declared VAT return as final |
403 (Forbidden) |
NOT_FINALISED |
|
User has already submitted a VAT return for the given period |
403 (Forbidden) |
DUPLICATE_SUBMISSION |
|
Return submitted too early |
403 (Forbidden) |
TAX_PERIOD_NOT_ENDED |
|
The client and/or agent is not authorised. This is normally because: the client is not subscribed to MTD, the agent is not subscribed to Agent Services, or the client has not authorised the agent to act on their behalf. |
403 (Forbidden) |
CLIENT_OR_AGENT_NOT_AUTHORISED |
For error scenarios that are common across all APIs, and for error formats, see our reference guide.
Test data
Scenario simulations using Gov-Test-Scenario headers are only available in sandbox environment.
Using this endpoint in the sandbox environment will store the data submitted. There is no requirement to use the periodKeys in the obligation response in the sandbox environment.
| Header Value (Gov-Test-Scenario) | Scenario |
|---|---|
INVALID_VRN |
Submission has not passed validation. Invalid parameter VRN. |
INVALID_PERIODKEY |
Submission has not passed validation. Invalid parameter PERIODKEY. |
INVALID_PAYLOAD |
Submission has not passed validation. Invalid parameter Payload |
DUPLICATE_SUBMISSION |
The remote endpoint has indicated that VAT has already been submitted for that period. |
TAX_PERIOD_NOT_ENDED |
The remote endpoint has indicated that the submission is for a tax period that has not ended. |
/organisations/vat/{vrn}/returns/{periodKey}
GET
Retrieve a submitted VAT return
Authorisation
This endpoint is
user-restricted
- it requires an Authorization header containing an OAuth 2.0 Bearer Token with the read:vat scope.
Path parameters
| Name | Description |
|---|---|
|
vrn
string
required
|
VAT registration number.
For example: |
|
periodKey
string
required
|
The ID code for the period that this obligation belongs to. The format is a string of four alphanumeric characters. Occasionally the format includes the “#” symbol, which must be URL-encoded.
For example: |
Request headers
| Name | Description |
|---|---|
|
Accept
required
|
Specifies the response format and the version of the API to be used. For example: application/vnd.hmrc.1.0+json
|
|
Gov-Test-Scenario
optional
|
Only in sandbox environment. See Test Data table for all header values. For example: -
|
|
Authorization
required
|
An
OAuth 2.0 Bearer Token
with the read:vat scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb
|
See also fraud prevention for other request headers which will become mandatory.
Response headers
| Name | Description |
|---|---|
|
X-CorrelationId
required
|
Unique id for operation tracking For example: c75f40a6-a3df-4429-a697-471eeec46435
|
See also fraud prevention for other request headers which will become mandatory.
Response
HTTP status: 200 (OK)
{
"periodKey": "A001",
"vatDueSales": 105.5,
"vatDueAcquisitions": -100.45,
"totalVatDue": 5.05,
"vatReclaimedCurrPeriod": 105.15,
"netVatDue": 100.1,
"totalValueSalesExVAT": 300,
"totalValuePurchasesExVAT": 300,
"totalValueGoodsSuppliedExVAT": 3000,
"totalAcquisitionsExVAT": 3000
}
{
"periodKey": "#001",
"vatDueSales": 100,
"vatDueAcquisitions": 100,
"totalVatDue": 200,
"vatReclaimedCurrPeriod": 100,
"netVatDue": 100,
"totalValueSalesExVAT": 500,
"totalValuePurchasesExVAT": 500,
"totalValueGoodsSuppliedExVAT": 500,
"totalAcquisitionsExVAT": 500
}
| Name | Description |
|---|---|
|
periodKey
string
required
|
The ID code for the period that this obligation belongs to. The format is a string of four alphanumeric characters. Occasionally the format includes the # symbol.
For example: |
|
vatDueSales
number
required
|
VAT due on sales and other outputs. This corresponds to box 1 on the VAT Return form. The value must be between -9999999999999.99 and 9999999999999.99. |
|
vatDueAcquisitions
number
required
|
VAT due on acquisitions from other EC Member States. This corresponds to box 2 on the VAT Return form. The value must be between -9999999999999.99 and 9999999999999.99. |
|
totalVatDue
number
required
|
Total VAT due (the sum of vatDueSales and vatDueAcquisitions). This corresponds to box 3 on the VAT Return form. The value must be between -9999999999999.99 and 9999999999999.99. |
|
vatReclaimedCurrPeriod
number
required
|
VAT reclaimed on purchases and other inputs (including acquisitions from the EC). This corresponds to box 4 on the VAT Return form. The value must be between -9999999999999.99 and 9999999999999.99. |
|
netVatDue
number
required
|
The difference between totalVatDue and vatReclaimedCurrPeriod. This corresponds to box 5 on the VAT Return form. The value must be between 0.00 and 99999999999.99 |
|
totalValueSalesExVAT
number
required
|
Total value of sales and all other outputs excluding any VAT. This corresponds to box 6 on the VAT Return form. The value must be between -9999999999999 and 9999999999999. |
|
totalValuePurchasesExVAT
number
required
|
Total value of purchases and all other inputs excluding any VAT (including exempt purchases). This corresponds to box 7 on the VAT Return form. The value must be between -9999999999999 and 9999999999999. |
|
totalValueGoodsSuppliedExVAT
number
required
|
Total value of all supplies of goods and related costs, excluding any VAT, to other EC member states. This corresponds to box 8 on the VAT Return form. The value must be between -9999999999999 and 9999999999999. |
|
totalAcquisitionsExVAT
number
required
|
Total value of acquisitions of goods and related costs excluding any VAT, from other EC member states. This corresponds to box 9 on the VAT Return form. The value must be between -9999999999999 and 9999999999999. |
Error scenarios
| Scenario | HTTP status | Code |
|---|---|---|
|
The provided VRN is invalid |
400 (Bad Request) |
VRN_INVALID |
|
Invalid period key |
400 (Bad Request) |
PERIOD_KEY_INVALID |
|
The date of the requested return cannot be more than four years from the current date |
403 (Forbidden) |
DATE_RANGE_TOO_LARGE |
|
The client and/or agent is not authorised. This is normally because: the client is not subscribed to MTD, the agent is not subscribed to Agent Services, or the client has not authorised the agent to act on their behalf. |
403 (Forbidden) |
CLIENT_OR_AGENT_NOT_AUTHORISED |
|
The remote endpoint has indicated that no associated data is found |
404 (Not Found) |
NOT_FOUND |
For error scenarios that are common across all APIs, and for error formats, see our reference guide.
Test data
Scenario simulations using Gov-Test-Scenario headers are only available in sandbox environment.
Using this endpoint in the sandbox environment will return the previously submitted data. A 404 (Not Found) response will be returned for a periodKey that has not been submitted.
| Header Value (Gov-Test-Scenario) | Scenario |
|---|---|
DATE_RANGE_TOO_LARGE |
The date of the requested return cannot be further than four years from the current date. |
/organisations/vat/{vrn}/liabilities
Retrieve VAT liabilities
Authorisation
This endpoint is
user-restricted
- it requires an Authorization header containing an OAuth 2.0 Bearer Token with the read:vat scope.
Path parameters
| Name | Description |
|---|---|
|
vrn
string
required
|
VAT registration number.
For example: |
Query parameters
| Name | Description |
|---|---|
|
from
string
required
|
Liabilities to return from date, the minimum 'from' date is 2017-12-01
For example: |
|
to
string
required
|
Liabilities to return up to date, the maximum 'to' date is the current date
For example: |
Request headers
| Name | Description |
|---|---|
|
Accept
required
|
Specifies the response format and the version of the API to be used. For example: application/vnd.hmrc.1.0+json
|
|
Gov-Test-Scenario
optional
|
Only in sandbox environment. See Test Data table for all header values. For example: -
|
|
Authorization
required
|
An
OAuth 2.0 Bearer Token
with the read:vat scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb
|
See also fraud prevention for other request headers which will become mandatory.
Response headers
| Name | Description |
|---|---|
|
X-CorrelationId
required
|
Unique id for operation tracking For example: c75f40a6-a3df-4429-a697-471eeec46435
|
See also fraud prevention for other request headers which will become mandatory.
Response
HTTP status: 200 (OK)
{
"liabilities": [{
"taxPeriod": {
"from": "2018-04-06",
"to": "2018-07-06"
},
"type": "VAT ...",
"originalAmount": 6000.3,
"outstandingAmount": 100.51,
"due": "2018-07-06"
}]
}
| Name | Description |
|---|---|
|
liabilities
array
required
|
Liability |
|
taxPeriod
object
optional
|
The tax period |
|
from
string
required
|
The from date of this tax period Date in the format
For example: |
|
to
string
required
|
The to date of this tax period Date in the format
For example: |
|
type
string
required
|
The charge type of this liability. Max length, 30 characters.
For example: |
|
originalAmount
number
required
|
The original liability value. Defines a monetary value (to 2 decimal places), between -9,999,999,999,999.99 and 9,999,999,999,999.99 |
|
outstandingAmount
number
optional
|
The outstanding liability value. Defines a monetary value (to 2 decimal places), between -9,999,999,999,999.99 and 9,999,999,999,999.99 |
|
due
string
optional
|
Liability due date Date in the format
For example: |
Error scenarios
| Scenario | HTTP status | Code |
|---|---|---|
|
Invalid VRN |
400 (Bad Request) |
VRN_INVALID |
|
Invalid date from |
400 (Bad Request) |
DATE_FROM_INVALID |
|
Invalid date to |
400 (Bad Request) |
DATE_TO_INVALID |
|
Invalid date range, must be 365 days or less |
400 (Bad Request) |
DATE_RANGE_INVALID |
|
The remote endpoint has indicated that no associated data is found |
404 (Not Found) |
NOT_FOUND |
|
The client and/or agent is not authorised. This is normally because: the client is not subscribed to MTD, the agent is not subscribed to Agent Services, or the client has not authorised the agent to act on their behalf. |
403 (Forbidden) |
CLIENT_OR_AGENT_NOT_AUTHORISED |
For error scenarios that are common across all APIs, and for error formats, see our reference guide.
Test data
Scenario simulations using Gov-Test-Scenario headers are only available in sandbox environment.
| Header Value (Gov-Test-Scenario) | Scenario |
|---|---|
SINGLE_LIABILITY |
Returns a single valid liability when used with dates from 2017-01-02 and to 2017-02-02. |
MULTIPLE_LIABILITIES |
Returns multiple valid liabilities when used with dates from 2017-04-05 and to 2017-12-21. |
SINGLE_LIABILITY_2018_19 |
Returns a single valid liability when used with dates from 2018-01-02 and to 2018-02-02. |
MULTIPLE_LIABILITIES_2018_19 |
Returns multiple valid liabilities when used with dates from 2018-04-05 and to 2018-12-21. |
The 'to' date of the liability must fall within the date range provided.
/organisations/vat/{vrn}/payments
Retrieve VAT payments
Authorisation
This endpoint is
user-restricted
- it requires an Authorization header containing an OAuth 2.0 Bearer Token with the read:vat scope.
Path parameters
| Name | Description |
|---|---|
|
vrn
string
required
|
VAT registration number.
For example: |
Query parameters
| Name | Description |
|---|---|
|
from
string
required
|
Payments to return from date, the minimum 'from' date is 2017-12-01
For example: |
|
to
string
required
|
Payments to return up to date, the maximum 'to' date is the current date
For example: |
Request headers
| Name | Description |
|---|---|
|
Accept
required
|
Specifies the response format and the version of the API to be used. For example: application/vnd.hmrc.1.0+json
|
|
Gov-Test-Scenario
optional
|
Only in sandbox environment. See Test Data table for all header values. For example: -
|
|
Authorization
required
|
An
OAuth 2.0 Bearer Token
with the read:vat scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb
|
See also fraud prevention for other request headers which will become mandatory.
Response headers
| Name | Description |
|---|---|
|
X-CorrelationId
required
|
Unique id for operation tracking For example: c75f40a6-a3df-4429-a697-471eeec46435
|
See also fraud prevention for other request headers which will become mandatory.
Response
HTTP status: 200 (OK)
{
"payments": [{
"amount": 100.05,
"received": "2018-04-06"
}]
}
| Name | Description |
|---|---|
|
payments
array
required
|
Payment |
|
amount
number
required
|
The payment value. Defines a monetary value (to 2 decimal places), between -9,999,999,999,999.99 and 9,999,999,999,999.99 |
|
received
string
optional
|
Payment received date Date in the format
For example: |
Error scenarios
| Scenario | HTTP status | Code |
|---|---|---|
|
Invalid VRN |
400 (Bad Request) |
VRN_INVALID |
|
Invalid date from |
400 (Bad Request) |
DATE_FROM_INVALID |
|
Invalid date to |
400 (Bad Request) |
DATE_TO_INVALID |
|
Invalid date range, must be 365 days or less |
400 (Bad Request) |
DATE_RANGE_INVALID |
|
The remote endpoint has indicated that no associated data is found |
404 (Not Found) |
NOT_FOUND |
|
The client and/or agent is not authorised. This is normally because: the client is not subscribed to MTD, the agent is not subscribed to Agent Services, or the client has not authorised the agent to act on their behalf. |
403 (Forbidden) |
CLIENT_OR_AGENT_NOT_AUTHORISED |
For error scenarios that are common across all APIs, and for error formats, see our reference guide.
Test data
Scenario simulations using Gov-Test-Scenario headers are only available in sandbox environment.
| Header Value (Gov-Test-Scenario) | Scenario |
|---|---|
SINGLE_PAYMENT |
Returns a single valid payment when used with dates from 2017-01-02 and to 2017-02-02. |
MULTIPLE_PAYMENTS |
Returns multiple valid payments when used with dates from 2017-02-27 and to 2017-12-21. |
SINGLE_PAYMENT_2018_19 |
Returns a single valid payment when used with dates from 2018-01-02 and to 2018-02-02. |
MULTIPLE_PAYMENTS_2018_19 |
Returns multiple valid payments when used with dates from 2018-02-27 and to 2018-12-21. |
The 'to' date of the payment must fall within the date range provided.