ETI examples

{
  "$schema": "https://spcm.gov.gg/schemas/0.3/message.schema.json",
  "spcmMessageVersion": "0.3",
  "effective": "2023-10-05T16:33:05Z",
  "senderEmail": "joseph@acme.gg",
  "senderName": "Joseph Administrator",
  "softwareAgent": "SPCMTasks",
  "type": "Revenue_EmployerReturn",
  "purposes": [
    "ETI"
  ],
  "test": false,
  "coverage": [
    {
      "frequency": "Monthly",
      "year": 2023,
      "period": 7
    },
    {
      "frequency": "Monthly",
      "year": 2023,
      "period": 8
    },
    {
      "frequency": "Monthly",
      "year": 2023,
      "period": 9
    }
  ],
  "employers": [
    {
      "id": "SPCM-12345-IncomeTax",
      "taxRef": "8Y123456",
      "name": "Acme Widgets",
      "employees": [
        {
          "id": "1",
          "firstName": "Joe",
          "lastName": "Bloggs",
          "dateOfBirth": "1980-01-01",
          "employmentEndDate": "2023-08-31",
          "payrollNumber": "555",
          "deliveryPointId": 1349,
          "address": "The Lodge\nLodge Street\nGY1 2UA",
          "taxRef": "0O139481",
          "purposes": [
            "ETI"
          ],
          "pay": [
            {
              "frequency": "Monthly",
              "year": 2023,
              "period": 7,
              "taxEarnings": 4444.44,
              "taxSuperannuation": 444.44,
              "taxCoding": 234,
              "taxDirection": 2,
              "taxDirectionDeduction": 22.22,
              "taxDeduction": 444.44,
              "taxRefund": 4.44
            },
            {
              "frequency": "Monthly",
              "year": 2023,
              "period": 8,
              "taxEarnings": 4444.44,
              "taxSuperannuation": 444.44,
              "taxCoding": 234,
              "taxDirection": 2,
              "taxDirectionDeduction": 22.22,
              "taxDeduction": 444.44,
              "taxRefund": 4.44
            }
          ]
        }
      ]
    }
  ]
}

Please note this documentation assumes you are familiar with the concepts explained in the example files for Secondary Pensions compliance.

"type": "Revenue_EmployerReturn"

"purposes": [ "ETI" ]

These headers indicate that this is an employer's ETI return.

"coverage"

The coverage array here indicates that the report covers the monthly payroll for 2023 Q3. The array is a list of periods, each identified by its year, frequency ("Monthly" or "Weekly"), and period (which ranges from 1-12 for months, and 1-53 for weeks).

Unlike the legacy ETI return format, which only supported weekly returns, the SPCM JSON format supports true monthly returns for ETI. Employers should use the 'Monthly' frequency for returns pertaining to monthly payrolls.

"employers"

This employers array contains one employer. It is expected that almost all returns will only contain one employer, but the format allows for multiple employers in the event that a single sender administers a group of related employers together.

"id"

minLength: 1; maxLength: 200

This is an identifier for the employer which is generated by the sender. It is defined as a string, and it does not matter what identifier you use, but you should use the same Id to refer to the same employer when sending successive messages.

The employer Id can only identify an employer within the scope of an API key. This means two messages received by SPCM will only be treated as referring to the same employer if both were sent with the same API key, as well as having the same employer Id.

"name"

minLength: 1; maxLength: 160

The name of the employer.

"taxRef"

pattern: \d[XY]\d{6}

The tax reference number for this employer, in the form "1X123456".

"employees"

This array must list all the employees in respect of whom ETI is reportable for any period covered by this return.

"id"

minLength: 1, maxLength: 200

This is an identifier for the employee which is generated by the sender. It can be any string, but it should be immutable. It identifies the employee within the scope of the employer, so if you are reporting for two or more employers using the same API key, then it is acceptable to have the same Id for two different people where they are employed by different employers.

"firstName"

minLength: 1; maxLength: 50

The employee's first name. If only initials are known then provide these.

"lastName"

minLength: 1; maxLength: 50

The employee's last name.

"dateOfBirth"

The employee's date of birth.

"employmentEndDate"

The date the employee ceased working for this employer in ISO 8601 (yyyy-mm-dd) format. If the employee is still employed, this must be null.

"payrollNumber"

minLength: 1; maxLength: 8

The employee's payroll number. This can be any combination of digits, upper or lower case letters A-Z, and a limited permitted set of punctuation. Spaces are permitted within the number, but leading or trailing space is not permitted.

If no payroll number is held, this attribute should have the value null.

"deliveryPointId"

The Corporate Address File (CAF) Delivery Point Id for the employee's residential address, if held.

"address"

The employee's residential address, if held. If possible, this should be provided with newlines, but lines can alternatively be comma-separated.

"taxRef"

pattern: \d[OABVNTW]\d{6}B?

The tax reference number for this employee, in the form "1A123456".

If no tax reference is held this attribute should have the value null and an address should be provided.

"purposes"

In this example, this array contains the single value "ETI", which indicates that this employee falls within the scope of ETI reporting.

Normally, the purposes listed for a each employee will be the same as the purposes in the message header. However, there may be situations where certain employees are not reportable for one or more of those purposes. This array is provided so that, in such cases, you can still provide a single combined return, rather than having to split a return into a separate file for each purpose.

"pay"

The pay array contains an object for every period covered by the return in which this employee was paid.

The year, frequency and period indicate the period covered by the object.

The period must be one of those in the "coverage" array in the return header, and each period included must only appear once.

If any period in the coverage array is missing from the pay array (such as period 9, September, in the example above), this means the employee was not paid in that period. This is equivalent to reporting a pay object with zero or null for all values.

All currency amounts are in pounds sterling.

Below we include a brief description of each field and the equivalent field name from the legacy ETI file specification. The precise meaning of these fields is outside the scope of this document, except to note that they must be populated and interpreted in accordance with the relevant laws and guidance regarding the operation of the Income Tax ETI scheme.

"taxEarnings"

minimum: 0; exclusiveMaximum: 100000000

Gross pay

Legacy name: Gross_Pay

"taxSuperannuation"

minimum: 0; exclusiveMaximum: 100000000

Superannuation

Legacy name: Superannuation

"taxCoding"

integer; minimum: 0; exclusiveMaximum: 100000000

The coding number applied to this period

Legacy name: Coding

"taxDirection"

integer; nullable; minimum: 1; exclusiveMaximum: 100

The number of the Direction Notice applied to this period, or null if no direction notice is being applied

Legacy name: Direction

"taxDirectionDeduction"

minimum: 0; exclusiveMaximum: 100000000

The amount of tax which was deducted from the pay because of a Direction Notice. This should be the actual amount of the deduction, which may be a different amount from the amount on the Direction Notice, for example if the employee was not paid enough to fully implement the deduction.

This is a new mandatory field in SPCM.

Legacy name: n/a

"taxDeduction"

minimum: 0; exclusiveMaximum: 100000000

The total amount of tax deducted (including any amount deducted because of a Direction Notice)

Legacy name: Tax_Deducteds

"taxRefund"

minimum: 0; exclusiveMaximum: 100000000

The amount of previously-deducted tax which was refunded

Legacy name: Tax_Refunds