Xero Integration in Scheduling
Overview
Connect Xero Payroll to send approved Timesheet Batches from Astalty to Xero. Before the first sync, configure Xero pay frequencies and pay items, then map Astalty Pay Groups and employees.
Connecting Xero
Open Settings > Integrations, find Xero, and select Connect.
Allow Access
Log in to Xero if prompted, review the requested access, and allow Astalty to connect.
If Xero Payroll is not yet configured, complete Xero Configuration before you set up Astalty.
Xero Configuration
Configure these items in Xero Payroll Settings:
- Pay Frequencies
- Pay Items
Pay Frequencies
In Xero, open Payroll Settings and check that the required Pay Frequency exists. Select Add if you need to create one.
Pay Items
In Xero, open the Pay Items tab under Payroll Settings. These are the pay items you can map to Astalty Pay Items in each Pay Group. Select Add to create any missing item.
Employees
In Xero, open Payroll > Employees. These employees become available for mapping to Astalty users. Select New employee to add anyone who is missing.
Employee Pay Templates
For the Multiplier method, set each employee's Ordinary Hours rate in Xero to their base pay rate for their classification, excluding casual loading. This allows the multipliers configured within the Pay Items to calculate correctly.
Review deductions, superannuation, leave and any default earnings that could duplicate imported timesheets. For both Multiplier and Rate Per Unit setup, use Setup Pay Items and Employee Templates in Xero. Check the resulting pay-run amounts before posting.
Astalty Configuration
Then configure these items in Astalty:
- Payroll Platform
- Payroll Calendar
- Pay Groups
- Employees
Payroll Platform
Begin by assigning Xero as your Payroll Platform within your Scheduling Settings.
Select Update to save your changes.
Payroll Calendar
Open the Xero Integration Overview in Astalty and select Edit.
Select the required Payroll Calendar (the Pay Frequency setup in Xero), and then Update to save your changes.
Pay Groups
Pay Groups organise the Pay Items used for different workers and employment conditions. Open Xero Integration > Pay Groups, then select Add Pay Group if you need one.
Give the group a Pay Group Name, select the Award matching its workers, and select Create Pay Group. Keep different awards and casual/permanent rate mappings in separate groups; see Setup Pay Groups and Employees.
Use the 3 dot menu of the Pay Group you just created to select Edit Pay Item Mapping.
Map each Astalty Pay Item to the matching Xero pay item or rate. If your workers use the On-Call Roster, map its on-call rows too; see Mapping On-Call Pay Items.
Use a Pay Group's 3 dot menu to select Edit Pay Group or Edit Pay Item Mapping.
You can delete a Pay Group only when it is not assigned to any user.
Employees
Open Xero Integration > Employees. The list separates employees who are Linked to Xero from those who are Not Linked. Link each worker included in Xero timesheet exports.
Set the Xero Employee filter to Not Linked, then open a user's actions menu and select Link Xero Employee.
Select the matching Xero employee, then select Update.
Linked users appear in the Linked list. Use Link Xero Employee on one to change the linked Xero employee.
Missing Employees
If an employee is missing from the dropdown, add or finish setting them up as an employee in Xero.
If an employee cannot be found in either Linked or Not Linked, make sure the user has their own Astalty profile under Users.
Custom Allowances
When custom allowances are in use, open Xero Integration > Custom Allowances and map each one to the Xero earnings rate that pays it. A rate per unit must have a Type of Units of Hours or Hour. A timesheet batch with an unmapped allowance on any of its shifts cannot be synced to Xero. See Mapping an Allowance to a Xero Earnings Rate.
Syncing Timesheet Batches to Xero
The Timesheet Batch dates must match the next Xero Pay Frequency period that has not been processed. Astalty shows that period while you create the batch.
Once you have generated your Timesheet Batch, use the Actions button to select Export Xero Timesheet (API). See our Timesheet Batches guide for more information on how to create these.
When you're ready to sync the Timesheets batch with Xero, select Validate.
After validation, answer the export questions, then select Create Export.
After selecting Create Export, review the new entry under Export Results. A successful sync reaches Completed.
Synced timesheets appear in Xero with a status of Draft, ready for processing.
Errors When Syncing Timesheets
Select Validate to check the Timesheet Batch before sending it to Xero.
Errors can surface at two different points, and the Fix issue button behaves differently in each:
- When you validate, before anything is sent to Xero. Each problem is listed against the worker it affects, and most rows have a Fix issue button (wrench icon) that takes you straight to the screen where you can resolve it. See Resolving Timesheet Batch Validation Errors for every error, where each button goes, and what to do when there's no button.
- After the sync runs, when Xero itself rejects the timesheets. The attempt is recorded in the Export Results panel with a status of Failed and the reason Xero gave. Here, Fix issue opens a Why this export failed drawer rather than navigating away.
Timesheet Already Exists
Xero allows one timesheet per employee per pay period, in any status - awaiting approval, approved, rejected and processed all count. If Xero already holds one for a worker in this pay period, it won't accept another, and the export is recorded as Failed in the Export Results panel. This usually happens when an earlier export partially succeeded, or when a timesheet was entered directly in Xero.
Select Fix issue on the failed row to open the Why this export failed drawer. Under Timesheet to remove in Xero it names the worker and the pay period the clashing timesheet covers, and offers a Manage Xero timesheets button that opens Astalty's draft timesheet tool in a new tab, already filtered to that worker and pay period.
Who removes the timesheet, and how, depends on its status and on who created it:
| The existing timesheet | How to remove it |
|---|---|
| Draft, created by Astalty or by you | Delete it from Manage Xero timesheets. |
| Any other status - approved, awaiting approval, rejected or processed - created by Astalty or by you | In Xero, revert it to draft, then delete it. Astalty deletes drafts only, so nothing else can be cleared from Astalty. |
| Entered by the worker in Xero Me | Only the worker can delete it. Ask them to open Xero Me, revert it to draft if needed, and delete it. Don't reject it - that hands it back to them without removing it. |
| Already in a pay run in Xero, draft or posted | Revert the pay run to draft if it's posted - that also unlocks the timesheet - then delete the pay run, remove the timesheet, export again, and create the pay run again. If the pay run has already been filed and paid, don't delete it - add the hours in Xero instead. |
Once the timesheet is gone, run the export again.
Incorrect Timesheet Batch Dates
Validate blocks the export unless the batch dates match Xero's next payroll period exactly:
Timesheet batch dates (01-08-2026 to 14-08-2026) do not match Xero next payroll period (15-08-2026 to 28-08-2026).
That period starts on the start date currently held on the batch's Xero payroll calendar and runs one period length - a week, fortnight, four weeks, month, half-month or quarter, depending on the calendar type. A batch that sits inside a period, spans two of them, or covers a period Xero has already moved past fails the check.
A Pay Run Has Moved Xero Past the Batch
Xero - not Astalty - moves that start date: creating a pay run, draft or posted, advances it by exactly one period. So when the batch ends the day before Xero's next period starts, a pay run for that period almost always already exists. Astalty recognises that case and prints the remedy underneath the message:
Xero's next pay period has moved past this batch, which usually means a pay run for this period already exists in Xero. Delete that pay run, export, then create it again. If the pay run is posted, revert it to draft first.
- In Xero, open the pay run covering the batch period. If it's posted, revert it to draft.
- Delete the pay run.
- If a timesheet for the period is still in Xero, remove it - see Timesheet Already Exists.
- In Astalty, select Validate and run the export again.
- Create the pay run again in Xero.
Other Date Mismatches
Every other mismatch shows the message on its own with no remedy underneath - the batch runs ahead of Xero's next period, its dates don't line up with the calendar, or it belongs to an older period. Correct the batch dates to match the period Xero is expecting. Don't delete the pay runs sitting between an older period and today to reach it: those are pay runs you've already processed.
To process missed timesheets from a previous period, export the batch as a file and enter it in Xero manually. Select Export as Excel in the top-right corner of the Export for Xero panel. This produces the same Xero-formatted Excel file as the Xero-formatted timesheet option under Export Timesheet as Excel, ready for importing into Xero - see Export Timesheet as Excel.
Missing Users
If you attempt to sync a batch that contains users who are not linked to employees in Xero, the sync will fail. You will need to link these employees before rerunning the sync.
Each error row has a Fix issue button (wrench icon). For this error it opens the worker's HR tab in a new tab, with the Update payroll platform drawer ready so you can link them to their Xero employee.
No Employment Details Error
If you attempt to sync a batch that contains users who do not have employment details in Astalty, the sync will fail. You will need to assign the employee employment details before rerunning the sync.
Xero Pay Item Configuration Walk-Through
Set up your pay items before linking Astalty and Xero. Use the Xero Payroll - Pay Item Configuration reference for the required pay items and the video walkthrough for creating them in Xero.
Xero Payroll Integration Walk-Through
This recording covers payroll setup in Xero and Astalty, including employee settings, pay items, and pay rates.