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, choose the Employees to export, tick both I have read and agree to the above boxes, then select Create Export.

After selecting Create Export, review the new entry under Export Results. Astalty sends each worker separately, so one worker's rejection does not undo drafts Xero already accepted. While the export runs, Details shows how many workers are done and roughly how long is left. You can leave the page.

Each worker sent has a Draft timesheet in Xero, ready for review and approval. The exception is an approved timesheet whose hours already matched the batch when you reverted approved timesheets: it stays Approved.
Astalty sends one timesheet line per pay item and day, and per cost code when your account uses cost codes. A worker with shifts on several days has several lines for the same pay item, one for each date. These are not duplicates, so check the dates before removing a line in Xero.

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. Errors must be fixed. Warnings do not block the whole export: they can say that Astalty will replace or clear a draft, or that one worker will be left out while the rest are sent. When there are no errors, select Continue anyway to proceed with the warnings. See Resolving Timesheet Batch Validation Errors for every error and warning.
- After the sync runs, when Xero itself rejects one or more workers. The attempt is recorded in the Export Results panel as Partially failed or Failed, with 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. It refuses a new timesheet for an earlier period when that worker already has a later-period timesheet. An existing draft for the batch's period can still be replaced, as described below. Astalty checks these conflicts during Validate and handles each worker separately.
| What Xero already has | What happens when you continue |
|---|---|
| A draft for this worker and pay period | Astalty replaces every line with the current batch. The warning shows the draft's status, period and hours. This can replace a draft created in Xero or by the worker in Xero Me, because Xero does not tell Astalty who created it. |
| A draft another Astalty batch for the same dates sent | Astalty leaves it unchanged and does not send this worker, so the other batch's hours are not removed. This batch pays only what the other batch missed, so do not delete the draft. Add this batch's hours to it in Xero by hand, using the Xero-formatted timesheet to list them, or delete both batches in Astalty and create one batch for those dates, which sends everything together. |
| An approved timesheet that an earlier export of this batch, or of a deleted batch for the same dates, created | Validation warns and offers to revert it to draft and replace its hours, as described below. Without the revert, Astalty leaves it unchanged and does not send this worker. |
| Any other approved timesheet, including one that started as a draft made in Xero or Xero Me | Astalty leaves it unchanged and does not send this worker. Revert it to draft in Xero, then export again. If another Astalty batch for the same dates sent it, reverting makes it that batch's draft: follow the row for a draft another Astalty batch sent. |
| A timesheet awaiting approval or rejected in Xero Me | Astalty leaves it unchanged and does not send this worker. Ask the worker to revert it to draft in Xero Me, then export again. Rejecting it does not make it a draft. |
| A timesheet already in a pay run, draft or posted | Astalty leaves it unchanged and does not send this worker. If the pay run is posted, revert it to draft first, which 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, compare the worker's payslip with the batch and add only the hours not yet paid in Xero. |
| A later-period timesheet, with no timesheet for this batch's pay period | Astalty leaves it unchanged and does not send this worker. If it is a draft, delete it, from Manage Xero timesheets when Astalty created it or in Xero or Xero Me otherwise. Then send this batch. Send the later batch again once this period's pay run exists in Xero, because until then Validate refuses its dates. If it is approved or paid, Xero won't take a timesheet for this period: compare payslips, then add this batch's unpaid hours straight onto the worker's payslip in the pay run. |
| A timesheet that overlaps the batch's dates without matching them | Astalty does not send this worker. This usually means the worker's payroll calendar in Xero does not match the batch. Check it in Xero. |
Warnings that leave a worker out affect only that worker. Select Continue anyway to send the others, then use the export result to resolve anyone Xero refused.

Reverting Approved Timesheets During the Export
When validation finds approved timesheets that an earlier export of this batch, or of a deleted batch for the same dates, created, and nothing else blocks the export, a switch beside Continue anyway offers Revert approved timesheets Astalty sent to draft and replace their hours, with a count. Turn it on, select Continue anyway, then Create Export. With the switch off, those workers are not sent.

During the export, Astalty reads each of those timesheets first. One whose hours already match the batch stays approved. Every other one becomes a draft holding the batch's hours. Approve the reverted timesheets again in Xero before you run the pay run, because a draft is left out of it.
Astalty never reverts a timesheet it did not create, including one that started as a draft made in Xero or Xero Me. It also leaves alone one awaiting approval or rejected, and one in a posted pay run. Sending a batch through the Astalty assistant never reverts a timesheet.
After an Export Fails
Select Fix issue on a failed result to open the Why this export failed drawer. Each card explains the cause and, where it applies, lists the cases with what to do in each. It links to How to fix this, or to Read the guide for a refusal Astalty doesn't recognise. Some cards also have a button:
- Manage Xero timesheets - for a timesheet in a later pay period. It opens the draft timesheet tool in a new tab, filtered to that worker.
- Export Xero spreadsheet - where Xero won't take this batch's hours for the worker, such as a draft another batch sent or a pay period Xero is holding. It opens the batch's Xero-formatted timesheet export, which lists the hours to enter by hand.
- Open pay item mappings, Open custom allowance mappings or the worker's payroll details - for a pay item that is unmapped or that Xero refused, or a worker linked to an employee Xero no longer has.

To remove a timesheet that blocks a worker, find its status in the table under Timesheet Already Exists. Once it is gone, run the export again. If the Export Fails covers the whole recovery, step by step.
Re-exporting a Corrected Batch
When you re-export the same batch, Astalty replaces each worker's existing draft with the batch's current hours. If a previous export sent a worker who no longer has any hours in the batch, validation warns that continuing will remove every line from that earlier draft, including lines later added in Xero.
Astalty removes those hours only when it recorded the draft during an earlier export of this batch and the timesheet is still a draft. It leaves manual drafts and drafts since used by another batch alone. If the recorded timesheet is no longer a draft, validation warns, that worker fails, and the hours remain in Xero until payroll resolves them. The warning says how for each status. When the timesheet has already been paid, adjust the worker's pay in Xero rather than entering the hours again.
This automatic cleanup applies only to recorded drafts. Check older re-exported batches in Xero and remove stale hours manually when their drafts are not listed in Astalty.
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, ready for importing into Xero - see Export Timesheet.
When Xero Refuses One Worker's Pay Period
The batch dates can pass validation and Xero can still refuse a named worker after the export starts. Select Fix issue on that result to see which case applies.
- The pay period has not started - export that worker again on or after the first day of the period.
- The worker is on another payroll calendar, or has an overlapping timesheet with different dates - validation usually catches both first. A worker on another calendar is an error that stops the whole export, and an overlapping timesheet that starts on the batch's first day is a warning. Assign the worker to the batch's calendar in Xero, or correct the conflicting timesheet, then export again.
- A posted future pay run holds the worker - when the Xero connection can read pay runs, validation warns before anything is sent and names the pay run period. The rest of the batch can still go. Reversing that pay run doesn't clear it: ask Xero Support how to move it. Compare the worker's payslips with the batch before changing anything, because the pay run may already have paid some of the hours.
- Xero is holding this or a later period without a timesheet Astalty can see - this is most often a pay run posted under a future pay period by mistake, and reversing it doesn't clear it. When the connection can't read pay runs, the failure asks you to refresh it - see Pay Run Access. After a refresh, the next refusal names the pay run. To pay this period now, compare the worker's payslips for this and later periods with the batch, then add only the unpaid hours straight onto their payslip in the pay run. Export Xero spreadsheet in the drawer lists the batch hours. To clear it for good, ask Xero Support how to move the pay run. Contact Astalty Support if you cannot find the period Xero is holding.
- Employee has no ordinary earnings rate in Xero - validation warns about this before anything is sent. Set an ordinary earnings rate on the employee's Employment tab in Xero, then export that worker again. Xero requires this rate before it accepts a timesheet.
Missing Users
If a batch contains users who are not linked to employees in Xero, Validate lists an error for each one and Create Export stays unavailable. Link them, then validate again.

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 a batch contains users who do not have employment details in Astalty covering the batch, Validate lists an error for each one and Create Export stays unavailable. Add their employment details, then validate again.

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.