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

This guide explains how to import employee records into Lightning Payroll and, for New Zealand employees, how to import historic gross earnings so annual-holiday calculations are accurate from the start.

These are two separate imports. You can import employee records only, historic gross earnings only, or both together.

Download Example Files

Use these example CSV files as a starting point:

• NZ Employee Import Example CSV - use this to import employee details, leave balances and year-to-date figures.
• NZ Historic Gross Earnings Example CSV - use this to import previous gross earnings for annual-holiday average calculations.

Quick Start

1. Download the example CSV file you need from the links above.
2. Fill in your employee details, copying information from your previous payroll software where possible.
3. Go to the Employees screen and choose Import Employees from CSV. In the desktop app, this is under Actions.
4. Select your employee CSV. New Zealand companies can also select an NZ historic gross earnings CSV in the same step.
5. Upload the file. Lightning Payroll will import the rows it can read and report any rows that need correcting.
6. Open each employee afterwards to review or complete their details.

Import Employee Records

The employee CSV is used to set up employees in Lightning Payroll. A few fields are especially important: first name, last name, employment start date and pay period.

Most other fields are optional, but we recommend completing as much as you can. You can edit employee details, including shifts, allowances and other pay items, after the import is complete.

Employee CSV Field Reference

Year-To-Date Figures

Year-to-date (YTD) figures let you carry an employee's earnings and deductions forward from a previous payroll system.

Enter the date the figures are accurate as at in ytd_as_at_date, then enter the matching totals in the relevant YTD columns.

YTD figures are separate from the historic gross earnings import described below.

Accepted Values for Coded Fields

Some CSV columns accept only specific values. Enter the short code shown below 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, 0.04, 0.06, 0.08 or 0.10
• kiwisaver_employer_rate: 0.03, 0.04, 0.06, 0.08 or 0.10
• esct_rate: 0.105, 0.175, 0.30, 0.33 or 0.39
• pay_period: Weekly, Fortnightly or Monthly
• has_student_loan and no_declaration: true or false

Import Historic Gross Earnings

Historic gross earnings are used for New Zealand annual-holiday calculations. Annual holidays are valued using a rolling 52-week average of gross earnings, also known as Average Weekly Earnings.

If an employee was paid outside Lightning Payroll during any part of the last 52 weeks, import their historic gross earnings so the average is accurate from their first leave payment in Lightning Payroll.

When to Import Historic Gross Earnings

• During the employee import: New Zealand companies can select a historic gross earnings CSV in the same import step as the employee CSV. This is best when setting up several employees at once.
• On its own later: You can import a historic gross earnings CSV without an employee file from the same import screen. This is useful when adding employees one at a time or back-filling pay history later.

Historic Gross Earnings CSV Requirements

Each row needs the following details:

• pay_date - the date the pay was made. Accepted formats include 15/04/2026 and 2026-04-15.
• gross_earnings - the gross earnings paid for that pay period.
• employee_number or ird_number - used to match the row to an employee. ird_number is preferred where available. If both are supplied, they must match the same employee.

The historic gross earnings template can also be downloaded from within Lightning Payroll when starting a CSV import.

What Happens During the Import

Lightning Payroll checks each row as it imports. Rows that can be read are imported. Rows that cannot be used are reported back so you can correct the CSV and upload it again.

A row may be reported if:

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

The last rule prevents double-counting. Pays already processed in Lightning Payroll already contribute to the 52-week average, so historic gross earnings should only cover the period before the employee's first Lightning Payroll pay.

Important Notes About Historic Gross Earnings

• Historic gross earnings are used only for the rolling 52-week average that values annual holidays.
• They do not create historical pays or payslips.
• They do not create or update YTD figures.
• If you need to carry forward year-to-date totals, enter those in the employee CSV instead.

Migrating From Another Payroll System

Ask your previous payroll system for a per-pay gross earnings report covering the last 12 months. Then reshape the report into the required columns: pay_date, gross_earnings, and either ird_number or employee_number.

Troubleshooting

Already using Lightning Payroll elsewhere? If you are moving employees between Lightning Payroll database files, rather than coming from other payroll software, you can export them from the other file to produce a ready-to-import CSV. For more information, see How Do I Export Employees Or Merge Lightning Payroll Databases?