VAT (MTD) API
Date | Amount |
---|---|
Version and status | |
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
This API allows developers to:
- retrieve VAT obligations
- submit and view a VAT return
- retrieve a VAT liability
- retrieve a VAT payment
- retrieve VAT penalties [test only]
- retrieve financial details relating to a penalty [test only]
For more background on the VAT API, see the MTDfB VAT Guide for Vendors.
For information on how to connect to this API see the VAT MTD end-to-end service guide.
Send fraud prevention data
HMRC monitors transactions to help protect your customers' confidential data from criminals and fraudsters.
Check the data you need to send. You can also use the Test API during initial development and as part of your quality assurance checks.
Changelog
You can find the changelog in the vat-api GitHub wiki.
Support
- For non-technical, fraud prevention, and platform-related issues, you need to contact 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
GET
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.
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. application/vnd.hmrc.1.0+json
|
Gov-Test-Scenario
optional
|
Only in sandbox environment. See Test Data table for all header values. -
|
Authorization
required
|
An
OAuth 2.0 Bearer Token
with the read:vat scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb
|
See also fraud prevention.
Responses
HTTP status 200 (OK)
Response headers
Name | Description |
---|---|
X-CorrelationId
required
|
Unique id for operation tracking c75f40a6-a3df-4429-a697-471eeec46435
|
See also fraud prevention.
Quarterly obligations; one fulfilled
{ "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" } ] }
Monthly obligations; one fulfilled
{ "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 |
The request could not be completed as it relates to an insolvent trader, which are not supported by this API. |
403 (Forbidden) |
RULE_INSOLVENT_TRADER |
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. |
INSOLVENT_TRADER |
Simulates the scenario where the client is an insolvent trader. |
NOT_FOUND |
Simulates the scenario where no data is found. |
Close Section
/organisations/vat/{vrn}/returns
Submit VAT return for period
POST
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.
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. application/vnd.hmrc.1.0+json
|
Content-Type
required
|
Specifies the format of the request body, which must be JSON. application/json
|
Gov-Test-Scenario
optional
|
Only in sandbox environment. See Test Data table for all header values. -
|
Authorization
required
|
An
OAuth 2.0 Bearer Token
with the write:vat scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb
|
See also fraud prevention.
Request
Scenario: VAT Return with decimals
{ "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 }
Scenario: VAT Return with a hash in the periodKey
{ "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 in the period on acquisitions of goods made in Northern Ireland from EU 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 in the period on purchases and other inputs (including acquisitions in Northern Ireland from EU member states). 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 dispatches of goods and related costs (excluding VAT) from Northern Ireland to EU 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 VAT) made in Northern Ireland from EU 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: |
Responses
HTTP status 201 (Created)
Response headers
Name | Description |
---|---|
X-CorrelationId
required
|
Unique id for operation tracking c75f40a6-a3df-4429-a697-471eeec46435
|
Receipt-ID
required
|
Unique reference number returned for a submission 2dd537bc-4244-4ebf-bac9-96321be13cdc
|
Receipt-Timestamp
required
|
The timestamp from the signature, in ISO8601 format 2018-02-14T09:32:15Z
|
Receipt-Signature
required
|
This header is not currently used DO NOT USE
|
See also fraud prevention.
{ "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 |
The request could not be completed as it relates to an insolvent trader, which are not supported by this API. |
403 (Forbidden) |
RULE_INSOLVENT_TRADER |
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. |
INSOLVENT_TRADER |
Simulates the scenario where the client is an insolvent trader. |
Close Section
/organisations/vat/{vrn}/returns/{periodKey}
View VAT Return
GET
Retrieve a submitted VAT return
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. application/vnd.hmrc.1.0+json
|
Gov-Test-Scenario
optional
|
Only in sandbox environment. See Test Data table for all header values. -
|
Authorization
required
|
An
OAuth 2.0 Bearer Token
with the read:vat scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb
|
See also fraud prevention.
Responses
HTTP status 200 (OK)
Response headers
Name | Description |
---|---|
X-CorrelationId
required
|
Unique id for operation tracking c75f40a6-a3df-4429-a697-471eeec46435
|
See also fraud prevention.
VAT Return with decimals
{ "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 }
VAT Return with a hash in the periodKey
{ "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 in the period on acquisitions of goods made in Northern Ireland from EU 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 in the period on purchases and other inputs (including acquisitions in Northern Ireland from EU member states). 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 dispatches of goods and related costs (excluding VAT) from Northern Ireland to EU 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 VAT) made in Northern Ireland from EU Member States. This corresponds to box 9 on the VAT Return form. The value must be in pounds (no pence) 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 request could not be completed as it relates to an insolvent trader, which are not supported by this API. |
403 (Forbidden) |
RULE_INSOLVENT_TRADER |
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. |
INSOLVENT_TRADER |
Simulates the scenario where the client is an insolvent trader. |
Close Section
/organisations/vat/{vrn}/liabilities
Retrieve VAT liabilities
GET
Retrieve VAT liabilities
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. application/vnd.hmrc.1.0+json
|
Gov-Test-Scenario
optional
|
Only in sandbox environment. See Test Data table for all header values. -
|
Authorization
required
|
An
OAuth 2.0 Bearer Token
with the read:vat scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb
|
See also fraud prevention.
Responses
HTTP status 200 (OK)
Response headers
Name | Description |
---|---|
X-CorrelationId
required
|
Unique id for operation tracking c75f40a6-a3df-4429-a697-471eeec46435
|
See also fraud prevention.
{ "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 |
The request could not be completed as it relates to an insolvent trader, which are not supported by this API. |
403 (Forbidden) |
RULE_INSOLVENT_TRADER |
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 endpoint has indicated that no associated data could be found. |
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. |
INSOLVENT_TRADER |
Simulates the scenario where the client is an insolvent trader. |
The 'to' date of the liability must fall within the date range provided.
Close Section
/organisations/vat/{vrn}/payments
Retrieve VAT payments
GET
Retrieve VAT payments
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. application/vnd.hmrc.1.0+json
|
Gov-Test-Scenario
optional
|
Only in sandbox environment. See Test Data table for all header values. -
|
Authorization
required
|
An
OAuth 2.0 Bearer Token
with the read:vat scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb
|
See also fraud prevention.
Responses
HTTP status 200 (OK)
Response headers
Name | Description |
---|---|
X-CorrelationId
required
|
Unique id for operation tracking c75f40a6-a3df-4429-a697-471eeec46435
|
See also fraud prevention.
{ "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 |
The request could not be completed as it relates to an insolvent trader, which are not supported by this API. |
403 (Forbidden) |
RULE_INSOLVENT_TRADER |
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 endpoint has indicated that no associated data could be found. |
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. |
INSOLVENT_TRADER |
Simulates the scenario where the client is an insolvent trader. |
The 'to' date of the payment must fall within the date range provided.
Close Section
/organisations/vat/{vrn}/penalties
Retrieve VAT penalties [test only]
GET
Retrieves details of all the penalties that have been applied to a VAT account. Twenty-four months' worth of penalty information will be returned.
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. application/vnd.hmrc.1.0+json
|
Gov-Test-Scenario
optional
|
Only in sandbox environment. See Test Data table for all header values. -
|
Authorization
required
|
An
OAuth 2.0 Bearer Token
with the read:vat scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb
|
See also fraud prevention.
Responses
HTTP status 200 (OK)
Response headers
Name | Description |
---|---|
X-CorrelationId
required
|
Unique id for operation tracking c75f40a6-a3df-4429-a697-471eeec46435
|
See also fraud prevention.
Example of an account with no penalties
{}
All fields example
{ "totalisations": { "lateSubmissionPenaltyTotalValue": 400, "penalisedPrincipalTotal": 10000, "latePaymentPenaltyPostedTotal": 425.21, "latePaymentPenaltyEstimateTotal": 30.68 }, "lateSubmissionPenalty": { "summary": { "activePenaltyPoints": 4, "inactivePenaltyPoints": 1, "periodOfComplianceAchievement": "2025-05-01", "regimeThreshold": 4, "penaltyChargeAmount": 400 }, "details": [ { "penaltyNumber": "00004", "penaltyOrder": "4", "penaltyCategory": "point", "penaltyStatus": "inactive", "frequencyAdjustmentPointIndicator": "X", "penaltyCreationDate": "2023-11-08", "penaltyExpiryDate": "2025-12-01", "expiryReason": "appeal", "communicationsDate": "2023-11-11", "lateSubmissions": [ { "lateSubmissionID": "1054600", "taxReturnStatus": "Fulfilled", "taxPeriodStartDate": "2023-07-01", "taxPeriodEndDate": "2023-09-30", "taxPeriodDueDate": "2023-11-07", "returnReceiptDate": "2023-11-13" } ], "appealInformation": [ { "appealStatus": "appeal-upheld", "appealLevel": "statutory-review" } ] }, { "penaltyNumber": "00005", "penaltyOrder": "5", "penaltyCategory": "threshold", "penaltyStatus": "active", "penaltyCreationDate": "2024-02-08", "penaltyExpiryDate": "2026-03-01", "communicationsDate": "2024-02-11", "lateSubmissions": [ { "lateSubmissionID": "1054700", "taxReturnStatus": "Fulfilled", "taxPeriodStartDate": "2023-10-01", "taxPeriodEndDate": "2023-12-31", "taxPeriodDueDate": "2024-02-07", "returnReceiptDate": "2024-02-15" } ], "chargeReference": "XS198765432109", "chargeAmount": 200, "chargeOutstandingAmount": 200, "chargeDueDate": "2024-02-28" }, { "penaltyNumber": "00006", "penaltyOrder": "6", "penaltyCategory": "charge", "penaltyStatus": "active", "penaltyCreationDate": "2024-05-08", "penaltyExpiryDate": "2026-06-01", "communicationsDate": "2024-05-11", "lateSubmissions": [ { "lateSubmissionID": "1054800", "taxReturnStatus": "Fulfilled", "taxPeriodStartDate": "2024-01-01", "taxPeriodEndDate": "2024-03-31", "taxPeriodDueDate": "2024-05-07", "returnReceiptDate": "2024-11-12" } ], "chargeReference": "XS212345678901", "chargeAmount": 200, "chargeOutstandingAmount": 200, "chargeDueDate": "2024-02-28" } ] }, "latePaymentPenalty": { "details": [ { "principalChargeReference": "XV123451234512", "penaltyCategory": "LPP1", "penaltyStatus": "posted", "penaltyAmountAccruing": 0, "penaltyAmountPosted": 400, "penaltyAmountPaid": 0, "penaltyAmountOutstanding": 400, "latePaymentPenalty1LowerRateCalculationAmount": 10000, "latePaymentPenalty1LowerRatePercentage": 2, "latePaymentPenalty1HigherRateCalculationAmount": 10000, "latePaymentPenalty1HigherRatePercentage": 4, "penaltyChargeCreationDate": "2024-06-06", "communicationsDate": "2024-06-09", "penaltyChargeReference": "XP123456789012", "penaltyChargeDueDate": "2024-07-06", "principalChargeDocNumber": "10023852", "principalChargeBillingFrom": "2024-01-01", "principalChargeBillingTo": "2024-03-31", "principalChargeDueDate": "2024-05-07", "principalChargeLatestClearing": "2024-07-31", "timeToPay": [ { "timeToPayStartDate": "2024-07-06", "timeToPayEndDate": "2024-07-11" } ], "appealInformation": [ { "appealStatus": "appeal-rejected", "appealLevel": "statutory-review" } ] }, { "principalChargeReference": "XV123451234512", "penaltyCategory": "LPP2", "penaltyStatus": "accruing", "penaltyAmountAccruing": 30.68, "penaltyAmountPosted": 25.21, "penaltyAmountPaid": 0, "penaltyAmountOutstanding": 25.21, "latePaymentPenalty2Days": "23", "latePaymentPenalty2Percentage": 4, "penaltyChargeCreationDate": "2024-07-01", "communicationsDate": "2024-07-04", "penaltyChargeReference": "XP298765432109", "penaltyChargeDueDate": "2024-08-07", "principalChargeDocNumber": "10023852", "principalChargeBillingFrom": "2024-01-01", "principalChargeBillingTo": "2024-03-31", "principalChargeDueDate": "2024-05-07", "principalChargeLatestClearing": "2024-07-31" } ] } }
Name | Description |
---|---|
totalisations
object
optional
|
Totals that relate to the penalties that HMRC has levied. |
lateSubmissionPenaltyTotalValue
number
optional
|
Total value of all unpaid late submission penalties. The value must be between -99999999999.99 and 99999999999.99 up to 2 decimal places.
For example: |
penalisedPrincipalTotal
number
optional
|
Total amount of late VAT (before penalties and interest). The value must be between -99999999999.99 and 99999999999.99 up to 2 decimal places.
For example: |
latePaymentPenaltyPostedTotal
number
optional
|
Total amount of late payment penalty charges. The value must be between -99999999999.99 and 99999999999.99 up to 2 decimal places.
For example: |
latePaymentPenaltyEstimateTotal
number
optional
|
Estimated total amount of uncharged late payment penalties, based upon the amount that is accruing. The value must be between -99999999999.99 and 99999999999.99 up to 2 decimal places.
For example: |
lateSubmissionPenalty
object
optional
|
Information about the late submission penalties that HMRC has levied. |
summary
object
required
|
A summary of the individual's or organisation's late submission penalty status. |
activePenaltyPoints
number
required
|
Number of active penalty points held for failure to submit on time.
For example: |
inactivePenaltyPoints
number
required
|
Number of inactive penalty points.
For example: |
periodOfComplianceAchievement
string
required
|
The date upon which all accrued penalty points will expire, if the individual or organisation meets the requirements for compliance.
For example: |
regimeThreshold
number
required
|
Total number of penalty points that are required before a financial penalty will be generated.
For example: |
penaltyChargeAmount
number
required
|
The total late submission penalty charge amount. The value must be between -99999999999.99 and 99999999999.99 up to 2 decimal places.
For example: |
details
array
required
|
Details of each late submission penalty that the individual or organisation has accrued. |
penaltyNumber
string
required
|
The unique identification number for the penalty.
For example: |
penaltyOrder
string
required
|
The position that the penalty currently occupies within the individual's or organisation's point balance.
For example: |
penaltyCategory
string
required
|
The category of the penalty. Limited to the following possible values: point
- The penalty represents a point that has not met the threshold for a charge.
charge
- The penalty represents a charge that has been levied because the point threshold has been exceeded. Although this penalty will not be added to the point total because the threshold has already been met, it will affect the period of compliance.
threshold
- The penalty represents a point that has met the threshold for a charge. The penalty thus consists of a point and a charge.
|
penaltyStatus
string
required
|
The status of the penalty. Its meaning depends upon the penalty's category. Limited to the following possible values: active
- If the penalty category is 'point', it counts towards the individual's or organisation's point balance. If the penalty category is 'threshold', it counts towards the individual's or organisation's point balance. It has also triggered a penalty charge. If the penalty category is 'charge', then it represents a charge that has been levied because the threshold has been exceeded.
inactive
- If the penalty category is 'point', it no longer counts towards the individual's or organisation's point balance. This might be because the point has expired, been successfully appealed against, or been removed due to an adjustment. If the penalty category is 'threshold', then it no longer counts towards the individual's or organisation's point balance for the same reasons. Alternatively, a 'threshold' penalty could be inactive because the charge that is associated with it has been reversed. If the penalty category is 'charge', then the charge has been reversed.
|
frequencyAdjustmentPointIndicator
string
optional
|
Indicates whether there has been an adjustment to the penalty point because of a change to your submission frequency (for example, changing from quarterly submissions to monthly submissions). Limited to the following possible values: X
|
penaltyCreationDate
string
required
|
The date that the penalty point was created.
For example: |
penaltyExpiryDate
string
required
|
The date that the penalty point will expire. If the penalty falls within the points threshold, it will expire once compliance is met.
For example: |
expiryReason
string
optional
|
The reason why a penalty point has expired. Limited to the following possible values: appeal
- The penalty point has expired due to a successful appeal.
submission-frequency-change
- The penalty point has expired due to a change in the user's submission frequency.
obligations-reversed
- A change has resulted in the user's obligations being reversed. For example, a user might have deregistered for VAT before a submission was due.
HMRC-removed
- An HMRC officer has removed the penalty. This might happen, for example, following a decision made by a tribunal.
natural-expiry
- The penalty point has expired naturally. For example, it has reached the end of its 24-month lifetime.
penalty-removed
- The penalty has been removed because the submission was deemed to be on time.
expiry-conditions-met
- The penalty point has expired because the user has met the conditions for the expiry of all active penalty points.
HMRC-reset
- An HMRC officer has reset the user's penalty points to zero.
|
communicationsDate
string
optional
|
The date when a letter about the penalty was sent to the customer.
For example: |
lateSubmissions
array
optional
|
The late submissions that relate to the period for which the penalty was levied. Note that although only one penalty point will be levied for late submissions of a particular type of obligation during a calendar month, more than one late submission of that type could be made during the month. In that case, the lateSubmissions array will contain more than one object. All of these late submissions are incorporated within the single penalty point and affect the period of compliance and expiry date (which will be set by the date of the most recent failure). |
lateSubmissionID
string
required
|
The unique identification number for the late submission penalty.
For example: |
taxReturnStatus
string
required
|
The status of the tax return. Limited to the following possible values: Open
- The VAT return is yet to be submitted.
Fulfilled
- The obligation has been met (whether the submission was late or not).
Reversed
- The obligation no longer exists. The individual or organisation is therefore not required to submit any information.
|
taxPeriodStartDate
string
optional
|
Start date of the VAT period to which the penalty relates.
For example: |
taxPeriodEndDate
string
optional
|
End date of the VAT period to which the penalty relates.
For example: |
taxPeriodDueDate
string
optional
|
The due date for the VAT return, which was missed and gave rise to the late submission penalty.
For example: |
returnReceiptDate
string
optional
|
The date upon which the VAT return was submitted.
For example: |
appealInformation
array
optional
|
Details of any appeals that the individual or organisation has made against the penalty point. |
appealStatus
string
required
|
The appeal status of a penalty. Limited to the following possible values: under-appeal
appeal-upheld
appeal-rejected
cannot-be-appealed
|
appealLevel
string
required
|
The level of appeal. Limited to the following possible values: statutory-review
appeal-first-tier-tribunal
|
chargeReference
string
optional
|
The late submission penalty charge reference.
For example: |
chargeAmount
number
optional
|
The late submission penalty charge amount. The value must be between -99999999999.99 and 99999999999.99 up to 2 decimal places.
For example: |
chargeOutstandingAmount
number
optional
|
The penalty charge amount that remains to be paid. The value must be between -99999999999.99 and 99999999999.99 up to 2 decimal places.
For example: |
chargeDueDate
string
optional
|
The due date for the late submission penalty charge (this will be a maximum of 30 days after the submission was originally due).
For example: |
latePaymentPenalty
object
optional
|
Information about the late payment penalties that HMRC has levied. |
details
array
optional
|
Details of all the late payment penalties that the individual or organisation has accrued. |
principalChargeReference
string
required
|
The reference for the principal charge upon which the late payment penalty is based. This is the original charge that was not paid on time (typically the VAT return charge reference).
For example: |
penaltyCategory
string
required
|
The category of the penalty. This specifies whether the penalty is a first late payment penalty (LPP1) or a second late payment penalty (LPP2).
For example: |
penaltyStatus
string
required
|
The status of the penalty. Limited to the following possible values: accruing
- The penalty is accruing, and is yet to be posted to the account.
posted
- The penalty has been posted to the account.
|
penaltyAmountAccruing
number
required
|
The unposted penalty amount that is accruing. The value must be between -99999999999.99 and 99999999999.99 up to 2 decimal places.
For example: |
penaltyAmountPosted
number
required
|
The penalty amount that has been posted to the account. The value must be between -99999999999.99 and 99999999999.99 up to 2 decimal places.
For example: |
penaltyAmountPaid
number
optional
|
The penalty amount that has already been paid. The value must be between -99999999999.99 and 99999999999.99 up to 2 decimal places.
For example: |
penaltyAmountOutstanding
number
optional
|
The remaining penalty amount to be paid. The value must be between -99999999999.99 and 99999999999.99 up to 2 decimal places.
For example: |
latePaymentPenalty1LowerRateCalculationAmount
number
optional
|
The amount of VAT that remained unpaid 16 days after the due date. The value must be between -99999999999.99 and 99999999999.99 up to 2 decimal places.
For example: |
latePaymentPenalty1LowerRatePercentage
number
optional
|
The percentage used to calculate the lower-rate part of the first late payment penalty.
For example: |
latePaymentPenalty1HigherRateCalculationAmount
number
optional
|
The amount of VAT that remained unpaid 31 days after the due date. The value must be between -99999999999.99 and 99999999999.99 up to 2 decimal places.
For example: |
latePaymentPenalty1HigherRatePercentage
number
optional
|
The percentage used to calculate the higher-rate part of the first late payment penalty.
For example: |
latePaymentPenalty2Days
string
optional
|
The number of days over which the second late payment penalty has accrued. This is the number of days that have elapsed since day 31 after the VAT payment due date.
For example: |
latePaymentPenalty2Percentage
number
optional
|
The percentage rate that has been applied to unpaid VAT in order to calculate the second late payment penalty.
For example: |
penaltyChargeCreationDate
string
optional
|
The date when the penalty charge was created.
For example: |
communicationsDate
string
optional
|
The date when a letter about the penalty was sent to the customer.
For example: |
penaltyChargeReference
string
optional
|
The late payment penalty charge reference.
For example: |
penaltyChargeDueDate
string
optional
|
The date that the penalty must be paid by.
For example: |
appealInformation
array
optional
|
|
appealStatus
string
required
|
The appeal status of a penalty. Limited to the following possible values: under-appeal
appeal-upheld
appeal-rejected
cannot-be-appealed
|
appealLevel
string
required
|
The level of appeal. Limited to the following possible values: statutory-review
appeal-first-tier-tribunal
|
principalChargeDocNumber
string
required
|
Document number relating to the VAT charge.
For example: |
principalChargeBillingFrom
string
required
|
The start date of the obligation period.
For example: |
principalChargeBillingTo
string
required
|
The end date of the obligation period.
For example: |
principalChargeDueDate
string
required
|
The date that the principal charge should have been paid by.
For example: |
principalChargeLatestClearing
string
optional
|
The date that the principal charge was paid.
For example: |
timeToPay
array
optional
|
Details of the Time to Pay arrangement that has been made. |
timeToPayStartDate
string
optional
|
This is the start date of the agreed time to pay the charge.
For example: |
timeToPayEndDate
string
optional
|
This is the last date of the agreed time to pay the charge.
For example: |
Error scenarios
Scenario | HTTP status | Code |
---|---|---|
Invalid VRN. |
400 (Bad Request) |
VRN_INVALID |
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 |
The default scenario which has multiple penalties in the last 2 years. |
NO_PENALTIES |
The scenario where there are no penalties in the last 2 years. |
LATE_SUBMISSION |
The scenario where there is a single late submission penalty in the last 2 years. |
LATE_PAYMENT |
The scenario where there is a single late payment penalty in the last 2 years. |
MULTIPLE_PENALTIES |
The scenario where there is a single late submission penalty and a single late payment penalty in the last 2 years. |
MULTIPLE_LATE_PAYMENT_PENALTIES |
The scenario where there are multiple late payment penalties in the last 2 years. |
MULTIPLE_LATE_SUBMISSION_PENALTIES |
The scenario where there are multiple late submission penalties in the last 2 years. |
THRESHOLD_LATE_SUBMISSION_PENALTIES |
The scenario where the number of penalties meets the penalty point threshold and the first charge has been generated. |
CHARGE_LATE_SUBMISSION_PENALTIES |
The scenario where the number of penalties exceeds the penalty point threshold and a second charge has been generated. |
Close Section
/organisations/vat/{vrn}/financial-details/{penaltyChargeReference}
Retrieve financial details [test only]
GET
Retrieves the financial details relating to a late submission or late payment penalty that has been applied to a VAT account.
Path parameters
Name | Description |
---|---|
vrn
string
required
|
VAT registration number.
For example: |
penaltyChargeReference
string
required
|
The late submission or late payment penalty charge reference, which has been obtained from the Retrieve VAT penalties endpoint. Only the financial details that relate to this charge will be returned.
For example: |
Request headers
Name | Description |
---|---|
Accept
required
|
Specifies the response format and the version of the API to be used. application/vnd.hmrc.1.0+json
|
Gov-Test-Scenario
optional
|
Only in sandbox environment. See Test Data table for all header values. -
|
Authorization
required
|
An
OAuth 2.0 Bearer Token
with the read:vat scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb
|
See also fraud prevention.
Responses
HTTP status 200 (OK)
Response headers
Name | Description |
---|---|
X-CorrelationId
required
|
Unique id for operation tracking c75f40a6-a3df-4429-a697-471eeec46435
|
See also fraud prevention.
all fields example
{ "totalisations": { "totalOverdue": 123.45, "totalNotYetDue": 12.34, "totalBalance": 12.45, "totalCredit": 13.46, "totalCleared": 12.35, "additionalReceivableTotalisations" :{ "totalAccountPostedInterest": 13.12, "totalAccountAccruingInterest": 12.10 } }, "documentDetails": [ { "postingDate": "2024-05-07", "issueDate": "2024-05-07", "documentTotalAmount": 123.45, "documentClearedAmount": 111.11, "documentOutstandingAmount": 12.34, "documentInterestTotals": { "interestPostedAmount": 13.12, "interestAccruingAmount": 12.10 }, "lineItemDetails": [ { "chargeDescription": "VAT Return", "periodFromDate": "2024-01-01", "periodToDate": "2024-03-31", "netDueDate": "2024-05-07", "amount": 123.45, "lineItemInterestDetails": { "interestStartDate": "2024-05-08", "currentInterestRate": 2, "interestPostedAmount": 13.12, "interestAccruingAmount": 12.10 } } ] } ] }
Name | Description |
---|---|
totalisations
object
optional
|
Totals that relate to the charge. |
totalOverdue
number
optional
|
The charge amount that is overdue (collectable now). The value must be between -99999999999.99 and 99999999999.99 to 2 decimal places.
For example: |
totalNotYetDue
number
optional
|
The charge amount that has been posted to the account, but is not yet overdue. The due date is today or in the future. The value must be between -99999999999.99 and 99999999999.99 to 2 decimal places.
For example: |
totalBalance
number
optional
|
The net charge amount (the amount that is overdue, minus any credit that is in the account). The value must be between -99999999999.99 and 99999999999.99 to 2 decimal places.
For example: |
totalCredit
number
optional
|
Credit that is in the individual's or organisation's account, which has not yet been allocated to any charges. The value must be between -99999999999.99 and 99999999999.99 to 2 decimal places.
For example: |
totalCleared
number
optional
|
The amount that has been paid, reversed, removed or cleared. The value must be between -99999999999.99 and 99999999999.99 to 2 decimal places.
For example: |
additionalReceivableTotalisations
object
optional
|
Interest totals that relate to the VAT account. |
totalAccountPostedInterest
number
optional
|
The total amount of interest that HMRC has actually posted to the account.
For example: |
totalAccountAccruingInterest
number
optional
|
The total amount of unposted interest that the account has currently accrued.
For example: |
documentDetails
array
optional
|
All the documents that relate to the charge. An individual document will only relate to one charge reference, but there could be multiple documents relating to that charge reference. For example, this might be the case if a charge has been levied and subsequently reversed, or if multiple periodic interest charges share the same charge reference. |
postingDate
string
optional
|
The date that the charge was posted to the individual's or organisation's account.
For example: |
issueDate
string
optional
|
The date that correspondence about the charge was sent to the individual or organisation.
For example: |
documentInterestTotals
object
optional
|
Interest totals that relate to the charge. |
interestPostedAmount
number
optional
|
The amount of interest, relating to the charge, that HMRC has actually posted to the account.
For example: |
interestAccruingAmount
number
optional
|
The amount of unposted interest that has currently accrued on the charge.
For example: |
documentTotalAmount
number
optional
|
The total sum of the line items within the document. The value must be between -99999999999.99 and 99999999999.99 to 2 decimal places.
For example: |
documentClearedAmount
number
optional
|
The amount that has been paid, reversed, removed or cleared. For example, this could be the portion of a charge that has already been paid. The value must be between -99999999999.99 and 99999999999.99 to 2 decimal places.
For example: |
documentOutstandingAmount
number
optional
|
The remaining balance. The value must be between -99999999999.99 and 99999999999.99 to 2 decimal places.
For example: |
lineItemDetails
array
optional
|
The line items that make up the document. A document can contain more than one line item. For example, an individual or organisation might submit an amendment form that contains multiple corrections (perhaps the individual or organisation paid too much VAT for one tax period, but not enough for the next). Each correction will comprise an individual line item. HMRC will take all of the line items into account when it calculates the charge. |
chargeDescription
string
optional
|
Describes what the charge relates to.
For example: |
periodFromDate
string
optional
|
The start date of this period.
For example: |
periodToDate
string
optional
|
The end date of this period.
For example: |
netDueDate
string
optional
|
The due date for payment.
For example: |
amount
number
optional
|
The amount. The value must be between -99999999999.99 and 99999999999.99 to 2 decimal places.
For example: |
lineItemInterestDetails
object
optional
|
Details of the interest that relates to the line item. |
interestStartDate
string
optional
|
The date that the interest charges started.
For example: |
currentInterestRate
number
optional
|
The rate of interest that currently applies to the line item.
For example: |
interestPostedAmount
number
optional
|
The amount of interest, relating to the line item, that HMRC has actually posted to the account. Interest will continue to be posted at the end of each month, until the customer pays the charge upon which the interest is based. At this point, a final interest charge will be calculated and posted.
For example: |
interestAccruingAmount
number
optional
|
The amount of unposted interest that has accrued on the line item to date, since the interest start date.
For example: |
Error scenarios
Scenario | HTTP status | Code |
---|---|---|
Invalid VRN. |
400 (Bad Request) |
VRN_INVALID |
The specified penalty charge reference is invalid. |
400 (Bad Request) |
CHARGE_REFERENCE_INVALID |
The remote endpoint has indicated that no associated data is found. |
404 (Not Found) |
MATCHING_RESOURCE_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 |
The default scenario. |
Close Section