Skip to main content

Submit UK tax return

Overview

Under Pillar 2 requirements, MNEs and enterprise groups based in the UK have an obligation to submit a UK Tax Return (UKTR) for every accounting period. MNEs/groups (or their agents) can use the Pillar 2 API to submit the UKTR and meet this obligation.

The request structure has four variants created from two dependencies.

  1. Are the group entities UK only or are they a mixture of UK and non-UK entities? This information must be confirmed during registration for Pillar 2.
  2. Is the return a nil return?

The table here contains some information on the differences between the request variants. Liability returns (for MNEs and UK only entities) should include evidence of a company ID in the entityType field - this can be either the Company Reference Number (CRN) or the Unique Taxpayer Reference (UTR) for corporation tax.

Return Variant Description
Nil Return (MNE/UK) The obligationMTT field can be set to “true” or “false” for a multinational group.
Nil Return (UK Only) The obligationMTT field must be set to “false”.
Liability return (MNE/UK) Request includes totals for DTT, IIR, UTPR and overall total. The obligationMTT field cannot be set to “true” for a domestic (UK only) group. A domestic only or multinational can be liable for DTT.
Liability return (UK Only) Request includes totals for DTT and overall total. The obligationMTT field is set to “false” and the MTT fields totalLiabilityIIR, amountOwedIIR, totalLiabilityUTPR and amountOwedUTPR are all set to 0, or the request is rejected. A domestic only or multinational can be liable for DTT.

If the request is successful, it returns a response containing several pieces of information.

Name Description
Processing date Date and time the request was processed.
Form bundle Unique identifier for the request, to be noted and retained in case amendments need to be filed against the return.
Charge reference Identifier for any liabilities specified in the return. Nil returns do not return a charge reference.

Note: The diagrams in this section relate to the Pillar 2 testing environment only.

Testing

Before using the sandbox, please read through the API Testing Setup page of the service guide and work through all the required steps for creating a test user and organisation.

Scenario 1: Submit UK Tax Return

This scenario demonstrates submitting a UKTR that satisfies the “UKTR” obligationType.

Sequence diagram showing REST calls for testing submit UK Tax Return

Before submitting a tax return, a GET request can be sent using the Retrieve Obligations and Submissions endpoint to check the obligations defined for the organisation.

curl --request GET \
  --url 'https://test-api.service.hmrc.gov.uk/organisations/pillar-two/obligations-and-submissions?fromDate=2024-01-01&toDate=2024-12-31' \
  --header 'Authorization: Bearer YOUR_BEARER_TOKEN' \
  --header 'X-Pillar2-Id: YOUR_PILLAR2_ID' \
  --header 'Accept: application/vnd.hmrc.1.0+json'

The response will return obligations for all accounting periods that fall within the requested date range. This example shows two obligations which are open and due for the accounting period specified in the request.

{
  "processingDate": "2025-03-17T09:26:17Z",
  "accountingPeriodDetails": [
    {
      "startDate": "2024-01-01",
      "endDate": "2024-12-31",
      "dueDate": "2025-01-31",
      "underEnquiry": false,
      "obligations": [
        {
          "obligationType": "UKTR",
          "status": "Open",
          "canAmend": false,
          "submissions": []
        },
        {
          "obligationType": "GIR",
          "status": "Open",
          "canAmend": false,
          "submissions": []
        }
      ]
    }
  ]
}

The obligationType “UKTR” can be fulfilled by submitting a UKTR.

curl --request POST \
  --url 'https://test-api.service.hmrc.gov.uk/organisations/pillar-two/uk-tax-return' \
  --header 'Accept: application/vnd.hmrc.1.0+json' \
  --header 'Authorization: Bearer YOUR_BEARER_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'X-Pillar2-Id: YOUR_PILLAR2_ID' \
  --data '{
  "accountingPeriodFrom": "2024-01-01",
  "accountingPeriodTo": "2024-12-31",
  "obligationMTT": false,
  "electionUKGAAP": true,
  "liabilities": {
    "electionDTTSingleMember": false,
    "electionUTPRSingleMember": false,
    "numberSubGroupDTT": 1,
    "numberSubGroupUTPR": 1,
    "totalLiability": 5000,
    "totalLiabilityDTT": 5000,
    "totalLiabilityIIR": 0,
    "totalLiabilityUTPR": 0,
    "liableEntities": [
      {
        "ukChargeableEntityName": "Newco PLC",
        "idType": "CRN",
        "idValue": "12345678",
        "amountOwedDTT": 5000,
        "amountOwedIIR": 0,
        "amountOwedUTPR": 0
      }
    ]
  }
}'

If the Submit UK Tax Return request is successful, it will generate the following response.

{
  "processingDate": "2025-03-17T09:26:17Z",
  "formBundleNumber": "119000004320",
  "chargeReference": "XTC01234123412"
}

Sending a new request using the Retrieve Obligations and Submissions endpoint will display the successful submission and the fulfilled obligation.

{
  "processingDate": "2025-03-17T09:26:17Z",
  "accountingPeriodDetails": [
    {
      "startDate": "2024-01-01",
      "endDate": "2024-12-31",
      "dueDate": "2025-01-31",
      "underEnquiry": false,
      "obligations": [
        {
          "obligationType": "UKTR",
          "status": "Fulfilled",
          "canAmend": true,
          "submissions": [
            {
              "submissionType": "UKTR_CREATE",
              "receivedDate": "2025-03-17T09:26:17Z"
            }
          ]
        },
        {
          "obligationType": "GIR",
          "status": "Open",
          "canAmend": true,
          "submissions": []
        }
      ]
    }
  ]
}

Nil Return

If an organisation is required to submit a UKTR (to fulfill an obligation) but does not have any liabilities to declare, they will have to submit a “Nil Return”. A nil return is also submitted through the Submit UK Tax Return endpoint, but has a different structure.

curl --request POST \
  --url 'https://test-api.service.hmrc.gov.uk/organisations/pillar-two/uk-tax-return' \
  --header 'Accept: application/vnd.hmrc.1.0+json' \
  --header 'Authorization: Bearer YOUR_BEARER_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'X-Pillar2-Id: YOUR_PILLAR2_ID' \
  --data '{
  "accountingPeriodFrom": "2024-01-01",
  "accountingPeriodTo": "2024-12-31",
  "obligationMTT": false,
  "electionUKGAAP": true,
  "liabilities": {
    "returnType": "NIL_RETURN"
  }
}'

A successful response will not include a chargeReference as there is no charge in relation to a nil return.

{
  "processingDate": "2025-03-17T09:26:17Z",
  "formBundleNumber": "119000004320",
  "chargeReference": null
}

Duplicate Submissions

Once a UKTR has been submitted, it cannot be submitted again for the same accounting period. The Amend UK Tax Return endpoint must be used for any amendments.

Sequence diagram showing client error on duplicate submission

If a duplicate submission is received, a 422 client error response with code “044” will be returned.

{
  "errors": {
    "processingDate": "2025-03-17T09:26:17Z",
    "code": "044",
    "message": "Tax obligation already fulfilled"
  }
}