Importing Employee Deductions in Bulk

Andrew

Updated 23 June 2025 04:02

If you are needing to update employee deductions in bulk, you can do this via the Payroll settings > Import pay run inclusions page.

This article contains the following information:

Exporting a file template
Instructions for import fields
Importing the deduction file
Reports

Exporting a file template

To help with the process of importing employee deductions in bulk, it's recommended that you first obtain a file template by going to the Payroll settings > Data extracts page and exporting one. Simply select 'Employee deductions' as the 'Data type', and the required 'File format':

Once you click 'Download', the export file will contain the following headers:

Employee Id
Employee First Name
Employee Surname
Employee External Id
Id
Deduction Name	Options are: List of all active deduction categories available to business, as per UI
Deduction Type	Options are: Fixed Percentage of gross Percentage of NET Varied based on earnings amount
Amount	Numbers only
Tiered Deduction Settings Name	Options are: List of all active tier settings available to business, as per UI
Priority
Student Loan Inclusion	Options are: Apply deduction first Apply student loan first Do not apply student loan
Paid To	Options are: Paid manually Paid to a bank account Paid to pension scheme
Paid To Account Name	Options are: List of bank account records set up. Each employee will have their own unique bank account records, as per UI
Pension Contribution Plan	Options are: List of pension plans linked to employee. Each employee will have different options available based on the plans linked to their contribution scheme, as per UI
Payment Reference
Preserved Earnings	Options are: Never Once a minimum net earnings limit has been reached Once a percentage of net earnings limit has been reached
Preserved Earnings Amount
Preserved Earnings Amount Not Reached Action	Options are: Do not pay the deduction Pay the deduction up to the preservation limit
Carry Forward Unpaid Deductions	Options are: True False
Carry Forward Unused Preserved Earnings	Options are: True False
From Date
Expiry Date
Maximum Amount Paid
Total Amount Paid
Notes

Instructions for import fields

The following information applies to each field upon import:

EmployeeID: Mandatory;
EmployeeFirstName: Changes made to this field will not be imported. Changes should be made via the employee import;
EmployeeSurname: Changes made to this field will not be imported. Changes should be made via the employee import;
EmployeeExternalId; Changes made to this field will not be imported. Changes should be made via the employee import;
Id: This is the system Id, and only applicable for existing deductions. If you provide an Id that matches an existing deduction, that record will be updated. If this field is blank, a new record will be created;
DeductionName: Mandatory. Only values listed in the drop down are accepted, and these represent the active deduction categories associated with the business;
DeductionType: Mandatory. Only values listed in the drop down are accepted, and these represent the active deduction categories associated with the business. The following rules apply:
- Varies based on earnings amount and percentage of net can only be selected on post-tax deductions.
Amount: Mandatory if 'Deduction type' is not 'varied based on earnings amount'. Only numbers accepted. Value provided will be set in the pounds or % field according to what was selected for 'Deduction type';
TieredDeductionSettingsName: This is mandatory if ‘Amount (per pay run)’ value provided is ‘Varies based on earnings amount’. Only values listed in drop down are accepted;
Priority: This needs to be entered as a whole number, and if not provided the value will be set as 0;
StudentLoanInclusion: Only values listed in drop down are accepted;
PaidTo: Mandatory. Only values listed in the drop down are accepted. The following conditions apply:
- Paid manually and paid to bank account options can only be selected against non system categories.
- Where the deduction is a system deduction, the 'PaidTo' value must be paid to a pension fund.
PaidToAccountName: This field is mandatory if the ‘PaidTo’ value provided is ‘Paid to a bank account’. Only values listed in the drop down are accepted, unless the template is empty. If the empty template is selected, the format accepted is <bank account name> (***<last 4 digits of bank account number>). The 4 digits provided must match to an existing employee bank account that has been set up in the employee file.
PensionContributionPlan: This is mandatory if the ‘PaidTo’ value provided is ‘Paid to a pension scheme’. Only values listed in the drop down are accepted, unless the template is empty. If the empty template is selected, the name of the contribution plan should manually be added (as displayed in the pay run inclusion screen). The employee must be associated with the selected plan.
PaymentReference: This is a free text field and is only applicable if ‘PaidTo’ value is set as ‘Pay to a bank account’;
PreservedEarnings: Only values listed in the drop down are accepted. If a value is not provided, the ‘PreservedEarnings’ option will be set to ‘Never’;
PreservedEarningsAmount: This field is mandatory if the ‘PreservedEarnings’ value is NOT ‘Never’;
PreservedEarningsAmountNotReachedAction: Only values listed in the drop down are accepted;
CarryForwardUnpaidDeductions: Values are ‘True’ and ‘False’;
CarryForwardUnusedPreservedEarnings: Values are ‘True’ and ‘False’;
FromDate: If this is not provided, the ‘when should this pay run inclusion start?’ field in the employee’s pay run inclusion screen will be set to ‘Today’;
ExpiryDate: Only 'ExpiryDate' or 'MaximumAmountPaid' can be set. If neither 'ExpiryDate' or 'MaximumAmountPaid' are provided, the ‘when should this pay run inclusion expire?’ field in the employee’s pay run inclusion screen will be set to ‘Never’;
MaximumAmountPaid: Only 'ExpiryDate' or 'MaximumAmountPaid' can be set;
TotalAmountPaid: This field is a calculated field which uses pay run data and only applies if the ‘MaximumAmountPaid’ is provided. Changes made to this field will not be imported;
Notes: Optional, Free text field.

Importing the deduction file

Once you have saved your import file, navigate to the Payroll settings > Import pay run inclusions page. The deduction type is set to 'Employee deductions' by default, and you simply need to 'Select file' or drag the relevant file across:

When data can only be partially imported, the system will import the records that are able to be imported and ignore the ones that can’t be imported. You see the following message if this happens, which contains 2 sections which includes the details of errors which prevented a record from importing, and details of employees that were successful :

Upon a successful import, you'll be able to see the changes within the Employee file > Pay run inclusions page.

Reports

Changes made to deductions via the via bulk import file will be listed in the employee details audit report, and can be filtered using the 'Pay run inclusions' section:

The results will display the following:

Type of pay run inclusion
Old value
New value: