Setting the Employee Tax Code

Tax codes are issued to employees by HMRC; when in doubt you should alway check with HMRC. The most common method of finding out an employee's tax code is from their P45, they may also be issued a P6 coding notice that can be retrieved via HMRC's DPS service.

For more detailed information on tax codes please see page Understanding Tax Codes.

Tip! If an employee does not have a pre-existing tax instruction, when the employee is included in a pay run, the pre-calculation rule TaxMissingPayInstructionRule will automatically create a new tax instruction using the emergency tax code.

To set an employee's tax code you will need to create a new TaxPayIntruction. Be aware that if an existing overlapping TaxPayIntruction exists then the creation of the new tax pay instruction will fail - see [DIR1404].

Getting the employee's current tax instruction

To help find the existing tax pay instruction, the PayRun.io API includes a pre-defined query. See Active Pay Instructions Report for more info.

Unlike most other payment instructions, Tax Pay Instructions are single instance items. This means that you can only have a single tax instruction active at any one time. The employee's tax pay instructions (start and end dates) cannot overlap.

If the employee has an active tax instruction and it requires changing following a notice from HMRC, you must end the existing instruction before the new one starts. Once the old instruction is ended, a new tax pay instruction can be added with the new tax code and basis.

If no tax instruction exists, simply add the new instruction.

Ending an existing tax instruction

Given the exising tax instruction has a resource location of: /Employer/ER001/Employee/EE001/PayInstruction/TAX001, you use the following API call to set the instruction end date.

If the new tax instruction takes effective on 2017-05-01, the existing instruction should end the day before, 2017-04-30.

curl -X PATCH
   https://api.test.payrun.io/Employer/ER001/Employee/EE001/PayInstruction/TAX001
   -H 'Content-type: application/xml'
   -H 'Accept: application/xml'
   -H 'Api-Version: default'
   -H 'Authorization: {OAuthHeader}'
   -H 'Cache-Control: no-cache'
-d '<?xml version="1.0"?>
<TaxPayInstruction xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <EndDate>2017-04-30</EndDate>
</TaxPayInstruction>'
curl -X PATCH
   https://api.test.payrun.io/Employer/ER001/Employee/EE001/PayInstruction/TAX001
   -H 'Content-type: application/json'
   -H 'Accept: application/json'
   -H 'Api-Version: default'
   -H 'Authorization: {OAuthHeader}'
   -H 'Cache-Control: no-cache'
-d '{
  "TaxPayInstruction": {
    "EndDate": "2017-04-30"
  }
}'

Response Example

<?xml version="1.0"?>
<TaxPayInstruction xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <StartDate>2017-04-06</StartDate>
    <EndDate>2017-04-30</EndDate>
    <TaxCode>1150L</TaxCode>
    <TaxBasis>Week1Month1</TaxBasis>
</TaxPayInstruction>
{
  "TaxPayInstruction": {
    "StartDate": "2017-04-06",
    "EndDate": "2017-04-30",
    "TaxCode": "1150L",
    "TaxBasis": "Week1Month1"
  }
}

Creating a new tax instruction

The following example demonstrates using [POST] to add a new tax instruction. Using post will create a new instruction with an auto generated unique key (e.g. TAX002). Alternatively, you can use a [PUT] and explicitly specify your own unique key.

curl -X POST
   https://api.test.payrun.io/Employer/ER001/Employee/EE001/PayInstructions
   -H 'Content-type: application/xml'
   -H 'Accept: application/xml'
   -H 'Api-Version: default'
   -H 'Authorization: {OAuthHeader}'
   -H 'Cache-Control: no-cache'
-d '<?xml version="1.0"?>
<TaxPayInstruction xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <StartDate>2017-05-01</StartDate>
    <TaxCode>D1</TaxCode>
    <TaxBasis>Cumulative</TaxBasis>
</TaxPayInstruction>
'
curl -X POST
   https://api.test.payrun.io/Employer/ER001/Employee/EE001/PayInstructions
   -H 'Content-type: application/json'
   -H 'Accept: application/json'
   -H 'Api-Version: default'
   -H 'Authorization: {OAuthHeader}'
   -H 'Cache-Control: no-cache'
-d '{
  "TaxPayInstruction": {
    "StartDate": "2017-05-01",
    "TaxCode": "D1",
    "TaxBasis": "Cumulative"
  }
}'

Response Example

<?xml version="1.0"?>
<Link 
    xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    title="Tax: [2017-05-01->]" 
    href="/Employer/ER001/Employee/EE001/PayInstruction/TAX002" 
    rel="TaxPayInstruction" 
/>
{
  "Link": {
    "@title": "Tax: [2017-05-01->]",
    "@href": "/Employer/ER001/Employee/EE001/PayInstruction/TAX002",
    "@rel": "TaxPayInstruction"
  }
}

Active Pay Instruction Report

You can find the current employee's tax instruction (if one exists) using the active pay instruction report.

Report Parameters

  • EmployerKey (Required)
    The unique key of the employer. E.g. ER001
  • EmployeeKey (Required)
    The unique key of the employee. E.g. EE001
  • ActiveOn (Required)
    The date to test on. E.g. 2017-04-30
  • Type (Optional)
    The pay instruction type to filter by. E.g. TaxPayInstruction. If omitted, then all active pay instructions are returned.

You can run the Active Pay Instructions Report from the online API explorer: Active Pay Instructions Report

This example demonstrates how to [GET] the report output.

curl -X GET
   https://api.test.payrun.io/Report/ACTPAYINS/run?EmployerKey=ER001&EmployeeKey=EE001&ActiveOn=2017-04-30&Type=TaxPayInstruction
   -H 'Content-type: application/xml'
   -H 'Accept: application/xml'
   -H 'Api-Version: default'
   -H 'Authorization: {OAuthHeader}'
   -H 'Cache-Control: no-cache'
curl -X GET
   https://api.test.payrun.io/Report/ACTPAYINS/run?EmployerKey=ER001&EmployeeKey=EE001&ActiveOn=2017-04-30&Type=TaxPayInstruction
   -H 'Content-type: application/json'
   -H 'Accept: application/json'
   -H 'Api-Version: default'
   -H 'Authorization: {OAuthHeader}'
   -H 'Cache-Control: no-cache'

Response Example

<?xml version="1.0"?>
<ActivePayInstructionsReport xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" Generated="2017-10-10T14:48:12">
  <PayInstructions ActiveOn="2017-04-30">
    <PayInstruction Type="TaxPayInstruction">
      <Link href="/Employer/ER001/Employee/EE001/PayInstruction/TAX001" />
      <StartDate>2017-04-06</StartDate>
      <EndDate>2018-04-05</EndDate>
      <TaxCode>1150L</TaxCode>
	  <TaxBasis>Week1Month1</TaxBasis>
    </PayInstruction>
  </PayInstructions>
</ActivePayInstructionsReport>
{
  "ActivePayInstructionsReport": {
    "@Generated": "2017-10-10T14:54:53",
    "PayInstructions": {
      "@ActiveOn": "2017-04-30",
      "PayInstruction": {
        "@Type": "TaxPayInstruction",
        "Link": {
          "@href": "/Employer/ER001/Employee/EE001/PayInstruction/TAX001"
        },
        "StartDate": "2017-04-06",
        "EndDate": "2018-04-05",
        "TaxCode": "1150L",
		"TaxBasis": "Week1Month1"
      }
    }
  }
}