Tax Return

Prerequisites

You will need to log in to the API Gateway by retrieving an access token from the identity service. The moneyhub-api-client can be used to retrieve this, make sure the API client is configured correctly to do this. If you choose to not use the moneyhub-api-client, make sure you use the following scopes to go through this guide:

• tax:read
• transactions:read:all
• transactions:write:all

Copy the access token returned and login to the API Gateway docs by putting Bearer ${accessToken} into the login modal.

Having an API client with users with attached transactions will be beneficial.

Transactions

Our financial data can now store enhancedCategories on transactions, in this use case this will allow us to store what kind of transaction, for tax return purposes, it is. enhancedCategories is a dictionary object type with restricted keys. The uk-tax-hmrc key will be used to categorise the transactions; the values allowed are restricted to the following regex: ^(income|expenditure)\.([a-zA-Z-]+)$

If you want to categorise a transaction as being one that is income that has come in from rent, then you would use the following body on the REST call PATCH /transactions/${transactionId}

{
  "enhancedCategories": {
    "uk-tax-hmrc": "income.rent"
  }
}

Similarly for an expenditure for maintenance, the following body can be used:

{
  "enhancedCategories": {
    "uk-tax-hmrc": "expenditure.maintenance"
  }
}

Automated Tax Categories

As well as being able to manually enrich a transaction with a tax category, you can let us do it for you on a transaction that doesn't have a tax category mapped on it. This can be achieved by adding a project ID to the transaction, i.e. calling PATCH /transactions/${transactionId} with the following body:

{
  "projectId": "00000000-0000-0000-0000-000000000000"
}

Tax Return

After some transactions have been patched to include these enhanced categories, we can now query the tax return end point. This end point has the following query parameters:

• startDate - the starting date to look for transactions (required)
• endDate - the ending date to look for transactions (required)
• accountId - a specific account ID to filter transactions
• projectId - a specific project ID to filter transactions

So to get the tax return for the tax year for 2019, you would make the following request: GET /tax?startDate=2019-04-06&endDate=2020-04-05

This will return a tax return object similar to the one below:

{
  "dateFrom": "2018-04-06",
  "dateTo": "2019-04-05",
  "taxReturn": {
    "sa105": {
      "income": {
        "total": {
          "value": 1500000,
          "currency": "GBP"
        },
        "details": [
          {
            "amount": {
              "value": 1500000,
              "currency": "GBP"
            },
            "category": "income.rent"
          }
        ]
      },
      "expenditure": {
        "total": {
          "value": 300000,
          "currency": "GBP"
        },
        "details": [
          {
            "amount": {
              "value": 200000,
              "currency": "GBP"
            },
            "category": "expenditure.professional"
          },
          {
            "amount": {
              "value": 100000,
              "currency": "GBP"
            },
            "category": "expenditure.maintenance"
          }
        ]
      },
      "taxableIncome": {
        "total": {
          "value": 1200000,
          "currency": "GBP"
        }
      }
    }
  }
}

The monetary values are an object with keys value and currency. The value key is in pence.