How Do I Import Employee Records And Pay History Into Lightning Payroll?

This guide covers importing your employee records and, for New Zealand employees, their historic gross earnings (pay history) so that annual-holiday calculations are accurate from day one. These are two separate imports — you can do either on its own, or both together.

Quick start

1. Prepare your employee CSV — download our example spreadsheet (see below) and fill in your employees' details, copying from your current payroll software where you can.
2. Go to the Employees screen and choose Import Employees from CSV (in the desktop app this is under Actions).
3. Select your employee CSV. New Zealand companies can also select an NZ historic gross earnings CSV in the same step.
4. Upload. Lightning Payroll imports the rows it can read and lists any it could not, so you can fix those and re-upload.
5. Open any employee afterwards to review or complete their details.

Part 1 — Import employee records (CSV)

Most businesses set up their employees from a CSV file — this is the usual way to bring staff across from other payroll software. Please see our example spreadsheet here, fill in your employees' details (copying from your current software where you can), and use the field reference below for what each column means.

A few fields identify and set up the employee — first name, last name, employment start date and pay period. Everything else is optional, but we recommend completing as much as you can. You can edit any detail — including shifts, allowances and other pay items — in the employee profile after the import is complete.

Field reference

Several columns accept only specific codes — see Accepted values for coded fields below for what to put in each one.

Year-to-date (YTD) figures let you carry an employee's earnings and deductions forward from a previous system. Enter the date they are accurate as at in ytd_as_at_date, then the matching totals. YTD figures are stored separately from the historic gross earnings described in Part 2.

Accepted values for coded fields

Put the short code (the left-hand value) in your CSV.

nz_tax_code — the employee's tax code from their IR330 form. For a student-loan version of a code, use the base code below and set has_student_loan to true.

kiwisaver_status_code — the employee's KiwiSaver status. Leave blank if not set.

kiwisaver_existing_action — only needed for an existing employee changing their KiwiSaver arrangement. Leave blank for no action.

employer_contrib_tax_method — how the employer's KiwiSaver contribution is taxed.

Rates and other set-value columns:

• kiwisaver_employee_rate — 0.00, 0.03 (default), 0.04, 0.06, 0.08 or 0.10
• kiwisaver_employer_rate — 0.03 (default), 0.04, 0.06, 0.08 or 0.10
• esct_rate — 0.105, 0.175, 0.30, 0.33 or 0.39 (10.5%, 17.5%, 30%, 33%, 39%)
• pay_period — Weekly, Fortnightly or Monthly
• has_student_loan, no_declaration — true or false

Part 2 — Import historic gross earnings (pay history for annual holidays)

Annual holidays are valued using a rolling 52-week average of gross earnings (Average Weekly Earnings). If your employees were paid outside Lightning Payroll for any part of the last 52 weeks, load their historic gross earnings so the average is accurate from their first leave payment.

Two ways to load historic gross earnings

• Together with the employee import — New Zealand companies get a second file selector in the import screen for an NZ historic gross earnings CSV, right alongside the employee CSV. Best when you are setting up the company and have history for several employees at once.
• On its own, later — you can import a historic gross earnings CSV without an employee file at any time from the same Import screen. You will also be offered this import straight after manually adding a new NZ employee. Best when you add employees one at a time and want to back-fill their history the same way.

What each row needs

Every historic gross earnings row needs three pieces of information:

• pay_date — the date the pay was made. Accepted formats include 15/04/2026 (DD/MM/YYYY) and 2026-04-15 (YYYY-MM-DD).
• gross_earnings — the gross earnings paid for that pay period.
• employee_number or ird_number — used to match the row to an employee. Prefer ird_number where available; if you supply both, they must point to the same employee.

Please see our historic gross earnings example spreadsheet here for a working sample. The same template can also be downloaded from within Lightning Payroll when you start a CSV import.

What happens when you import

Lightning Payroll checks every row as it imports and brings in the ones it can use. Any row it cannot use is reported back so you can correct your CSV and upload again. A row is reported when:

• the file is missing the pay_date or gross_earnings column, or is missing both employee_number and ird_number;
• the pay_date is not a valid date, or gross_earnings is not a valid number;
• the IRD number or employee number does not match anyone in the company;
• the pay_date falls on or after an existing Lightning Payroll pay for that employee.

That last rule prevents double-counting: a pay you have already run in Lightning Payroll already contributes to the 52-week average, so an imported row covering the same period is rejected rather than added on top. Historic gross earnings should only cover the period before the employee's first Lightning Payroll pay.

Important: historic rows feed the average only

Historic gross earnings rows are used only for the rolling 52-week average that values annual holidays. They do not create historical pays, payslips or YTD figures. If you need to carry forward year-to-date totals, enter those on the main employee CSV (Part 1).

Migrating from another payroll system

Ask your previous system for a per-pay gross earnings report covering the last 12 months, then reshape it into the three columns above (pay_date, gross_earnings, and ird_number or employee_number). Most systems can produce this directly.

Troubleshooting

Already using Lightning Payroll elsewhere? If you are moving employees between Lightning Payroll database files (rather than coming from other software), you can export them from the other file to produce a ready-to-import CSV in the exact format above. This is uncommon, but if you need it see How Do I Export Employees Or Merge Lightning Payroll Databases?