This version is in beta - expect some breaking changes.

VAT (MTD) API

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.

Warning You are required by law to submit header data for this API. This includes all associated APIs and endpoints.

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

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.

Skip to main content

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.

Authorisation

This endpoint is user-restricted and 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.
A nine-digit number.

For example: 123456789

Query parameters

Name Description
from
string
optional

Date from which to return obligations. Mandatory unless the status is O.

For example: 2017-01-25

to
string
optional

Date to which to return obligations. Mandatory unless the status is O.

For example: 2017-01-25

status
string
optional

Obligation status to return: O=Open, F= Fulfilled. Omit status to retrieve all obligations.

For example: F

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.

Responses

HTTP status 200 (OK)

Response headers

Name Description
X-CorrelationId
required

Unique id for operation tracking
String, 36 characters.

For example: 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 YYYY-MM-DD

For example: 2017-01-25

end
string
required

The end date of this obligation period

Date in the format YYYY-MM-DD

For example: 2017-01-25

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: F

received
string
optional

The obligation received date, is returned when status is (F = Fulfilled)

Date in the format YYYY-MM-DD

For example: 2017-01-25

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: 18AD, 18A1, #001

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.

Authorisation

This endpoint is user-restricted and 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.
A nine-digit number.

For example: 123456789

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.

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: 18AD, 18A1, #001

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: true

Responses

HTTP status 201 (Created)

Response headers

Name Description
X-CorrelationId
required

Unique id for operation tracking
String, 36 characters.

For example: c75f40a6-a3df-4429-a697-471eeec46435
Receipt-ID
required

Unique reference number returned for a submission
String, 36 characters.

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.

{
  "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 ^[0-9]{12}$

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

Authorisation

This endpoint is user-restricted and 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.
A nine-digit number.

For example: 123456789

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: 18AD, 18A1, #001

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.

Responses

HTTP status 200 (OK)

Response headers

Name Description
X-CorrelationId
required

Unique id for operation tracking
String, 36 characters.

For example: 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: 18AD, 18A1, #001

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

Authorisation

This endpoint is user-restricted and 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.
A nine-digit number.

For example: 123456789

Query parameters

Name Description
from
string
required

Liabilities to return from date, the minimum 'from' date is 2017-12-01

For example: 2018-01-25

to
string
required

Liabilities to return up to date, the maximum 'to' date is the current date

For example: 2018-12-31

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.

Responses

HTTP status 200 (OK)

Response headers

Name Description
X-CorrelationId
required

Unique id for operation tracking
String, 36 characters.

For example: 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 YYYY-MM-DD

For example: 2017-01-25

to
string
required

The to date of this tax period

Date in the format YYYY-MM-DD

For example: 2017-01-25

type
string
required

The charge type of this liability. Max length, 30 characters.

For example: VAT ...

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 YYYY-MM-DD

For example: 2017-01-25

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

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

Authorisation

This endpoint is user-restricted and 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.
A nine-digit number.

For example: 123456789

Query parameters

Name Description
from
string
required

Payments to return from date, the minimum 'from' date is 2017-12-01

For example: 2018-01-25

to
string
required

Payments to return up to date, the maximum 'to' date is the current date

For example: 2018-12-31

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.

Responses

HTTP status 200 (OK)

Response headers

Name Description
X-CorrelationId
required

Unique id for operation tracking
String, 36 characters.

For example: 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 YYYY-MM-DD

For example: 2017-01-25

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

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.

Authorisation

This endpoint is user-restricted and 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.
A nine-digit number.

For example: 123456789

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.

Responses

HTTP status 200 (OK)

Response headers

Name Description
X-CorrelationId
required

Unique id for operation tracking
String, 36 characters.

For example: c75f40a6-a3df-4429-a697-471eeec46435

See also fraud prevention.

all fields example 

{
  "totalisations": {
    "LSPTotalValue": 200,
    "penalisedPrincipalTotal": 2000,
    "LPPPostedTotal": 165.25,
    "LPPEstimatedTotal": 15.26
  },
  "lateSubmissionPenalty": {
    "summary": {
      "activePenaltyPoints": 2,
      "inactivePenaltyPoints": 10,
      "PoCAchievementDate": "2023-10-30",
      "regimeThreshold": 10,
      "penaltyChargeAmount": 684.25
    },
    "details": [
      {
        "penaltyNumber": "12345678901234",
        "penaltyOrder": "01",
        "penaltyCategory": "point",
        "penaltyStatus": "inactive",
        "FAPIndicator": "X",
        "penaltyCreationDate": "2023-10-30",
        "penaltyExpiryDate": "2024-04-31",
        "expiryReason": "appeal",
        "communicationsDate": "2023-10-30",
        "lateSubmissions": [
          {
            "lateSubmissionID": "123",
            "taxPeriod": "2023",
            "taxReturnStatus": "reversed",
            "taxPeriodStartDate": "2022-10-30",
            "taxPeriodEndDate": "2022-12-30",
            "taxPeriodDueDate": "2023-01-30",
            "returnReceiptDate": "2023-02-04"
          }
        ],
        "appealInformation": [
          {
            "appealStatus": "appeal-upheld",
            "appealLevel": "appeal-first-tier-tribunal"
          }
        ],
        "chargeReference": "12345678901234",
        "chargeAmount": 424.34,
        "chargeDueDate": "2023-06-30"
      },
      {
        "penaltyNumber": "43210987654321",
        "penaltyOrder": "02",
        "penaltyCategory": "point",
        "penaltyStatus": "active",
        "penaltyCreationDate": "2023-10-30",
        "penaltyExpiryDate": "2025-10-30",
        "communicationsDate": "2023-10-30" ,
        "lateSubmissions": [
          {
            "lateSubmissionID": "321",
            "taxPeriod": "2023",
            "taxReturnStatus": "open",
            "taxPeriodStartDate": "2023-01-30",
            "taxPeriodEndDate": "2023-03-30",
            "taxPeriodDueDate": "2023-04-30",
            "returnReceiptDate": "2023-05-04"
          }
        ],
        "chargeReference": "12345678901234",
        "chargeAmount": 534.34,
        "chargeOutstandingAmount": 132.26,
        "chargeDueDate": "2023-06-30"
      }
    ]
  },
  "latePaymentPenalty": {
    "details": [
      {
        "principalChargeReference": "12345678901234",
        "penaltyCategory": "LPP1",
        "penaltyStatus": "accruing",
        "penaltyAmountAccruing": 1435.21,
        "penaltyAmountPosted": 832.35,
        "penaltyAmountPaid": 529.35,
        "penaltyAmountOutstanding": 303,
        "LPP1LRCalculationAmount": 754.43,
        "LPP1LRPercentage": 2.00,
        "LPP1HRCalculationAmount": 724.24,
        "LPP1HRPercentage": 2.00,
        "LPP2Days": "12",
        "LPP2Percentage": 85.35,
        "penaltyChargeCreationDate": "2023-03-30",
        "communicationsDate": "2023-03-30",
        "penaltyChargeReference": "12345678901234",
        "penaltyChargeDueDate": "2023-04-30",
        "appealInformation": [
          {
            "appealStatus": "cannot-be-appealed",
            "appealLevel": "statutory-review"
          }
        ],
        "principalChargeDocNumber": "123456789012",
        "principalChargeMainTransaction": "4700",
        "principalChargeSubTransaction": "1174",
        "principalChargeBillingFrom": "2023-01-01",
        "principalChargeBillingTo": "2023-03-30",
        "principalChargeDueDate": "2023-04-30",
        "principalChargeLatestClearing": "2023-05-30",
        "timeToPay": [
          {
            "TTPStartDate": "2023-5-01",
            "TTPEndDate": "2023-5-30"
          }
        ]
      }
    ]
  }
}

Name Description
totalisations
object
optional

Totals that relate to the penalties that HMRC has levied.
LSPTotalValue
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: 200.00

penalisedPrincipalTotal
number
optional

Total value of Value Added Tax (VAT) owed before penalties and interest. The value must be between -99999999999.99 and 99999999999.99 up to 2 decimal places.

For example: 4286.55

LPPPostedTotal
number
optional

Total value of Late Payment Penalty (LPP) charged. The value must be between -99999999999.99 and 99999999999.99 up to 2 decimal places.

For example: 171.46

LPPEstimatedTotal
number
optional

Estimated total value of uncharged Late Payment Penalty (LPP) with amount accruing. The value must be between -99999999999.99 and 99999999999.99 up to 2 decimal places.

For example: 171.46

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: 1

inactivePenaltyPoints
number
required

Number of inactive penalty points.

For example: 4

PoCAchievementDate
string
required

This is the date that penalty points expire if customer meets requirements.

For example: 2023-04-01

regimeThreshold
number
required

Total number of penalty points required to generate a financial penalty.

For example: 6

penaltyChargeAmount
number
required

Total amount charged per penalty after reaching threshold. The value must be between -99999999999.99 and 99999999999.99 up to 2 decimal places.

For example: 200.00

details
array
required

Details of each late submission penalty that the individual or organisation has accrued.
penaltyNumber
string
required

This is used to identify the penalty points received within a set period.

For example: 12345678901234

penaltyOrder
string
required

Used to sort penalty points in order of the date the customer received the penalty.

For example: 01

penaltyCategory
string
required

This shows the category of the penalty object.

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

Shows if the penalty has been paid, or not been paid.

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.
FAPIndicator
string
optional

Indicates if there's been an adjustment to your 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

Date that the penalty point was created.

For example: 2022-07-01

penaltyExpiryDate
string
required

This is the date a penalty point will expire. If penalty points fall into a threshold, it will expire once compliance is met.

For example: 2024-07-01

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
required

This is the date that letters about a penalty are sent to users.

For example: 2022-07-01

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

Late Submission Identification linked to the penalty.

For example: 001

taxPeriod
string
optional

Tax period one failed to submit.

For example: 18AD

taxReturnStatus
string
required

This shows the status of a tax return.

Limited to the following possible values:

open
fulfilled
reversed
taxPeriodStartDate
string
optional

Start date of the obligation period for the penalty.

For example: 2022-04-01

taxPeriodEndDate
string
optional

End date of the obligation period for the penalty.

For example: 2022-06-30

taxPeriodDueDate
string
optional

Tax period due date that a failed submission happened.

For example: 2022-07-07

returnReceiptDate
string
optional

The date a VAT return submission was made.

For example: 2022-07-15

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:

appeal-to-HMRC
statutory-review
appeal-first-tier-tribunal
chargeReference
string
optional

Penalty charge reference

For example: 12345678901234

chargeAmount
number
optional

Total amount of Late Submission Penalty (LSP) charge. The value must be between -99999999999.99 and 99999999999.99 up to 2 decimal places.

For example: 200.00

chargeOutstandingAmount
number
optional

Total amount remaining on the penalty that needs to be paid. The value must be between -99999999999.99 and 99999999999.99 up to 2 decimal places.

For example: 103.12

chargeDueDate
string
optional

Late Submission Penalty (LSP) charge due date (30 days max)

For example: 2022-07-31

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

Principal Charge Reference number

For example: 1234567890

penaltyCategory
string
required

This shows if the penalty is LPP (Type 1) or an additional penalty (Type 2).

For example: LPP1

penaltyStatus
string
required

This is used to show the status of the penalty.

Limited to the following possible values:

accruing
posted
penaltyAmountAccruing
number
required

Total amount to be paid on penalty. The value must be between -99999999999.99 and 99999999999.99 up to 2 decimal places.

For example: 400.00

penaltyAmountPosted
number
required

Total amount to be paid on penalty. The value must be between -99999999999.99 and 99999999999.99 up to 2 decimal places.

For example: 400.00

penaltyAmountPaid
number
optional

Amount of the penalty that has already been paid. The value must be between -99999999999.99 and 99999999999.99 up to 2 decimal places.

For example: 100.00

penaltyAmountOutstanding
number
optional

Remaining amount on penalty to be paid. The value must be between -99999999999.99 and 99999999999.99 up to 2 decimal places.

For example: 300.00

LPP1LRCalculationAmount
number
optional

Amount of unpaid tax on day 16, after the due date. The value must be between -99999999999.99 and 99999999999.99 up to 2 decimal places.

For example: 3605.50

LPP1LRPercentage
number
optional

The percentage used to calculate the lower rate part of the penalty.

For example: 2.00

LPP1HRCalculationAmount
number
optional

Amount of unpaid tax on day 31, after the due date. The value must be between -99999999999.99 and 99999999999.99 up to 2 decimal places.

For example: 10000.00

LPP1HRPercentage
number
optional

The percentage used to calculate the higher rate part of the penalty.

For example: 2.00

LPP2Days
string
optional

The number of days since day 31 of the late penalty payment.

For example: 14

LPP2Percentage
number
optional

The rate applied to unpaid tax to calculate the penalty payment.

For example: 2.00

penaltyChargeCreationDate
string
required

This is the date when the penalty charge was created.

For example: 2022-07-08

communicationsDate
string
required

This is the date a letter was sent to the customer.

For example: 2022-07-09

penaltyChargeReference
string
optional

This is the identifier used to appeal

For example: 12345678901234

penaltyChargeDueDate
string
required

This is the date the penalty must be paid by.

For example: 2022-07-31

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:

appeal-to-HMRC
statutory-review
appeal-first-tier-tribunal
principalChargeDocNumber
string
required

Document number relating to VAT charge

For example: 123456789012

principalChargeMainTransaction
string
required

Used to identify the type of charge.
principalChargeSubTransaction
string
required

Used to identify the type of charge that the penalty was applied to.
principalChargeBillingFrom
string
required

principal Charge Billing date from
principalChargeBillingTo
string
required

principal Charge Billing date to
principalChargeDueDate
string
required

Principal Charge Due Date
principalChargeLatestClearing
string
optional

Principal Charge Latest Clearing
timeToPay
array
optional

Details of the Time to Pay arrangement that has been made.
TTPStartDate
string
optional

This is the start date of the agreed time to pay the charge.
TTPEndDate
string
optional

This is the last date of the agreed time to pay the charge.

Error scenarios

Scenario HTTP status Code

Invalid VRN

400 (Bad Request)

VRN_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

The default scenario which has multiple 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.

NOT_FOUND

The scenario where no penalties are found.

Close Section
/organisations/vat/{vrn}/financial-details/{searchItem}

Retrieve financial details [test only]
GET

Retrieves the financial details relating to a penalty that has been applied to a VAT account.

Authorisation

This endpoint is user-restricted and 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.
A nine-digit number.

For example: 123456789

searchItem
string
required

The 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: XC00178236592

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.

Responses

HTTP status 200 (OK)

Response headers

Name Description
X-CorrelationId
required

Unique id for operation tracking
String, 36 characters.

For example: 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
  },
  "documentDetails": [
    {
      "postingDate": "2022-03-01",
      "issueDate": "2022-03-01",
      "documentTotalAmount": 123.45,
      "documentClearedAmount": 111.11,
      "documentOutstandingAmount": 12.34,
      "documentInterestTotal": 1.23,
      "lineItemDetails": [
        {
          "periodFromDate": "2022-03-01",
          "periodToDate": "2022-03-01",
          "periodKey": "13RL",
          "netDueDate": "2022-03-01",
          "amount": 123.45,
          "lineItemInterestDetails": {
            "interestKey": "01",
            "interestStartDate": "2022-03-01"
          }
        }
      ]
    }
  ]
}

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: 5009.99

totalNotYetDue
number
optional

The charge amount that has been posted to the account, but is not yet overdue. The due date is in the future. The value must be between -99999999999.99 and 99999999999.99 to 2 decimal places.

For example: 5009.99

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: 5009.99

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: 5009.99

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: 5009.99

documentDetails
array
optional

All the documents that refer to the charge. An individual document will only contain one charge reference, but that charge reference could appear in multiple documents. 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: 2022-08-16

issueDate
string
optional

The date that correspondence about the charge was sent to the individual or organisation.

For example: 2022-08-16

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: 5009.99

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: 5009.99

documentOutstandingAmount
number
optional

The remaining balance. The value must be between -99999999999.99 and 99999999999.99 to 2 decimal places.

For example: 5009.99

documentInterestTotal
number
optional

The total amount of interest that is associated with the document. The value must be between -99999999999.99 and 99999999999.99 to 2 decimal places.

For example: 5009.99

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.
periodFromDate
string
optional

The start date of this period.

For example: 2022-08-16

periodToDate
string
optional

The end date of this period.

For example: 2022-08-16

periodKey
string
optional

A four-digit reference containing characters and numbers that identify a specific period of the due date.

For example: 13RL

netDueDate
string
optional

The due date for payment.

For example: 2022-08-16

amount
number
optional

The value must be between -99999999999.99 and 99999999999.99 to 2 decimal places.

For example: 5009.99

lineItemInterestDetails
object
optional
interestKey
string
optional

A specific line item that has been locked, rather than the entirety of the document. A two-digit reference to identify the interest key.

For example: 01

interestStartDate
string
optional

The date that the interest charges started.

For example: 2022-08-16

Error scenarios

Scenario HTTP status Code

Invalid VRN

400 (Bad Request)

VRN_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

The default scenario.

Close Section

Skip to main content

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